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.
UrbanSim Templates was created in 2018 by Sam Maurer (firstname.lastname@example.org), who remains the lead developer, with contributions from Paul Waddell, Max Gardner, Eddie Janowicz, Arezoo Besharati Zadeh, Xavier Gitiaux, and others.
UrbanSim Templates is currently tested with Python versions 3.6, 3.7, 3.8, and 3.9.
UrbanSim Templates can be installed using the Pip or Conda package managers.
pip install urbansim_templates
conda install urbansim_templates --channel conda-forge
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 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
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.
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 : import urbansim_templates print(urbansim_templates.__version__) Out: '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
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:
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 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.
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.