Obtaining coefficients, changes and synthetic images (API)

Access the API and load CCDC results

This tutorial requires access to the API. It also requires access to any results obtained from running the CCDC algorithm on Google Earth Engine (GEE). For this tutorial we can use the results created by the GEE team for the entire globe. As of May 27, 2020, these results include multiple runs with varying inputs and configurations, and therefore we need to filter the results for a specific model run before we can process them. A model run we have been using so far is the 'z_' model, but others include the BRDF-corrected 'brdf'. Until the GEE team publishes an official public dataset, we can use the 'z_' or 'brdf' for testing purposes. Finally, if we want to look at the results for a specific location we can filter them using the built-in filterBounds function, or remove it if we want to see the results for the current map view extent.

// First load the API file
var utils = require('projects/GLANCE:ccdcUtilities/api')

// Load the global results computed by the GEE team
var ccdcCol = ee.ImageCollection("projects/CCDC/v2")
var ccdc = ccdcCol.filterMetadata('system:index', 'starts_with', 'z_')
                  .filterBounds(geometry)
                  .mosaic()

Obtain CCDC coefficients and synthetic images

The CCDC module provides functions that facilitate obtaining any coefficient for any point in the time within the range of the results. In the case of the global results generated by the GEE team, the time period corresponds to 1999 to 2019. Since the CCDC algorithm can be run in three different time formats, it is important to know which format was used to encode the results. The results used here were computed using fractional years, therefore we need to convert the date we want to obtain coefficients for to that format. This can be done using the Dates module:

Get date in the right format

var inputDate = '2001-12-30'
var dateParams = {inputFormat: 3, inputDate: inputDate, outputFormat: 1}
var formattedDate = utils.Dates.convertDate(dateParams)

In the example above, we convert the input date into fractional year, corresponding to the outputFormat 1. Other output formats are: 0 for Julian days, and 2 for Unix time.

Obtain CCDC results in ‘regular’ image format

The CCDC outputs are stored as array images to facilitate storing the variable-length arrays that are computed by the algorithm, as it is not known in advance how many temporal segments will be obtained for each pixel. However, operating on those arrays and displaying them tends to be slower than using a regular ee.Image(). For this reason, we convert the array image results into a regular image using the utils.CCDC.buildCcdImage function. The function expects the CCDC results, the number of segments we want to extract, and the names of the spectral bands.

// Spectral band names. This list contains all possible bands in this dataset
var BANDS = ['BLUE', 'GREEN', 'RED', 'NIR', 'SWIR1', 'SWIR2', 'TEMP']

// Names of the temporal segments
var SEGS = ["S1", "S2", "S3", "S4", "S5", "S6", "S7", "S8", "S9", "S10"]

// Obtain CCDC results in 'regular' ee.Image format
var ccdImage = utils.CCDC.buildCcdImage(ccdc, SEGS.length, BANDS)

Get coefficients

The resulting image will contain the ee.Image() version of the results with the number of coefficients specified. A lower number of segments requested will speed up subsequent processing, but may result in some missing segments for highly dynamic areas, such as agricultural lands in California. For several locations, 10 segments seems to be a good compromise. With this image, we can request any set of bands and coefficients for a the date we selected above. You can read the API documentation to specify the other parameters of the get_multi_coefs function.

// Define bands to select.
var SELECT_BANDS = ['RED', 'NIR']

// Define coefficients to select. This list contains all possible segments
var SELECT_COEFS = ["INTP", "SLP", "COS", "SIN", "COS2", "SIN2", "COS3", "SIN3", "RMSE"]

// Obtain coefficients
var coefs = utils.CCDC.getMultiCoefs(ccdImage, formattedDate, SELECT_BANDS, SELECT_COEFS, true, SEGS, 'after')

Compute synthetic image

The regression models can be used to calculate the surface reflectance of any of the bands for any point in time within the data time range (i.e. 1999 to 2019 in our case). This image is called a synthetic image, and it is computed with the getMultiSynthetic function.

// Bands to  get surface reflectance for
var SUB_BANDS = ['RED', 'NIR', 'SWIR1', 'SWIR2']

// Obtain synthetic image
var synt = utils.CCDC.getMultiSynthetic(ccdImage, formattedDate, 1, BANDS, SEGS)

Get change information

Finally, to obtain change information we can use the filterMag function. The function expects the CCDC results in the regular image format, start and end dates in the correct date format, the spectral band for which to get the information, and the list of segments defined previously.

var changeStart = '2001-01-01'
var changeEnd = '2018-12-31'
var startParams = {inputFormat: 3, inputDate: changeStart, outputFormat: 1}
var endParams = {inputFormat: 3, inputDate: changeEnd, outputFormat: 1}
var formattedStart = utils.Dates.convertDate(startParams)
var formattedEnd = utils.Dates.convertDate(endParams)

var filteredChanges = utils.CCDC.filterMag(ccdImage, formattedStart, formattedEnd, 'SWIR1', SEGS)

The image filteredChanges contains three bands:

  1. 'MAG': Represents the magnitude of the largest change for the specified time range and band.

  2. 'tBreak': Represents the date when the change with the largest magnitude occurred.

  3. 'numTbreak': Represents the total number of changes in the specified time period.