创建 OD 成本矩阵分析图层 (Network Analyst)

摘要

创建起始-目的地 (OD) 成本矩阵网络分析图层并设置其分析属性。 OD 成本矩阵分析图层对于描述从一组起始位置到一组目的地位置的成本矩阵十分有用。 该图层可通过本地网络数据集进行创建,也可通过在线托管服务或门户托管服务进行创建。

使用情况

  • 通过此工具创建分析图层后,您可以使用添加位置工具向图层中添加网络分析对象;使用求解工具来求解分析;以及使用保存至图层文件工具将结果保存到磁盘中。

  • 在地理处理模型中使用此工具时,如果模型作为工具来运行,则必须将输出网络分析图层创建为模型参数;否则,输出图层将无法添加到地图内容中。

  • ArcGIS AllSource 中,网络分析图层数据存储在文件地理数据库要素类中的磁盘上。 在工程中创建网络分析图层时,将在当前工作空间环境的新要素数据集中创建图层数据。 在 Python 脚本中创建网络分析图层时,您必须首先使用 arcpy.env.workspace = "<path to file gdb>" 将工作空间环境显式地设置到想要存储图层数据的文件地理数据库。 创建图层后,将向该文件地理数据库添加一个包含相应子图层要素类的新要素数据集。

参数

标注说明数据类型
网络数据源

将对其执行网络分析的网络数据集或服务。 将门户 URL 用于服务。

Network Dataset Layer;String
图层名称
(可选)

要创建的网络分析图层的名称。

String
出行模式
(可选)

分析中使用的出行模式名称。 出行模式为一组网络设置(例如行驶限制和 U 形转弯),用于确定行人、车辆、卡车或其他交通媒介在网络中的移动方式。 出行模式在网络数据源中进行定义。

arcpy.na.TravelMode 对象和包含出行模式有效 JSON 表示的字符串也可用作参数的输入。

String
中断
(可选)

停止为指定起始点搜索目的地时所对应的阻抗值。 该值将以所选出行模式使用的阻抗属性为单位。 无法找到超过此限制的目的地。 可通过在起始点子图层中指定单个中断值来逐个起始点覆盖中断值。 默认情况下分析不使用中断。

Double
要查找的目的地数
(可选)

要为每个起始点查找的目的地数。 可通过为起始点子图层的 TargetDestinationCount 属性指定一个值来覆盖此默认值。 默认情况下无任何限制,可找到所有目的地。

Long
时间
(可选)

从起始点出发的时间。

如果您选择基于流量的阻抗属性,将会根据特定的某天某时的动态交通状况来生成解决方案。 日期和时间可被指定为 5/14/2012 10:30 AM。

将您的分析配置为使用以下特殊日期之一来模拟一周中的某天或当前日期,而不是特定的静态日期:

  • 今天 - 12/30/1899
  • 星期日 - 12/31/1899
  • 星期一 - 1/1/1900
  • 星期二 - 1/2/1900
  • 星期三 - 1/3/1900
  • 星期四 - 1/4/1900
  • 星期五 - 1/5/1900
  • 星期六 - 1/6/1900

了解如何在网络分析中使用和解释日期和时间的详细细腻

Date
时区
(可选)

时间参数的时区。

  • 各位置的本地时间时间参数是指起始点所处的时区。 这是默认设置。
  • UTC时间参数是指协调世界时间 (UTC)。 如果您想要在指定时间内(如现在)计算 OD 成本矩阵,但不确定起始点所在的时区,请选择此选项。
String
线状
(可选)

指定输出线形状。

无论选择何种输出 shape 类型,最佳路径始终由网络阻抗(而非欧氏距离)决定。 这表示只是路径形状不同,而对网络进行的基础遍历则相同。

  • 无线将不会为输出起始点-目的地路径对生成任何形状。 适用于存在大量起始点和目的地,但仅对 OD 成本矩阵表中的阻抗成本(而不是查看地图中的 OD 成本矩阵)感兴趣的情况。
  • 直线输出路径形状是介于各个起始点-目的地对之间的直线(单线)。 这是默认设置。
String
累积属性
(可选)

分析过程中要累积的成本属性的列表。 这些累积属性仅供参考;求解程序仅使用求解分析时指定的出行模式所使用的成本属性。

对于每个累积的成本属性,会在网络分析输出要素中填充 Total_[阻抗] 属性。

如果网络数据源为 ArcGIS Online 服务,或如果网络数据源是不支持累积的 Portal for ArcGIS 版本上的服务,则此参数不可用。

String
忽略求解时无效的位置
(可选)

指定是否忽略无效的输入位置。 通常,如果无法在网络上定位,则位置无效。 当无效位置被忽略时,求解器将跳过它们并尝试使用剩余位置执行分析。

  • 选中 - 将忽略无效的输入位置,并且仅使用有效的位置。 这是默认设置。
  • 未选中 - 将使用所有输入位置。 无效的位置将导致分析失败。
Boolean

派生输出

标注说明数据类型
网络分析图层

新创建的网络分析图层。

Network Analyst Layer

arcpy.management.MakeODCostMatrixAnalysisLayer(network_data_source, {layer_name}, {travel_mode}, {cutoff}, {number_of_destinations_to_find}, {time_of_day}, {time_zone}, {line_shape}, {accumulate_attributes}, {ignore_invalid_locations})
名称说明数据类型
network_data_source

将对其执行网络分析的网络数据集或服务。 将门户 URL 用于服务。

Network Dataset Layer;String
layer_name
(可选)

要创建的网络分析图层的名称。

String
travel_mode
(可选)

分析中使用的出行模式名称。 出行模式为一组网络设置(例如行驶限制和 U 形转弯),用于确定行人、车辆、卡车或其他交通媒介在网络中的移动方式。 出行模式在网络数据源中进行定义。

arcpy.na.TravelMode 对象和包含出行模式有效 JSON 表示的字符串也可用作参数的输入。

String
cutoff
(可选)

停止为指定起始点搜索目的地时所对应的阻抗值。 该值将以所选出行模式使用的阻抗属性为单位。 无法找到超过此限制的目的地。 可通过在起始点子图层中指定单个中断值来逐个起始点覆盖中断值。 默认情况下分析不使用中断。

Double
number_of_destinations_to_find
(可选)

要为每个起始点查找的目的地数。 可通过为起始点子图层的 TargetDestinationCount 属性指定一个值来覆盖此默认值。 默认情况下无任何限制,可找到所有目的地。

Long
time_of_day
(可选)

从起始点出发的时间。

如果您选择基于流量的阻抗属性,将会根据特定的某天某时的动态交通状况来生成解决方案。 日期和时间可被指定为 5/14/2012 10:30 AM。

将您的分析配置为使用以下特殊日期之一来模拟一周中的某天或当前日期,而不是特定的静态日期:

  • 今天 - 12/30/1899
  • 星期日 - 12/31/1899
  • 星期一 - 1/1/1900
  • 星期二 - 1/2/1900
  • 星期三 - 1/3/1900
  • 星期四 - 1/4/1900
  • 星期五 - 1/5/1900
  • 星期六 - 1/6/1900

了解如何在网络分析中使用和解释日期和时间的详细细腻

Date
time_zone
(可选)

时间参数的时区。

  • LOCAL_TIME_AT_LOCATIONS时间参数是指起始点所处的时区。 这是默认设置。
  • UTC时间参数是指协调世界时间 (UTC)。 如果您想要在指定时间内(如现在)计算 OD 成本矩阵,但不确定起始点所在的时区,请选择此选项。
String
line_shape
(可选)

指定输出线形状。

  • NO_LINES将不会为输出起始点-目的地路径对生成任何形状。 适用于存在大量起始点和目的地,但仅对 OD 成本矩阵表中的阻抗成本(而不是查看地图中的 OD 成本矩阵)感兴趣的情况。
  • STRAIGHT_LINES输出路径形状是介于各个起始点-目的地对之间的直线(单线)。 这是默认设置。

无论选择何种输出 shape 类型,最佳路径始终由网络阻抗(而非欧氏距离)决定。 这表示只是路径形状不同,而对网络进行的基础遍历则相同。

String
accumulate_attributes
[accumulate_attributes,...]
(可选)

分析过程中要累积的成本属性的列表。 这些累积属性仅供参考;求解程序仅使用求解分析时指定的出行模式所使用的成本属性。

对于每个累积的成本属性,会在网络分析输出要素中填充 Total_[阻抗] 属性。

如果网络数据源为 ArcGIS Online 服务,或如果网络数据源是不支持累积的 Portal for ArcGIS 版本上的服务,则此参数不可用。

String
ignore_invalid_locations
(可选)

指定是否忽略无效的输入位置。 通常,如果无法在网络上定位,则位置无效。 当无效位置被忽略时,求解器将跳过它们并尝试使用剩余位置执行分析。

  • SKIP无效的输入位置将被忽略,只使用有效的位置。 这是默认设置。
  • HALT将使用所有输入位置。 无效的位置将导致分析失败。
Boolean

派生输出

名称说明数据类型
out_network_analysis_layer

新创建的网络分析图层。

Network Analyst Layer

代码示例

MakeODCostMatrixAnalysisLayer 示例 1(Python 窗口)

仅使用必需参数运行此工具。

network = "C:/Data/Paris.gdb/Transportation/ParisMultimodal_ND"
arcpy.na.MakeODCostMatrixAnalysisLayer(network, "DrivetimeCosts")
MakeODCostMatrixAnalysisLayer 示例 2(Python 窗口)

使用所有参数运行此工具

network = "C:/Data/Paris.gdb/Transportation/ParisMultimodal_ND"
arcpy.na.MakeODCostMatrixAnalysisLayer(network, "DrivetimeCosts", 
                                "Driving Time", 10, 20, "1/1/1900 9:00 AM",
                                "UTC", "NO_LINES", ["Meters", "DriveTime"])
MakeODCostMatrixAnalysisLayer 示例 3(工作流)

以下独立 Python 脚本演示了如何使用 MakeODCostMatrixAnalysisLayer 函数创建起始-目的地成本矩阵,用于将货物从仓库交付给距离仓库十分钟行程范围内的所有商店。

# Name: MakeODCostMatrixAnalysisLayer_Workflow.py
# Description: Create an origin-destination cost matrix for delivery of goods
#              from the warehouses to all stores within a 10-minute drive time
#              and save the results to a layer file on disk. Such a matrix can
#              be used as an input for logistics, delivery and routing analyses.
# Requirements: Network Analyst Extension

#Import system modules
import arcpy
from arcpy import env
import os

try:
    #Check out Network Analyst license if available. Fail if the Network Analyst license is not available.
    if arcpy.CheckExtension("network") == "Available":
        arcpy.CheckOutExtension("network")
    else:
        raise arcpy.ExecuteError("Network Analyst Extension license is not available.")
    
    #Set environment settings
    output_dir = "C:/Data"
    #The NA layer's data will be saved to the workspace specified here
    env.workspace = os.path.join(output_dir, "Output.gdb")
    env.overwriteOutput = True

    #Set local variables
    input_gdb = "C:/Data/Paris.gdb"
    network = os.path.join(input_gdb, "Transportation", "ParisMultimodal_ND")
    layer_name = "WarehouseToStoreDrivetimeMatrix"
    travel_mode = "Driving Time"
    search_tolerance = "1000 Meters"
    origins = os.path.join(input_gdb, "Analysis", "Warehouses")
    destinations = os.path.join(input_gdb, "Analysis", "Stores")
    output_layer_file = os.path.join(output_dir, layer_name + ".lyrx")

    #Create a new OD Cost matrix layer. We wish to find all stores within a 10
    #minute cutoff.
    result_object = arcpy.na.MakeODCostMatrixAnalysisLayer(network, layer_name,
                                                travel_mode, 10)

    #Get the layer object from the result object. The OD cost matrix layer can
    #now be referenced using the layer object.
    layer_object = result_object.getOutput(0)

    #Get the names of all the sublayers within the OD cost matrix layer.
    sublayer_names = arcpy.na.GetNAClassNames(layer_object)
    #Stores the layer names that we will use later
    origins_layer_name = sublayer_names["Origins"]
    destinations_layer_name = sublayer_names["Destinations"]

    #Load the warehouse locations as origins using a default field mappings and
    #a search tolerance of 1000 Meters.
    arcpy.na.AddLocations(layer_object, origins_layer_name, origins, "",
                          search_tolerance)

    #Load the store locations as destinations and map the NOM field from stores
    #features as Name property using field mappings
    field_mappings = arcpy.na.NAClassFieldMappings(layer_object,
                                                        destinations_layer_name)
    field_mappings["Name"].mappedFieldName = "NOM"
    arcpy.na.AddLocations(layer_object, destinations_layer_name, destinations,
                          field_mappings, search_tolerance)

    #Solve the OD cost matrix layer
    arcpy.na.Solve(layer_object)

    #Save the solved OD cost matrix layer as a layer file on disk
    layer_object.saveACopy(output_layer_file)

    print("Script completed successfully")

except Exception as e:
    # If an error occurred, print line number and error message
    import traceback, sys
    tb = sys.exc_info()[2]
    print("An error occurred on line %i" % tb.tb_lineno)
    print(str(e))
MakeODCostMatrixAnalysisLayer 示例 4(工作流)

下面的独立 Python 脚本演示了如何访问子图层、如何连接输入和输出图层以及如何将输入源和目的地的字段值传输至输出线图层。

旧版本:

GetNASublayer 功能可用于检索网络分析图层的子图层。 它是在 ArcGIS Pro 2.7 中引入的。 在以前的软件版本中,用于检索网络分析图层的子图层对象的最佳方法是使用网络分析 Layer 对象的 listLayers 方法,该方法将子图层名称用作通配符。

# Name: MakeODCostMatrixAnalysisLayer_Workflow2.py
# Description: Find the travel time to the closest hospital from each census
#               tract and join the travel time and hospital name to the input
#               tracts.
# Requirements: Network Analyst Extension

#Import system modules
import arcpy
from arcpy import env
import datetime
import os

try:
    #Check out Network Analyst license if available. Fail if the Network Analyst license is not available.
    if arcpy.CheckExtension("network") == "Available":
        arcpy.CheckOutExtension("network")
    else:
        raise arcpy.ExecuteError("Network Analyst Extension license is not available.")
    
    #Set environment settings
    output_dir = "C:/Data"
    #The NA layer's data will be saved to the workspace specified here
    env.workspace = os.path.join(output_dir, "Output.gdb")
    env.overwriteOutput = True

    #Set inputs and outputs
    input_gdb = "C:/Data/SanFrancisco.gdb"
    network = os.path.join(input_gdb, "Transportation", "Streets_ND")
    origins = os.path.join(input_gdb, "Analysis", "TractCentroids")
    destinations = os.path.join(input_gdb, "Analysis", "Hospitals")
    output_features = "TractCentroids_withOD"

    #Define some OD cost matrix analysis settings
    layer_name = "HospitalsOD"
    #User settings for driving
    travel_mode = "Driving Time"
    #Calculate the total distance, even though the analysis is optimizing time
    accumulate_attributes = ["Meters"]
    #Find only the closest hospital
    num_hospitals_to_find = 1
    #Set the time of day for the analysis to 6PM on a generic Monday.
    start_time = datetime.datetime(1900, 1, 1, 18, 0, 0)
    #Don't output line shapes (output Lines will still list travel times)
    out_lines = "NO_LINES"

    #Create a new OD cost matrix layer.
    result_object = arcpy.na.MakeODCostMatrixAnalysisLayer(network, layer_name,
                    travel_mode,
                    number_of_destinations_to_find=num_hospitals_to_find,
                    time_of_day=start_time, line_shape=out_lines, 
                    accumulate_attributes=accumulate_attributes)

    #Get the layer object from the result object. The OD layer can
    #now be referenced using the layer object.
    layer_object = result_object.getOutput(0)

    #Get the names of all the sublayers within the OD layer.
    sublayer_names = arcpy.na.GetNAClassNames(layer_object)
    #Store the layer names for later use
    origins_layer_name = sublayer_names["Origins"]
    destinations_layer_name = sublayer_names["Destinations"]

    #The input census tract data has a unique ID field that can be transferred
    #to the analysis layer. Add the field, and then use field mapping to
    #transfer the values.
    arcpy.na.AddFieldToAnalysisLayer(layer_object, origins_layer_name,
                                                        "Tract_ID", "TEXT")
    field_mappings = arcpy.na.NAClassFieldMappings(layer_object,
                                                            origins_layer_name)
    field_mappings["Tract_ID"].mappedFieldName = "ID"

    #Load the census tracts as origins.
    arcpy.na.AddLocations(layer_object, origins_layer_name, origins,
                            field_mappings, "")

    #Map the input hospital NAME field to a new Hospital_Name field in
    #Destinations
    arcpy.na.AddFieldToAnalysisLayer(layer_object, destinations_layer_name,
                                                        "Hospital_Name", "TEXT")
    field_mappings = arcpy.na.NAClassFieldMappings(layer_object,
                                                        destinations_layer_name)
    field_mappings["Hospital_Name"].mappedFieldName = "NAME"

    #Load the hospitals as desinations.
    arcpy.na.AddLocations(layer_object, destinations_layer_name, destinations,
                            field_mappings, "")

    #Solve the OD layer
    arcpy.na.Solve(layer_object)

    #Get sublayers
    #listLayers returns a list of sublayer layer objects contained in the NA
    #group layer, filtered by layer name used as a wildcard. Use the sublayer
    #name from GetNAClassNames as the wildcard string in case the sublayers
    #have non-default names.
    origins_sublayer = layer_object.listLayers(origins_layer_name)[0]
    destinations_sublayer = layer_object.listLayers(destinations_layer_name)[0]
    lines_sublayer = layer_object.listLayers(sublayer_names["ODLines"])[0]

    #Use the JoinField tool to transfer OD Cost Matrix information to the
    #output feature class
    #Transfer the tract ID from the input Origins to the output Lines
    arcpy.management.JoinField(lines_sublayer, "OriginID",
                                    origins_sublayer, "ObjectID", "Tract_ID")
    #Transfer the hospital name from the input Destinations to the output Lines
    arcpy.management.JoinField(lines_sublayer, "DestinationID",
                            destinations_sublayer, "ObjectID", "Hospital_Name")
    #Transfer fields of interest (hospital name, impedance attribute, and other
    #accumulated costs) from the output Lines to a copy of the input census
    #tracts feature class using the Tract_ID field
    # Determine the impedance attribute
    solver_props = arcpy.na.GetSolverProperties(layer_object)
    impedance = solver_props.impedance
    output_impedance_fieldname = "Total_" + impedance
    fields_to_transfer = ["Hospital_Name", output_impedance_fieldname]
    for field in accumulate_attributes:
        fields_to_transfer.append("Total_" + field)
    arcpy.management.CopyFeatures(origins, output_features)
    arcpy.management.JoinField(output_features, "ID",
                                lines_sublayer, "Tract_ID", fields_to_transfer)

    print("Script completed successfully")

except Exception as e:
    # If an error occurred, print line number and error message
    import traceback, sys
    tb = sys.exc_info()[2]
    print("An error occurred on line %i" % tb.tb_lineno)
    print(str(e))
MakeODCostMatrixAnalysisLayer 示例 5(独立脚本)

以下独立 Python 脚本演示了如何从网络数据集创建出行模式的修改版本,并在创建新的 OD 成本矩阵图层时使用此出行模式。

import json

network = r"C:/Data/SanFrancisco.gdb/Transportation/Streets_ND"
# Get all travel modes from the network dataset
travel_modes = arcpy.na.GetTravelModes(network)
# Get the Driving Distance travel mode
dd_travel_mode = travel_modes["Driving Distance"]
# Make a json representation of the travel mode
travel_mode_json = json.loads(str(dd_travel_mode))
# Modify the userHierarchy property to turn hierarchy off, and update the name
travel_mode_json["useHierarchy"] = False
travel_mode_json["name"] = "Driving Distance without Hierarchy"
# Create a new travel mode object from the modified json
new_travel_mode_object = arcpy.na.TravelMode(json.dumps(travel_mode_json))
# Use the new travel mode object to MakeODCostMatrixAnalysisLayer
# We could also pass in the json directly without first converting it to an object
arcpy.na.MakeODCostMatrixAnalysisLayer(network, "OD Without Hierarchy", new_travel_mode_object)