Aggregate

Available with Image Analyst license.

Summary

Creates a raster object by combining slices from the input multidimensional raster based on a dimension interval and an aggregation method.

Discussion

Use the Aggregate function to aggregate variable values from a multidimensional raster over a given variable. For example, if you have daily precipitation data, you can determine the monthly average precipitation value.

This function creates a raster object that is the aggregation of the input multidimensional raster. By default, aggregation will be computed for all variables that are associated with the given dimension. For example, if precipitation, temperature, and wind speed all have a time dimension, all three variables will be aggregated separately if dimension_name is set to the time dimension. If you only want to aggregate one variable, use the Subset function before you use Aggregate.

The referenced raster dataset for the raster object is temporary. To make it permanent, call the raster object's save method.

Syntax

Aggregate (in_raster, dimension_name, raster_function, {raster_function_arguments}, {aggregation_definition}, {dimensionless})
ParameterExplanationData Type
in_raster

The input multidimensional raster to be aggregated.

Raster
dimension_name

The aggregation dimension. This is the dimension along which the variables will be aggregated.

String
raster_function

The name of a raster function as a string or the path to a custom raster function (.rft.xml file) that will be used to compute the aggregated pixel values.

The following are the supported raster functions as strings:

  • Majority—The pixel value that occurs most frequently will be calculated across all slices in the interval, and NoData will be returned if there are any NoData pixels along the dimension.
  • MajorityContinueOnNoData—The pixel value that occurs most frequently will be calculated across all slices in the interval, and NoData pixels will be ignored.
  • Max—The maximum value of a pixel will be calculated across all slices in the interval, and NoData will be returned if there are any NoData pixels along the dimension.
  • MaxContinueOnNoData—The maximum value of a pixel will be calculated across all slices in the interval, and NoData pixels will be ignored.
  • Mean—The mean of a pixel will be calculated across all slices in the interval, and NoData will be returned if there are any NoData pixels along the dimension.
  • MeanContinueOnNoData—The mean of a pixel will be calculated across all slices in the interval, and NoData pixels will be ignored.
  • Med—The median of a pixel will be calculated across all slices in the interval, and NoData will be returned if there are any NoData pixels along the dimension.
  • MedContinueOnNoData—The median of a pixel will be calculated across all slices in the interval, and NoData pixels will be ignored.
  • Min—The minimum of a pixel will be calculated across all slices in the interval, and NoData will be returned if there are any NoData pixels along the dimension.
  • MinContinueOnNoData—The minimum of a pixel will be calculated across all slices in the interval, and NoData pixels will be ignored.
  • Minority—The pixel value that occurs least frequently will be calculated across all slices in the interval, and NoData will be returned if there are any NoData pixels along the dimension.
  • MinorityContinueOnNoData—The pixel value that occurs least frequently will be calculated across all slices in the interval, and NoData pixels will be ignored.
  • Percentile—The percentile of values for a pixel will be calculated across all slices in the interval, and NoData will be returned if there are any NoData pixels along the dimension.
  • PercentileContinueOnNoData—The percentile of values for a pixel will be calculated across all slices in the interval, and NoData pixels will be ignored.
  • Range—The range of values for a pixel will be calculated across all slices in the interval, and NoData will be returned if there are any NoData pixels along the dimension.
  • RangeContinueOnNoData—The range of values for a pixel will be calculated across all slices in the interval, and NoData pixels will be ignored.
  • Std—The standard deviation of a pixel will be calculated across all slices in the interval, and NoData will be returned if there are any NoData pixels along the dimension.
  • StdContinueOnNoData—The standard deviation of a pixel will be calculated across all slices in the interval, and NoData pixels will be ignored.
  • Sum—The sum of a pixel's values will be calculated across all slices in the interval, and NoData will be returned if there are any NoData pixels along the dimension.
  • SumContinueOnNoData—The sum of a pixel's values will be calculated across all slices in the interval, and NoData pixels will be ignored.
  • Variety—The number of unique pixel values will be calculated across all slices in the interval, and NoData will be returned if there are any NoData pixels along the dimension.
  • VarietyContinueOnNoData—The number of unique pixel values will be calculated across all slices in the interval, and NoData pixels will be ignored.

String
raster_function_arguments

The parameters and values associated with the raster function or function chain. If not specified, default values will be used.

(The default value is None)

Dictionary
aggregation_definition

The dimension interval for which the data will be aggregated. The key-value pairs must follow one of the following formats:

  • 'interval':<interval_keyword>

    Use the interval keyword only when dimension_name is a time dimension. Interval keywords include HOURLY, DAILY, WEEKLY, MONTHLY, QUARTERLY, and YEARLY. For example, use this option to aggregate daily temperature data into monthly temperature data for each year. The output will include no more than 12 slices for each year.

  • 'recurrent_interval':<recurrent_interval_keyword>

    Use the recurrent interval keyword only when dimension_name is a time dimension. Recurrent interval keywords include DAILY, WEEKLY, MONTHLY, and QUARTERLY. For example, use this option to calculate the average temperature value for each month across all the years in the dataset. The output will include no more than 12 slices (one slice for each month of the year).

  • 'interval_value':<value>, 'interval_unit':<unit>

    Use the interval value to define recurring intervals. The interval unit is required when dimension_name is a time dimension. Interval unit keywords include HOUR, DAY, WEEK, MONTH, QUARTER, and YEAR. For example, use this option to aggregate daily temperature into temperature every 10 days.

  • 'interval_ranges':[(min, max),(min, max), ...]

    Use the interval ranges option to define custom intervals for aggregation. For example, use this option to aggregate daily temperature into temperature across specific seasonal dates.

If not specified, all slices across the dimension will be aggregated.

(The default value is None)

Dictionary
dimensionless

Specifies whether the output will be a dimensionless raster. This is only possible when the output has a single slice.

  • True—The layer will not have dimension values.
  • False—The layer will have dimension values.

(The default value is False)

Boolean
Return Value
Data TypeExplanation
Raster

The output aggregated multidimensional raster.

Code sample

Aggregate example

Aggregate precipitation data by calculating the overall average, monthly average, minimum over 10 days, and maximum over 2 ranges.

import arcpy
from arcpy.ia import *

arcpy.CheckOutExtension("ImageAnalyst")

in_raster = Raster('ClimateData_Daily.nc', True)

# Choose the precipitation variable
prcp_raster = Subset(in_raster, variables = 'prcp')

# Calculate the average precipitation across the whole time period
avg_prcp = Aggregate(prcp_raster, 'StdTime', 'Mean')

# Calculate the monthly mean precipitation 
monthly_avg_prcp = Aggregate(prcp_raster, 'StdTime', 
	'Mean', {'interval': 'monthly'})

# Calculate the minimum precipitation every 10 days
min_precip_10day = Aggregate(prcp_raster, 'StdTime', 'Min', 
	{'interval_value' : 10, 'interval_unit': 'day'})

# Calculate the maximum precipitation in two separate time ranges
max_prcp_range = Aggregate(prcp_raster, 'StdTime', 'Max', 
	{'interval_ranges':  [('2001-01-01T00:00:00', '2001-02-01T00:00:00'), 
	('2001-12-01T00:00:00', '2001-12-24T00:00:00')]})