ActivitySim includes the ability to re-estimate submodels using choice model estimation tools such as larch. To do so, ActivitySim adopts the concept of an estimation data bundle (EDB), which is a collection of the necessary data to re-estimate a submodel. For example, for the auto ownership submodel, the EDB consists of the following files:

  • model settings - the auto_ownership_model_settings.yaml file

  • coefficients - the auto_ownership_coefficients.csv file with each coefficient name, value, and constrain set to True or False if the coefficient is estimatable

  • utilities specification - the auto_ownership_SPEC.csv utility expressions file

  • chooser and alternatives data - the auto_ownership_values_combined.csv file with all chooser and alternatives data such as household information, land use information, and the utility data components for each alternative

ActivitySim also includes Jupyter Estimation Notebooks for estimating submodels with larch, as well as an activitysim.estimation.larch submodule that transforms EDBs into larch models. Additional estimation software translators can be added later if desired.

The combination of writing an EDB for a submodel + a larch estimation notebook means users can easily re-estimate submodels. This combination of functionality means:

  • There is no duplication of model specifications. ActivitySim owns the specification and larch pivots off of it. Users code model specifications and utility expressions in ActivitySim so as to facilitate ease of use and eliminate inconsistencies and errors between the code used to estimate the models and the code used to apply the models.

  • The EDB includes all the data and model structure information and the activitysim.estimation.larch submodule used by the example notebooks transforms the EDB to larch’s data model for estimation.

  • Users are able to add zones, alternatives, new chooser data, new taz data, new modes, new coefficients, revise utilities, and revise nesting structures in ActivitySim and larch responds accordingly.

  • Eventually it may be desirable for ActivitySim to automatically write larch estimators (or other types of estimators), but for now the integration is loosely coupled rather than tightly coupled in order to provide flexibility.


The general workflow for estimating models is shown in the figure below and explained in more detail below.

  • The user converts their household travel survey into ActivitySim format households, persons, tours, joint tour participants, and trip tables. The households and persons tables must have the same fields as the synthetic population input tables since the surveyed households and persons will be run through the same set of submodels as the simulated households and persons.

  • The ActivitySim estimation example scripts\ module reads the ActivitySim format household travel survey files and checks for inconsistencies in the input tables versus the model design + calculates additional fields such as the household joint tour frequency based on the trips and joint tour participants table. Survey households and persons observed choices much match the model design (i.e. a person cannot have more work tours than the model allows).

  • ActivitySim is then run in estimation mode to read the ActivitySim format household travel survey files, run the ActivitySim submodels to write estimation data bundles (EDB) that contains the model utility specifications, coefficients, chooser data, and alternatives data for each submodel. Estimation mode runs single-processed and without destination sampling.

  • The relevant EDBs are read and transformed into the format required by the model estimation tool (i.e. larch) and then the coefficients are re-estimated. The activitysim.estimation.larch library is included for integration with larch. No changes to the model specification are made in the process.

  • The user can then update the ActivitySim model coefficients file(s) for the estimated submodel and re-run the model in simulation mode. The user may want to use the restartable pipeline feature of ActivitySim to just run the submodel of interest.



The estimation_mode.ipynb Jupyter Estimation Notebooks also introduces estimation mode and walks the user through the process.

To run the estimation example, do the following:

  • Activate the correct conda environment if needed

  • Create a local copy of the estimation example folder

activitysim create -e example_estimation_sf -d test_example_estimation_sf
  • Run the example

cd test_example_estimation_sf
activitysim run -c configs_estimation/configs -c configs -o output -d data_sf
  • ActivitySim should log some information and write outputs to the output folder, including EDBs for each submodel. The estimation example runs for about 15 minutes and writes EDBs for 2000 households.

  • Open Estimation Notebooks for a specific submodel and then step through the notebook to re-estimate the sub-model.


Additional settings for running ActivitySim in estimation mode are specified in the estimation.yaml file. The settings are:

  • enable - enable estimation, either True or False

  • bundles - the list of submodels for which to write EDBs

  • survey_tables - the list of input ActivitySim format survey tables with observed choices to override model simulation choices in order to write EDBs. These tables are the output of the scripts\ script that pre-processes the ActivitySim format household travel survey files for the example data and submodels

Estimation Notebooks

ActivitySim includes a Jupyter Notebook recipe book with interactive re-estimation examples for each estimatable submodel. To run a Jupyter notebook, do the following:

  • Open an Anaconda prompt and activate the Anaconda environment with ActivitySim installed

  • If needed, conda install jupyterlab so you can run jupyter notebooks

  • Type jupyter notebook to launch the web-based notebook manager

  • Navigate to the examples/examples_estimaton/notebooks folder and select a notebook from the table below

  • Save the updated coefficient file(s) to the configs folder and run the model in simulation mode



Estimation mode overview


School location


Work location


Auto ownership


Free parking




Mandatory tour frequency


Work tour scheduling


School tour scheduling


Joint tour frequency


Jointatory tour composition


Jointatory tour participation


Joint nonmandatory tour destination


Joint tour scheduling


Non mandatory tour frequency


Non mandatory tour scheduling


Tour mode choice


Atwork subtour frequency


Atwork subtour destination


Atwork subtour scheduling


Stop frequency


Trip destination


Trip mode choice


General API

Models API