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 same results used for the GUI guide.
// First load the API file
var utils = require('users/parevalo_bu/gee-ccdc-tools:ccdcUtilities/api')
// Load the results
var ccdc = ee.Image("projects/GLANCE/RESULTS/CHANGEDETECTION/SA/Rondonia_example")
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 example results used here, the time
period corresponds to 1999 to 2020. 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 getMultiCoefs
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 2020 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.