Working estimation mode and visualizer integration

.github/workflows/ci.yml

@@ -48,6 +48,15 @@ jobs:
           uv pip install -e . --no-deps
           uv pip list
 
+      # Clone the ActivitySim visualizer and build its virtual environment
+      - name: Set up ActivitySim visualizer
+        run: |
+          mkdir -p $GITHUB_WORKSPACE/ext_dependencies
+          cd $GITHUB_WORKSPACE/ext_dependencies
+          git clone --branch main https://github.com/RSGInc/activitysim_visualizer.git
+          cd activitysim_visualizer
+          uv sync
+
       # Run the test
       - name: Run Metro cropped example test
         run: |
@@ -97,3 +106,48 @@ jobs:
         run: |
           cd ../activitysim
           uv run python $GITHUB_WORKSPACE/resident/test/test_cropped_dataset_skats.py
+
+  lcog_cropped_example:
+    strategy:
+      matrix:
+        python-version:
+          - "3.10"
+      fail-fast: false
+
+    name: lcog-cropped-example-py${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      # Clone ActivitySim from SimOR_pnr branch
+      - name: Clone ActivitySim
+        run: |
+          cd ..
+          git clone --branch SimOR_pnr https://github.com/RSGInc/activitysim.git
+          pwd
+          ls -la
+
+      # Install UV
+      - name: Install UV
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      # Set up Python with UV
+      - name: Set up Python
+        run: uv python install ${{ matrix.python-version }}
+
+      # Install dependencies using UV and the lock file from ActivitySim
+      - name: Install dependencies with UV
+        run: |
+          cd ../activitysim
+          uv sync --frozen
+          uv pip install -e . --no-deps
+          uv pip list
+
+      # Run the test
+      - name: Run LCOG cropped example test
+        run: |
+          cd ../activitysim
+          uv run python $GITHUB_WORKSPACE/resident/test/test_cropped_dataset_lcog.py

.gitignore

@@ -2,6 +2,7 @@
 .vscode/*
 resident/model_data/metro/data_full/*
 resident/model_data/skats/data_full/*
+resident/model_data/lcog/data_full/*
 resident/outputs/*
 
 # Unit test / coverage reports

.vscode/launch.json

@@ -18,7 +18,92 @@
             ]
         },
         {
-            "name": "Run Cropped Example",
+            "name": "Metro Estimation Mode",
+            "type": "debugpy",
+            "request": "launch",
+            "cwd": "${workspaceFolder}/resident",
+            "program": "simulation.py",
+            "console": "integratedTerminal",
+            "args": [
+                "-c", "configs_estimation", // check the settings.yaml file for run settings!
+                "-c", "configs",
+                "-d", "model_data/metro/data_full",
+                "-o", "outputs/estimation_metro",
+            ]
+        },
+        {
+            "name": "SKATS Estimation Mode",
+            "type": "debugpy",
+            "request": "launch",
+            "cwd": "${workspaceFolder}/resident",
+            "program": "simulation.py",
+            "console": "integratedTerminal",
+            "args": [
+                "-c", "configs_skats",
+                "-c", "configs_estimation", // check the settings.yaml file for run settings!
+                "-c", "configs",
+                "-d", "model_data/skats/data_full",
+                "-o", "outputs/estimation_skats",
+            ]
+        },
+        {
+            "name": "LCOG Estimation Mode",
+            "type": "debugpy",
+            "request": "launch",
+            "cwd": "${workspaceFolder}/resident",
+            "program": "simulation.py",
+            "console": "integratedTerminal",
+            "args": [
+                "-c", "configs_estimation", // check the settings.yaml file for run settings!
+                "-c", "configs",
+                "-d", "model_data/lcog/data_full",
+                "-o", "outputs/estimation_lcog",
+            ]
+        },
+        {
+            "name": "CALM Estimation Mode",
+            "type": "debugpy",
+            "request": "launch",
+            "cwd": "${workspaceFolder}/resident",
+            "program": "simulation.py",
+            "console": "integratedTerminal",
+            "args": [
+                "-c", "configs_estimation", // check the settings.yaml file for run settings!
+                "-c", "configs",
+                "-d", "model_data/calm/data_full",
+                "-o", "outputs/estimation_calm",
+            ]
+        },
+        {
+            "name": "Bend Estimation Mode",
+            "type": "debugpy",
+            "request": "launch",
+            "cwd": "${workspaceFolder}/resident",
+            "program": "simulation.py",
+            "console": "integratedTerminal",
+            "args": [
+                "-c", "configs_estimation", // check the settings.yaml file for run settings!
+                "-c", "configs",
+                "-d", "model_data/bend/data_full",
+                "-o", "outputs/estimation_bend",
+            ]
+        },
+        {
+            "name": "Rogue Estimation Mode",
+            "type": "debugpy",
+            "request": "launch",
+            "cwd": "${workspaceFolder}/resident",
+            "program": "simulation.py",
+            "console": "integratedTerminal",
+            "args": [
+                "-c", "configs_estimation", // check the settings.yaml file for run settings!
+                "-c", "configs",
+                "-d", "model_data/rogue/data_full",
+                "-o", "outputs/estimation_rogue",
+            ]
+        },
+        {
+            "name": "Run Cropped Metro Example",
             "type": "debugpy",
             "request": "launch",
             "cwd": "${workspaceFolder}/resident",
@@ -27,7 +112,21 @@
             "args": [
                 "-c", "configs", // check the settings.yaml file for run settings!
                 "-d", "model_data/metro/data_cropped",
-                "-o", "outputs/cropped",
+                "-o", "outputs/metro_cropped",
+            ]
+        },
+        {
+            "name": "Run Cropped SKATS Example",
+            "type": "debugpy",
+            "request": "launch",
+            "cwd": "${workspaceFolder}/resident",
+            "program": "simulation.py",
+            "console": "integratedTerminal",
+            "args": [
+                "-c", "configs_skats",
+                "-c", "configs", // check the settings.yaml file for run settings!
+                "-d", "model_data/skats/data_cropped",
+                "-o", "outputs/skats_cropped",
             ]
         },
         {
@@ -94,5 +193,33 @@
                 "-o", "outputs/skats_cropped",
             ]
         },
+        {
+            "name": "Run LCOG",
+            "type": "debugpy",
+            "request": "launch",
+            "cwd": "${workspaceFolder}/resident",
+            "program": "simulation.py",
+            "console": "integratedTerminal",
+            "args": [
+                "-c", "configs_lcog",
+                "-c", "configs", // check the settings.yaml file for run settings!
+                "-d", "model_data/lcog/data_full",
+                "-o", "outputs/lcog",
+            ]
+        },
+        {
+            "name": "Run LCOG Cropped",
+            "type": "debugpy",
+            "request": "launch",
+            "cwd": "${workspaceFolder}/resident",
+            "program": "simulation.py",
+            "console": "integratedTerminal",
+            "args": [
+                "-c", "configs_lcog",
+                "-c", "configs", // check the settings.yaml file for run settings!
+                "-d", "model_data/lcog/data_cropped",
+                "-o", "outputs/lcog_cropped",
+            ]
+        },
     ]
 }

README.md

@@ -2,8 +2,39 @@
 Simulate Oregon (SimOR) - Oregon's Jointly Estimated ActivitySim Model
 ![image](SimOR.png)
 
+> [!WARNING]
+> This model is under active development, and the following instructions are subject to change.
+
+Please see this repo's Wiki page for more detailed information on this model.
+
+## Repository structure
+
+The repository is organized into the following major components:
+
+| Path | Purpose |
+|------|---------|
+| `runSIMOR.bat` | Top-level batch script that runs environment setup, skimming, preprocessing, and the current ActivitySim example run |
+| `setup_environment.bat` | Installs UV if needed, clones and updates external dependencies, creates Python environments, and installs required Visum Python packages |
+| `ext_dependencies/` | Cloned external repositories and their virtual environments, including ActivitySim, maz_skimming, and optionally sandag_parking |
+| `resident/` | ActivitySim model code, configurations, test cases, model input data, and outputs |
+| `resident/configs/` | Shared ActivitySim settings used across regions |
+| `resident/configs_*` | Region-specific ActivitySim settings, constants, and overrides such as `configs_skats`; additional region folders such as `configs_metro` or `configs_lcog` may be added over time |
+| `resident/model_data/` | Region-specific model inputs, including cropped example datasets and full datasets |
+| `skimming_and_assignment/visum/` | Visum runner scripts, procedure sequences, and version files used to build motorized skims and export network inputs |
+| `skimming_and_assignment/maz_maz_stop_skims/` | Non-motorized skim preprocessor and skim settings |
+| `misc/` | Miscellaneous analysis and support scripts |
+
 ## Running the model
 
+### Prerequisites
+
+Before running the model, make sure the following are available:
+
+1. PTV Visum 2026 with its bundled Python installation
+2. Git available on your system PATH or installed in a standard Windows location
+3. PowerShell with permission to run the UV installer invoked by `setup_environment.bat`
+4. Local write access to the Visum Python `site-packages` directory, or Administrator privileges if package installation there is restricted
+
 ### Setup
 
 1. **Configure `setup_environment.bat`**
@@ -12,27 +43,38 @@ Simulate Oregon (SimOR) - Oregon's Jointly Estimated ActivitySim Model
 
    | Variable | Description | Default |
    |----------|-------------|---------|
-   | `VISUM_PYTHON_DIR` | Folder containing your Visum 2026 Python interpreter | `C:\Program Files\PTV Vision\PTV Visum 2026\Exe\Junction_Preview\Python` |
-   | `INSTALL_PARKING` | Clone and install sandag_parking (`Y` or `N`) | `Y` |
+   | `VISUM_PYTHON_DIR` | Folder containing your Visum 2026 Python interpreter | `C:\Program Files\PTV Vision\PTV Visum 2026\Exe\Python` |
+   | `INSTALL_PARKING` | Clone and install sandag_parking (`Y` or `N`) | `N` |
 
    You can run this script on its own to install all dependencies without running the model:
    ```
    setup_environment.bat
    ```
-   It will install UV (if needed), clone and build the required repositories into `ext_dependencies/`, create the MAZ skimming Python environment from `ext_dependencies/maz_skimming/pyproject.toml`, and install the necessary Python packages into Visum's Python environment. On subsequent runs it detects existing installs and pulls the latest changes instead of re-cloning.
+   It will install UV (if needed), verify Git is available, clone and build the required repositories into `ext_dependencies/`, create the ActivitySim and MAZ skimming Python environments, and install the necessary Python packages into Visum's Python environment. On subsequent runs it detects existing installs and pulls the latest changes instead of re-cloning.
+
+   `sandag_parking` is not required for a typical model run. It is only needed when preparing land use inputs that require expected parking costs. In that workflow, it can be run once to generate the parking cost input file used by the preprocessor.
+
+   **If permissions errors arise, try running the setup with Administrator privileges. The Visum Python package install in particular may require elevated permissions.**
 
 2. **Place the Visum version file**
 
    Copy your Visum network version file (`.ver`) into `skimming_and_assignment/visum/`.
 
 3. **Update configuration files**
 
-   Edit the following files to match your local data paths and project settings:
+   Edit the following files to match your local data paths, region, and project settings:
 
    | File | Purpose |
    |------|---------|
-   | `skimming_and_assignment/maz_maz_stop_skims/2zoneSkim_params.yaml` | Non-motorized skim settings and file paths |
-   | `resident/preprocessor_settings.yaml` | Land use preprocessor input/output paths and network settings |
+   | `skimming_and_assignment/maz_maz_stop_skims/2zoneSkim_params.yaml` | Non-motorized skim settings, Visum export locations, network inputs, and skim outputs |
+   | `resident/preprocessor_settings.yaml` | Land use preprocessor input/output paths, network shapefiles, skim inputs, and optional parking or fare inputs |
+
+   At minimum, confirm that these files point to the correct local locations for:
+
+   1. Household, person, and land use CSV inputs
+   2. MAZ, node, and link shapefiles
+   3. Non-motorized skim inputs and outputs
+   4. Optional expected parking cost and transit fare inputs
 
 4. **Set user-defined variables in `runSIMOR.bat`**
 
@@ -42,6 +84,22 @@ Simulate Oregon (SimOR) - Oregon's Jointly Estimated ActivitySim Model
    |----------|-------------|
    | `VISUM_VERSION_FILE` | Filename of the Visum version file |
    | `PROCEDURE_SEQ` | Path to the Visum procedure sequence XML |
+   | `VISUM_PED_VERSION_FILE` | Optional pedestrian network Visum version file used when a separate pedestrian export is needed |
+   | `PED_PROCEDURE_SEQ` | Optional Visum procedure sequence for the pedestrian network export |
+
+### ActivitySim configuration layout
+
+ActivitySim settings are split into a shared configuration folder and optional region-specific configuration folders.
+
+- `resident/configs/` contains shared settings used across model regions.
+- Region-specific folders such as `resident/configs_skats/`, and future folders such as `resident/configs_metro/` or `resident/configs_lcog/`, contain region-specific constants and overrides.
+- When running a region-specific model, pass the region-specific config directory first and then the shared config directory so region overrides are applied before shared settings.
+
+For example:
+
+```bat
+python resident\simulation.py -c resident\configs_skats -c resident\configs -d resident\model_data\skats\data_cropped -o resident\outputs\test
+```
 
 ### Running the Pipeline
 
@@ -52,8 +110,23 @@ runSIMOR.bat
 
 The script automatically calls `setup_environment.bat` to ensure all dependencies are installed and Python paths are set, then runs the following steps in sequence:
 
-1. **Motorized skims** — Using Visum `Visum_Runner.py`. Automatically outputs required files to run non-motorized skims. 
+1. **Motorized skims** — Using Visum `Visum_Runner.py`. Automatically outputs required files to run non-motorized skims.
 2. **Non-motorized skim preprocessor** — Prepares walk network inputs via `2zoneSkim_preprocessor.py`.
 3. **Non-motorized skims** — Computes MAZ-to-MAZ and MAZ-to-stop walk skims via `2zoneSkim.py`.
 4. **Land use preprocessor** — Builds ActivitySim-ready land use table via `preprocessor.py`.
-5. **Run ActivitySim** -- Runs ActivitySim -- (not yet implemented)
+5. **Run ActivitySim** — Runs the current ActivitySim example configured in `runSIMOR.bat`.
+
+At present, the ActivitySim command in `runSIMOR.bat` runs the Metro cropped example dataset:
+
+```bat
+python resident\simulation.py -c resident\configs -d resident\model_data\metro\data_cropped -o outputs\cropped
+```
+
+This is a smoke-test style example run, not yet a generalized full-region launcher for all supported scenarios.
+
+### Expected inputs and outputs
+
+- Visum produces the motorized skims and exported network files consumed by the non-motorized skim workflow.
+- The non-motorized skim tools produce files such as `maz_maz_walk.csv` and `maz_stop_walk.csv` for use by the land use preprocessor and ActivitySim.
+- The land use preprocessor reads the configured raw model inputs and writes updated ActivitySim-ready tables to the configured output directory.
+- ActivitySim writes model outputs to the output folder passed on the command line.