Calculate Rates (Spatial Statistics)

Summary

Calculates crude or smoothed rates. The global empirical Bayes rate method smooths the rates toward a global reference rate. The local empirical Bayes, locally weighted average, and locally weighted median rate methods use local neighbors to spatially smooth rates.

Learn more about how Calculate Rates works

Usage

  • If the Input Table or Features parameter value is a table, the options for the Rate Method parameter will be limited to Crude Rate and Global Empirical Bayes. The Local Empirical Bayes, Locally Weighted Average, and Locally Weighted Median options are only valid for spatial data.

  • The tool provides several Neighborhood Type parameter options. However, to customize the neighborhoods further, use Neighborhood Explorer to configure the neighborhoods and to export a .swm file. Use the .swm file as the Spatial Weights Matrix parameter value.

  • If the rate values are small, they may be difficult to interpret. Use the Rate Multiplier parameter to scale the rates or to report the rates per specific unit of population. For example, if the Rate Multiplier value is 10,000, the rates will be reported as a number per 10,000 people.

  • If a spatial smoothing rate method is selected, each focal feature will be included in its own neighborhood. For example, if the Neighborhood Type parameter value is K Nearest Neighbors and the Number of Neighbors parameter value is 7, each feature will have a neighborhood with 8 features. The entire neighborhood is used to calculate the rate of a focal feature.

  • If the Rate Method parameter is set to Local Empirical Bayes, Locally Weighted Average, or Locally Weighted Median, the output will include a Number of Non-Null Neighbors field. This field contains the number of neighbors, including the focal feature, that did not have a negative or null value in the Population Field and Count Field parameter values.

  • Features with a value of 0 in the Population Field value will receive a null crude rate value.

  • If the Rate Method parameter is set to Locally Weighted Average or Locally Weighted Median, the output will include a Fill Missing Value field. This field indicates whether a rate was imputed for a feature with a negative or null Count Field or Population Field value.

Parameters

LabelExplanationData Type
Input Table or Features

The table or features containing count fields and population fields to calculate rates.

Table View
Rate Fields

The count and population fields that will be used to calculate rates.

Value Table
Append Fields to Input
(Optional)

Specifies whether fields will be appended to the input dataset or saved to an output table or feature class.

  • Checked—Fields will be appended to the input features. This modifies the input data.
  • Unchecked—An output table or feature class containing the fields will be created. This is the default.

Boolean
Output Table or Features
(Optional)

The output table or feature class containing the rates and additional fields to help evaluate the rates.

Feature Class; Table
Rate Method
(Optional)

Specifies the method that will be used to calculate rates.

  • Crude RateThe rates will be calculated by dividing the count field values by the population field values. This is the default.
  • Global Empirical BayesThe rates will be the weighted average of the crude rate and the global average rate. The weight will depend on the feature's population size.
  • Local Empirical BayesThe rates will be the weighted average of the focal feature's crude rate and the weighted average rate of its neighborhood.
  • Locally Weighted Average The rates will be the spatially weighted average rate of each feature and its neighborhood.
  • Locally Weighted Median The rates will be the spatially weighted median rate of each feature and its neighborhood.
String
Probability Distribution

Specifies the probability distribution of the count field.

  • PoissonThe count field is assumed to follow a Poisson distribution. This is the default.
  • BinomialThe count field is assumed to follow a binomial distribution.
String
Neighborhood Type
(Optional)

Specifies the method that will be used to identify the neighbors of each feature.

  • Distance BandA threshold distance is applied to identify neighbors. Every feature that is within the threshold distance of a focal feature is considered a neighbor. If the input contains point or line features, this is the default.
    Fixed distance
  • Contiguity Edges Only Polygon features that share an edge or overlap a feature become neighbors of that feature.
    Contiguity edges only
  • Contiguity Edges Corners Features that overlap, share an edge, or share a vertex with a feature are neighbors of that feature. If the input contains polygon features, this is the default.
    Contiguity edges corners
  • K Nearest NeighborsThe same number of neighbors, k, is assigned to every feature. The k nearest features to a feature become its neighbors.
    K nearest neighbors
  • Delaunay TriangulationA nonoverlapping mesh of triangles is created from feature centroids. Each feature is a triangle node and nodes that share edges are considered neighbors.
    Trimmed Delaunay triangulation
  • Get Spatial Weights from FileThe spatial relationships between features is defined in a spatial weights matrix (.swm) file.
String
Distance Band
(Optional)

The distance from each feature that will be used to search for neighbors. All features within this distance will be included as neighbors.

Linear Unit
Number of Neighbors
(Optional)

The number of neighbors that will be included in a feature's neighborhood.

Long
Spatial Weights Matrix
(Optional)

The path and file name of the spatial weights matrix file that defines the spatial relationships among features.

File
Local Weighting Scheme
(Optional)

Specifies the weighting scheme that will be applied to neighbors when calculating local statistics.

  • Unweighted Neighbors will not be weighted. This is the default.
  • BisquareNeighbors will be weighted using a bisquare kernel scheme.
  • GaussianNeighbors will be weighted using a Gaussian kernel scheme.
String
Kernel Bandwidth
(Optional)

The bandwidth of the bisquare or Gaussian local weighting schemes. If no value is provided, one will be estimated during processing and included as a geoprocessing message.

Linear Unit
Rate Multiplier

A constant value that will be multiplied by the rates. This parameter can be used to scale the rates or to report the rates per specific unit of population. For example, when the value is set to 10,000, the rates will be reported as a number per 10,000 people.

Long

Derived Output

LabelExplanationData Type
Updated Input Table

The updated input table.

Table View
Output Layer Group

If a feature class is specified for the Input Table or Features parameter, a group layer is output with a layer for each rate specified in the Rate Fields parameter.

Group Layer

arcpy.stats.CalculateRates(in_table, rate_fields, {append_to_input}, {out_table}, {rate_method}, probability_distribution, {neighborhood_type}, {distance_band}, {number_of_neighbors}, {weights_matrix_file}, {local_weighting_scheme}, {kernel_bandwidth}, rate_multiplier)
NameExplanationData Type
in_table

The table or features containing count fields and population fields to calculate rates.

Table View
rate_fields
[[count_field, population_field],...]

The count and population fields that will be used to calculate rates.

Value Table
append_to_input
(Optional)

Specifies whether fields will be appended to the input dataset or saved to an output table or feature class.

  • APPEND Fields will be appended to the input features. This modifies the input data.
  • NO_APPENDAn output table or feature class containing the fields will be created. This is the default.
Boolean
out_table
(Optional)

The output table or feature class containing the rates and additional fields to help evaluate the rates.

Feature Class; Table
rate_method
(Optional)

Specifies the method that will be used to calculate rates.

  • CRUDE_RATEThe rates will be calculated by dividing the count field values by the population field values. This is the default.
  • GLOBAL_EMPIRICAL_BAYESThe rates will be the weighted average of the crude rate and the global average rate. The weight will depend on the feature's population size.
  • LOCAL_EMPIRICAL_BAYESThe rates will be the weighted average of the focal feature's crude rate and the weighted average rate of its neighborhood.
  • LOCALLY_WEIGHTED_AVERAGE The rates will be the spatially weighted average rate of each feature and its neighborhood.
  • LOCALLY_WEIGHTED_MEDIAN The rates will be the spatially weighted median rate of each feature and its neighborhood.
String
probability_distribution

Specifies the probability distribution of the count field.

  • POISSONThe count field is assumed to follow a Poisson distribution. This is the default.
  • BINOMIALThe count field is assumed to follow a binomial distribution.
String
neighborhood_type
(Optional)

Specifies the method that will be used to identify the neighbors of each feature.

  • DISTANCE_BANDA threshold distance is applied to identify neighbors. Every feature that is within the threshold distance of a focal feature is considered a neighbor. If the input contains point or line features, this is the default.
    Fixed distance
  • CONTIGUITY_EDGES_ONLY Polygon features that share an edge or overlap a feature become neighbors of that feature.
    Contiguity edges only
  • CONTIGUITY_EDGES_CORNERS Features that overlap, share an edge, or share a vertex with a feature are neighbors of that feature. If the input contains polygon features, this is the default.
    Contiguity edges corners
  • K_NEAREST_NEIGHBORSThe same number of neighbors, k, is assigned to every feature. The k nearest features to a feature become its neighbors.
    K nearest neighbors
  • DELAUNAY_TRIANGULATIONA nonoverlapping mesh of triangles is created from feature centroids. Each feature is a triangle node and nodes that share edges are considered neighbors.
    Trimmed Delaunay triangulation
  • GET_SPATIAL_WEIGHTS_FROM_FILEThe spatial relationships between features is defined in a spatial weights matrix (.swm) file.
String
distance_band
(Optional)

The distance from each feature that will be used to search for neighbors. All features within this distance will be included as neighbors.

Linear Unit
number_of_neighbors
(Optional)

The number of neighbors that will be included in a feature's neighborhood.

Long
weights_matrix_file
(Optional)

The path and file name of the spatial weights matrix file that defines the spatial relationships among features.

File
local_weighting_scheme
(Optional)

Specifies the weighting scheme that will be applied to neighbors when calculating local statistics.

  • UNWEIGHTED Neighbors will not be weighted. This is the default.
  • BISQUARENeighbors will be weighted using a bisquare kernel scheme.
  • GAUSSIANNeighbors will be weighted using a Gaussian kernel scheme.
String
kernel_bandwidth
(Optional)

The bandwidth of the bisquare or Gaussian local weighting schemes. If no value is provided, one will be estimated during processing and included as a geoprocessing message.

Linear Unit
rate_multiplier

A constant value that will be multiplied by the rates. This parameter can be used to scale the rates or to report the rates per specific unit of population. For example, when the value is set to 10,000, the rates will be reported as a number per 10,000 people.

Long

Derived Output

NameExplanationData Type
updated_table

The updated input table.

Table View
output_layer_group

If a feature class is specified for the in_table parameter, a group layer is output with a layer for each rate specified in the rate_fields parameter.

Group Layer

Code sample

CalculateRates example 1 (Python window)

The following Python script demonstrates how to use the CalculateRates function.

import arcpy
in_features = r"C:\Health.gdb\cancer_deaths"
out_features = r"C:\Health.gdb\cancer_rate"
rate_fields = "deaths_2024 population_2024; deaths_2023 population_2023"
rate_method = "Global Empirical Bayes"
distribution = "Poisson"
scaling_factor = 100000

arcpy.stats.CalculateRates(
    in_features, rate_fields, "NO_APPEND", out_features, rate_method,
    distribution, None, None, None, None, None, None, scaling_factor)
CalculateRates example 2 (stand-alone script)

The following Python script demonstrates how to use the CalculateRates function.

import arcpy

arcpy.env.workspace = r"C:\Health.gdb"

in_features = "cancer_deaths"
out_features = "cancer_rate"
rate_fields = "deaths_2024 population_2024; deaths_2023 population_2023"
rate_method = "RAW_RATE"
scaling_factor = 100000

arcpy.stats.CalculateRates(
    in_features, rate_fields,"NO_APPEND", out_features, rate_method, None, 
    None, None, None, None, None, None, scaling_factor)