ActivitySim Visualizer

ActivitySim Visualizer turns ActivitySim output into an interactive dashboard. Use it to examine one model run, compare multiple runs, or compare model results with survey data.

ActivitySim Visualizer can:

• prepare and summarize household, person, tour, and trip output;
• compare travel patterns, model choices, and validation measures for multiple runs;
• reuse valid cached results for faster startup; and
• launch a local dashboard or create a standalone HTML file.

Quick Start

1. Install the project

From the repository root, use uv to create the environment and install the locked dependencies:

uv sync --locked

If Windows reports a hardlink problem, use:

uv sync --locked --link-mode=copy

2. Create a configuration

Copy config.yaml to local_config.yaml, then set each runs.dir value to an ActivitySim output directory:

runs:
  - dir: C:\models\base\output
    label: Base
  - dir: C:\models\build\output
    label: Build

The default file names are final_households, final_persons, final_tours, final_trips, final_joint_tour_participants, and final_land_use. The visualizer accepts CSV and Parquet input files.

For a small example configuration and instructions for nonstandard files or zones, see Getting Started and Configuring Your Data.

3. Start the visualizer

uv run activitysim-viz --config local_config.yaml

On the first run, the visualizer prepares the input, builds the required summary tables, and starts a local server at http://localhost:5006. Later runs reuse valid caches. Press Ctrl+C to stop the server.

If data is missing or the first run fails, see Troubleshooting.

How It Works

ActivitySim outputs
  -> prepare canonical tables
  -> summarize travel measures
  -> display a live dashboard or export standalone HTML

The YAML configuration selects the input, workflow steps, output location, and dashboard mode. The start command stays the same for every workflow.

Goal	Where to learn more
Use raw ActivitySim output directories	Configuring Your Data
Use already-prepared tables	Already-Prepared Tables
Use dashboard-ready summary tables	Dashboard-Ready Summary Tables
Run only the processor	Processor-Only Workflow
Create a standalone HTML dashboard	HTML Export
Understand caches and workflow steps	Running Workflows
Build summaries for configured subsets	Segmentation
Add district, county, or other zone groupings	Geography
Find an exact configuration field	Configuration Reference
Verify raw or prepared table requirements	Input Data Contract
Interpret cache manifests and rebuild decisions	Cache And Manifest Reference
Understand a summary table or field	Summary Catalog

Documentation

The wiki home is the main documentation index.

For a standard setup, read these chapters in order:

1. Getting Started
2. Configuring Your Data
3. Running Workflows

Other user references:

• Output Visualizer explains the dashboard.
• Dashboard User Guide lists the available analyses and explains how to interpret them.
• Posit Connect Cloud explains how to publish a standalone dashboard with the free public plan.
• Input Data Contract defines source and canonical table boundaries.
• Cache And Manifest Reference explains stored identities and diagnostics.
• HTML Export explains how to create an offline file.
• Summary Catalog documents every summary table.
• Segmentation explains subset summaries and their caches.
• Geography explains zone mappings and spatial outputs.
• Glossary defines project terminology.
• Troubleshooting covers common failures.

For Contributors

Start with Architecture and Developer Workflows, then use the guide for your task:

• extending prepared data;
• adding a summary function;
• adding dashboard pages, figures, or widgets;
• changing configuration, columns, or labels;
• skim enrichment; and
• testing.

Run focused tests during development. To run the full test suite, use:

uv run pytest --basetemp .pytest_tmp

If you change summary declarations or dashboard page definitions, regenerate the wiki catalogs from the code:

uv run python scripts/generate_wiki_catalogs.py

License

The GNU General Public License v3.0 applies to this project. See LICENSE.txt.