# bayareametro/bayarea_urbansim architecture

> Architecture diagram of the GitHub repository bayareametro/bayarea_urbansim, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bayareametro/bayarea_urbansim
- Repository: https://github.com/bayareametro/bayarea_urbansim

## Overview

##### Project type and purpose
- This is a domain-specific, open-source simulation and data-processing tool built on the UrbanSim framework (Bay Area UrbanSim, “BAUS”).
- It is a command-line Python application that ingests large spatial and tabular data sets, runs a multi-stage urban development simulation, generates summaries and metrics, and optionally publishes notifications (Slack/Asana) and a Tableau-based visualizer.

##### File structure
- Top-level entrypoint:
- baus.py
- run_setup*.yaml files (model run configurations)
- Core Python package (baus/):
- datasources.py (loads raw inputs)
- preprocessing.py (data cleaning & feature engineering)
- models.py, slr.py, earthquake.py, subsidies.py, ual.py (simulation sub-models)
- summaries/ (post-model summary functions by theme)
- slack.py, debug.py, utils.py, variables.py
- visualizer/ (Tableau workbook, scripts to push artifacts)
- Configuration (configs/):
- Nested YAML/CSV files by module (accessibility, hedonic pricing, location choice, adjusters, transition relocation, developer settings, etc.)
- Scripts (scripts/):
- Pre- & post-processing helpers, validation checks, capacity analysis, metrics calculators, data exports, notebook debugging, external forces analyses, strategy-building notebooks and utilities, JSON/HTTP serving (serve_json.py)
- Documentation (docs/, mkdocs.yml) and tests (baus/tests/)

##### Key insights from README
- Invocation: `python baus.py --run-setup run_setup.yaml [--disable-slack] [--enable-asana]`
- Requires a Conda environment (baus-env-2023.yml)
- Optional integrations: Slack SDK, Asana SDK
- Optional Model Run Visualizer published to Tableau

- Command-Line Interface (baus.py + CLI args)
- Configuration Loader (YAML: run_setup + configs/)
- Data Sources layer (raw inputs from MTC servers or local folders)
- Preprocessing module
- Simulation Engine with sub-models (location choice, developer, hedonic price, subsidies, SLR, earthquake impacts, etc.)
- Summaries & Metrics module
- Output Writers (CSV/GeoJSON/Hyper files, logs)
- Integrations:
– Slack notifications
– Asana task updates
– Tableau Visualizer (push_model_files.py → Tableau workbook)
- Supporting scripts & services (serve_json for real-time JSON queries)
b. Relationships & interactions:
- CLI → Configuration Loader
- Configuration → Data Sources + Preprocessing
- Preprocessing → Simulation Engine
- Simulation Engine → Summaries/ Metrics
- Summaries → Output Writers (files, DB)
- Output Writers → Integrations (Slack/Asana/Visualizer)
- Supporting scripts may consume outputs or invoke sub-modules directly
c. Architectural patterns & principles:
- Modular design: each simulation concern in its own module
- Config-driven: behavior controlled by YAML files
- Separation of concerns: data access, model logic, summarization, notification, visualization
- Extensibility: add new summaries, adjusters, or sub-models by dropping in YAML + Python files
d. Technologies & frameworks:
- Python 3.x, UrbanSim library
- Pandas, NumPy, HDF5 or SQL (as configured)
- YAML for configuration
- Slack SDK, Asana SDK
- Tableau (.twb/.twbx), serve_json (Flask or similar)

## Diagram (Mermaid)

```mermaid
graph TB
    %% Entrypoint and CLI
    CLI["CLI: baus.py"]:::core
    click CLI "https://github.com/bayareametro/bayarea_urbansim/blob/main/baus.py"

    %% Configuration
    ConfigLoader["Configuration Loader"]:::config
    click ConfigLoader "https://github.com/bayareametro/bayarea_urbansim/tree/main/configs/"

    %% Data Sources and Preprocessing
    DataSources["Data Sources"]:::core
    click DataSources "https://github.com/bayareametro/bayarea_urbansim/blob/main/baus/datasources.py"
    Preprocessing["Preprocessing"]:::core
    click Preprocessing "https://github.com/bayareametro/bayarea_urbansim/blob/main/baus/preprocessing.py"

    %% Simulation Engine
    subgraph "Simulation Engine" 
        direction TB
        LocationChoice["Location Choice (ual.py)"]:::core
        click LocationChoice "https://github.com/bayareametro/bayarea_urbansim/blob/main/baus/ual.py"
        Models["Model Orchestration (models.py)"]:::core
        click Models "https://github.com/bayareametro/bayarea_urbansim/blob/main/baus/models.py"
        SLR["Sea Level Rise (slr.py)"]:::core
        click SLR "https://github.com/bayareametro/bayarea_urbansim/blob/main/baus/slr.py"
        Earthquake["Earthquake (earthquake.py)"]:::core
        click Earthquake "https://github.com/bayareametro/bayarea_urbansim/blob/main/baus/earthquake.py"
        Subsidies["Subsidies (subsidies.py)"]:::core
        click Subsidies "https://github.com/bayareametro/bayarea_urbansim/blob/main/baus/subsidies.py"
    end

    %% Summaries & Metrics
    subgraph "Summaries & Metrics" 
        direction TB
        CoreSumm["core_summaries.py"]:::output
        click CoreSumm "https://github.com/bayareametro/bayarea_urbansim/blob/main/baus/summaries/core_summaries.py"
        AffordableSumm["affordable_housing_summaries.py"]:::output
        click AffordableSumm "https://github.com/bayareametro/bayarea_urbansim/blob/main/baus/summaries/affordable_housing_summaries.py"
        GeoSumm["geographic_summaries.py"]:::output
        click GeoSumm "https://github.com/bayareametro/bayarea_urbansim/blob/main/baus/summaries/geographic_summaries.py"
        HazardsSumm["hazards_summaries.py"]:::output
        click HazardsSumm "https://github.com/bayareametro/bayarea_urbansim/blob/main/baus/summaries/hazards_summaries.py"
        TravelSumm["travel_model_summaries.py"]:::output
        click TravelSumm "https://github.com/bayareametro/bayarea_urbansim/blob/main/baus/summaries/travel_model_summaries.py"
        Metrics["metrics.py"]:::output
        click Metrics "https://github.com/bayareametro/bayarea_urbansim/blob/main/baus/summaries/metrics.py"
    end

    %% Output Writers & Utilities
    Outputs["Output Writers & Utilities"]:::output
    Utils["utils.py"]:::output
    click Utils "https://github.com/bayareametro/bayarea_urbansim/blob/main/baus/utils.py"
    Vars["variables.py"]:::output
    click Vars "https://github.com/bayareametro/bayarea_urbansim/blob/main/baus/variables.py"

    %% Integrations and Helpers
    Slack["Slack Integration"]:::external
    click Slack "https://github.com/bayareametro/bayarea_urbansim/blob/main/baus/slack.py"
    Debug["Debug Helpers"]:::core
    click Debug "https://github.com/bayareametro/bayarea_urbansim/blob/main/baus/debug.py"

    subgraph "Tableau Visualizer" 
        direction TB
        VizDir["Visualizer Directory"]:::external
        click VizDir "https://github.com/bayareametro/bayarea_urbansim/tree/main/baus/visualizer/"
        Push["push_model_files.py"]:::external
        click Push "https://github.com/bayareametro/bayarea_urbansim/blob/main/baus/visualizer/push_model_files.py"
        TWB["BAUS_Visualizer_PBA50Plus.twb"]:::external
        click TWB "https://github.com/bayareametro/bayarea_urbansim/blob/main/baus/visualizer/BAUS_Visualizer_PBA50Plus.twb"
    end

    ServeJSON["JSON Service (serve_json.py)"]:::external
    click ServeJSON "https://github.com/bayareametro/bayarea_urbansim/blob/main/scripts/serve_json.py"

    %% Flow
    CLI --> ConfigLoader
    ConfigLoader --> DataSources
    ConfigLoader --> Preprocessing
    DataSources --> Preprocessing
    Preprocessing --> LocationChoice
    Preprocessing --> Models
    Preprocessing --> SLR
    Preprocessing --> Earthquake
    Preprocessing --> Subsidies
    LocationChoice --> CoreSumm
    Models --> CoreSumm
    SLR --> HazardsSumm
    Earthquake --> HazardsSumm
    Subsidies --> AffordableSumm
    CoreSumm --> Outputs
    AffordableSumm --> Outputs
    GeoSumm --> Outputs
    HazardsSumm --> Outputs
    TravelSumm --> Outputs
    Metrics --> Outputs
    Outputs --> Slack
    Outputs --> VizDir
    Outputs --> Debug
    Outputs -.-> ServeJSON

    %% Styles
    classDef core fill:#D0E9FF,stroke:#0288D1,stroke-width:1px;
    classDef config fill:#E0F7DA,stroke:#2E7D32,stroke-width:1px;
    classDef output fill:#FFF9C4,stroke:#F9A825,stroke-width:1px;
    classDef external fill:#FFE0B2,stroke:#EF6C00,stroke-width:1px;
```
