| Label | Explanation | Data Type |
Input Feature Class | A feature class containing a distribution of features for which the standard deviational ellipse or ellipsoid will be calculated. | Feature Layer |
Output Ellipse Feature Class | A polygon feature class that will contain the output ellipse feature. | Feature Class |
Ellipse Size | Specifies the size of the output ellipses in standard deviations.
| String |
Weight Field (Optional) | The numeric field that will be used to weight locations according to their relative importance. | Field |
Case Field (Optional) | The field that will be used to group features for separate directional distribution calculations. The case field can be of integer, date, or string type. | Field |
Summary
Creates standard deviational ellipses or ellipsoids to summarize the spatial characteristics of geographic features: central tendency, dispersion, and directional trends.
Learn how Directional Distribution (Standard Deviational Ellipse) works
Illustration
Usage
This tool creates an output containing elliptical polygons or 3D ellipsoidal multipatches, one for each case if the Case Field parameter is specified. The attribute values for these elliptical polygons include x- and y-coordinates for the mean center, two standard distances (long and short axes), and the orientation of the ellipse. When z-enabled point data is used, the attribute values will also include the z-coordinate for the mean center, a third standard distance (height), and orientation measures of the ellipsoid. If the input features are 2D, the field names will be CenterX, CenterY, XStdDist, YStdDist, and Rotation. If the input features are 3D points, the following fields will also be added to the output: CenterZ, ZStdDist, AngleZ, TiltX, RollY, and Volume. When a Case Field parameter value is provided, this field will also be added to the output.
This tool honors the 3D nature of point data and will use x-, y-, and z-values in its calculations if z-values are available. Since these results are 3D in nature, they will need to be visualized in a scene. Ensure that you are running the analysis in a scene, or copy the result layer into a scene for correct visualization of the analysis results.
Calculations require projected data to accurately measure distances.
When the underlying spatial pattern of features is concentrated toward the center with fewer features toward the periphery (following a spatial Gaussian distribution), a one standard deviational ellipse polygon will cover approximately 68 percent of the features, two standard deviations will cover approximately 95 percent of the features, and three standard deviations will cover approximately 99 percent of the features.
If the input data is z-enabled, the values in the output AngleZ, TiltX, and RollY fields are Euler angles and describe the orientation of the ellipsoid in 3D space. If the data is not z-enabled, the value in the output Rotation field represents the rotation of the long axis measured clockwise from noon.
The Calculate Geometry Attributes tool can be used to view the x, y, and z coordinates of the data.
The Case Field parameter is used to group features before analysis. When a Case Field parameter value is specified, the input features are first grouped according to case field values. Then, a standard deviational ellipse or ellipsoid is computed for each group. The case field can be of integer, date, or string type. Records with NULL values for the Case Field parameter value will be excluded from analysis.
The standard deviational ellipse or ellipsoid calculation can be based on the optional Weight Field parameter (to get the ellipses for traffic accidents weighted by severity, for example). The weight field should be numeric.
-
For line and polygon features, feature centroids are used in distance computations. For multipoints, polylines, or polygons with multiple parts, the centroid is computed using the weighted mean center of all feature parts. The weighting for point features is 1, for line features is length, and for polygon features is area.
-
Map layers can be used to define the Input Feature Class. When using a layer with a selection, only the selected features are included in the analysis.
Caution:
When using shapefiles, keep in mind that they cannot store null values. Tools or other procedures that create shapefiles from nonshapefile inputs may store or interpret null values as zero. In some cases, nulls are stored as very large negative values in shapefiles. This can lead to unexpected results. See Geoprocessing considerations for shapefile output for more information.
Parameters
arcpy.stats.DirectionalDistribution(Input_Feature_Class, Output_Ellipse_Feature_Class, Ellipse_Size, {Weight_Field}, {Case_Field})| Name | Explanation | Data Type |
Input_Feature_Class | A feature class containing a distribution of features for which the standard deviational ellipse or ellipsoid will be calculated. | Feature Layer |
Output_Ellipse_Feature_Class | A polygon feature class that will contain the output ellipse feature. | Feature Class |
Ellipse_Size | Specifies the size of the output ellipses in standard deviations.
| String |
Weight_Field (Optional) | The numeric field that will be used to weight locations according to their relative importance. | Field |
Case_Field (Optional) | The field that will be used to group features for separate directional distribution calculations. The case field can be of integer, date, or string type. | Field |
Code sample
The following Python window script demonstrates how to use the DirectionalDistribution function.
import arcpy
arcpy.env.workspace = r"C:\data"
arcpy.stats.DirectionalDistribution("AutoTheft.shp", "auto_theft_SE.shp",
"1_STANDARD_DEVIATION")The following stand-alone Python script demonstrates how to use the DirectionalDistribution function.
# Measure the geographic distribution of auto thefts.
# Import system modules
import arcpy
# Local variables...
workspace = "C:/data"
locations = "AutoTheft.shp"
links = "AutoTheft_links.shp"
standardDistance = "auto_theft_SD.shp"
stardardEllipse = "auto_theft_SE.shp"
linearDirectMean = "auto_theft_LDM.shp"
# Set the workspace (to avoid having to type in the full path to the data every
# time).
arcpy.env.workspace = workspace
# Process: Standard Distance of auto theft locations
arcpy.stats.StandardDistance(locations, standardDistance, "1_STANDARD_DEVIATION")
# Process: Directional Distribution (Standard Deviational Ellipse) of auto theft
# locations.
arcpy.stats.DirectionalDistribution(locations, standardEllipse,
"1_STANDARD_DEVIATION")
# Process: Linear Directional Mean of auto thefts.
arcpy.stats.DirectionalMean(links, linearDirectMean, "DIRECTION")Environments
Output Coordinate System, Geographic Transformations, Current Workspace, Scratch Workspace, Qualified Field Names, Output has M values, M Resolution, M Tolerance, Output has Z values, Default Output Z Value, Z Resolution, Z Tolerance, XY Resolution, XY Tolerance, Output Z Domain
Special cases
- Output Coordinate System
Feature geometry is projected to the Output Coordinate System prior to analysis. All mathematical computations are based on the Output Coordinate System spatial reference.
Licensing information
- Basic: Yes
- Standard: Yes
- Advanced: Yes