Multidimensional Raster Correlation (Image Analyst)

Available with Image Analyst license.

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.

Illustration

A correlation raster is calculated from monthly soil moisture and monthly precipitation.

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.

  

  Two variables are dimensionally aligned using the Lag parameter. For a value of 0: 0, 1, 2, 3 versus 4, 5, 6, 7 will be computed; for a value of 2: 0, 1, 2, 3 versus 6, 7, 8, 9 will be computed; and for a value of -1: 1, 2, 3 versus 4, 5, 6 will be computed.

• 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

Dialog

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

Python

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

Environments

Cell Alignment, 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

Licensing information

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