Ranch

This is the Python package for building standard roadway and transit networks from scratch. Before becoming Ranch, it was also referred to as the Standard Network Building Pipeline, which consisted of a series of Python notebooks.

It aims to have the following functionality:

1. build OSM-based roadway network in standard Network Wrangler format
2. build GTFS-based transit network in standard Network Wrangler format
3. build travel model centroid connectors

For the latest code developments, check out the develop branch.

Installation

Install the published package with uv:

uv add ranch-network-wrangler

Or install it with pip:

python -m pip install ranch-network-wrangler

The Python import package remains ranch.

Requirements

• Ranch requires user to install SharedStreets' Node.js implementation, using the Docker installation. User will first install Docker on the machine, and then build SharedStreets image using this Dockerfile. See more instruction below.

• Ranch uses Python 3.7 and above. Runtime requirements are installed with the package. Development dependencies are managed by uv and can be installed with uv sync. Install the documentation dependencies as well with uv sync --group doc.

  The intallation instructions use the conda virtual environment manager and some use the 'git' version control software.

Ranch Installation from GitHub

If you are managing multiple python versions, we suggest using virtualenv or conda virtual environments. All commands should executed in a conda command prompt, not powershell or the system command prompt. Do not add conda to the system path during installation. This may cause problems with other programs that require python 2.7 to be placed in the system path.

Example using a conda environment and using the package manager pip to install Ranch from the source on GitHub.

Basic Installation

conda config --add channels conda-forge
conda create python=3.7 rtree geopandas folium osmnx -n <my_ranch_environment>
conda activate <my_ranch_environment>
pip install git+https://github.com/wsp-sag/Ranch@master

Ranch can be installed in several ways depending on the user's needs. The above installation is the simplest method and is appropriate when the user does not anticipate needing to update Ranch. An update will require rebuilding the ranch environment. Installing from clone is slightly more involved and requires the user to have a git manager on their machine, but permits the user to install Ranch with the -e, edit, option so that their Ranch installation can be updated through pulling new commits from the Ranch repo without a full reinstallation.

Note: if you wanted to install from a specific tag/version number or branch, replace @master with @<branchname> or @tag

From Clone (Recommended for project team)

If you are going to be working on Ranch locally, you might want to clone it to your local machine and install it from the clone. The -e will install it in editable mode.

conda config --add channels conda-forge
conda create python=3.7 rtree geopandas folium osmnx -n <my_ranch_environment>
conda activate <my_ranch_environment>
git clone -b develop https://github.com/wsp-sag/Ranch
cd Ranch
pip install -e .

Note: if you are not part of the project team and want to contribute code bxack to the project, please fork before you clone and then add the original repository to your upstream origin list per these directions on github.

Docker & SharedStreets

Before running Ranch, user need to install SharedStreets via Docker. The steps are as following:

1. Install Docker.
2. Open command line prompt, change base directory to the Ranch directory

cd path/to/your/ranch/directory/

3. Build SharedStreets image using this Dockerfile, name the local image as shst

cd ranch
docker build -t shst .

4. To test if SharedStreets image is built successfully, user can run the following to start a container node

docker run -it --rm -v /path/to/your/local/directory:/usr/node/ shst:latest /bin/bash

if succeeded, user can see a node being launched

Documentation

Documentation is located at https://wsp-sag.github.io/Ranch/

Edit the source of the documentation in the /docs folder.

To build the documentation locally, install its dependencies from the Ranch folder:

uv sync --group doc

To build the documentation, navigate to the /docs folder and execute the command: make html

cd docs
make html

Usage

To learn basic Ranch functionality, please refer to the following jupyter notebooks in the /notebooks directory:

• Ranch-Demo.ipynb

Jupyter notebooks can be started by activating the Ranch conda environment and typing jupyter notebook:

conda activate <my_ranch_environment>
jupyter notebook

Troubleshooting

Issue: Conda is unable to install a library or to update to a specific library version Try installing libraries from conda-forge

conda install -c conda-forge *library*

Issue: User does not have permission to install in directories Try running Anaconda Prompt as an administrator.

Client Contact and Relationship

Before becoming Ranch, the Standard Network Building Pipeline consisted of a series of python notebooks, which have been implemented to build networks for regions including Minneapolis (Met Council), Bay Area (MTC), and Southeast Florida (SERPM). Those agencies all had different variations of the Standard Network Building Pipeline notebooks due to many reasons, e.g. steps in the pipeline have been getting revised and methods have been evolving, also agencies required different network features. However, the fundamental steps in the process are the same across regions. To standardize the network building process so that the same basic steps can be applied to any region, Ranch was created as a Python package that hosts universal network building steps. Our agency partners so far include Met Council, MTC, Miami-Dade TPO, and BART.