mma python module¶

Note

Dependencies

• arcpy (installs with ArcGIS) v. 10.2 or later
• numpy v. 1.11.2 or later
• pandas v. 0.18.1 or later

This module facilitates many procedures required to develop multimodal accessibility (mma) scores in ArcGIS.

The MMA module allows users to generate network analysis problems to create (series of) travel time skims and process those skims against related zone data and decay curves to generate accessibility scores for each zone.

Key functions:

• createAverageMatrix()
• createSkims()
• summarizeAccessibility()

Key classes:

• Decay
• Skim
• SkimSet

Notes

Accessibility scores describe the quantity of “activities” reachable within a given impedance (usually travel time) by a given mode, discounted by impedance tolerances for that mode. Key steps in generating accessibility scores include:

• Configure decay rates
• Create skims (OD matrices)
• Summarize accessibility for a table of land uses

The mma module relies on the following dependencies:

• arcpy (ArcGIS Network Analyst extension must be installed, licensed, and enabled)
• numpy
• pandas

Classes and Functions¶

class mma.Decay(name, const, coef, min_impedance=0, max_impedance=inf, excl_less_than_min=False, excl_greater_than_max=True, lbound=0.0, ubound=1.0, desc='')

The Decay class defines how to discount activities at different destinations based on the cumulative impedance (usually travel time) from the origin.

The Decay object assumes a (negative) exponential formula that defines a curve for discounting activities at destinations based on their cumulative impedance (usually travel time) from the origin. The basic decay formula is:

$self.const * (e^{self.coef * impedance })$

It can be modified such that the value of impedance and/or the results of the formula can be constrained by minimum/maximum values as specified in various attributes.

Parameters: name (String) – A short name to identify the decay rate. const (Float) – The constant term in the decay expression. Typical values are generally near or slightly above 1.0. coef (Float) – The coefficient term in the decay expression. Typical values are less than zero. min_impedance (Float, optional) – Default is 0, which implies no minimum value. max_impedance (Float, optional) – Default is float(‘inf’), which implies no maximum value. excl_less_than_min (Boolean, optional) – Default is False (values less than min_impedance are treated as min_impedance) excl_greater_than_max (Boolean, optional) – Default is True (values greater than max_impedance are ignored). lbound (Float, optional) – Default is None. ubound (Float, optional) – Default is None. desc (String, optional) – Default is None.
name

A short name to identify the decay rate. The name is added to fields in the tables generated by the summarizeAccessibility function, so a short string of a few characters is recommended.

Type: String
const

The constant term in the decay expression.

Type: Float
coef

The coefficient term in the decay expression.

Type: Float
min_impedance

The minimum impedance value to be evaluated as the impedance term in the Decay formula. Values less than min_impedance are ignored if excl_less_than_min is True. Otherwise, values less than min_impedance are treated as the min_impedance value.

Type: Float
max_impedance

The maximum impedance value to be evaluated as the impedance term in the Decay formula. Values greater than max_impedance are ignored if excl_greater_than_max is True. Otherwise, values greater than max_impedance are treated as the max_impedance value.

Type: Float
excl_less_than_min

Flag defining how to treat impedance values less than min_impedance. If True, values less than min_impedance are ignored. If False, values less than min_impedance are treated as min_impedance.

Type: Boolean
excl_greater_than_max

Flag defining how to treat impedance values greater than max_impedance. If True, values greater than max_impedance are ignored. If False, values greater than max_impedance are treated as max_impedance.

Type: Boolean
lbound

Minimum value to return when evaluating the decay funtion specified by the Decay object with respect to a given value of impedance.

Type: Float
ubound

Maximum value to return when evaluating the decay funtion specified by the Decay object with respect to a given value of impedance.

Type: Float
desc

A longer description of the decay curve being defined. The desc parameter offers more detail than can be conveyed in the name parameter.

Type: String
evaluate(impedance)

Estimates the decay weight to return based on the Decay object’s attributes and a float value impedance

Parameters: impedance (Float) – A non-negative numeric value representing cumulative impedance (usually travel time) between an O-D pair. decay_factor – A weighting factor that reflects the discount to apply when weighting destinations in accessibility analyses based on the Decay object’s attributes and the cumulative impedance between an O-D pair. Float
class mma.Skim(path, table, impedance_field, o_field, d_field=None, delimiter=None)

The Skim class describes an OD matrix (skim) table to guide the mma module in parsing the table during accessibility processing.

Skims tabluate impedances (usually travel times) between pairs of zones. These data are stored in tables in which each row represents an O-D pair and an impedance field defines the impedance between the two zones. A Skim object exposes the path location, key fields, and type (arcpy vs text) of a skim table for parsing during accesibility analysis.

Parameters: path (String) – The workspace path in which the skim table is stored. table (String) – The name of the skim table (with file extension, if any). impedance_field (String) – The field in the skim table containing the operative cumulative impedance (usually travel time) value. o_field (String) – The field in the skim table that identifies the origin zone or the field that provides the full origin- destination pair names. d_field (String, optional) – The field in the skim table that identifies the destination zone. (Default is None, which implies that o_field gives the full origin-destination pair names.) delimiter (String, optional) – If o_field gives the full origin-destination pair names, delimeter indicates the character sequance by which to split o_field values to get separate origin and destination ID’s. (Default is None, implying o_field and d_field have been provided. Note that delimiter can’t be None if d_field is also None.)
path

The workspace path in which the skim table is stored.

Type: String
table

The name of the skim table (with file extension, if any).

Type: String
impedance_field

The field in the skim table containint the operative cumulative impedance (usually travel time) value.

Type: String
o_field

The field in the skim table that provides the origin value or the field that provides the full origin- destination pair names.

Type: String
d_field

The field in the skim table that identifies the destination zone.

Type: String
delimiter

Indicates the character sequance by which to split o_field values to get separate origin and destination ID’s when o_field provides full O-D pair names.

Type: String
o_idx

Expected index of o_field in a cursor navigating table

Type: Integer
d_idx

Expected index of d_field in a cursor navigating table

Type: Integer
imp_idx

Expected index of impedance_field in a cursor navigating table

Type: Integer
table_type

Indicates the appropriate method for navigating the table for processing. –Probable deprecation.–

Type: {“arcpy”, “text”}
getSkimFields()

Returns a list of skim fields to pass to cursor for processing.

setDField(d_field)

Set the field in table that identifies destination zones. Can be None if o_field contains full O-D pair names.

setImpedanceField(impedance_field)

Set the field in table that represents the operative cumulative impedance (usually total travel time) between two zones.

setOField(o_field)

Set the field in table that identifies origin zones or that identifies the full O-D pair name.

setPathAndTable(path, table)

Set the the Skim object’s path and table attributes. table must already existing in path.

class mma.SkimSet

The SkimSet class groups one or many Skim objects for use in batch accessibility summarization.

skims

The Skim objects that comprise the SkimSet

Type: [Skim…]
addSkim(skim_obj)

Adds a skim_obj to the SkimSet’s skims list.

removeSkim(path, table)

Remove a skim_obj from the SkimSet’s skims list based on its path and table attributes.

mma.createAverageMatrix(skims_ws, skims_files, name_field, impedance_field, zones_table, zone_id_field, output_table)

Tabulates average O-D impedances (usually travel times) based on a set of skims representing variable O-D travel times (by time of day, for instance).

If multiple skims are developed representing a consistent set of potential O-D pairs (using a travel time window or alternative network parameters, e.g.), it may be desirable to summarize the average impedance between each O-D pair describing a single “typical” impedance.

Parameters: skims_ws (ArcGIS workspace or string) – ArcGIS Workspace object (file folder, geodatabase, etc.) or string representing the path to the workspace. Location where input skim tables are stored. skims_files ([String...]) – List of strings representing file names (with extensions) within skims_ws to reference in developing average impedance values between each potential O-D pair listed in zones_table. name_field (String) – The name of the field in each skims_file containing O-D zone ID information. The field must by a string field formatted as “origin_id - destiantion_id”. It must be present in all skims_files to be analyzed. impedance_field (String) – The name of the field in each skims_file containing impedance information. The field must have a numeric type. The field must have the same name in all skims_files to be analyzed. zones_table (String) – Path to an ArcGIS table or name of an ArcGIS table view in the active data frame containing the set of zones expected to be found in the skims_files. zone_id_field (String) – The name of the field in zones_table containing zone ID information. Unique values in this field are used to construct an O-D matrix that is used to calculated average travel times. output_table (String) – Full path to an ArcGIS table where the average O-D impedances will be stored. Writes an output skim table with average impedance values by OD pair to output_table. None

Notes

Skim tables to be averaged are assumed to reside in a single workspace.

Skim tables to be averaged are assumed to contain consistent field names. All are assumed to have name field containing values formatted as “origin_id - destination_id” and an impedance field containing non-negative numerical values.

The averaging process generally takes the sum of the impedance values recorded in each skims_file for each OD pair and divides it by the number of skims_files being analyzed.

In the event an OD pair is present in one skims_file and not another, it is assumed the impedance between the two zones is infinity in the file(s) for which the value is missing. This accomplished using inversion. All impedance values are stored as recipricals, such that OD pairs with no impedance are given a value of 1.0, missing OD pairs are given a value of 0.0, and all OD pairs’ impedance values are stored as a value between 0.0 and 1.0. These values are then summed and normalized by the number of skims_files being analyzed. The resulting value is then re-inverted to obtain the average typical impedance between each OD pair.

Skim(), gp_averageTravelTime()

mma.createSkims(network, impedance_attribute, o_features, o_name, d_features, d_name, output_workspace, analysis_name, cutoff=None, number_of_ds=None, restrictions=None, u_turns='ALLOW_UTURNS', group_origins=False, group_features=None, group_id_field=None, group_selection_method='INTERSECT', group_selection_radius='', use_network_locations=False, o_SourceID='', o_SourceOID='', o_PosAlong='', o_SideOfEdge='', o_SnapX='', o_SnapY='', o_Distance='', d_SourceID='', d_SourceOID='', d_PosAlong='', d_SideOfEdge='', d_SnapX='', d_SnapY='', d_Distance='', search_criteria='', tolerance='5000 Meters', match=True, exclude_restricted=True, query_layer='', search_query='', use_time_of_day=False, day_of_week='Today', time_window_start='', time_window_end='', time_window_increment=1)

Create a (set of) OD travel time matrix tables.

Skims tabluate travel times between pairs of zones. This function generates output tables in which each row represents an O-D pair and an impedance column defines the travel time between the two zones. Numerous optional parameters are provided representing location loading preferences, time window settings, groupings of origins for data management needs, etc.

mma.decayToJson(decay_obj, output_file)

Stores a Decay object in a JSON config file.

Parameters: decay_obj (Decay) – A Decay object defines how to discount activities at different destinations based on the travel time from the origin. output_file (String) – The full path to the output file. If just the file name is passed, the file will be saved in the current working directory. Writes a decay config JSON file to the output_file. None

mma.jsonToDecay(in_file)

Creates a Decay object for accessibility processing from a JSON config file.

Parameters: in_file (string) – The file name in the current working directory or full path to the JSON config file from which to generate the Decay object. KeyError – If in_file is not a valid Decay config file. Decay

mma.jsonToSkim(in_file)

Creates a Skim object for accessibility processing from a JSON config file.

Parameters: in_file (String) – The file name in the current working directory or full path to the JSON config file from which to generate the Skim object. KeyError – If in_file is not a valid Skim config file. Skim

mma.skimToJson(skim_obj, output_file)

Stores a Skim object in a JSON config file.

Parameters: skim_obj (Skim) – A Skim object desribes an OD matrix (skim) table to guide the mma module in parsing the table during accessibility processing. output_file (String) – The full path to the output file. (If just the file name is passed, the file is saved in the current working directory.) Writes a skim config JSON file to the output_file. None

mma.summarizeAccessibility(skim_set_obj, lu_table, lu_table_id, lu_table_activity_fields, out_table, decays=[])