Directional Distribution (Standard Deviational Ellipse) (Spatial Statistics)—ArcGIS Pro

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

Directional Distribution (Standard Deviational Ellipse) graphic

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.
The Calculate 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.

Parameters

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	The size of output ellipses in standard deviations. The default ellipse size is 1; valid choices are 1, 2, or 3 standard deviations. 1 standard deviation—1 standard deviation 2 standard deviations—2 standard deviations 3 standard deviations—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

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	The size of output ellipses in standard deviations. The default ellipse size is 1; valid choices are 1, 2, or 3 standard deviations. 1_STANDARD_DEVIATION—1 standard deviation 2_STANDARD_DEVIATIONS—2 standard deviations 3_STANDARD_DEVIATIONS—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

DirectionalDistribution example (Python window)

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")

DirectionalDistribution example 2 (stand-alone script)

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, 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