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

Multidimensional Raster Correlation tool 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.

    Use the Lag parameter to filter multidimensional data
    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

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

  • PearsonThe correlation method will be Pearson. This is the default.
  • SpearmanThe correlation method will be Spearman.
  • KendallThe 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

LabelExplanationData 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})
NameExplanationData 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.

  • PEARSONThe correlation method will be Pearson. This is the default.
  • SPEARMANThe correlation method will be Spearman.
  • KENDALLThe 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_CORRELATIONThe 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_VALUEThe 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

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

Related topics