Example

This page describes the example model design and how to setup and run the Nashville regional example. The Nashville example does three things:

  • nearby_zones - calculates nearby zone-to-zone network distances

  • buffer_zones - calculates network accessibility (buffer) variables

  • write_daysim_files - writes DaySim formatted output files

Example Model Design

Netbuffer contains two network models and one output model:

  • nearby_zones

  • buffer_zones

  • write_daysim_files

The main input for the network models is a CSV file containing zone data. This file is called zones_sample.csv in the Nashville example.

nearby_zones calculates the nearby zones for each zone in the input file within a given network distance. It does this by finding the nearest network node for each zone, using Pandana’s nearest_pois algorithm to find the nearest network nodes.

netbuffer.abm.models.nearby_zones.nearby_zones(zone_data, network, settings)

Calculates distances to nearby zones for each zone in the zone_data table. The ‘max_dist’ setting determines which zones are included in the calculation.

Saves a ‘nearby_zones’ table to the pipeline with from/to/total_dist columns.

netbuffer.abm.models.nearby_zones.get_nearest_network_nodes(zone_data, network, settings)

Updates zone_data table with network data.

Adds the nearest net_node_id for each zone and calculates the distance from the zone centroid to the network node.

netbuffer.abm.models.nearby_zones.build_zone_pairs_df(near_zones, max_num_pois, zones, settings)
Pandana’s nearest_pois returns a DataFrame with

index: node_id column[i]: distance from index node to ith closest poi (zone) column[i*2]: zone id for ith closest poi

buffer_zones takes two additional input files – a POI (Point of Interest) file and a Python expressions file, and performs custom operations on the zone data to calculate network buffer / accessibility attributes for each input zone.

netbuffer.abm.models.buffer_zones.buffer_zones(settings, buffer_zones_spec, buffer_zones_settings, zone_data, trace_zones, network)

Performs network buffering (using Pandana libary http://udst.github.io/pandana/) for each point in zone file using expressions from buffer_zones_spec.

The actual results depend on the expressions in buffer_zones_spec, but this is initially intended to replicate PSRC’s Soundcast (Daysim) zone accessibilities.

Using a point file representing the centroid of a land use boundary (zone), quanitifes the amount of some variable within a specified distance or the distance to a variable. For example, the total number of jobs within a half mile of each zone or the distance to the nearest bus stop from each zone.

The following configs should be set in buffer_zones.yaml:

  • buffer_zones_spec: expressions file

  • pois: Point of Interest file

The CONSTANTS hash is made availabe to the expressions parser.

  • CONSTANTS: - max_pois: integer, maxitems used in nearest pois calculation - pois-x: longitude column in pois file - pois-y: latitude column in pois file

write_daysim_files then outputs the final tables according to the formats required for input to DaySim.

netbuffer.abm.models.write_daysim_files.write_daysim_files()

Pipeline step that writes formatted output files.

Specify in daysim_files.yaml to output pipeline tables:

nearby_zones:

  • outfile: filename

  • delimiter: ‘comma’, ‘space’, or ‘tab’

  • header: bool, whether to include column headers

  • cols: list of columns from nearby zones to include.

Nearby zones column options are ‘from’, ‘to’, ‘distance’, ‘net_node_dist’, ‘net_node_dist_to_zone’, ‘total_dist’.

buffered_zones:

  • outfile: filename

  • delimiter: ascii code

  • header: bool

  • cols: list of columns to include from buffered zones.

Buffered zone column names must match the input zones table.

netbuffer.abm.models.write_daysim_files.write_pipeline_table(file_settings, pipeline_table)

Writes output files according to user settings.

Parameters
file_settingsdict

cols : pipeline_table columns to include in output delimiter : str, either ‘comma’, ‘space’, or ‘tab’ col_types : dict, col/type mapping (python or numpy dtypes) outfile : output file name header : bool, whether to include header row in output

Each network model is independent and can be run separately. Configuration is described in the following section.

Setup

The following describes the example model setup.

Folder and File Setup

The example has the following root folder/file setup:

  • configs - settings, expressions files, etc.

  • data - input data such as the zones CSV, the POI CSV, and saved network H5

  • output - outputs folder

  • run_netbuffer.py - main script to run the model

Configuration

The configs folder contains settings, expressions files, and other files required for specifying model utilities and form. The first place to start in the configs folder is settings.yaml, which is the main settings file for the model run. This file includes:

  • models - list of model steps to run

  • input_table_list - input file name and index column for the initial zone table

  • network - instruction for sourcing the Pandana network (‘read’, ‘build’, or ‘download’)

  • max_dist - maximum network search distance (in meters) for calculating nearby zones and POIs

  • zones_lon, zones_lat - columns to use for latitude/longitude in zones input file

The buffer_zones.yaml file provides instructions to the buffer_zones step.

  • buffer_zones_spec - filename for the user-defined network expressions

  • pois - Point of Interest file name

  • CONSTANTS - variables that are made available to the Python interpreter when evaluating the expressions from buffer_zones_spec. The following constants are required:

    • max_pois - number of POIs to look for around each zone. E.x. max_pois: 1 will find only the closest bus stop in a given zone

    • pois-x - the longitude column in the POI file

    • pois-y - the latitude column in the POI file

Read more on expressions files in the ActivitySim framework.

Network

Netbuffer uses a Pandana network for the majority of the heavy lifting. This network must be loaded at the program’s start and can be sourced in three different ways via the network flag in settings.yaml:

  • download - calculates a geographic area from the input zones table and download a network from the Open Street Map API. Netbuffer will then save a file in the outputs folder named pandana_network.h5 which can be used for subsequent model runs.

  • read - loads a network from a saved H5 file. Be sure to use a network that geographically matches the input zones/POIs. This option requires an additional saved_network flag specifying the input file name.

  • build - creates a network from a set of nodes and links files. Requires an additional network_settings_file configuration setting. See example_psrc for more details.

Note

Netbuffer uses Pandana’s default distance unit meters. All distances in the input tables, expressions, and configs are assumed to be in meters.

netbuffer.core.network.network(zone_data, settings)

Injected Pandana Network object containing network node and edge data.

User can specify three ‘network’ options in settings.yaml:

  • network: read

    uses an existing saved network HDF5 file specified by and additional ‘saved_network’ setting

  • network: build

    creates a new network using a set of node and link files specified in an additional ‘network_settings_file’.

  • network: download

    downloads a complete network from Open Street Maps using the ‘max_dist’ setting and the zone latitudes/longitudes found in the zone_data table.

netbuffer.core.network.read_network_file(settings)

Read network from saved HDF5 file

netbuffer.core.network.get_osm_network(zone_data, settings)

Retrieve Pandana network from Open Street Maps

netbuffer.core.network.build_network(settings)

Build a Pandana network from CSV files