Estimates the trend for each pixel along a dimension for one or more variables in a multidimensional raster.
Usage
A use example for this tool is you have 40 years worth of monthly ocean temperature data, and you want to fit a trend line for each pixel to see where and how temperature changed over time.
Supported multidimensional raster datasets include Cloud Raster Format (CRF), multidimensional mosaic datasets, or multidimensional raster layers generated by netCDF, GRIB, or HDF files.
This tool produces a multidimensional raster dataset in Cloud Raster Format (CRF). Currently, no other output formats are supported.
By default, the multidimensional raster output will be compressed using the LZ77 compression type. It is recommended, however, that you change the compression type to LERC and adjust the maximum error value based on your data. For example, if you expect the results of the analysis to be accurate to three decimal places, use 0.001 for the maximum error value. It's best to avoid unnecessary accuracy requirements, as they will increase the processing time and storage size.
This tool can be used to fit data along a linear, harmonic, or polynomial trend line, or it can be used to perform trend detection using the Mann-Kendall or Seasonal-Kendall test.
The Mann-Kendall and Seasonal-Kendall tests are used to determine whether there is a monotonic trend in the data. They are nonparametric, meaning they do not assume a specific distribution of data The Mann-Kendall test does not consider serial correlation or seasonal effects. If the data is seasonal, the Seasonal-Kendall test is more appropriate.
If the tool is used to perform either the Mann-Kendall or Seasonal-Kendall test, the output is a five-band raster as follows:
Band 1 = Sen's slope
Band 2 = p-value
Band 3 = Mann-Kendall score (S)
Band 4 = S Variance
Band 5 = Z-score
The outputs from the Mann-Kendall or Seasonal-Kendall test can be used to determine which pixels in your multidimensional time series have a statistically significant trend. You can use this information in conjunction with the linear, harmonic, or polynomial trend analysis to extract significant trends in your time series. You can generate a mask including pixels with significant p-values, apply the mask to the multidimensional raster, and use this masked multidimensional raster as the input to the tool to perform linear, harmonic, or polynomial trend analysis.
There are three trend line options for fitting a trend to the variable values along a dimension: linear, harmonic, and polynomial. The three trend fitting options are described below.
Linear—The linear trend line is a best-fit straight line that is used to estimate simple linear relationships. A linear trend highlights a rate of change that is increasing or decreasing at a steady rate. The formula for the linear trend line is as follows:
y = the pixel's variable value
x = the dimension value
ß0 = the y-intercept
ß1 = the linear slope or rate of change
ß1 > 0 indicates an increasing trend
ß1 < 0 indicates a decreasing trend
Harmonic—The harmonic trend line is a periodically repeating curved line that is best used to describe data that follows a cyclical pattern, such as seasonal temperature changes. The formula for the harmonic trend line is as follows:
y = the pixel's variable value
t = the Julian date
ß0 = the y-intercept
ß1 = the rate of change
α, γ = coefficients of inter-annual or intra-annual changes
ω = i
f = the harmonic frequency
Polynomial—The polynomial trend line is a curved line that is useful for data that fluctuates. In this case, a polynomial order value is used to indicate the maximum number of fluctuations that occur. The formula for the polynomial trend line is as follows:
y = the pixel's variable value
x = the dimension value
ß0, ß1, ß2, ß3, ..., ßn = constant coefficients
If the tool is used to perform linear, harmonic, or polynomial trend analysis, the output trend raster can be used as the input to the Predict Using Trend Raster tool. The trend raster is a multidimensional raster in which each slice is a multiband raster containing information about the trend line. If you are analyzing the trend for a single variable for a dataset containing a single dimension (for example, time), there will be a single slice in the output dataset. If you are analyzing a single variable for a dataset containing multiple dimensions (for example, time and depth), each slice will contain trend information for each dimension value along the dimension that was not included in the analysis.
For Linear trend analysis, the output contains three-band rasters, where:
Band 1 = Slope
Band 2 = Intercept
Band 3 = Root Mean Square Error (RMSE) or the error around the line of best fit
For Harmonic trend analysis, the number of bands in the output depends on the harmonic frequency. When the frequency is set to 1, the output is a five-band raster as follows:
Band 1 = Slope
Band 2 = Intercept
Band 3 = Harmonic_sin1
Band 4 = Harmonic_cos1
Band 5 = RMSE
When the frequency is set to 2, the output is a seven-band raster as follows
Band 1 = Slope
Band 2 = Intercept
Band 3 = Harmonic_sin1
Band 4 = Harmonic_cos1
Band 5 = Harmonic_sin2
Band 6 = Harmonic_cos2
Band 7 = RMSE
For Polynomial trend analysis, the number of bands in the output depends on the polynomial order. Second order polynomial fitting produces a four-band raster as follows:
Band 1 = Polynomial_2
Band 2 = Polynomial_1
Band 3 = Polynomial_0
Band 4 = RMSE
Third order polynomial fitting produces a five-band raster as follows:
Band 1 = Polynomial_3
Band 2 = Polynomial_2
Band 3 = Polynomial_1
Band 4 = Polynomial_0
Band 5 = RMSE
The Length of Cycle parameter for harmonic trend analysis is used to indicate the number and length of cycles you expect to see in your data throughout a day or year. For example, if you expect your data to go through two cycles of variation in one year, the length of cycle will be 182.5 days or 0.5 years. If you have temperature data collected every three hours, and there is one cycle of variation per day, the length of cycle is one day.
The Frequency parameter for harmonic trend analysis is used to describe the harmonic model to fit to the data. If the frequency is set to 1, a combination of linear and the first order harmonic curve will be used to fit the model. If the frequency is 2, a combination of linear, first order harmonic curve, and second order harmonic curve will be used to fit the data. If the frequency is 3, an additional third order harmonic curve will be used to model the data, and so on.
Model goodness-of-fit statistics can be generated as optional outputs for linear, harmonic, and polynomial trend rasters. The root mean square error (RMSE), R-squared, and the trend slope p-value can be calculated and displayed in the output raster's Properties window in the Statistics section. You can also display the statistics by symbolizing the output trend raster using RGB symbology and specifying the statistics as the red, green, and blue bands.
The dimension along which a trend will be extracted for the variable or variables selected in the analysis.
String
Variables [Dimension Info] (Description)
(Optional)
The variable or variables for which trends will be calculated. If no variable is specified, the first variable in the multidimensional raster will be analyzed.
String
Trend Type
(Optional)
Specifies the type of trend analysis to perform to pixel values along a dimension.
Linear —Variable pixel values will be fitted along a linear trend line. This is the default.
Polynomial —Variable pixel values will be fitted along a second order polynomial trend line.
Harmonic —Variable pixel values will be fitted along a harmonic trend line.
Mann-Kendall —Variable pixel values will be evaluated using the Mann-Kendall trend test.
Seasonal-Kendall —Variable pixel values will be evaluated using the Seasonal-Kendall trend test.
String
Frequency / Polynomial Order
(Optional)
The frequency or the polynomial order number to use in the trend fitting. If the trend type is polynomial, this parameter specifies the polynomial order. If the trend type is harmonic, this parameter specifies the number of models to use to fit the trend.
This parameter is only included in the trend analysis when the dimension being analyzed is time.
If the Trend Type parameter is Harmonic, the default value is 1, meaning a first order harmonic curve is used to fit the model.
If the Trend Type parameter is Polynomial, the default value is 2, or second order polynomial.
Long
Ignore NoData
(Optional)
Specifies whether NoData values are ignored in the analysis.
Checked—The analysis will include all valid pixels along a given dimension and ignore any NoData pixels. This is the default.
Unchecked—The analysis will result in NoData if there are any NoData values for the pixels along the given dimension.
Boolean
Length of Cycle
(Optional)
The length of periodic variation to model. This parameter is required when Trend Type is set to Harmonic. For example, leaf greenness often has one strong cycle of variation in a single year, so the cycle length is 1 year. Hourly temperature data
has one strong cycle of variation throughout a single day, so the cycle length is 1 day.
The default length is 1 year for data that varies on an annual cycle.
Double
Cycle
Unit
(Optional)
Specifies the time unit to be used for the length of a harmonic cycle.
Days —The unit for the length of the harmonic cycle is days.
Years —The unit for the length of the harmonic cycle is years. This is the default.
String
RMSE
(Optional)
Specifies whether the root mean square error (RMSE) of the trend fit line will be calculated.
Checked—The RMSE will be calculated and displayed in the raster dataset properties window under Statistics. This is the default.
Unchecked—The RMSE will not be calculated.
Boolean
R-Squared
(Optional)
Specifies whether the R-squared goodness-of-fit statistic for the trend fit line will be calculated.
Checked—The R-squared value will be calculated and displayed in the raster dataset properties window under Statistics.
Unchecked—The R-squared value will not be calculated. This is the default.
Boolean
P-Value of Slope Coefficient
(Optional)
Specifies whether the p-value statistic for the slope coefficient of the trend line will be calculated.
Checked—The p-value will be calculated and displayed in the raster dataset properties window under Statistics.
Unchecked—The p-value will not be calculated. This is the default.
Boolean
Seasonal Period
(Optional)
Specifies the time unit to be used for the length of a seasonal period when performing the Seasonal-Kendall test.
Days —The unit for the length of the seasonal period is days. This is the default.
Months —The unit for the length of the seasonal period is months.
String
Return Value
Label
Explanation
Data Type
Output Multidimensional Raster
The output Cloud Raster Format (CRF) multidimensional raster dataset.
The dimension along which a trend will be extracted for the variable or variables selected in the analysis.
String
variables
[variables,...]
(Optional)
The variable or variables for which trends will be calculated. If no variable is specified, the first variable in the multidimensional raster will be analyzed.
String
line_type
(Optional)
Specifies the type of trend analysis to perform to pixel values along a dimension.
LINEAR —Variable pixel values will be fitted along a linear trend line. This is the default.
POLYNOMIAL —Variable pixel values will be fitted along a second order polynomial trend line.
HARMONIC —Variable pixel values will be fitted along a harmonic trend line.
MANN-KENDALL —Variable pixel values will be evaluated using the Mann-Kendall trend test.
SEASONAL-KENDALL —Variable pixel values will be evaluated using the Seasonal-Kendall trend test.
String
frequency
(Optional)
The frequency or the polynomial order number to use in the trend fitting. If the trend type is polynomial, this parameter specifies the polynomial order. If the trend type is harmonic, this parameter specifies the number of models to use to fit the trend.
This parameter is only included in the trend analysis when the dimension being analyzed is time.
If the line_type parameter is HARMONIC, the default value is 1, meaning a first order harmonic curve is used to fit the model.
If the line_type parameter is POLYNOMIAL, the default value is 2, or second order polynomial.
Long
ignore_nodata
(Optional)
Specifies whether NoData values are ignored in the analysis.
DATA — The analysis will include all valid pixels along a given dimension and ignore any NoData pixels. This is the default.
NODATA —The analysis will result in NoData if there are any NoData values for the pixels along the given dimension.
Boolean
cycle_length
(Optional)
The length of periodic variation to model. This parameter is required when line_type is set to HARMONIC. For example, leaf greenness often has one strong cycle of variation in a single year, so the cycle length is 1 year. Hourly temperature data
has one strong cycle of variation throughout a single day, so the cycle length is 1 day.
The default length is 1 year for data that varies on an annual cycle.
Double
cycle_unit
(Optional)
Specifies the time unit to be used for the length of a harmonic cycle.
DAYS —The unit for the length of the harmonic cycle is days.
YEARS —The unit for the length of the harmonic cycle is years. This is the default.
String
rmse
(Optional)
Specifies whether the root mean square error (RMSE) of the trend fit line will be calculated.
RMSE —The RMSE will be calculated. This is the default.
NO_RMSE —The RMSE will not be calculated.
Boolean
r2
(Optional)
Specifies whether the R-squared goodness-of-fit statistic for the trend fit line will be calculated.
R2 —The R-squared value will be calculated.
NO_R2 —The R-squared value will not be calculated. This is the default.
Boolean
slope_p_value
(Optional)
Specifies whether the p-value statistic for the slope coefficient of the trend line will be calculated.
SLOPEPVALUE —The p-value will be calculated.
NO_SLOPEPVALUE —The p-value will not be calculated. This is the default.
Boolean
seasonal_period
(Optional)
Specifies the time unit to be used for the length of a seasonal period when performing the Seasonal-Kendall test.
DAYS —The unit for the length of the seasonal period is days. This is the default.
MONTHS —The unit for the length of the seasonal period is months.
String
Return Value
Name
Explanation
Data Type
out_multidimensional_raster
The output Cloud Raster Format (CRF) multidimensional raster dataset.
Raster
Code sample
GenerateTrendRaster example 1 (Python window)
This example calculates the polynomial trend fit for precipitation data over time.
# Import system modules
import arcpy
from arcpy.ia import *
# Check out the ArcGIS Image Analyst extension license
arcpy.CheckOutExtension("ImageAnalyst")
# Execute
trendCoeffMultidim = arcpy.ia.GenerateTrendRaster("model_time_series.crf",
"StdTime", "precip", "POLYNOMIAL", 2, "DATA", None, '', "RMSE","R2", None)
# Save output
trendCoeffMultidim.save("C:/data/polynomial_trend_coefficients.crf")
GenerateTrendRaster example 2 (stand-alone script)
This example calculates the linear trend fit for temperature and salinity data over depth.
# Import system modules
import arcpy
from arcpy.ia import *
# Check out the ArcGIS Image Analyst extension license
arcpy.CheckOutExtension("ImageAnalyst")
# Define input parameters
inFile = "C:/Data/ClimateVariables.crf"
dimensionName = "Depth"
variables = "salinity;temp"
trend_model = "LINEAR"
ignore_Nodata = "DATA"
# Execute - fit a linear model for salinity and temperature
trendCoeffMultidim = GenerateTrendRaster(inFile, dimensionName,
variables, trend_model, None, ignore_nodata)
# Save output
trendCoeffMultidim.save("C:/data/linear_trend_coefficients.crf")
GenerateTrendRaster example 3 (stand-alone script)
This example tests for monotonic trend, then calculates the harmonic trend fit along an NDVI time series.
