Find Argument Statistics (Image Analyst)

Available with Image Analyst license.

Summary

Extracts the dimension value or band index at which a given statistic is attained for each pixel in a multidimensional or multiband raster.

Usage

  • Use the Find Argument Statistics tool to extract the dimension value (for example, the date, height, or depth) at which a specific statistic is reached in the stack of rasters in a multidimensional raster dataset. Alternatively, find the band number at which the statistic is reached in a multiband raster.

    For example, you can find the month in which each pixel reached the highest sea surface temperature over 30 years of data collection. Another example is you have an eight-band remote sensing image and you want to know the band in which the minimum reflectance value was reached for each pixel.

  • Supported multidimensional raster datasets include Cloud Raster Format (CRF), multidimensional mosaic datasets, or multidimensional raster layers generated by netCDF, GRIB, or HDF format files.

  • This tool produces a multidimensional raster dataset in Cloud Raster Format (CRF). Currently, no other output formats are supported.

  • If the input multidimensional raster contains only one dimension, the output will be a single-band raster dataset. If the input multidimensional raster contains multiple dimensions, the output multidimensional raster will include those dimensions that were not included in the analysis.

Parameters

LabelExplanationData Type
Input Multidimensional or Multiband Raster

The input multidimensional or multiband raster to be analyzed.

Raster Dataset; Raster Layer; Mosaic Dataset; Mosaic Layer; Image Service; File
Dimension
(Optional)

The dimension from which the statistic will be extracted. If the input raster is not a multidimensional raster, this parameter is not required.

String
Dimension Definition
(Optional)

Specifies how the statistic will be extracted from the dimension.

  • AllThe statistic will be extracted across all dimensions. This is the default.
  • Interval KeywordThe statistic will be extracted from the time dimension according to the interval keyword.
String
Keyword Interval
(Optional)

The unit of time for which the statistic will be extracted.

For example, you have five years of daily sea surface temperature data and you want to know the year in which the maximum temperature was observed. Set Statistics Type to Argument of the maximum, set Dimension Definition to Interval Keyword, and set Keyword Interval to Yearly.

Alternatively, if you want to know the month in which the maximum temperature was consistently observed, set Statistics Type to Argument of the maximum, set Dimension Definition to Interval Keyword, and set Keyword Interval to Recurring Monthly. This will generate a raster in which each pixel contains the month in which the statistic was reached across the five-year record (for example, 08/18/2018, 08/25/2016, 08/07/2013).

This parameter is required when the Dimension parameter is set to StdTime and the Dimension Definition parameter is set to Interval Keyword.

  • Recurring DailyThe statistic will be extracted across days.
  • Recurring WeeklyThe statistic will be extracted across weeks.
  • Recurring MonthlyThe statistic will be extracted across months.
  • Recurring QuarterlyThe statistic will be extracted across quarters.
  • HourlyThe statistic will be extracted for the hour in which the statistic was reached.
  • DailyThe statistic will be extracted for the day in which the statistic was reached.
  • WeeklyThe statistic will be extracted for the week in which the statistic was reached.
  • MonthlyThe statistic will be extracted for the month in which the statistic was reached.
  • QuarterlyThe statistic will be extracted for the quarter in which the statistic was reached.
  • YearlyThe statistic will be extracted for the year in which the statistic was reached.
String
Variables [Dimension Info] (Description)
(Optional)

The variable or variables to be analyzed. If the input raster is not multidimensional, the pixel values of the multiband raster are considered the variable. If the input raster is multidimensional and no variable is specified, all variables with the selected dimension will be analyzed.

For example, to find the years in which temperature values were highest, specify temperature as the variable to be analyzed. If you do not specify any variables and you have both temperature and precipitation variables, both variables will be analyzed, and the output multidimensional raster will include both variables.

String
Statistics Type
(Optional)

Specifies the statistic to extract from the variable or variables along the given dimension.

  • Argument of the minimumThe dimension value at which the minimum variable value is reached will be extracted. This is the default.
  • Argument of the maximumThe dimension value at which the maximum variable value is reached will be extracted.
  • Argument of the medianThe dimension value at which the median variable value is reached will be extracted.
  • DurationThe longest dimension duration value between the minimum and maximum variable values will be extracted.
  • Argument of the valueThe dimension value at which the specified variable value is reached will be extracted.
String
Minimum Value
(Optional)

The minimum variable value to be used to extract the duration.

This parameter is required when the Statistics Type parameter is set to Duration.

Double
Maximum Value
(Optional)

The maximum variable value to be used to extract the duration.

This parameter is required when the Statistics Type parameter is set to Duration.

Double
Multiple Occurrence Value
(Optional)

The pixel value to use to indicate that a given argument statistic was reached more than once in the input raster dataset. If not specified, the pixel value will be the value of the dimension as specified by the Occurrence parameter, either the first or last occurrence.

Long
Ignore NoData
(Optional)

Specifies whether NoData values will be ignored in the analysis.

  • Checked—The analysis will include all valid pixels along a given dimension and ignore NoData pixels. This is the default.
  • Unchecked—The analysis will result in NoData if there are NoData values for the pixels along the given dimension.
Boolean
Argument Value
(Optional)

The value at which a comparison will be made to extract the dimension value.

This parameter is required when the Statistics Type parameter is set to Argument of the value.

The value at which a comparison will be made to extract the dimension value.

This parameter is required when the statistics_type parameter is set to ARGUMENT_VALUE.

Long
Comparison
(Optional)

Specifies the comparison type that will be used to extract the dimension value.

  • Equal toThe extracted dimension is equal to the specified value. This is the default.
  • Greater thanThe extracted dimension is greater than the specified value.
  • Smaller thanThe extracted dimension is smaller than the specified value.
String
Occurrence
(Optional)

Specifies whether the value of the dimension will be returned the first time or last time the argument statistic is reached.

  • First occurrenceThe value of the dimension will be returned the first time the argument statistic is reached. This is the default.
  • Last occurrenceThe value of the dimension will be returned the last time the argument statistic is reached.
String

Return Value

LabelExplanationData Type
Output Raster

The output raster dataset.

Raster

FindArgumentStatistics(in_raster, {dimension}, {dimension_def}, {interval_keyword}, {variables}, {statistics_type}, {min}, {max}, {multiple_occurrence}, {ignore_nodata}, {value}, {comparison}, {occurrence})
NameExplanationData Type
in_raster

The input multidimensional or multiband raster to be analyzed.

Raster Dataset; Raster Layer; Mosaic Dataset; Mosaic Layer; Image Service; File
dimension
(Optional)

The dimension from which the statistic will be extracted. If the input raster is not a multidimensional raster, this parameter is not required.

String
dimension_def
(Optional)

Specifies how the statistic will be extracted from the dimension.

  • ALLThe statistic will be extracted across all dimensions. This is the default.
  • INTERVAL_KEYWORDThe statistic will be extracted from the time dimension according to the interval keyword.
String
interval_keyword
(Optional)

The unit of time for which the statistic will be extracted.

For example, you have five years of daily sea surface temperature data and you want to know the year in which the maximum temperature was observed. Set Statistics Type to Argument of the maximum, set Dimension Definition to Interval Keyword, and set Keyword Interval to Yearly.

Alternatively, if you want to know the month in which the maximum temperature was consistently observed, set Statistics Type to Argument of the maximum, set Dimension Definition to Interval Keyword, and set Keyword Interval to Recurring Monthly. This will generate a raster in which each pixel contains the month in which the statistic was reached across the five-year record (for example, 08/18/2018, 08/25/2016, 08/07/2013).

This parameter is required when the dimension parameter is set to StdTime and the dimension_def parameter is set to INTERVAL_KEYWORD.

  • RECURRING_DAILYThe statistic will be extracted across days.
  • RECURRING_WEEKLYThe statistic will be extracted across weeks.
  • RECURRING_MONTHLYThe statistic will be extracted across months.
  • RECURRING_QUARTERLYThe statistic will be extracted across quarters.
  • HOURLYThe statistic will be extracted for the hour in which the statistic was reached.
  • DAILYThe statistic will be extracted for the day in which the statistic was reached.
  • WEEKLYThe statistic will be extracted for the week in which the statistic was reached.
  • MONTHLYThe statistic will be extracted for the month in which the statistic was reached.
  • QUARTERLYThe statistic will be extracted for the quarter in which the statistic was reached.
  • YEARLYThe statistic will be extracted for the year in which the statistic was reached.
String
variables
[variables,...]
(Optional)

The variable or variables to be analyzed. If the input raster is not multidimensional, the pixel values of the multiband raster are considered the variable. If the input raster is multidimensional and no variable is specified, all variables with the selected dimension will be analyzed.

For example, to find the years in which temperature values were highest, specify temperature as the variable to be analyzed. If you do not specify any variables and you have both temperature and precipitation variables, both variables will be analyzed, and the output multidimensional raster will include both variables.

String
statistics_type
(Optional)

Specifies the statistic to extract from the variable or variables along the given dimension.

  • ARGUMENT_MINThe dimension value at which the minimum variable value is reached will be extracted. This is the default.
  • ARGUMENT_MAXThe dimension value at which the maximum variable value is reached will be extracted.
  • ARGUMENT_MEDIANThe dimension value at which the median variable value is reached will be extracted.
  • DURATIONThe longest dimension duration value between the minimum and maximum variable values will be extracted.
  • ARGUMENT_VALUEThe dimension value at which the specified variable value is reached will be extracted.
String
min
(Optional)

The minimum variable value to be used to extract the duration.

This parameter is required when the statistics_type parameter is set to DURATION.

Double
max
(Optional)

The maximum variable value to be used to extract the duration.

This parameter is required when the statistics_type parameter is set to DURATION.

Double
multiple_occurrence
(Optional)

The pixel value to use to indicate that a given argument statistic was reached more than once in the input raster dataset. If not specified, the pixel value will be the value of the dimension as specified by the occurrence parameter, either the first or last occurrence.

Long
ignore_nodata
(Optional)

Specifies whether NoData values will be ignored in the analysis.

  • DATAThe analysis will include all valid pixels along a given dimension and ignore NoData pixels. This is the default.
  • NODATAThe analysis will result in NoData if there are NoData values for the pixels along the given dimension.
Boolean
value
(Optional)

The value at which a comparison will be made to extract the dimension value.

This parameter is required when the Statistics Type parameter is set to Argument of the value.

Long
comparison
(Optional)

Specifies the comparison type that will be used to extract the dimension value.

  • EQUAL_TOThe extracted dimension is equal to the specified value. This is the default.
  • GREATER_THANThe extracted dimension is greater than the specified value.
  • SMALLER_THANThe extracted dimension is smaller than the specified value.
String
occurrence
(Optional)

Specifies whether the value of the dimension will be returned the first time or last time the argument statistic is reached.

  • FIRST_OCCURRENCEThe value of the dimension will be returned the first time the argument statistic is reached. This is the default.
  • LAST_OCCURRENCEThe value of the dimension will be returned the last time the argument statistic is reached.
String

Return Value

NameExplanationData Type
out_raster

The output raster dataset.

Raster

Code sample

FindArgumentStatistics example 1 (Python window)

This example finds the minimum monthly precipitation and temperature values across a time series multidimensional raster. If the same minimum value is found multiple times, the pixel value will be 99999.

# Import system modules
import arcpy
from arcpy.ia import *

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

# get the date when the minimal precipitation was observed in each year
# as well as the date when the minimal temperature was observed in each year
argStatOutput = FindArgumentStatistics("prcp_temp_time_series.crf", "StdTime", "INTERVAL_KEYWORD", "YEARLY",
	"prcp;temp", "ARGUMENT_MIN", None, None, 0, "DATA")
	
# Save output
argStatOutput.save("C:/data/yearly_min_temp_precip.crf")
FindArgumentStatistics example 2 (stand-alone script)

This example finds the longest time interval for which salinity fell between 10 and 15 units of measurement in the multidimensional raster.

# 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/salinity.crf"
dimensionName = "Time"
dimensiondef = "ALL"
intervalkeyword = ''
variables = "temp"
arg_statistics_type = "DURATION"
min_value = 20
max_value = 25
multiple_occurrances_value = None
ignore_nodata = "NODATA"

# Execute 
# get the number of continous slices that have temperature value between 20 and 25
argStatOutput = FindArgumentStatistics(inFile, dimensionName, dimensiondef, intervalkeyword,
	variables, arg_statistics_type, min_value, max_value, multiple_occurrances_value, ignore_nodata)
	
# Save output
argStatOutput.save("C:/data/arg_statistics_output2.crf")

Related topics