Analyze Changes Using LandTrendr (Image Analyst)

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.

Learn more about how LandTrendr works

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 occurs. 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.

• This tool extracts 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.

Parameters

Dialog

Label	Explanation	Data Type
Input Multidimensional Raster	The input multidimensional raster dataset.	Raster Dataset; Raster Layer; Mosaic Dataset; Mosaic Layer; Image Service; File
Processing Band Name (Optional)	The image band name to use for segmenting the pixel value trajectories over time. Choose the band name 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 identify a slice for each year in the input multidimensional dataset. The slice with the date closest to the snapping date will be used. This parameter is required if the input dataset contains sub-yearly data. The default is 06-30, or June 30, which is approximately midway through a calendar year.	String
Maximum Number of 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 Threshold (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 in which 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. Checked—Segments that exhibit a one year recovery will be excluded. This is the default. Unchecked—Segments that exhibit a one year recovery will be not be excluded.	Boolean
Recovery Has Increasing Trend (Optional)	Specifies whether the recovery has an increasing (positive) trend. Checked—The recovery has an increasing trend. This is the default. Unchecked—The recovery has a decreasing trend.	Boolean
Minimum Number of 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 identify 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
P-Value 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
Include Other Bands (Optional)	Specifies whether other bands will be included in the results. Checked—Other bands will be included in the results. The segmentation and vertices information from the initial segmentation band specified in the Processing Band parameter will also be fitted to the remaining bands in the multiband images. The model results will include the segmentation band first, then the remaining bands. Unchecked—Other bands will not be included in the results. This is the default.	Boolean

Return Value

Label	Explanation	Data Type
Output Multidimensional Raster	The output Cloud Raster Format (CRF) multidimensional raster dataset. The output change analysis raster containing model information from the LandTrendr analysis.	Raster

Python

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})

Name	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 image band name to use for segmenting the pixel value trajectories over time. Choose the band name 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 identify a slice for each year in the input multidimensional dataset. The slice with the date closest to the snapping date will be used. This parameter is required if the input dataset contains sub-yearly data. The default is 06-30, or June 30, which is 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 in which 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. ALLOW_ONE_YEAR_RECOVERY—Segments that exhibit a one year recovery will not be excluded. PREVENT_ONE_YEAR_RECOVERY—Segments that exhibit a one year recovery will be excluded. This is the default.	Boolean
recovery_trend (Optional)	Specifies whether the recovery has an increasing (positive) trend. INCREASING_TREND—The recovery has an increasing trend. This is the default. DECREASING_TREND—The recovery has a decreasing 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 identify 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. INCLUDE_OTHER_BANDS—Other bands will be included. The segmentation and vertices information from the initial segmentation band specified in the processing_band parameter will also be fitted to the remaining bands in the multiband images. The model results will include the segmentation band first, then the remaining bands. EXCLUDE_OTHER_BANDS—Other bands will not be included. This is the default.	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

AnalyzeChangesUsingLandTrendr example 1 (Python window)

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")

AnalyzeChangesUsingLandTrendr example 2 (stand-alone script)

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

Cell Size, Compression, Current Workspace, Geographic Transformations, NoData, Output CONFIG Keyword, Output Coordinate System, Extent, Parallel Processing Factor, Pyramid, Raster Statistics, Resampling Method, Scratch Workspace, Snap Raster, Tile Size