Skip to content

tm2py-utils

Utilities and analysis tools for Travel Model Two (TM2)

Overview

tm2py-utils provides a collection of utilities for working with Travel Model Two outputs, including:

  • Summary Generation - Automated summary statistics from CTRAMP model outputs
  • PopulationSim Integration - Synthetic population analysis and validation
  • Network Analysis - Tools for analyzing transportation networks

Quick Start

Installation

# Clone repository
git clone https://github.com/BayAreaMetro/tm2py-utils.git
cd tm2py-utils

# Create conda environment
conda env create -f environment.yml
conda activate tm2py_utils

# Install package
pip install -e .

See Installation Guide for detailed instructions.

Generating Summaries

# Navigate to validation directory
cd tm2py_utils/summary/validation

# Generate summaries for a model run
python summarize_model_run.py "C:/path/to/ctramp_output"

# View summaries (use Excel, Python, R, or other analysis tools)

📚 New to the validation system? Check out: - User Guide - Complete user guide - README.md - Toolkit overview
- Summaries Guide - System documentation

Key Features

📊 Summary Generation System

Simple, transparent tool for generating validation summaries from CTRAMP model outputs:

  • 30 configured summaries covering households, tours, trips, and activity patterns
  • Automatic validation with built-in quality checks
  • Config-driven - Add summaries by editing YAML, no Python coding
  • Fast - Process full model run in ~10 minutes
# Generate all summaries for one model run
python summarize_model_run.py "C:/path/to/ctramp_output"

# Custom output location
python summarize_model_run.py "C:/path/to/ctramp_output" --output "my_results"

# Strict validation mode (treat warnings as errors)
python summarize_model_run.py "C:/path/to/ctramp_output" --strict

See Summaries Guide for complete documentation.

🏘️ PopulationSim Integration

Analysis tools for synthetic population outputs:

  • Household demographics (size, income, workers)
  • Person demographics (age distribution)
  • Geographic distribution by county
  • Validation against ACS data

Documentation

Architecture

tm2py_utils/
├── summary/
│   ├── validation/                        # NEW: Simple validation toolkit
│   │   ├── summarize_model_run.py        # Main tool - generates summaries
│   │   ├── validate_summaries.py         # Quality checker
│   │   ├── data_model/                   # Configuration files
│   │   │   ├── ctramp_data_model.yaml   # Summary definitions (edit here!)
│   │   │   └── variable_labels.yaml      # Display labels
│   │   ├── outputs/                      # Generated summary CSVs
│   │   ├── HOW_TO_SUMMARIZE.md          # User guide
│   │   ├── README.md                     # Toolkit overview
│   │   └── archived_validation_system/   # Old multi-dataset comparison system
│   └── core_summaries/                   # DEPRECATED (use validation/ instead)
├── inputs/                                # Input data preparation tools
├── requests/                              # Special analysis requests
└── docs/                                  # Documentation (this site)

Support

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.