Generate Origin-Destination Links (Analysis)

Summary

Generates connecting lines from origin features to destination features. This is often referred to as a spider diagram.

Illustration

Usage

• When the origin or destination features are lines or polygons, the feature centroids are used for generating links.

• The output features will include the following attribute fields:

  • ORIG_FID—The ObjectID field of the origin feature.
  • ORIG_X—The x-coordinate of the origin feature (or centroid).
  • ORIG_Y—The y-coordinate of the origin feature (or centroid).
  • DEST_FID—The ObjectID field of the destination feature.
  • DEST_X—The x-coordinate of the destination feature (or centroid).
  • DEST_Y—The y-coordinate of the destination feature (or centroid).
  • LINK_DIST—The length of the output link, measured in the specified distance unit.
  • GROUP_ID—The group field values that are shared between linked pairs of origin and destination features. This field will only be added if both origin and destination group fields are specified.
  • COLOR_ID—A numeric value that is used to symbolize origins or groups into at most eight unique colored links. The values are random numbers between 1 and 8.
  • LINK_COUNT—The number of overlapping links. This is added when you specify to aggregate overlapping links.
  • Any statistics fields specified when aggregating overlapping links will also be added to the output feature class.

• The origin features and destination features can be specified as the same layer or dataset. If the same data is used for origins and destinations, links will not be generated from an origin to the destination feature with the same Object ID, as this zero-length line is a null geometry error.

• This tool can be used for both one-to-one and one-to-many relationships. For example, you can link a motor vehicle theft to its recovery location (one-to-one), or perform a proximity analysis to understand the distances between a central headquarters location to several regional office locations (one-to-many).

• The output links layer will include the following charts to help you visualize the result of the analysis:

  • A bar chart of the count of each group ID, if you specified group fields.
  • A bar chart of the sum of link lengths for each origin ID or group ID (if you specified group fields). This is useful to see if some origins or groups have large or small total distances to destinations.
  • A bar chart of the mean link lengths for each origin ID or group ID (if you specified group fields). This is useful to see the average distance between origin features or groups and their linked destinations.
  • A box plot of the distribution of link lengths for each origin ID or group ID (if you specified group fields). This is useful to see if most of the links for an origin or group have small or large lengths to their destinations, and the range and distribution summary of those link lengths. If an origin ID or group ID has a vertically short box, it means the distances from that origin or group to all linked destinations were similar. If an origin ID or group ID has a box that is located high on the y-axis, most of the links have a long length.

Parameters

Dialog

Label	Explanation	Data Type
Origin Features	The input features from which links will be generated.	Feature Layer
Destination Features	The destination features to which links will be generated.	Feature Layer
Output Feature Class	The output polyline feature class that will contain the output links.	Feature Class
Origin Group Field (Optional)	The attribute field from the input origin features that will be used for grouping. Features that have the same group field value between origins and destinations will be connected with a link.	Field
Destination Group Field (Optional)	The attribute field from the input destination features that will be used for grouping. Features that have the same group field value between origins and destinations will be connected with a link.	Field
Line Type (Optional)	Specifies whether a shortest path on a spheroid (geodesic) or a Cartesian projected earth (planar) will be used when generating the output links. Geodesic lines will have a slight curve when their length exceeds approximately 50 kilometers, as the curvature of the Earth makes the shortest distance between two points appear curved when viewed on a 2D map. It is recommended that you use the Geodesic line type with data stored in a coordinate system that is not appropriate for distance measurements (for example, Web Mercator and any geographic coordinate system) or any dataset that spans a large geographic area. Planar—Planar distance will be used between features. This is the default. Geodesic—Geodesic distances will be used between features. This line type takes into account the curvature of the spheroid and correctly deals with data near the dateline and poles.	String
Number of Nearest Destinations (Optional)	The maximum number of links that will be generated per origin feature to the nearest destination features. If no number is specified, the tool will generate links between all origin and destination features. For example, using a value of 1 will generate links between each origin feature and its closest destination feature.	Double
Search Distance (Optional)	The maximum distance between an origin and destination feature that will produce a link feature in the output. The unit of the search distance is specified in the distance unit parameter. If no search distance is specified, the tool will generate links between all origin and destination features regardless of their distance apart.	Double
Distance Unit	Specifies the units used to measure the length of the links. Distances for each link will appear in the LINK_DIST field. If a distance unit is not specified, the distance unit of the origin features' coordinate system will be used. Kilometers—The distance between origin and destination will be calculated in kilometers. Meters—The distance between origin and destination will be calculated in meters. Miles—The distance between origin and destination will be calculated in miles. Nautical miles—The distance between origin and destination will be calculated in nautical miles. Yards—The distance between origin and destination will be calculated in yards. Feet—The distance between origin and destination will be calculated in feet.	String
Aggregate Overlapping Links (Optional)	Specifies whether overlapping links will be aggregated. Checked—Overlapping links will be aggregated if the starting point coordinates are the same. Unchecked—Overlapping links will not be aggregated. This is the default.	Boolean
Summary Fields (Optional)	Specifies the numeric field or fields containing the attribute values that will be used to calculate the specified statistic. Multiple statistic and field combinations can be specified. Null values are excluded from all calculations. Text attribute fields can be summarized using first and last statistics. Numeric attribute fields can be summarized using any statistic. Available statistics types are as follows: Sum—The values for the specified field will be added together. Mean—The average for the specified field will be calculated. Minimum—The smallest value for all records of the specified field will be found. Maximum—The largest value for all records of the specified field will be found. Range—The range of values (maximum minus minimum) for the specified field will be calculated. Standard deviation—The standard deviation of values in the specified field will be calculated. Count—The number of values included in the statistical calculations will be found. Each value will be counted except null values. To determine the number of null values in a field, create a count on the field in question, create a count on a different field that does not contain null values (for example, the OID if present), and subtract the two values. First—The specified field value of the first record in the input will be used. Last—The specified field value of the last record in the input will be used. Median—The median for all records of the specified field will be calculated. Variance—The variance for all records of the specified field will be calculated. Unique—The number of unique values of the specified field will be counted.	Value Table

Python

arcpy.analysis.GenerateOriginDestinationLinks(origin_features, destination_features, out_feature_class, {origin_group_field}, {destination_group_field}, {line_type}, {num_nearest}, {search_distance}, distance_unit, {aggregate_links}, {sum_fields})

Name	Explanation	Data Type
origin_features	The input features from which links will be generated.	Feature Layer
destination_features	The destination features to which links will be generated.	Feature Layer
out_feature_class	The output polyline feature class that will contain the output links.	Feature Class
origin_group_field (Optional)	The attribute field from the input origin features that will be used for grouping. Features that have the same group field value between origins and destinations will be connected with a link.	Field
destination_group_field (Optional)	The attribute field from the input destination features that will be used for grouping. Features that have the same group field value between origins and destinations will be connected with a link.	Field
line_type (Optional)	Specifies whether a shortest path on a spheroid (geodesic) or a Cartesian projected earth (planar) will be used when generating the output links. Geodesic lines will have a slight curve when their length exceeds approximately 50 kilometers, as the curvature of the Earth makes the shortest distance between two points appear curved when viewed on a 2D map. It is recommended that you use the GEODESIC line type with data stored in a coordinate system that is not appropriate for distance measurements (for example, Web Mercator and any geographic coordinate system) or any dataset that spans a large geographic area. PLANAR—Planar distance will be used between features. This is the default. GEODESIC—Geodesic distances will be used between features. This line type takes into account the curvature of the spheroid and correctly deals with data near the dateline and poles.	String
num_nearest (Optional)	The maximum number of links that will be generated per origin feature to the nearest destination features. If no number is specified, the tool will generate links between all origin and destination features. For example, using a value of 1 will generate links between each origin feature and its closest destination feature.	Double
search_distance (Optional)	The maximum distance between an origin and destination feature that will produce a link feature in the output. The unit of the search distance is specified in the distance unit parameter. If no search distance is specified, the tool will generate links between all origin and destination features regardless of their distance apart.	Double
distance_unit	Specifies the units used to measure the length of the links. Distances for each link will appear in the LINK_DIST field. If a distance unit is not specified, the distance unit of the origin features' coordinate system will be used. KILOMETERS—The distance between origin and destination will be calculated in kilometers. METERS—The distance between origin and destination will be calculated in meters. MILES—The distance between origin and destination will be calculated in miles. NAUTICALMILES—The distance between origin and destination will be calculated in nautical miles. YARDS—The distance between origin and destination will be calculated in yards. FEET—The distance between origin and destination will be calculated in feet.	String
aggregate_links (Optional)	Specifies whether overlapping links will be aggregated. AGGREGATE_OVERLAPPING—Overlapping links will be aggregated if the starting point coordinates are the same. NO_AGGREGATE—Overlapping links will not be aggregated. This is the default.	Boolean
sum_fields [sum_fields,...] (Optional)	Specifies the numeric field or fields containing the attribute values that will be used to calculate the specified statistic. Multiple statistic and field combinations can be specified. Null values are excluded from all calculations. Text attribute fields can be summarized using first and last statistics. Numeric attribute fields can be summarized using any statistic. Available statistics types are as follows: SUM—The values for the specified field will be added together. MEAN—The average for the specified field will be calculated. MIN—The smallest value for all records of the specified field will be found. MAX—The largest value for all records of the specified field will be found. RANGE—The range of values (maximum minus minimum) for the specified field will be calculated. STD—The standard deviation of values in the specified field will be calculated. COUNT—The number of values included in the statistical calculations will be found. Each value will be counted except null values. To determine the number of null values in a field, create a count on the field in question, create a count on a different field that does not contain null values (for example, the OID if present), and subtract the two values. FIRST—The specified field value of the first record in the input will be used. LAST—The specified field value of thee last record in the input will be used. MEDIAN—The median for all records of the specified field will be calculated. VARIANCE—The variance for all records of the specified field will be calculated. UNIQUE—The number of unique values of the specified field will be counted.	Value Table

Code sample

GenerateOriginDestinationLinks example 1 (Python window)

The following demonstrates how to use the GenerateOriginDestinationLinks function in the Python window:

import arcpy
arcpy.env.workspace = "C:/data/input/genODLinks.gdb"

arcpy.analysis.GenerateOriginDestinationLinks(
    "Station_100", "City_FireResponses", "Station_100_OD_Links")

GenerateOriginDestinationLinks example 2 (stand-alone script)

The following Python script demonstrates how to use the GenerateOriginDestinationLinks function in a stand-alone script:

# Name: GenerateODLinks.py
# Description: Finds 10 nearest links within 25 miles from the origin fire
#              stations to the destination response points.

# import system modules
import arcpy

# set workspace environment
arcpy.env.workspace = "C:/data/input/genODLinks.gdb"

# set required parameters 
origin_features = "Station_100"
destination_features = "City_FireResponses"
out_feature_class = "Station_100_OD_Links"

# optional parameters
origin_group_field = 'STA_NUM'
destination_group_field = 'District'
line_type = 'PLANAR'
num_nearest = 10
search_distance = 25
distance_unit = 'MILES'
aggregate_links='AGGREGATE_OVERLAPPING'
sum_fields = 'TimeSpentOnCall SUM'

# make links between fire stations and call response points
arcpy.analysis.GenerateOriginDestinationLinks(
    origin_features, destination_features, out_feature_class,
    origin_group_field, destination_group_field, line_type, num_nearest,
    search_distance, distance_unit, aggregate_links, sum_fields)

Environments

Current Workspace, Scratch Workspace, Extent

Licensing information

• Basic: Yes
• Standard: Yes
• Advanced: Yes