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:
'MAG'
: Represents the magnitude of the largest change for the specified time range and band.'tBreak'
: Represents the date when the change with the largest magnitude occurred.'numTbreak'
: Represents the total number of changes in the specified time period.