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})| Parameter | Explanation | Data 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.
| 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.
| 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
| Name | Explanation | Data 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
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")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)Environments
Licensing information
- Basic: Requires Geostatistical Analyst
- Standard: Requires Geostatistical Analyst
- Advanced: Requires Geostatistical Analyst