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.
Returns:	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.
Return type:	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…]

See also

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.
Returns:	Writes an output skim table with average impedance values by OD pair to output_table.
Return type:	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.

See also

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.

Other Parameters:
Parameters:	network (ArcGIS Network Dataset or Network Dataset Layer) – Path to an ArcGIS network dataset or name of an ArcGIS network dataset layer in the active data frame. impedance_attribute (String) – The name of the impedance attribute in network to be used in determining shortest paths between o_features and d_features. o_features (ArcGIS Feature Class or Feature Layer) – Path to an ArcGIS point feature class or name of an ArcGIS point feature layer in the active data frame representing origin locations to be recorded in the skim(s). o_name (String) – Field in o_features to use as the origin ID value when tabulating travel times in the skim(s). d_features (ArcGIS Feature Class or Feature Layer) – Path to an ArcGIS point feature class or name of an ArcGIS point feature layer in the active data frame (can be the same FC/FL as o_features). d_name (String) – Field in d_features to use as the destination ID value when tabulating travel times. output_workspace (ArcGIS Workspace or string) – ArcGIS Workspace object (file folder, geodatabase, etc.) or string representing the path to the workspace. Location where output skim tables will be stored. analysis_name (String) – A string of characters to include in the names of output files to differentiate them from other files produced in the same output_workspace. Short strings of 7 characters or fewer are recommended. cutoff (Double, optional) – The maximum impedance_attribute value from o_features beyond which d_features will not be tabulated in the skim. (Default is None, which implies no maximum impedance_attribute value.) number_of_ds (Integer, optional) – The maximum number of d_features to find for each o_feature. (Default is None, which finds all origins within cutoff.) restrictions (String, optional) – (Default is None.) The restriction attributes in network to honor when finding shortest paths as a semi-colon-separated string. Example : “Oneway;PedesetrianOnly” u_turns ({"ALLOW_UTURNS", "NO_UTURNS", "ALLOW_DEAD_ENDS_ONLY", "ALLOW_DEAD_ENDS_AND_INTERSECTIONS_ONLY" }) – The u-turn policy to honor when finding shortest paths.
Returns:	Nothing is retured by the function. It will output one or more skim tables to the output_workspace with names reflecting analysis_name, group_id_field (if any), and the time window (if any). For each output skim, a skim reference configuration file (.json) will also be created in {output_workspace\_skim_references}
Return type:	None
	group_origins (Boolean, optional) – (Default is False.) True indicates that origins should be grouped for processing. Grouping limits the number of features included in a given OD matrix tabulation to manage memory and output file sizes. group_features (ArcGIS Feature Class or Feature Layer, optional) – (Deafult is None.) If group_origins is True, origins will be grouped based on the relationship of features in o_features to features in group_features. group_id_field (String, optional) – (Default is None.) Name of the field in group_features that organizes the grouping of o_features. Distinct values in this field will be included in output file names to relate each skim table to its origin group. group_selection_method (String, optional) – The spatial relationship to apply when grouping o_features based on group_features. (Default is “INTERSECT”, which relates o_features to group_features that they intersect. All ArcGIS overlap_types are valid.) group_selection_radius (Linear Unit (String), optional) – The distance to search around group_features for testing their spatial relationship to o_features. (Default is “”, which implies a strict relationship among featues [i.e., no search radius].) Example: “100 Feet” use_network_locations (Boolean, optional) – (Default is False.) True indicates o_features and d_features will load on to the network using pre-calculated values stored in various fields stored in their respective attribute tables. False indicates o_features and d_featues will load on to the network based on spatial criteria (this takes longer and can lead to inconsistencies in loading locations). o_SourceID (String, optional) – (Default is “”.) If use_network_locations is True, provide the name of the SourceID field in o_features o_SourceOID (String, optional) – (Default is “”.) If use_network_locations is True, provide the name of the SourceOID field in o_features o_PosAlong (String, optional) – (Default is “”.) If use_network_locations is True, provide the name of the PosAlong field in o_features o_SideOfEdge (String, optional) – (Default is “”.) If use_network_locations is True, provide the name of the SideOfEdge field in o_features o_SnapX (String, optional) – (Default is “”.) If use_network_locations is True, provide the name of the SnapX field in o_features o_SnapY (String, optional) – (Default is “”.) If use_network_locations is True, provide the name of the SnapY field in o_features o_Distance (String, optional) – (Default is “”.) If use_network_locations is True, provide the name of the Distance field in o_features d_SourceID (String, optional) – (Default is “”.) If use_network_locations is True, provide the name of the SourceID field in d_features d_SourceOID (String, optional) – (Default is “”.) If use_network_locations is True, provide the name of the SourceOID field in d_features d_PosAlong (String, optional) – (Default is “”.) If use_network_locations is True, provide the name of the PosAlong field in d_features d_SideOfEdge (String, optional) – (Default is “”.) If use_network_locations is True, provide the name of the SideOfEdge field in d_features d_SnapX (String, optional) – (Default is “”.) If use_network_locations is True, provide the name of the SnapX field in d_features d_SnapY (String, optional) – (Default is “”.) If use_network_locations is True, provide the name of the SnapY field in d_features d_Distance (String, optional) – (Default is “”.) If use_network_locations is True, provide the name of the Distance field in d_features search_criteria (String, optional) – If use_network_locations is False, list the network sources and snapping points on which o_features and d_features may load in a semi-colon-separated string. Example: “Streets Midpoint;Streets Endpoint” tolerance (Linear Unit (String), optional) – If use_network_locations is False, specify the maximum distance from a network source listed in search_citeria to search for o_features and d_features for loading. Features beyond the tolerance will be ignored during analysis. (Default is “5000 Meters”.) match (Boolean, optional) – If use_network_locations is False, specify how to select loading locations based on network sources listed in search_criteria. If match is True, features will load on the closest valid source. This is the deafult. If match is False, features will honor the priority of network sources implied by the order in which they are listed in search_criteria, loading on the closest in a given priority group. exclude_restricted (Boolean, optional) – If use_network_locations is False, specify whether o_features and d_features can be loaded on excluded network features. Excluded features are those honored as restricted as listed in restrictions. If exclude_restricted is True, excluded features will be ignored. This is the default. If exclude_restricted is False, some locations may load on restricted features. search_query (String, optional) – If use_network_locations is False, optionally specify which network features are available for loading. This is an expression string that further constrains loading beyond the limits set by search_criteria, match, and exclude_restricted. (Default is “”.) use_time_of_day (Boolean, optional) – (Default is False.) True indicates that network is time-enabled and the user desires skims for a specific day and time. If False, no differentiation by time of day will be considered. day_of_week ({“Today”, “Monday”, “Tuesday”, “Wednesday”, “Thursday”, “Friday”, “Saturday”}, optional) – If use_time_of_day is True, indicate the day of week to analyze. time_window_start (DateTime, optional) – If use_time_of_day is True, indicate the initial time to analyze. Multiple skims may be produced based on the time_window_end and time_window_increment values. time_window_end (DateTime, optional) – If use_time_of_day is True, indicate the last time to analyze. Multiple skims may be produced based on the time_window_start and time_window_increment values. If only a single time of day skim is required, set time_window_end equal to time_window_start. time_window_increment (Double, optional) – If use_time_of_day is True, indicate the interval at which to increment the time so that multiple skims will be produced for every interval of time_window_increment between time_window_start and time_window_end.

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.
Returns:	Writes a decay config JSON file to the output_file.
Return type:	None

See also

jsonToDecay(), Decay()

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.
Raises:	`KeyError` – If in_file is not a valid Decay config file.
Returns:
Return type:	Decay

See also

decayToJson(), 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.
Raises:	`KeyError` – If in_file is not a valid Skim config file.
Returns:
Return type:	Skim

See also

skimToJson(), 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.)
Returns:	Writes a skim config JSON file to the output_file.
Return type:	None

See also

jsonToSkim(), Skim()

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

Summarizes access to activities at desinations based on skims in a SkimSet object, a land use table, and a list of Decay objects.

Parameters:	skim_set_obj (SkimSet) – A SkimSet object comprised of the Skim objects describing the skim tables to reference in accessibility summarization. lu_table (ArcGIS Table or TableView) – A table that organizes land use data by zones with an ID field that corresponds to values in each skim table’s destination ID values. lu_table_id (String) – The field in lu_table that identifies each zone. Values in this field should correspond to values in each skim table’s destination ID values. lu_table_activity_fields ([String,..]) – A list of field names representing the activities at each (destination) zone to summarize in the accessibility tabulation. out_table (ArcGIS Table) – The output table containing accessiblity summarization results. decays ([Decay,..]) – A list of Decay objects to be applied in the summarization of activities (in lu_table_activity_fields).
Returns:	Nothing is retured by the function. It generates an output_table containing accessibility summaries. The output_table will contain a row for each distinct origin ID listed in the skim tables included in skim_set_obj. For each origin, fields summarizing all activities listed in lu_table_activity_fields (having the same field names as those in that list) as well as sets of the same fields with decayed summaries with names pre- fixed by each decay rate’s name attribute.
Return type:	None

See also

Skim(), SkimSet(), Decay()