Loaders

Pandana has some support for creating a Network from the OpenStreetMap API, and for storing Network data to disk as HDF5 so that it can be restored later.

OpenStreetMap

A Network is created from OpenStreetMap using the pdna_network_from_bbox() function:

from pandana.loaders import osm
network = osm.pdna_network_from_bbox(37.859, -122.282, 37.881, -122.252)

By default the generated network contains only walkable routes, specify type='drive' to get driveable routes. These networks have one impedance set, named 'distance', which is the distance between nodes in meters.

Note

pdna_network_from_bbox uses the UDST library OSMnet to download and process OpenStreetMap (OSM) street network data. Please see the OSMnet repo for any OSM loader questions, bugs, or features.

The OSM API also includes the node_query() function for getting specific nodes within a bounding box. This can be used to populate a network with points of interest:

nodes = osm.node_query(
    37.859, -122.282, 37.881, -122.252, tags='"amenity"="restaurant"')
network.set_pois('restaurants', 2000, 10, nodes['lon'], nodes['lat'])

For more about tags see the Overpass API Language Guide and the list of OSM map features.

Pandas HDF5

Saving a Network to HDF5 is a way to share a Network or to preserve it between sessions. For example. you can build a Network using the OpenStreetMap API, then save the Network to HDF5 so you can reuse it without querying OSM again. Users will typically use the save_hdf5() and from_hdf5() methods.

Note

Only the nodes and edges of the network are saved. Points-of-interest and data attached to nodes via the set() method are not included.

You may find the Pandas HDFStore useful to save POI and other data.

When saving a Network to HDF5 it’s possible to exclude certain nodes. This can be useful when refining a network so that it includes only validated nodes. (In the current design of Pandana it’s not possible to modify a Network in place.) As an example, you can use the low_connectivity_nodes() method to identify nodes that may not be connected to the larger network, then exclude those nodes when saving to HDF5:

lcn = network.low_connectivity_nodes(10000, 10, imp_name='distance')
network.save_hdf5('mynetwork.h5', rm_nodes=lcn)

OpenStreetMap API

pandana.loaders.osm.pdna_network_from_bbox(lat_min=None, lng_min=None, lat_max=None, lng_max=None, bbox=None, network_type='walk', two_way=True, timeout=180, memory=None, max_query_area_size=2500000000)

Make a Pandana network from a bounding lat/lon box via a request to the OpenStreetMap Overpass API. Distance will be in meters. Requires installing the OSMnet library.

Parameters:

lat_min, lng_min, lat_max, lng_maxfloat
bboxtuple: Bounding box formatted as a 4 element tuple: (lng_max, lat_min, lng_min, lat_max)
network_type{‘walk’, ‘drive’}, optional: Specify whether the network will be used for walking or driving. A value of ‘walk’ attempts to exclude things like freeways, while a value of ‘drive’ attempts to exclude things like bike and walking paths.
two_waybool, optional: Whether the routes are two-way. If True, node pairs will only occur once.
timeoutint, optional: the timeout interval for requests and to pass to Overpass API
memoryint, optional: server memory allocation size for the query, in bytes. If none, server will use its default allocation size
max_query_area_sizefloat, optional: max area for any part of the geometry, in the units the geometry is in

Returns:

networkpandana.Network

pandana.loaders.osm.node_query(lat_min, lng_min, lat_max, lng_max, tags=None)

Search for OSM nodes within a bounding box that match given tags.

Parameters:

lat_min, lng_min, lat_max, lng_maxfloat
tagsstr or list of str, optional: Node tags that will be used to filter the search. See http://wiki.openstreetmap.org/wiki/Overpass_API/Language_Guide for information about OSM Overpass queries and http://wiki.openstreetmap.org/wiki/Map_Features for a list of tags.

Returns:

nodespandas.DataFrame: Will have ‘lat’ and ‘lon’ columns, plus other columns for the tags associated with the node (these will vary based on the query). Index will be the OSM node IDs.

Pandas HDF5 API

Network.save_hdf5(filename, rm_nodes=None)

Save network data to a Pandas HDF5 file.

Only the nodes and edges of the actual network are saved, points-of-interest and data attached to nodes are not saved.

Parameters:

filenamestr
rm_nodesarray_like: A list, array, Index, or Series of node IDs that should not be saved as part of the Network.

classmethod Network.from_hdf5(filename, migrate_legacy=False)

Load a previously saved Network from a Pandas HDF5 file.

Parameters:

filenamestr
migrate_legacybool, optional: If True and the installed Pandas can’t read the file’s legacy metadata (files saved with older Pandas versions), migrate it into a temporary copy before reading. The default is False so large network files are not copied implicitly.

Returns:

networkpandana.Network

pandana.loaders.pandash5.network_to_pandas_hdf5(network, filename, rm_nodes=None)

Save a Network’s data to a Pandas HDFStore.

Parameters:

networkpandana.Network
filenamestr
rm_nodesarray_like: A list, array, Index, or Series of node IDs that should not be saved as part of the Network.

pandana.loaders.pandash5.network_from_pandas_hdf5(cls, filename, migrate_legacy=False)

Build a Network from data in a Pandas HDFStore.

Parameters:

clsclass: Class to instantiate, usually pandana.Network.
filenamestr
migrate_legacybool, optional: If True and the installed Pandas can’t read the file’s legacy metadata, migrate it into a temporary copy before reading. The default is False so large network files are not copied implicitly.

Returns:

networkpandana.Network

Network files saved with older versions of Pandas have metadata that Pandas 3 can no longer read. These helpers handle that:

pandana.loaders.pandash5.open_hdf_store(filename, mode='r', migrate_legacy=False)

Open a Pandas HDFStore, handling files written by older Pandas versions.

Pandana network files saved with older Pandas/PyTables combinations have metadata stored as byte strings, which Pandas 3 can no longer read. This context manager opens the file normally when Pandas can read it. If it can’t and the file has legacy metadata, the file is either migrated into a temporary copy for the duration of the read (migrate_legacy=True), or a ValueError is raised explaining how to migrate the file with migrate_legacy_hdf().

Parameters:

filenamestr
modestr, optional: Passed to pandas.HDFStore. Legacy handling only applies to read mode.
migrate_legacybool, optional: If True, migrate legacy metadata into a temporary copy when Pandas can’t read the file directly. The default is False so large network files are not copied implicitly.

Yields:

storepandas.HDFStore

pandana.loaders.pandash5.migrate_legacy_hdf(filename, output_filename=None)

Normalize legacy Pandas HDF5 metadata written as byte strings.

Older Pandas/PyTables combinations stored attributes such as pandas_type as bytes. Pandas 3 expects text when it reconstructs storers. This utility explicitly migrates those attributes either in place or into output_filename if one is supplied.