Gaussian Geostatistical Simulations (Geostatistical Analyst)

Available with Geostatistical Analyst license.

Summary

Performs a conditional or unconditional geostatistical simulation based on a Simple Kriging model. The simulated rasters can be considered equally probable realizations of the kriging model.

Learn more about how Gaussian Geostatistical Simulations works

Usage

  • The input geostatistical layer must be the result of performing Simple Kriging on a dataset. Geostatistical layers resulting from other types of kriging cannot be used with this tool.

    Additionally:

    • A normal score transformation of the data is recommended to ensure that the input data follows a standard normal distribution.
    • Clustered data should be declustered (using either the cell or polygon with a clipping outline method) so that the input histogram accurately represents the sampled population. This histogram will be reproduced (on average) in the realizations.
  • To generate conditional realizations, the conditioning data should be the same as the data that was used to construct the Simple Kriging model from which the simulation will be based; however, other datasets can be used to condition the realizations.

  • Output generated by this tool can be identified as follows:

    • The prefix followed by s0 to sN (where N is the number of realizations) is used to name the simulated rasters when the option Save simulated rasters has been selected.
    • The prefix followed by MIN, MAX, MEAN, STDDEV, QUARTILE1, MEDIAN, QUARTILE3, QUANTILE, or P_THRSHLD is used to name the output rasters when these postprocessing options have been selected.
    • The prefix followed by the polygon feature class name is used to name the output polygon feature class when postprocessing for areas of interest (statistical polygons) has been selected.
  • Use different prefixes to identify output from different simulation runs. If you use the same prefix, all previous results starting with that prefix will be erased before the new results are created. Alternatively, the output from different simulation runs can be stored in separate folders or geodatabases.

  • If input statistical polygons are provided, the polygon output feature class will contain summary statistics of the values simulated within each polygon. To learn more about these summary statistics, refer to How Gaussian Geostatistical Simulations work.

  • Polygons representing areas of interest must be fully contained within the simulated raster's extent. If any portion of a polygon is covered by NoData values in the simulated rasters, the polygon attribute table will contain invalid results. In this case, the CELL_COUNT field will show the number of cells within the polygon that have simulated values, and the number will be expressed as a negative value.

  • This tool uses a random number generator in its operation. The Seed value used can be controlled in the Random number generator environment.

    • If a seed value of 0 is used (the default value), then each time the tool is run, a different set of random numbers will be used and a different set of simulations will be generated.
    • If the random number seed is set to a fixed number greater than 0, then the tool will produce the same set of simulations each time it is run, until the seed value is changed.

    Note:

    Only the Mersenne Twister random number generator type is supported; if ACM collected algorithm 599 or Standard C Rand is chosen, Mersenne Twister will be used instead.

  • If you have opted to save the simulated rasters, only the first two will be added to the table of contents in ArcMap. You can, however, browse to the output workspace and add the rest.

  • For conditional simulations, points of the conditioning dataset that fall inside the same cell will be averaged, and the realizations will be conditioned to honor that average value. If the output cell size is large, many points will fall inside each cell and be averaged, and the realizations will be conditioned to honor these (relatively) few average values.

  • If bounding features are supplied, any features or rasters supplied in the Mask environment will be ignored.

  • Current software limitations are as follows:

    • The maximum raster size is limited to 2,0492 cells (that is, 2,049 rows by 2,049 columns for a square raster).
    • The maximum number of realizations that can be requested in a single run is 4,500. Note that the maximum number of rasters that can be contained in a workspace is 4,999.
    • Simulations based on periodical semivariogram models (J-Bessel and Hole Effect) may not be accurate.
  • An error of Not enough memory to execute requested operation might indicate that the cell size requested will produce an output raster that is too large.

  • For data formats that support Null values, such as file geodatabase feature classes, a Null value will be used to indicate that a prediction could not be made for that location or that the value should be ignored when used as input. For data formats that do not support Null values, such as shapefiles, the value of -1.7976931348623158e+308 is used (this is the negative of the C++ defined constant DBL_MAX) to indicate that a prediction could not be made for that location.

Syntax

arcpy.ga.GaussianGeostatisticalSimulations(in_geostat_layer, number_of_realizations, output_workspace, output_simulation_prefix, {in_conditioning_features}, {conditioning_field}, {cell_size}, {in_bounding_dataset}, {save_simulated_rasters}, {quantile}, {threshold}, {in_stats_polygons}, {raster_stat_type}, {conditioning_measurement_error_field})
ParameterExplanationData Type
in_geostat_layer

Input a geostatistical layer resulting from a Simple Kriging model.

Geostatistical Layer
number_of_realizations

The number of simulations to perform.

Long
output_workspace

Stores all the simulation results. The workspace can be either a folder or a geodatabase.

Workspace
output_simulation_prefix

A one- to three-character alphanumeric prefix that is automatically added to the output dataset names.

String
in_conditioning_features
(Optional)

The features used to condition the realizations. If left blank, unconditional realizations are produced.

Feature Layer
conditioning_field
(Optional)

The field used to condition the realizations. If left blank, unconditional realizations are produced.

Field
cell_size
(Optional)

The cell size at which the output raster will be created.

This value can be explicitly set in the Environments by the Cell Size parameter.

If not set, it is the shorter of the width or the height of the extent of the input point features, in the input spatial reference, divided by 250.

Analysis Cell Size
in_bounding_dataset
(Optional)

Limits the analysis to these features' bounding polygon. If point features are entered, then a convex hull polygon is automatically created. Realizations are then performed within that polygon. If bounding features are supplied, any features or rasters supplied in the Mask environment will be ignored.

Feature Layer
save_simulated_rasters
(Optional)

Specifies whether or not the simulated rasters are saved to disk.

  • SAVE_SIMULATIONSIndicates that the simulated rasters will be saved to disk.
  • DO_NOT_SAVE_SIMULATIONSIndicates that the simulated rasters will not be saved to disk.
Boolean
quantile
(Optional)

The quantile value for which the output raster will be generated.

Double
threshold
(Optional)

The threshold value for which the output raster will be generated, as the percentage of the number of times the set threshold was exceeded, on a cell-by-cell basis.

Double
in_stats_polygons
(Optional)

These polygons represent areas of interest for which summary statistics are calculated.

If in_stats_polygons are provided, the output polygon feature class will be saved in the location defined by output_workspace, and it will have the same name as the input polygons, preceded by the output_simulation_prefix. For example, if the input statistical polygons were named myPolys and you entered aaa as the output prefix, then the output polygons will be named aaamyPolys and will be saved in the specified output workspace.

Feature Layer
raster_stat_type
[raster_stat_type,...]
(Optional)

The simulated rasters are postprocessed on a cell-by-cell basis, and each selected statistics type is calculated and reported in an output raster.

  • MINCalculates the minimum (smallest value).
  • MAXCalculates the maximum (largest value).
  • MEANCalculates the mean (average).
  • STDDEVCalculates the standard deviation.
  • QUARTILE1Calculates the 25th quantile.
  • MEDIANCalculates the median.
  • QUARTILE3Calculates the 75th quantile.
  • QUANTILECalculates a user-specified quantile (0 < Q < 1).
  • P_THRSHLDCalculates the percentage of the simulations where the cell value exceeds a user-specified threshold value.
String
conditioning_measurement_error_field
(Optional)

A field that specifies the measurement error for each input point in the conditioning features. For each conditioning feature, the value of this field should correspond to one standard deviation of the measured value of the feature. Use this field if the measurement error values are not the same at each sampling location.

A common source of nonconstant measurement error is when the data is measured with different devices. One device might be more precise than another, which means that it will have a smaller measurement error. For example, one thermometer rounds to the nearest degree and another thermometer rounds to the nearest tenth of a degree. The variability of measurements is often provided by the manufacturer of the measuring device, or it may be known from empirical practice.

Leave this parameter blank if there are no measurement error values or the measurement error values are unknown.

Field

Derived Output

NameExplanationData Type
out_workspace

The workspace containing the simulation results.

Workspace
out_polygon_stat

The output statistical polygons.

Feature Class
out_raster_simulation

The output simulation rasters.

Raster Layer
out_raster_stat

The output statistical rasters.

Raster Layer
out_convergence_value

The output convergence value.

Double

Code sample

GaussianGeostatisticalSimulations example 1 (Python window)

Perform an unconditional simulation.

import arcpy
arcpy.env.workspace = "C:/gapyexamples/data"
arcpy.GaussianGeostatisticalSimulations_ga("C:/gapyexamples/data/kriging.lyr", "10",
                                           "C:/gapyexamples/output", "ggs", "", "",
                                           "2000", "", "", "", "", "", "MEAN")
GaussianGeostatisticalSimulations example 2 (stand-alone script)

Perform an unconditional simulation.

# Name: GaussianGeostatisticalSimulations_Example_02.py
# Description: This tool performs conditional or unconditional geostatistical
#              simulation based on a Simple Kriging model.
# Requirements: Geostatistical Analyst Extension

# Import system modules
import arcpy

# Set environment settings
arcpy.env.workspace = "C:/gapyexamples/data"

# Set local variables
inLayer = "C:/gapyexamples/data/kriging.lyr"
numRealizations = 10
outWorkspace = "C:/gapyexamples/output"
cellSize = 2000
prefix = "ggs"
rasstatType = "MEAN"
conFeatures = ""
conField = ""
boundingData = ""
savesimRasters = ""
quantile = ""
threshold = ""
statsPolygons = ""
errorField = ""

# Execute GaussianGeostatisticalSimulations
arcpy.GaussianGeostatisticalSimulations_ga(
    inLayer, numRealizations, outWorkspace, prefix, conFeatures, conField, 
    cellSize, boundingData, savesimRasters, quantile, threshold, 
    statsPolygons, rasstatType, errorField)

Licensing information

  • Basic: Requires Geostatistical Analyst
  • Standard: Requires Geostatistical Analyst
  • Advanced: Requires Geostatistical Analyst

Related topics