Available with Image Analyst license.
Summary
Evaluates changes in pixel values over time using the Landsat-based detection of trends in disturbance and recovery (LandTrendr) method and generates a change analysis raster containing the model results.
Usage
The LandTrendr algorithm is a method for identifying change in pixel values over time. It was developed for a time series of multiband Landsat imagery and is used to detect change and classify land cover before and after the change occurred. This tool can be used with imagery from supported sensors and can be used to detect change in single-band rasters. For example, this tool can be used to detect changes in a time series of NDVI rasters to identify deforestation events.
The LandTrendr algorithm extracts the time series trajectory for each pixel over time, using the pixel value information from a single spectral band or spectral index. The trajectory is then segmented to capture and model periods of no change, change, and recovery from change.
The output from this tool is model information in a change analysis raster in which each pixel stores a suite of model information that describes that pixel's history over time. The change analysis raster is a multidimensional raster in which each slice is a multiband raster composed of the model coefficients, the root mean square error (RMSE), and the observed changes. It can be used as the input to the Detect Change Using Change Analysis Raster tool, which generates a raster containing change information for each pixel.
There is one slice for each year in the analysis.The purpose of this tool is to extract changes in an observed feature, so the ideal input multidimensional imagery should capture a consistent observation throughout time and should not include atmospheric or sensor interference, clouds, or cloud shadow. The best practice is to use data that has been normalized and can be masked using a QA band, for example Landsat Collection 1 Surface Reflectance products with a cloud mask.
The tool performs analysis on one image per year, and the number of yearly slices must be equal to or greater than the value specified in the Minimum Number of Observations parameter. It is recommended that you have at least six years of data.
If you have monthly, weekly, or daily data, it is recommended that you select several images from each year (preferably from the same season), remove clouds and cloud shadow, and combine the images to generate a single image that captures the observation well. If monthly, weekly, or daily data is provided as the input multidimensional raster, the tool will identify one slice for analysis based on the date closest to that provided in the Snapping Date parameter.
A feature in a landscape will often take time to recover from a nonpermanent change such as a forest fire or insect infestation. To control the rate of recovery recognized by the model, set the Recovery Threshold parameter. A distinct segment cannot have a recovery rate that is faster than 1/recovery threshold.
The recovery from a change in landscape can occur in the positive or negative direction. For example, when a landscape experiences forest loss, a time series of vegetation index values shows a drop in index values, and the recovery shows a gradual increase in vegetation index values, or a positive recovery trend. Specify the direction of recovery trend with the Recovery Has Increasing Trend parameter.
To explore the changes calculated in the output change analysis raster, create a temporal profile chart. Generate graphs for various locations in the change analysis raster using the Fitted Value band or the Slope band to see where changes have occurred. You can hover the pointer over the points on the graph to identify the date of change.
This tool may take a long time to run and requires significant disk space to store the results. To improve processing time and reduce the amount of storage space, the following steps are recommended:
- Turn off the Pyramid environment. Uncheck the Build Pyramids check box in the Environment pane or set the environment to NONE in Python.
- Set the Compression environment to LERC and set Max error to 0.000001.
- If you expect to run the Detect Change Using Change Analysis Raster tool on the output of this tool multiple times, build a multidimensional transpose on the result.
This tool produces a multidimensional raster dataset in Cloud Raster Format (CRF). Currently, no other output formats are supported.
Syntax
AnalyzeChangesUsingLandTrendr(in_multidimensional_raster, {processing_band}, {snapping_date}, {max_num_segments}, {vertex_count_overshoot}, {spike_threshold}, {recovery_threshold}, {prevent_one_year_recovery}, {recovery_trend}, {min_num_observations}, {best_model_proportion}, pvalue_threshold, {output_other_bands})| Parameter | Explanation | Data Type |
in_multidimensional_raster | The input multidimensional raster dataset. | Raster Dataset; Raster Layer; Mosaic Dataset; Mosaic Layer; Image Service; File |
processing_band (Optional) | The band to use for segmenting the pixel value trajectories over time. Choose the band that will best capture the changes in the feature you want to observe. If no band value is specified and the input is multiband imagery, the first band in the multiband image will be used. | String |
snapping_date (Optional) | The date used to select a slice for each year in the input multidimensional dataset. The slice with the date closest to the snapping date will be selected. This parameter is required if the input dataset contains sub-yearly data. The default is 06-30, or June 30, approximately midway through a calendar year. | String |
max_num_segments (Optional) | The maximum number of segments to be fitted to the time series for each pixel. The default is 5. | Long |
vertex_count_overshoot (Optional) | The number of additional vertices beyond max_num_segments + 1 that can be used to fit the model during the initial stage of identifying vertices. Later in the modeling process, the number of additional vertices will be reduced to max_num_segments + 1. The default is 2. | Long |
spike_threshold (Optional) | The threshold to use for dampening spikes or anomalies in the pixel value trajectory. The value must range between 0 and 1, where 1 means no dampening. The default is 0.9. | Double |
recovery_threshold (Optional) | The recovery threshold value, in years. If a segment has a recovery rate that is faster than 1/recovery threshold, the segment is discarded and not included in the time series model. The value must range between 0 and 1. The default is 0.25. | Double |
prevent_one_year_recovery (Optional) | Specifies whether segments that exhibit a one year recovery will be excluded.
| Boolean |
recovery_trend (Optional) | Specifies whether the recovery has an increasing (positive) trend.
| Boolean |
min_num_observations (Optional) | The minimum number of valid observations required to perform fitting. The number of years in the input multidimensional dataset must be equal to or greater than this value. The default is 6. | Long |
best_model_proportion (Optional) | The best model proportion value. During the model selection process, the tool will calculate the p-value for each model and select a model that has the most vertices while maintaining the smallest (most significant) p-value based on this proportion value. A value of 1 means the model has the lowest p-value but may not have a high number of vertices. The default is 1.25. | Double |
pvalue_threshold | The p-value threshold for a model to be selected. After the vertices are detected in the initial stage of the model fitting, the tool will fit each segment and calculate the p-value to determine the significance of the model. On the next iteration, the model will decrease the number of segments by one and recalculate the p-value. This will continue and, if the p-value is smaller than the value specified in this parameter, the model will be selected and the tool will stop searching for a better model. If no such model is selected, the tool will select a model with a p-value smaller than the lowest p-value × best model proportion value. The default is 0.01. | Double |
output_other_bands (Optional) | Specifies whether other bands will be included in the segmentation process.
| Boolean |
Return Value
| Name | Explanation | Data Type |
| out_multidimensional_raster | The output Cloud Raster Format (CRF) multidimensional raster dataset. The output change analysis raster containing model information from the LandTrendr analysis. | Raster |
Code sample
This example performs the LandTrendr algorithm for change detection on a time series of NDVI data.
# Import system modules
import arcpy
from arcpy.ia import *
# Check out the ArcGIS Image Analyst extension license
arcpy.CheckOutExtension("ImageAnalyst")
changeAnalysisRaster = arcpy.ia.AnalyzeChangesUsingLandTrendr(
"Monthly_NDVI_30_years.crf","","",10,3,0.9,0.25, 'PREVENT_ONE_YEAR_RECOVERY',
'INCREASING_TREND',10,1.25,0.05, 'EXCLUDE_OTHER_BANDS')
# Save output
changeAnalysisRaster.save(r"C:\data\NDVI_ChangeAnalysis.crf")This example performs continuous change detection on a time series of Landsat imagery.
# Import system modules
import arcpy
from arcpy.ia import *
# Check out the ArcGIS Image Analyst extension license
arcpy.CheckOutExtension("ImageAnalyst")
# Define input parameters
in_multidimensional = r"C:\data\Landsat_time_series.crf"
processing_band = "Band_4"
snapping_date = ""
max_num_segments = 10
vertex_count_overshoot = 3
spike_threshold = 0.9
recovery_threshold = 0.25
prevent_one_year_recovery = "PREVENT_ONE_YEAR_RECOVERY"
recovery_trend = "INCREASING_TREND"
min_num_observations = 6
best_model_proportion = 1.25
pvalue_threshold = 0.01
output_other_bands = "EXCLUDE_OTHER_BANDS"
# Execute
changeAnalysisRaster = arcpy.ia.AnalyzeChangesUsingCCDC(
in_multidimensional, processing_band, snapping_date, max_num_segments,
vertex_count_overshoot, spike_threshold, recovery_threshold, prevent_one_year_recovery,
recovery_trend, min_num_observations, best_model_proportion, pvalue_threshold, output_other_bands)
# Save output
changeAnalysisRaster.save(r"C:\data\Landsat_ChangeAnalysis.crf")Environments
Licensing information
- Basic: Requires Image Analyst
- Standard: Requires Image Analyst
- Advanced: Requires Image Analyst