Multidimensional Raster Correlation (Image Analyst)

Summary

Analyzes correlations between two variables in one or two multidimensional rasters.

The tool takes two multidimensional rasters as input, compares two variables using the Pearson, Kendall, or Spearman correlation method, and outputs a correlation raster, with each pixel representing the correlation values of the corresponding pixel arrays. The output raster can map where the two variables are correlated and where they are not correlated.

The tool can also calculate cross correlation when the lag is a nonzero value and calculate auto correlation when the two inputs are the same.

You can analyze correlations between two variables in one or two multidimensional rasters. The output is a correlation raster in which each pixel is the correlation of the two time series from the two variables. The tool can be used to calculate correlation with a lag, a cross correlation, or an autocorrelation. For example, the correlation raster in the images below was calculated from a soil moisture variable over time and a precipitation variable over time.

Usage

• For each pixel location in the two multidimensional rasters, the tool uses the two corresponding pixel arrays from the two variables and calculates a correlation value. The tool compares the two ordered arrays for each overlapped pixel, trimming off unnecessary data. When the lengths of the pixel arrays are different, the tail of the longer one will be trimmed.

• The two multidimensional rasters must have the same cell size, spatial extent, and projection. They do not need the same time extent or interval.

• Use the Aggregate Multidimensional Raster tool or the Interpolate Raster By Dimension function to resample the dimensional interval if the same intervals are needed.

• Use the Subset Multidimensional Raster tool or the Multidimensional Filter function to define the same dimensional extent.

• Alternately, you can use the Lag parameter to control how the two variables will be dimensionally aligned to calculate a correlation value by shifting the pixel array by the step specified. A value of 0 means no shift, a value of 2 means shifting the first variable by two indexes (steps) forward to calculate, and a value of -2 means shifting the first variable by two steps backward to calculate.

For example, a pixel array in the first raster is 0, 1, 2, 3 and the pixel array in the second raster is 4, 5, 6, 7, 8, 9.

• A lag describes the situation in which one (leading) variable is cross-correlated with the values of another (lagging) variable at later times and synchronization.

• Cross correlation calculates a correlation raster for each lag in the specified range, and the resulting correlation rasters will be saved as multiband rasters. When the Calculate P-value parameter is checked, additional bands will be added to the output. Design your workflow to avoid creating unnecessary output bands.

• To calculate autocorrelation, set the first and second input with the same multidimensional raster, dimension name, and variable.

Parameters

 Label Explanation Data Type Input Multidimensional Raster 1 The input multidimensional raster dataset.The first multidimensional raster in any supported format. Raster Dataset; Raster Layer; Mosaic Dataset; Mosaic Layer; Image Service Input Multidimensional Raster 2 The second multidimensional raster that will be correlated with the first input. Autocorrelation will be calculated if the Input Multidimensional Raster 1 parameter value is the same as the Input Multidimensional Raster 2 parameter value. Autocorrelation refers to the degree of correlation of the same variables between two successive time intervals. Raster Dataset; Raster Layer; Mosaic Dataset; Mosaic Layer; Image Service Dimension Name of Raster 1(Optional) A dimension name in the first dataset, along which the pixel array is defined. When the input has two nonspatial dimensions, a dimension must be specified. The length of the dimension used in the calculation must be greater than 2. String Variable 1 (Optional) A variable name from the first input raster. String Dimension Name of Raster 2(Optional) A dimension name in the second dataset. The length of the dimension used in the calculation must be greater than 2. String Variable 2 (Optional) A variable name from the second input raster. String Correlation Method (Optional) Specifies the correlation calculation method that will be used.Pearson—The correlation method will be Pearson. This is the default.Spearman—The correlation method will be Spearman.Kendall—The correlation method will be Kendall. String Lag (Optional) Calculate a correlation value by shifting the pixel array by the step specified, from 0 to dimension/2, depending on the time lag. The default is 0. Long Calculate Cross Correlation at Lags(Optional) Specifies whether the cross correlation will be computed at lags.When enabled, the correlations will be calculated at each lag within a range defined by the lag value. For example, if the lag value is 2, correlations of -2, -1, 0, 1, and 2 will be calculated and stored as bands in the output raster.Checked—The cross correlation will be computed at lags.Unchecked—The cross correlation will not be computed at lags. This is the default. Boolean Calculate P-value(Optional) Specifies whether the p-value will be computed at lags. P-value is a confidence value that describes how well the two variables are correlated.Checked—The p-value will be computed at lags. The output will include additional bands storing the p-values.Unchecked—The p-value will not be computed at lags. This is the default. Boolean Output Maximum Correlation Raster(Optional) A 2-band raster with maximum correlation values and the lags at which the maximum correlations occur. The raster will be created when the Calculate Cross Correlation at Lags parameter is checked.A 2-band raster with maximum correlation values and the lags at which the maximum correlations occur. The raster will be created when the calculate_xcorr parameter is specified as ALL_CROSS_CORRELATION. Raster Dataset

Return Value

 Label Explanation Data Type Output Raster The output raster dataset. When the lag parameter value is not 0, a cross correlation at each lag will be calculated and stored as bands in the output. Raster Dataset

`MultidimensionalRasterCorrelation(in_mdim_raster1, in_mdim_raster2, {dimension1}, {variable1}, {dimension2}, {variable2}, {corr_method}, {lag}, {calculate_xcorr}, {calculate_pvalue}, {out_max_corr_raster})`
 Name Explanation Data Type in_mdim_raster1 The input multidimensional raster dataset.The first multidimensional raster in any supported format. Raster Dataset; Raster Layer; Mosaic Dataset; Mosaic Layer; Image Service in_mdim_raster2 The second multidimensional raster that will be correlated with the first input. The length of the dimension used in the calculation must be greater than 2. Autocorrelation will be calculated if the in_mdim_raster1 parameter value is the same as the in_mdim_raster2 parameter value. Autocorrelation refers to the degree of correlation of the same variables between two successive time intervals. Raster Dataset; Raster Layer; Mosaic Dataset; Mosaic Layer; Image Service dimension1(Optional) A dimension name in the first dataset, along which the pixel array is defined. When the input has two nonspatial dimensions, a dimension must be specified. The length of the dimension used in the calculation must be greater than 2. String variable1(Optional) A variable name from the first input raster. String dimension2(Optional) A dimension name in the second dataset. The length of the dimension used in the calculation must be greater than 2. String variable2(Optional) A variable name from the second input raster. String corr_method(Optional) Specifies the correlation calculation method that will be used.PEARSON—The correlation method will be Pearson. This is the default.SPEARMAN—The correlation method will be Spearman.KENDALL—The correlation method will be Kendall. String lag(Optional) Calculate a correlation value by shifting the pixel array by the step specified, from 0 to dimension/2, depending on the time lag. The default is 0. Long calculate_xcorr(Optional) Specifies whether the cross correlation will be computed at lags.When ALL_CROSS_CORRELATION is specified, the correlations will be calculated at each lag within a range defined by the lag value. For example, if the lag value is 2, correlations of -2, -1, 0, 1, and 2 will be calculated and stored as bands in the output raster. ALL_CROSS_CORRELATION— The cross correlation will be computed at lags.NO_CROSS_CORRELATION—The cross correlation will not be computed at lags. This is the default. Boolean calculate_pvalue(Optional) Specifies whether the p-value will be computed at lags. P-value is a confidence value that describes how well the two variables are correlated.CALCULATE_P_VALUE— The p-value will be computed at lags. The output will include additional bands storing the p-values.NO_P_VALUE—The p-value will not be computed at lags. This is the default. Boolean out_max_corr_raster(Optional) A 2-band raster with maximum correlation values and the lags at which the maximum correlations occur. The raster will be created when the calculate_xcorr parameter is specified as ALL_CROSS_CORRELATION. Raster Dataset

Return Value

 Name Explanation Data Type out_raster The output raster dataset. When the lag parameter value is not 0, a cross correlation at each lag will be calculated and stored as bands in the output. Raster Dataset

Code sample

MultidimensionalRasterCorrelation example 1 (Python window)
``````# Import system modules
import arcpy
from arcpy.ia import *

# Check out the ArcGIS Image Analyst extension license
arcpy.CheckOutExtension("ImageAnalyst")

# Execute
arcpy.env.workspace = r"c:\data"
output=arcpy.ia.MultidimensionalRasterCorrelation("soil2022.crf", "weather2022.crf", "StdTime", "soilm", "StdTime", "temperature", "PEARSON", 0, "NO_CROSS_CORRELATION", "NO_P_VALUE", None)
output.save("correlationraster.crf")``````
MultidimensionalRasterCorrelation example 2 (stand-alone script)
``````# Import system modules
import arcpy
from arcpy.ia import *

# Check out the ArcGIS Image Analyst extension license
arcpy.CheckOutExtension("ImageAnalyst")

# Define input parameters
raster1=r"E:\data\soil2022.crf"
raster2=r"E:\data\weather2022.crf"
dimension1="StdTime"
variable1="soilm"
dimension2="StdTime"
variable2="temperature"
correlation_method="PEARSON"
lag=3
calculate_cross_correlation="ALL_CROSS_CORRELATION"
calculate_pvalue="CACULATE_P_VALUE"
out_max_correlation_raster=r"E:\data\max_correlation.crf"

# Execute
output = arcpy.ia.MultidimensionalRasterCorrelation(raster1, raster2, dimension1, variable1, dimension2, variable2, correlation _method, lag, calculate_cross_correlatio, calculate_pvalue, out_max_ correlation_raster)
output.save(r"E:\data\cross_correlation_raster.crf")``````

Licensing information

• Basic: Requires Image Analyst
• Standard: Requires Image Analyst