Make Closest Facility Layer (Network Analyst)

License Level:BasicStandardAdvanced

Summary

Makes a closest facility network analysis layer and sets its analysis properties. A closest facility analysis layer is useful in determining the closest facility or facilities to an incident based on a specified network cost.

Usage

Syntax

MakeClosestFacilityLayer_na (in_network_dataset, out_network_analysis_layer, impedance_attribute, {travel_from_to}, {default_cutoff}, {default_number_facilities_to_find}, {accumulate_attribute_name}, {UTurn_policy}, {restriction_attribute_name}, {hierarchy}, {hierarchy_settings}, {output_path_shape}, {time_of_day}, {time_of_day_usage})
ParameterExplanationData Type
in_network_dataset

The network dataset on which the closest facility analysis will be performed.

Network Dataset Layer
out_network_analysis_layer

Name of the closest facility network analysis layer to create.

String
impedance_attribute

The cost attribute to be used as impedance in the analysis.

String
travel_from_to
(Optional)

Specifies the direction of travel between facilities and incidents.

  • TRAVEL_FROMDirection of travel is from facilities to incidents.
  • TRAVEL_TODirection of travel is from incidents to facilities.

Using this option can find different facilities on a network with one-way restrictions and different impedances based on direction of travel. For instance, a facility may be a 10-minute drive from the incident while traveling from the incident to the facility, but while traveling from the facility to the incident, it may be a 15-minute journey because of different travel time in that direction.

Fire departments commonly use the TRAVEL_FROM setting since they are concerned with the time it takes to travel from the fire station (facility) to the location of the emergency (incident). A retail store (facility) is more concerned with the time it takes the shoppers (incidents) to reach the store; therefore, stores commonly use the TRAVEL_TO option.

String
default_cutoff
(Optional)

Default impedance value at which to stop searching for facilities for a given incident. The default can be overridden by specifying the cutoff value on incidents when the TRAVEL_TO option is used or by specifying the cutoff value on facilities when the TRAVEL_FROM option is used.

Double
default_number_facilities_to_find
(Optional)

Default number of closest facilities to find per incident. The default can be overridden by specifying a value for the TargetFacilityCount property on the incidents.

Long
accumulate_attribute_name
[accumulate_attribute_name,...]
(Optional)

List of cost attributes to be accumulated during analysis. These accumulation attributes are purely for reference; the solver only uses the cost attribute specified by the Impedance attribute parameter to calculate the route.

For each cost attribute that is accumulated, a Total_[Impedance] property is added to the routes that are output by the solver.

String
UTurn_policy
(Optional)

The U-Turn policy at junctions. Allowing U-turns implies the solver can turn around at a junction and double back on the same street. Given that junctions represent street intersections and dead ends, different vehicles may be able to turn around at some junctions but not at others—it depends on whether the junction represents an intersection or dead end. To accommodate, the U-turn policy parameter is implicitly specified by how many edges connect to the junction, which is known as junction valency. The acceptable values for this parameter are listed below; each is followed by a description of its meaning in terms of junction valency.

  • ALLOW_UTURNSU-turns are permitted at junctions with any number of connected edges. This is the default value.
  • NO_UTURNSU-turns are prohibited at all junctions, regardless of junction valency. Note, however, that U-turns are still permitted at network locations even when this setting is chosen; however, you can set the individual network locations' CurbApproach property to prohibit U-turns there as well.
  • ALLOW_DEAD_ENDS_ONLYU-turns are prohibited at all junctions, except those that have only one adjacent edge (a dead end).
  • ALLOW_DEAD_ENDS_AND_INTERSECTIONS_ONLYU-turns are prohibited at junctions where exactly two adjacent edges meet but are permitted at intersections (junctions with three or more adjacent edges) and dead ends (junctions with exactly one adjacent edge). Oftentimes, networks have extraneous junctions in the middle of road segments. This option prevents vehicles from making U-turns at these locations.
TipTip:

If you need a more precisely defined U-turn policy, consider adding a global turn delay evaluator to a network cost attribute, or adjusting its settings if one exists, and pay particular attention to the configuration of reverse turns. Also, look at setting the CurbApproach property of your network locations.

String
restriction_attribute_name
[restriction_attribute_name,...]
(Optional)

List of restriction attributes to apply during the analysis.

String
hierarchy
(Optional)
  • USE_HIERARCHY Use the hierarchy attribute for the analysis. Using a hierarchy results in the solver preferring higher-order edges to lower-order edges. Hierarchical solves are faster, and they can be used to simulate the preference of a driver who chooses to travel on freeways over local roads when possible—even if that means a longer trip. This option is valid only if the input network dataset has a hierarchy attribute.
  • NO_HIERARCHYDo not use the hierarchy attribute for the analysis. Not using a hierarchy yields an exact route for the network dataset.

The parameter is not used if a hierarchy attribute is not defined on the network dataset used to perform the analysis. In such cases, use "#" as the parameter value.

Boolean
hierarchy_settings
(Optional)

LegacyLegacy:

Prior to version 10, this parameter allowed you to change the hierarchy ranges for your analysis from the default hierarchy ranges established in the network dataset. At version 10, this parameter is no longer supported and should be specified as an empty string. If you wish to change the hierarchy ranges for your analysis, update the default hierarchy ranges in the network dataset.

Network Analyst Hierarchy Settings
output_path_shape
(Optional)

Specifies the shape type for the route features that are output by the analysis.

  • TRUE_LINES_WITH_MEASURESThe output routes will have the exact shape of the underlying network sources. Furthermore, the output includes route measurements for linear referencing. The measurements increase from the first stop and record the cumulative impedance to reach a given position.
  • TRUE_LINES_WITHOUT_MEASURESThe output routes will have the exact shape of the underlying network sources.
  • STRAIGHT_LINESThe output route shape will be a single straight line between each paired incident and facility.
  • NO_LINESNo shape will be generated for the output routes.

No matter which output shape type is chosen, the best route is always determined by the network impedance, never Euclidean distance. This means only the route shapes are different, not the underlying traversal of the network.

String
time_of_day
(Optional)

Specifies the time and date at which the routes should begin or end. The interpretation of this value depends on whether Time of Day Usage is set to START_TIME or END_TIME.

If you have chosen a traffic-based impedance attribute, the solution will be generated given dynamic traffic conditions at the time of day specified here. A date and time can be specified as 5/14/2012 10:30 AM.

Instead of using a particular date, a day of the week can be specified using the following dates.

  • Today—12/30/1899
  • Sunday—12/31/1899
  • Monday—1/1/1900
  • Tuesday—1/2/1900
  • Wednesday—1/3/1900
  • Thursday—1/4/1900
  • Friday—1/5/1900
  • Saturday—1/6/1900
For example, to specify that travel should begin at 5:00 PM on Tuesday, specify the parameter value as 1/2/1900 5:00 PM.

Date
time_of_day_usage
(Optional)

Indicates whether the value of the Time of Day parameter represents the arrival or departure time for the route or routes.

  • START_TIMETime of Day is interpreted as the departure time from the facility or incident.When START_TIME is chosen, Time of Day indicates the solver should find the best route given a departure time. NOT_USED can be chosen if a value isn't specified in the Time of Day parameter.
  • END_TIMETime of Day is interpreted as the arrival time at the facility or incident. This option is useful if you want to know what time to depart from a location so that you arrive at the destination at the time specified in Time of Day.
  • NOT_USEDWhen Time of Day doesn't have a value, NOT_USED is the only choice. When Time of Day has a value, NOT_USED isn't available.
String

Code Sample

MakeClosestFacilityLayer example 1 (Python window)

Execute the tool using only the required parameters.

network = "C:/Data/SanFrancisco.gdb/Transportation/Streets_ND"
arcpy.na.MakeClosestFacilityLayer(network, "ClosestFireStations", "TravelTime")
MakeClosestFacilityLayer example 2 (Python window)

Execute the tool using all parameters.

network = "C:/Data/SanFrancisco.gdb/Transportation/Streets_ND"
arcpy.na.MakeClosestFacilityLayer(network, "ClosestHospitals", "TravelTime",
                                    "TRAVEL_TO", 5 ,3, ["Meters", "TravelTime"],
                                    "ALLOW_UTURNS", ["Oneway"], "USE_HIERARCHY",
                                    "", "TRUE_LINES_WITH_MEASURES")
MakeClosestFacilityLayer example 3 (workflow)

The following stand-alone Python script demonstrates how the MakeClosestFacilityLayer tool can be used to find the closest warehouse from the store locations.

# Name: MakeClosestFacilityLayer_Workflow.py
# Description: Find the closest warehouse from the store locations and save the
#              results to a layer file on disk.
# Requirements: Network Analyst Extension

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

try:
    #Check out the Network Analyst extension license
    arcpy.CheckOutExtension("Network")

    #Set environment settings
    env.workspace = r"C:/data/Paris.gdb"
    env.overwriteOutput = True

    #Set local variables
    inNetworkDataset = r"Transportation/ParisMultimodal_ND"
    outNALayerName = "ClosestWarehouse"
    impedanceAttribute = "Drivetime"
    accumulateAttributeName = ["Meters"]
    inFacilities = r"Analysis/Warehouses"
    inIncidents = r"Analysis/Stores"
    outLayerFile = os.path.join(r"C:/data/output", outNALayerName + ".lyr")

    #Create a new closest facility analysis layer. Apart from finding the drive
    #time to the closest warehouse, we also want to find the total distance. So
    #we will accumulate the "Meters" impedance attribute.
    NAResultObject = arcpy.na.MakeClosestFacilityLayer(inNetworkDataset,outNALayerName,
                                                   impedanceAttribute,"TRAVEL_TO",
                                                   "",1, accumulateAttributeName,
                                                   "NO_UTURNS")

    #Get the layer object from the result object. The closest facility layer can
    #now be referenced using the layer object.
    outNALayer = NAResultObject.getOutput(0)

    #Get the names of all the sublayers within the closest facility layer.
    subLayerNames = arcpy.na.GetNAClassNames(outNALayer)
    #Stores the layer names that we will use later
    facilitiesLayerName = subLayerNames["Facilities"]
    incidentsLayerName = subLayerNames["Incidents"]

    #Load the warehouses as Facilities using the default field mappings and
    #search tolerance
    arcpy.na.AddLocations(outNALayer, facilitiesLayerName, inFacilities, "", "")

    #Load the Stores as Incidents. Map the Name property from the NOM field
    #using field mappings
    fieldMappings = arcpy.na.NAClassFieldMappings(outNALayer, incidentsLayerName)
    fieldMappings["Name"].mappedFieldName = "NOM"
    arcpy.na.AddLocations(outNALayer, incidentsLayerName, inIncidents,
                          fieldMappings,"")

    #Solve the closest facility layer
    arcpy.na.Solve(outNALayer)

    #Save the solved closest facility layer as a layer file on disk with
    #relative paths
    arcpy.management.SaveToLayerFile(outNALayer,outLayerFile,"RELATIVE")

    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 occured on line %i" % tb.tb_lineno
    print str(e)

Environments

Related Topics

Licensing Information

ArcGIS for Desktop Basic: Yes
ArcGIS for Desktop Standard: Yes
ArcGIS for Desktop Advanced: Yes
1/20/2015