Getting started

Intro

UrbanSim Templates is a Python library that provides building blocks for Orca-based simulation models. It’s part of the Urban Data Science Toolkit (UDST).

The library contains templates for common types of model steps, plus a tool called ModelManager that runs as an extension to the Orca task orchestrator. ModelManager can register template-based model steps with the orchestrator, save them to disk, and automatically reload them for future sessions. The package was developed to make it easier to set up new simulation models — model step templates reduce the need for custom code and make settings more portable between models.

UrbanSim Templates is hosted on Github with a BSD 3-Clause open source license. The code repository includes some material not found in this documentation: a change log, a contributor’s guide, and instructions for running the tests, updating the documentation, and creating a new release.

Another useful resource is the issues and pull requests on Github, which include detailed feature proposals and other discussions.

UrbanSim Templates was created in 2018 by Sam Maurer (maurer@urbansim.com), who remains the lead developer, with contributions from Paul Waddell, Max Gardner, Eddie Janowicz, Arezoo Besharati Zadeh, Xavier Gitiaux, and others.

Installation

UrbanSim Templates is currently tested with Python versions 3.6, 3.7, 3.8, and 3.9.

Production releases

UrbanSim Templates can be installed using the Pip or Conda package managers.

pip install urbansim_templates

conda install urbansim_templates --channel conda-forge

Dependencies include NumPy, Pandas, and Statsmodels, plus two other UDST libraries: Orca and ChoiceModels. These will be included automatically when you install UrbanSim Templates.

Certain less-commonly-used templates require additional packages: currently, PyLogit and Scikit-learn. You’ll need to install these separately to use the associated templates.

When new production releases of UrbanSim Templates come out, you can upgrade like this:

pip install urbansim_templates --upgrade

conda update urbansim_templates --channel conda-forge

Developer pre-releases

Developer pre-releases of UrbanSim Templates can be installed using the Github URL. These versions sometimes require having a developer release of ChoiceModels as well. Information about the developer releases can be found in Github pull requests.

pip install git+git://github.com/udst/choicemodels.git
pip install git+git://github.com/udst/urbansim_templates.git

You can use the same command to upgrade.

Cloning the repository

If you’ll be modifying the code, you can install UrbanSim Templates by cloning the Github repository:

git clone https://github.com/udst/urbansim_templates.git
cd urbansim_templates
python setup.py develop

Update it with git pull.

Basic usage

Initializing ModelManager

To get started, import and initialize ModelManager. This makes sure there’s a directory set up to store any template-based model steps that are generated within the script or notebook.

from urbansim_templates import modelmanager

modelmanager.initialize()

The default file location is a configs folder located in the current working directory; you can provide an alternate path if needed. If ModelManager finds existing saved objects in the directory, it will load them and register them with Orca.

Note

It can be helpful to add a cell to your notebook that reports which version of UrbanSim Templates is installed, particularly if you’re using development releases!

In [2]: import urbansim_templates
        print(urbansim_templates.__version__)

Out[2]: '0.2'

Creating a model step

Now we can choose a template and use it to build a model step. The templates are Python classes that contain logic for setting up and running different kinds of model logic — currently focusing on OLS regressions and discrete choice models.

A template takes a variety of arguments, which can either be passed as parameters or set as object properties after an instance of the template is created.

from urbansim_templates.models import OLSRegressionStep

m = OLSRegressionStep()
m.name = 'price-prediction'
m.tables = 'buildings'
m.model_expression = 'sale_price ~ residential_sqft'

This sets up m as an instance of the OLS regression template. The tables and model_expression arguments refer to data that needs to be registered separately with Orca. So let’s load the data before trying to estimate the model:

import orca
import pandas as pd

url = "https://raw.githubusercontent.com/UDST/urbansim_templates/dev/examples/data/buildings-demo.csv"
df = pd.read_csv(url).dropna()
orca.add_table('buildings', df)

Fitting the statistical model

Now we can fit the building price model:

m.fit()

This will print a summary table describing the estimation results.

Now that we have a fitted model, we can use it to predict sale prices for other buildings. UrbanSim forecasting models consist of many interconnected steps like this, iteratively predicting real estate prices, household moves, construction, and other urban dynamics.

Registering the step

Now we can register the model step:

modelmanager.register(m)

ModelManager parses the step, saves a copy to disk, and registers a runnable version of it as a standard Orca step, so that it can be invoked as part of a sequence of other steps:

orca.run(['price-prediction', 'household-moves', 'residential-development'])

In real usage, some additional parameters would be set to specify which data to use for prediction, and where to store the output.

Making changes

ModelManager also includes some interactive functionality. Previously registered steps can be retrieved as template objects, which can be modified and re-registered as needed. This also works with model steps loaded from disk.

modelmanager.list_steps()

m2 = modelmanager.get_step('price-prediction')
...

m2.name = 'better-price-prediction'
modelmanager.register(m2)
modelmanager.remove_step('price-prediction')

If you take a look in the configs folder, you’ll see a yaml file representing the saved model step. It includes the settings we provided, plus the fitted coefficients and anything else generated by the internal logic of the template.