Home

Network Wrangler is a Python library for managing travel model network scenarios.

System Requirements ¶

Network Wrangler should be operating system agonistic and has been tested on Ubuntu and Mac OS.

Network Wrangler does require Python 3.9+. If you have a different version of Python installed (e.g. from ArcGIS), conda or a similar virtual environment manager can care of installing it for you in the installation instructions below.

installing conda

In order to assist in installation, its helpful to have miniconda or another virtual environment manager installed to make sure the network wrangler dependencies don’t interfer with any other package requirements you have. If you don’t have any of these already, we recommend starting with Miniconda as it has the smallest footprint. conda is the environment manager that is contained within both the Anaconda and mini-conda applications.

installing conda or Anaconda (the GUI version) for the first time on computer with Cube or ArcGIS?

For ArcGIS / Cube users - Recommend Install conda by leaving boxes unchecked for advanced options – system path and register anaconda. On some systems, checking these boxes will break Cube and ArcGis systems.

Installation ¶

Create and Activate Virtual Environment ¶

Create and/or activate the virtual environment where you want to install Network Wrangler.

Option 1. Create a new conda environment for wrangler using conda

conda config --add channels conda-forge
conda create python=3.11 -n wrangler #if you don't already have a virtual environment
conda activate wrangler

Option 2. Use pre-packaged conda-environment with all dependencies

Network wrangler comes packaged with a conda environment that already has all the required dependencies. This can be helpful if you are having trouble with different versions of requirements since conda can be better at sorting through them than pip.

conda config --add channels conda-forge
conda env create -f environments/conda/environment.yml
conda activate wrangler

Step 2. Consider which Dependencies you want ¶

The core requirements for network wrangler are specified in pyproject.toml and will be automatically checked and installed when you install network wrangler.

Additional, optional libraries are specified in separate requirements files to reduce the bloat of the minimum installation.

File	pip Option Code	Purpose
`requirements.viz.txt`	`viz`	Requirements for running visualizations.
`requirements.docs.txt`	`docs`	Requirements for building documentation.
`requirements.tests.txt`	`tests`	Requirements for running tests.

If you want to view your networks or use jupyter notebooks, will likely want to install at least the visualization dependencies, which you can always do later as follows:

conda activate wrangler
pip install -r requirements.viz.txt

install additional dependencies using pip

You don’t have to separately install these dependencies. You can also install them when you install network wrangler itself using command like follows using the respective pip option code or a list of them:

conda activate wrangler
pip install network-wrangler[viz]

tricky dependencies

rtree, geopandas and osmnx can have some tricky co-dependencies. If don’t already have an up-to-date installation of them, we’ve had the best success installing them using conda (as opposed to pip).

conda install rtree geopandas osmnx

Step 3. Install Wrangler ¶

Latest ReleaseFrom GitHub

pip install network-wrangler

Only necessary if you want to test features before they have released as official versions.

pip install git+https://github.com/wsp-sag/network_wrangler.git@develop#egg=network_wrangler

Tip

If you wanted to install from a specific tag/version number or branch, replace @develop with @<branchname> or @tag

Common Installation Issues ¶

libstdc++ is deprecated

clang: warning: libstdc++ is deprecated; move to libc++ with a minimum deployment target of OS X 10.9 [-Wdeprecated]`

If you are using MacOS, you might need to update your xcode command line tools and headers

libspatialindex_c or Missing GEOS module

“OSError: Could not find libspatialindex_c library file

or

Shapely, a pre-requisite, doesn’t install propertly because it is missing GEOS module

Try installing them using conda.

conda uninstall geopandas rtree shapely
conda install rtree shapely geopandas

Conda is unable to install a library or to update to a specific library version

Add libraries from conda-forge

conda install -c conda-forge *library*

User does not have permission to install in directories

Try running Anaconda as an administrator, even if you are an admin on your machine.

Quickstart ¶

To get a feel for the API and using project cards, please refer to the “Wrangler Quickstart” jupyter notebook.

To start the notebook, open a command line in the network_wrangler top-level directory and type:

jupyter notebook

Usage ¶

import network_wrangler

##todo this is just an example for now

network_wrangler.setup_logging()

## Network Manipulation
my_network = network_wrangler.read_roadway_network(...) # returns
my_network.apply_project_card(...) # returns
my_network.write_roadway_network(...) # returns

## Scenario Building
my_scenario = network_wrangler.create_scenario(
        base_scenario=my_base_scenario,
        card_search_dir=project_card_directory,
        tags = ["baseline-2050"]
        )
my_scenario.apply_all_projects()
my_scenario.write("my_project/baseline", "baseline-2050")
my_scenario.summarize(outfile="scenario_summary_baseline.txt")

my_scenario.add_projects_from_files(list_of_build_project_card_files)
my_scenario.queued_projects
my_scenario.apply_all_projects()
my_scenario.write("my_project/build", "baseline")

Attribution ¶

NetworkWrangler was developed using resources from the Metropolitan Transportation Commission, Metropolitan Council MN, and in-kind time from UrbanLabs LLC and WSP. It is currently maintained using in-kind time…so please be patient.

This project is built upon the ideas and concepts implemented in the network wrangler project by the San Francisco County Transportation Authority and expanded upon by the Metropolitan Transportation Commission.

While Network Wrangler as written here is based on these concepts, the code is distinct and builds upon other packages such as geopandas and pydantic which hadn’t been implemented when networkwrangler 1.0 was developed.

Contributing ¶

Contributions are welcome. Please review contributing guidelines and instructions.

Companion Software ¶

ProjectCard: Initially part of NetworkWrangler, the functionality for reading, writing and validating ProjectCard objects was pulled out into a separate project so that it could be used by other entities without necessitating NetworkWrangler.

Having an issue? ¶

🪲 NetworkWrangler may contain bugs.

🤔 Also, since it has primarily been used by its developers, the documentation may contain some omissions or not be entirely clear.

But we’d love to make it better! Please report bugs or incorrect/unclear/missing documentation with a GitHub Issue - or fix them yourself with a pull request!

License ¶

Apache-2.0

Release History ¶

Changelog ¶

Notable changes and version history.

Version	Date	Comment
v1.0-beta-2	20204-10-15	Bug fixes in scenario loading, projectcard API and compatibility of transit net with roadway deletions. Some additional performance improvements.
v1.0-beta-1	20204-10-9	Feature-complete for 1.0
v1.0-alpha-2	2024-10-8	Testing for Met Council
v1.0-alpha-1	2024-07-17	Full refactor
v0.2.0-alpha	2020-09-16	-
v0.1.0-alpha	2020-09-09	-
0.0.2	2020-02-05	-