Summary
Creates standard deviational ellipses or ellipsoids to summarize the spatial characteristics of geographic features: central tendency, dispersion, and directional trends.
Learn about how Directional Distribution (Standard Deviational Ellipse) works
Illustration
Usage
The Standard Deviational Ellipse tool creates a new Output Ellipse Feature Class containing elliptical polygons or 3D ellipsoidal multipatches, one for each case if the Case Field parameter is used. 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 fieldnames are CenterX, CenterY, XStdDist, YStdDist, and Rotation. If the input features are 3D points, the following additional fields are added to the Output Ellipse Feature Class: CenterZ, ZStdDist, AngleZ, TiltX, RollY, and Volume. When a Case Field is provided, this field is added to the Output Feature Class as well.
This tool honors the 3D nature of your 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. Be sure that you are running the analysis in a Scene, or copy the result layer into a Scene for correct visualization of your 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 Rayleigh distribution), a one standard deviational ellipse polygon will cover approximately 63 percent of the features; two standard deviations will contain approximately 98 percent of the features; and three standard deviations will cover approximately 99 percent of the features in two dimensions. In three dimensions, a 61-99-100 percentage rule will result.
If your 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 your data is not z-enabled, the value in the output Rotation field represents the rotation of the long axis measured clockwise from noon.
If your data is z-enabled, the Add Geometry Attributes tool can be used to view the x, y, and z coordinates of your data.
The Case Field parameter is used to group features prior to analysis. When a Case Field 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 will be excluded from analysis.
The standard deviational ellipse or ellipsoid calculation can be based on an 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.
Syntax
arcpy.stats.DirectionalDistribution(Input_Feature_Class, Output_Ellipse_Feature_Class, Ellipse_Size, {Weight_Field}, {Case_Field})| Parameter | 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 | The size of output ellipses in standard deviations. The default ellipse size is 1; valid choices are 1, 2, or 3 standard deviations.
| String |
Weight_Field (Optional) | The numeric field used to weight locations according to their relative importance. | Field |
Case_Field (Optional) | The field 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 tool.
import arcpy
arcpy.env.workspace = r"C:\data"
arcpy.DirectionalDistribution_stats("AutoTheft.shp", "auto_theft_SE.shp", "1_STANDARD_DEVIATION")The following stand-alone Python script demonstrates how to use the DirectionalDistribution tool.
# 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.StandardDistance_stats(locations, standardDistance, "1_STANDARD_DEVIATION", "#", "#")
# Process: Directional Distribution (Standard Deviational Ellipse) of auto theft locations...
arcpy.DirectionalDistribution_stats(locations, standardEllipse, "1_STANDARD_DEVIATION", "#", "#")
# Process: Linear Directional Mean of auto thefts...
arcpy.DirectionalMean_stats(links, linearDirectMean, "DIRECTION", "#")Environments
- 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