OriginDestinationCostMatrixResult

Summary

An object containing the results of an origin destination cost matrix analysis that can be used to access outputs and solver messages.

Discussion

Instances of this class cannot be created directly. Instead, they are returned by the solve method of the OriginDestinationCostMatrix class.

Learn more about how to use the result object to access and work with the analysis outputs

Properties

Name	Explanation	Data type
isPartialSolution (Read only)	Returns `True` if the solver produced a partial solution, meaning that not all inputs were included in the results. This can occur if one of the inputs is unlocated and the solver class's `ignoreInvalidLocations` property is set to `True`.	Boolean
solveSucceeded (Read only)	Returns `True` if the solve was successful.	Boolean
spatialReference (Read only)	Returns the spatial reference of the output features. For example, feature classes created using the `export` method and geometry objects retrieved from the `searchCursor` method will have this spatial reference. The `spatialReference` value is typically the spatial reference of the network dataset or service used in the analysis.	SpatialReference

Methods

`count(output_type)`

Returns the number of rows for an output type.

Raises no exception.

Name Explanation Data type

Name	Explanation	Data type
output_type	The type of output features to count. Set this parameter using the `OriginDestinationCostMatrixOutputDataType` enumeration.	Object

output_type

The type of output features to count.

Set this parameter using the OriginDestinationCostMatrixOutputDataType enumeration.

Object

Return value

Data type	Explanation
Integer	The number of rows.

`export(output_type, output_features)`

Exports the analysis results to a feature class or table.

The output features will be created in the spatial reference of the network dataset used for the analysis. If the arcpy.env.outputCoordinateSystem environment is set, the output features will be created with the specified coordinate system instead.

Name Explanation Data type

Name	Explanation	Data type
output_type	The type of output to export. Set this parameter using the `OriginDestinationCostMatrixOutputDataType` enumeration. Learn more about the fields included in each output type	Object
output_features	The catalog path to the output feature class or table that will contain the exported features.	String

output_type

The type of output to export.

Set this parameter using the OriginDestinationCostMatrixOutputDataType enumeration.

Learn more about the fields included in each output type

Object

output_features

The catalog path to the output feature class or table that will contain the exported features.

String

`extent({output_type})`

Returns the extent of the analysis output.

The method returns a RuntimeError exception if the analysis solve failed.

Name Explanation Data type

Name	Explanation	Data type
output_type (Optional)	The type of output features for which to get the extent. Set this parameter using the `OriginDestinationCostMatrixOutputDataType` enumeration. If you do not specify a value, or you specify a value of `None`, the extent for the combined analysis outputs is returned.	Object

output_type

(Optional)

The type of output features for which to get the extent.

Set this parameter using the OriginDestinationCostMatrixOutputDataType enumeration.

If you do not specify a value, or you specify a value of None, the extent for the combined analysis outputs is returned.

Object

Return value

Data type	Explanation
Extent	An `arcpy.Extent` object indicating the extent of the designated output type.

`fieldNames(output_type)`

Returns a list of field names supported by a specified output type.

Name Explanation Data type

Name	Explanation	Data type
output_type	The type of output for which to return a list of field names. Set this parameter using the `OriginDestinationCostMatrixOutputDataType` enumeration. Learn more about the fields included in each output type	Object

output_type

The type of output for which to return a list of field names.

Set this parameter using the OriginDestinationCostMatrixOutputDataType enumeration.

Learn more about the fields included in each output type

Object

Return value

Data type	Explanation
String	A list of field names supported by the specified output type.

`saveAsLayerFile(file_name)`

Save the analysis result and settings to a network analysis layer file or package. The layer file or package can be opened in ArcGIS Pro as a record of the analysis settings or to visualize the results.

The method returns a RuntimeError exception if the allowSaveLayerFile property on the solver object is set to False.

Legacy:

Routing services based on portals running versions of ArcGIS Enterprise older than 10.9 do not support saving layer packages. The method returns a RuntimeError exception if this is the case.

Name	Explanation	Data type
file_name	The catalog path of the output layer file (`.lyr`) or layer package (`.lpkx`) to write. Caution: Layer files with an `.lyr` extension cannot be saved if the solver object uses a service URL as its network data source. The method returns a `RuntimeError` exception in this case.	String

`searchCursor(output_type, field_names[field_names,...], {where_clause})`

Establishes a search cursor on the specified output type. This cursor can be used to read rows directly from the output.

Name Explanation Data type

Name	Explanation	Data type
output_type	The type of output that will be read. Set this parameter using the `OriginDestinationCostMatrixOutputDataType` enumeration.	Object
field_names[field_names,...]	A list of field names of the output type whose values will be returned by the cursor. You can get the names of the fields supported by an output type using the `fieldNames` method. Learn more about the fields included in each output type In addition to regular fields, you can also access the geometry of the output using one of the following geometry tokens: SHAPE@XY—A tuple of the feature's centroid's x- and y-coordinates. SHAPE@XYZ—A tuple of the feature's centroid's x-, y-, and z-coordinates. SHAPE@JSON—The Esri JSON string representing the geometry. SHAPE@WKB—The well-known binary (WKB) representation for OGC geometry. It provides a portable representation of a geometry value as a contiguous stream of bytes. SHAPE@WKT—The well-known text (WKT) representation for OGC geometry. It provides a portable representation of a geometry value as a text string. SHAPE@—A geometry object for the feature. The `SHAPE@XY` and `SHAPE@XYZ` tokens are only supported for point-based output types. The x-, y-, and z-values returned when using the `SHAPE@XY` and `SHAPE@XYZ` tokens are in the spatial reference reported by the solver result object's `spatialReference` property, and this is typically the same as the spatial reference of the network data source used for the analysis. Tip: Retrieving geometry for the `Lines` output type can be slow. For best performance, do not request geometry using any of the geometry tokens.	String
where_clause (Optional)	An optional expression that limits the records returned. For more information on WHERE clauses and SQL statements, see SQL reference for query expressions used in ArcGIS. The default value is None.	String

output_type

The type of output that will be read.

Set this parameter using the OriginDestinationCostMatrixOutputDataType enumeration.

Object

field_names[field_names,...]

A list of field names of the output type whose values will be returned by the cursor. You can get the names of the fields supported by an output type using the fieldNames method.

Learn more about the fields included in each output type

In addition to regular fields, you can also access the geometry of the output using one of the following geometry tokens:

SHAPE@XY—A tuple of the feature's centroid's x- and y-coordinates.
SHAPE@XYZ—A tuple of the feature's centroid's x-, y-, and z-coordinates.
SHAPE@JSON—The Esri JSON string representing the geometry.
SHAPE@WKB—The well-known binary (WKB) representation for OGC geometry. It provides a portable representation of a geometry value as a contiguous stream of bytes.
SHAPE@WKT—The well-known text (WKT) representation for OGC geometry. It provides a portable representation of a geometry value as a text string.
SHAPE@—A geometry object for the feature.

The SHAPE@XY and SHAPE@XYZ tokens are only supported for point-based output types. The x-, y-, and z-values returned when using the SHAPE@XY and SHAPE@XYZ tokens are in the spatial reference reported by the solver result object's spatialReference property, and this is typically the same as the spatial reference of the network data source used for the analysis.

Tip:

Retrieving geometry for the Lines output type can be slow. For best performance, do not request geometry using any of the geometry tokens.

String

where_clause

(Optional)

An optional expression that limits the records returned. For more information on WHERE clauses and SQL statements, see SQL reference for query expressions used in ArcGIS.

The default value is None.

String

Return value

Data type	Explanation
Object	A `SolverResultSearchCursor` object that reads rows from the output.

`solverMessages(severity)`

Get error, warning, and informational messages returned by the solver.

Name Explanation Data type

Name	Explanation	Data type
severity	The type of messages to be returned. The parameter should be specified using the `MessageSeverity` enumeration.	Object

severity

The type of messages to be returned.

The parameter should be specified using the MessageSeverity enumeration.

Object

Return value

Data type Explanation

Data type	Explanation
List	The messages are returned as a list of lists. The inner list contains two values; the first is a number representing the message code, and the second value is the message text. An example of a list of messages returned from a failed origin destination cost matrix analysis. `[[-2147200995, '0 location(s) in "Destinations" are valid. Need at least 1 valid location(s).'], [30024, 'Solve returned a failure.'], [-2147200995, 'Insufficient number of valid locations in "Origins" or "Destinations".']]`

List

The messages are returned as a list of lists. The inner list contains two values; the first is a number representing the message code, and the second value is the message text.

An example of a list of messages returned from a failed origin destination cost matrix analysis.

[[-2147200995, '0 location(s) in "Destinations" are valid.  Need at least 1 valid location(s).'],
 [30024, 'Solve returned a failure.'],
 [-2147200995, 'Insufficient number of valid locations in "Origins" or "Destinations".']]

`toArrowTable(output_type, field_names[field_names,...], {file_name}, {max_batch_size})`

Returns the OD Cost Matrix result in Apache Arrow format.

Note:

Arrow output is not available if the solver object uses a service URL as its network data source. The method returns a RuntimeError exception in this case.

Learn more about how to use this method and see examples

Name	Explanation	Data type
output_type	The type of output that will be read. Set this parameter using the `OriginDestinationCostMatrixOutputDataType` enumeration. Caution: Only the `Lines` output type is currently supported. The method returns a `RuntimeError` exception if a different output type is specified.	Object
field_names[field_names,...]	A list of field names of the output type to include in the Arrow table. Learn more about the fields included in each output type Caution: For the `Lines` output type, the `Shape`, `OriginName`, and `DestinationName` fields are not supported.	String
file_name (Optional)	The file path to use to save the analysis results permanently. The file will contain one or more Arrow record batches and can be opened in any package or library that supports the Arrow format. This parameter is optional. If it is not specified, the Arrow table returned by the method can be used within the current Python operation but will not be stored permanently.	String
max_batch_size (Optional)	The maximum number of records to include in a single record batch in the output Arrow table. When no value or `None` is specified, a value of 2,147,483,647 is used. If the total number of records is smaller than the specified `max_batch_size`, the output Arrow table and file will contain only one record batch. For very large analyses, writing the output in batches prevents out-of-memory errors. The method always returns a single Arrow table and output file (if the `file_name` parameter is specified), but the presence of multiple record batches in the output may influence how you handle it in subsequent code. When an Arrow table or file containing multiple record batches is converted to another format, such as a Pandas DataFrame, you may not be able to do a zero-copy read of the entire table or file. In a zero-copy read, the data can be accessed without additional serialization overhead to load it in RAM. To achieve this zero-copy read behavior, your code may need to handle one record batch at a time. For the `Lines` output type, for most applications, it is important to keep all records associated with the same origin together in the same batch. This ensures that you can do a zero-copy read of all records for that origin for post-processing or further analysis. If the number of records associated with a given origin exceeds the specified `max_batch_size`, the method will override the `max_batch_size` value, and the resulting record batches will increase to the minimum size needed to store all records associated with the origin. The value for `max_batch_size` cannot exceed 2,147,483,647.	Integer

Return value

Data type	Explanation
Object	An Apache Arrow Table Python object representing the desired output type with the specified fields.

OriginDestinationCostMatrixResult

Summary

Discussion

Properties

Methods

count(output_type)

Return value

export(output_type, output_features)

extent({output_type})

Return value

fieldNames(output_type)

Return value

saveAsLayerFile(file_name)

Legacy:

Caution:

searchCursor(output_type, field_names[field_names,...], {where_clause})

Tip:

Return value

solverMessages(severity)

Return value

toArrowTable(output_type, field_names[field_names,...], {file_name}, {max_batch_size})

Note:

Caution:

Caution:

Return value

`count(output_type)`

`export(output_type, output_features)`

`extent({output_type})`

`fieldNames(output_type)`

`saveAsLayerFile(file_name)`

`searchCursor(output_type, field_names[field_names,...], {where_clause})`

`solverMessages(severity)`

`toArrowTable(output_type, field_names[field_names,...], {file_name}, {max_batch_size})`