Upload 11 files

pages/10_🧠_AI_Link_Flow_Emulator.py

@@ -0,0 +1,105 @@
+# pages/10_🧠_AI_Link_Flow_Emulator.py
+
+import streamlit as st
+import pandas as pd
+import numpy as np
+import os
+
+from modules.ai_link_flow_emulator import (
+    train_link_flow_emulator,
+    predict_link_flows,
+)
+from modules.route_assignment import generate_synthetic_network
+
+st.set_page_config(layout="wide")
+st.title("🧠 AI Link Flow Emulator")
+
+# -----------------------------------------------------
+# CHECK REQUIRED STATE
+# -----------------------------------------------------
+if "mode_choice" not in st.session_state:
+    st.error("Run Mode Choice first (Page 4).")
+    st.stop()
+
+if "city" not in st.session_state:
+    st.error("Generate synthetic city first (Page 1).")
+    st.stop()
+
+city = st.session_state["city"]
+taz = city.taz
+mode_choice = st.session_state["mode_choice"]
+
+# Use car OD as baseline demand
+base_car_od = mode_choice.volumes["car"]
+base_car_od_np = base_car_od.to_numpy()
+
+# -----------------------------------------------------
+# NETWORK
+# -----------------------------------------------------
+if "network" not in st.session_state:
+    network = generate_synthetic_network(taz)
+    st.session_state["network"] = network
+else:
+    network = st.session_state["network"]
+
+st.markdown("### Network Summary")
+st.write(f"Number of links: **{len(network)}**")
+
+# -----------------------------------------------------
+# TRAINING SCENARIOS
+# -----------------------------------------------------
+n_scenarios = st.slider(
+    "Number of training scenarios to generate",
+    min_value=5, max_value=100, value=20, step=1,
+    help="More scenarios → better emulator accuracy, slower training."
+)
+
+if st.button("Train Emulator"):
+    st.info("Training emulator… please wait.")
+
+    emulator, training_history = train_link_flow_emulator(
+        base_car_od_np,
+        network,
+        n_scenarios=n_scenarios
+    )
+
+    st.session_state["link_flow_emulator"] = emulator
+    st.session_state["emulator_training_history"] = training_history
+
+    st.success("AI Link Flow Emulator trained successfully!")
+
+# -----------------------------------------------------
+# PREDICTION MODULE
+# -----------------------------------------------------
+if "link_flow_emulator" in st.session_state:
+    emulator = st.session_state["link_flow_emulator"]
+
+    st.header("📡 Predict New Link Flows with AI")
+    scale = st.slider(
+        "Demand scaling factor",
+        min_value=0.5, max_value=1.5, value=1.0, step=0.05,
+        help="Scale baseline OD (e.g., 1.2 = +20% demand)"
+    )
+
+    if st.button("Predict Link Flows"):
+        pred_df = predict_link_flows(emulator, scale, network)
+
+        st.subheader("AI Predicted Link Flows (sample)")
+        st.dataframe(pred_df.head(12))
+
+        # Save output
+        os.makedirs("data", exist_ok=True)
+        pred_df.to_csv("data/emulator_predicted_link_flows.csv", index=False)
+        st.success("Predicted flows saved to /data/emulator_predicted_link_flows.csv")
+
+        # Download button
+        csv_bytes = pred_df.to_csv(index=False).encode("utf-8")
+        st.download_button(
+            label="⬇ Download Predicted Link Flows (CSV)",
+            data=csv_bytes,
+            file_name="predicted_link_flows_ai.csv",
+            mime="text/csv"
+        )
+
+else:
+    st.info("Train the emulator to enable AI predictions.")

pages/11_🎯_Scenario_Optimization.py

@@ -0,0 +1,228 @@
+# pages/11_🎯_Scenario_Optimization.py
+
+import streamlit as st
+import numpy as np
+import pandas as pd
+import os
+
+from typing import Dict
+
+from modules.route_assignment import generate_synthetic_network, frank_wolfe_ue
+from modules.ai_link_flow_emulator import predict_link_flows
+
+st.set_page_config(layout="wide")
+st.title("🎯 Scenario Optimization Engine")
+
+# ------------------------------------------------------
+# CHECK REQUIRED STATE
+# ------------------------------------------------------
+required_keys = ["city", "productions", "attractions", "od", "mode_choice"]
+missing = [k for k in required_keys if k not in st.session_state]
+if missing:
+    st.error(f"Please complete earlier steps first. Missing: {', '.join(missing)}")
+    st.stop()
+
+city = st.session_state["city"]
+taz = city.taz
+od_base_dict: Dict[str, pd.DataFrame] = st.session_state["od"]
+mode_choice_base = st.session_state["mode_choice"]
+tt_car_base = city.travel_time_matrix
+
+# ------------------------------------------------------
+# NETWORK
+# ------------------------------------------------------
+if "network" not in st.session_state:
+    network = generate_synthetic_network(taz)
+    st.session_state["network"] = network
+else:
+    network = st.session_state["network"]
+
+od_total_car = mode_choice_base.volumes["car"]
+
+
+# ------------------------------------------------------
+# REUSE POLICY MODE CHOICE LOGIC (copied from Page 8)
+# ------------------------------------------------------
+def build_policy_time_cost_matrices(
+        tt_car_base: pd.DataFrame,
+        metro_time_reduction_pct: float,
+        metro_fare_change_pct: float,
+        congestion_charge: float,
+        cbd_zones: list
+):
+    tt_car = tt_car_base.copy()
+    tt_metro = tt_car * 0.8 * (1 - metro_time_reduction_pct / 100.0)
+    tt_bus = tt_car * 1.3
+
+    dist_proxy = tt_car / 60 * 30
+    cost_car = 2 + 0.12 * dist_proxy
+    cost_metro = 15 * (1 + metro_fare_change_pct / 100.0)
+    cost_bus = 8 + 0.03 * dist_proxy
+
+    # Vectorized congestion charge
+    cost_car.loc[:, cbd_zones] += congestion_charge
+
+    return (
+        {"car": tt_car, "metro": tt_metro, "bus": tt_bus},
+        {"car": cost_car, "metro": cost_metro, "bus": cost_bus},
+    )
+
+
+def policy_mode_choice(
+        od_mats: dict,
+        taz: pd.DataFrame,
+        tt_car_base: pd.DataFrame,
+        metro_time_reduction_pct: float,
+        metro_fare_change_pct: float,
+        congestion_charge: float,
+        cbd_zones: list,
+        beta_time: float = -0.06,
+        beta_cost: float = -0.03,
+        beta_car_own: float = 0.5
+):
+    zones = tt_car_base.index
+    total_od = sum(od_mats.values()).loc[zones, zones]
+
+    time_mats, cost_mats = build_policy_time_cost_matrices(
+        tt_car_base,
+        metro_time_reduction_pct,
+        metro_fare_change_pct,
+        congestion_charge,
+        cbd_zones,
+    )
+
+    car_own = taz["car_ownership_rate"].reindex(zones).to_numpy()
+    car_own_mat = np.repeat(car_own[:, None], len(zones), axis=1)
+
+    modes = ["car", "metro", "bus"]
+    utilities = {}
+
+    for mode in modes:
+        tt = time_mats[mode].to_numpy()
+        cc = cost_mats[mode].to_numpy()
+
+        if mode == "car":
+            U = beta_time * tt + beta_cost * cc + beta_car_own * car_own_mat
+        else:
+            U = beta_time * tt + beta_cost * cc
+
+        utilities[mode] = U
+
+    exp_sum = sum(np.exp(U) for U in utilities.values())
+    probabilities = {
+        m: pd.DataFrame(np.exp(U) / np.maximum(exp_sum, 1e-12), index=zones, columns=zones)
+        for m, U in utilities.items()
+    }
+
+    volumes = {
+        m: pd.DataFrame(
+            total_od.to_numpy() * probabilities[m].to_numpy(),
+            index=zones, columns=zones
+        )
+        for m in modes
+    }
+
+    return probabilities, volumes, total_od
+
+
+# ------------------------------------------------------
+# UI OPTIONS
+# ------------------------------------------------------
+use_emulator = st.checkbox(
+    "Use AI Link Flow Emulator (if trained)",
+    value=False
+)
+
+st.sidebar.header("Search Space")
+
+mt_min = st.sidebar.slider("Metro time reduction min (%)", 0, 50, 0)
+mt_max = st.sidebar.slider("Metro time reduction max (%)", 0, 50, 30)
+mt_step = st.sidebar.slider("Metro step (%)", 5, 20, 10)
+
+fare_min = st.sidebar.slider("Metro fare change min (%)", -50, 50, -30)
+fare_max = st.sidebar.slider("Metro fare change max (%)", -50, 50, 10)
+fare_step = st.sidebar.slider("Metro fare step (%)", 10, 30, 20)
+
+cc_min = st.sidebar.slider("Congestion charge min", 0, 100, 0)
+cc_max = st.sidebar.slider("Congestion charge max", 0, 100, 50)
+cc_step = st.sidebar.slider("Charge step", 10, 50, 20)
+
+default_cbd = list(taz.index[:5])
+cbd_zones = st.sidebar.multiselect(
+    "CBD zones",
+    options=list(taz.index),
+    default=default_cbd,
+)
+
+objective_choice = st.selectbox(
+    "Optimization Objective",
+    ["Minimize total car trips", "Minimize total car link flow"]
+)
+
+
+# ------------------------------------------------------
+# OPTIMIZATION ENGINE
+# ------------------------------------------------------
+if st.button("Run Optimization Search"):
+    st.info("Running optimization… may take some time.")
+
+    metro_range = np.arange(mt_min, mt_max + 1e-6, mt_step)
+    fare_range = np.arange(fare_min, fare_max + 1e-6, fare_step)
+    cc_range = np.arange(cc_min, cc_max + 1e-6, cc_step)
+
+    emulator = st.session_state.get("link_flow_emulator", None)
+    results = []
+
+    for mt_red in metro_range:
+        for fare_ch in fare_range:
+            for cc in cc_range:
+
+                probs, vols, total_od = policy_mode_choice(
+                    od_base_dict, taz, tt_car_base,
+                    mt_red, fare_ch, cc, cbd_zones
+                )
+
+                car_od = vols["car"]
+                total_car_trips = car_od.values.sum()
+
+                if use_emulator and emulator is not None:
+                    base = od_total_car.values.sum()
+                    demand_scale = float(total_car_trips / max(base, 1e-9))
+                    df_flows = predict_link_flows(emulator, demand_scale, network)
+
+                    col = "flow_vehph_emulated" if "flow_vehph_emulated" in df_flows.columns else df_flows.columns[-1]
+                    total_car_flow = df_flows[col].sum()
+                else:
+                    df_flows = frank_wolfe_ue(car_od, network, max_iter=30)
+                    col = "flow_vehph" if "flow_vehph" in df_flows.columns else df_flows.columns[-1]
+                    total_car_flow = df_flows[col].sum()
+
+                objective_value = total_car_trips if objective_choice.startswith("Minimize total car trips") else total_car_flow
+
+                results.append({
+                    "metro_time_reduction_pct": mt_red,
+                    "metro_fare_change_pct": fare_ch,
+                    "congestion_charge": cc,
+                    "total_car_trips": total_car_trips,
+                    "total_car_flow": total_car_flow,
+                    "objective": objective_value
+                })
+
+    res_df = pd.DataFrame(results)
+    res_sorted = res_df.sort_values("objective", ascending=True).reset_index(drop=True)
+
+    st.subheader("Top 10 Best Scenarios")
+    st.dataframe(res_sorted.head(10))
+
+    # Save results
+    os.makedirs("data", exist_ok=True)
+    res_sorted.to_csv("data/optimization_results.csv", index=False)
+
+    st.session_state["opt_results"] = res_sorted
+
+    best = res_sorted.iloc[0]
+    st.success(
+        f"Best scenario: Metro time ↓{best['metro_time_reduction_pct']}%, "
+        f"Metro fare {best['metro_fare_change_pct']}%, "
+        f"Charge={best['congestion_charge']} → Objective={best['objective']:.2f}"
+    )

pages/1_📊_Generate_Synthetic_City.py

@@ -0,0 +1,158 @@
+# modules/synthetic_city.py
+# TripAI – Synthetic City Generator (20 TAZ by default)
+
+from __future__ import annotations
+from dataclasses import dataclass
+from typing import Optional
+
+import numpy as np
+import pandas as pd
+
+
+# Global defaults
+RANDOM_SEED = 42
+NUM_ZONES_DEFAULT = 20
+
+
+@dataclass
+class SyntheticCity:
+    """
+    Container for synthetic city data.
+    """
+    taz: pd.DataFrame                 # TAZ-level attributes
+    distance_matrix: pd.DataFrame     # inter-TAZ distances (km)
+    travel_time_matrix: pd.DataFrame  # inter-TAZ travel times (minutes)
+
+
+def generate_synthetic_city(
+    num_zones: int = NUM_ZONES_DEFAULT,
+    seed: Optional[int] = RANDOM_SEED
+) -> SyntheticCity:
+    """
+    Generate a synthetic metropolitan region with a specified number of
+    Traffic Analysis Zones (TAZs).
+
+    Outputs:
+    - taz: DataFrame indexed by TAZ id with socio-economic attributes
+    - distance_matrix: symmetric TAZ-to-TAZ distances (km)
+    - travel_time_matrix: car travel time (minutes)
+
+    Parameters
+    ----------
+    num_zones : int
+        Number of zones (TAZ) to generate. Default = 20.
+    seed : int, optional
+        Random seed for reproducibility.
+
+    Returns
+    -------
+    SyntheticCity
+    """
+    rng = np.random.default_rng(seed)
+
+    # ---------------------------------------------------------
+    # 1. Generate basic spatial layout (coordinates)
+    # ---------------------------------------------------------
+    # City spread over roughly 10 x 10 km area
+    x = rng.uniform(0, 10, size=num_zones)
+    y = rng.uniform(0, 10, size=num_zones)
+
+    # ---------------------------------------------------------
+    # 2. Socio-economic attributes at TAZ level
+    # ---------------------------------------------------------
+
+    # Population distribution (clip to avoid negative / too small)
+    population = rng.normal(loc=25000, scale=5000, size=num_zones)
+    population = np.clip(population, 8000, None).astype(int)
+
+    # Average household size ~3.2 with small variation
+    hh_size = rng.normal(loc=3.2, scale=0.3, size=num_zones)
+    households = (population / np.maximum(hh_size, 1.5)).astype(int)
+
+    # Workers and students as shares of population
+    workers = (population * rng.uniform(0.35, 0.45, size=num_zones)).astype(int)
+    students = (population * rng.uniform(0.20, 0.30, size=num_zones)).astype(int)
+
+    # Monthly income (arbitrary units), lognormal
+    income = rng.lognormal(mean=10.0, sigma=0.4, size=num_zones)
+
+    # Car ownership rate as a sigmoid of income
+    def sigmoid(z):
+        return 1.0 / (1.0 + np.exp(-z))
+
+    car_ownership_rate = sigmoid(0.00003 * income - 3.0)
+    cars = (
+        car_ownership_rate
+        * households
+        * rng.uniform(0.8, 1.2, size=num_zones)
+    ).astype(int)
+
+    # Land-use mix index (0–1)
+    land_use_mix = rng.uniform(0.2, 0.9, size=num_zones)
+
+    # Jobs and floor area
+    service_jobs = (workers * rng.uniform(0.8, 1.4, size=num_zones)).astype(int)
+    industrial_jobs = (workers * rng.uniform(0.3, 0.8, size=num_zones)).astype(int)
+    retail_jobs = (workers * rng.uniform(0.3, 0.7, size=num_zones)).astype(int)
+
+    school_capacity = (students * rng.uniform(1.1, 1.5, size=num_zones)).astype(int)
+    retail_floor_area = retail_jobs * rng.uniform(20, 40, size=num_zones)  # arbitrary units
+
+    # Build TAZ DataFrame
+    taz_df = pd.DataFrame({
+        "TAZ": np.arange(1, num_zones + 1),
+        "x_km": x,
+        "y_km": y,
+        "population": population,
+        "households": households,
+        "workers": workers,
+        "students": students,
+        "income": income,
+        "car_ownership_rate": car_ownership_rate,
+        "cars": cars,
+        "land_use_mix": land_use_mix,
+        "service_jobs": service_jobs,
+        "industrial_jobs": industrial_jobs,
+        "retail_jobs": retail_jobs,
+        "school_capacity": school_capacity,
+        "retail_floor_area": retail_floor_area,
+    }).set_index("TAZ")
+
+    # ---------------------------------------------------------
+    # 3. Distance & travel time matrices
+    # ---------------------------------------------------------
+    coords = taz_df[["x_km", "y_km"]].to_numpy()
+    dx = coords[:, 0][:, None] - coords[:, 0][None, :]
+    dy = coords[:, 1][:, None] - coords[:, 1][None, :]
+    dist_km = np.sqrt(dx**2 + dy**2)
+
+    # Average car speed (km/h) and base travel times (minutes)
+    avg_speed_kmh = rng.uniform(25, 35)
+    tt_base = (dist_km / np.maximum(avg_speed_kmh, 1e-3)) * 60.0  # minutes
+
+    # Add random terminal / intersection delays (3–8 minutes)
+    tt_matrix = tt_base + rng.uniform(3, 8, size=(num_zones, num_zones))
+
+    # Intra-zonal adjustment (short distances and times)
+    np.fill_diagonal(dist_km, rng.uniform(0.2, 0.5, size=num_zones))
+    np.fill_diagonal(tt_matrix, rng.uniform(3, 5, size=num_zones))
+
+    distance_df = pd.DataFrame(
+        dist_km,
+        index=taz_df.index,
+        columns=taz_df.index,
+    )
+    travel_time_df = pd.DataFrame(
+        tt_matrix,
+        index=taz_df.index,
+        columns=taz_df.index,
+    )
+
+    # ---------------------------------------------------------
+    # 4. Return SyntheticCity object
+    # ---------------------------------------------------------
+    return SyntheticCity(
+        taz=taz_df,
+        distance_matrix=distance_df,
+        travel_time_matrix=travel_time_df,
+    )

pages/2_🚶_Trip_Generation.py

@@ -0,0 +1,33 @@
+import streamlit as st
+from modules.trip_generation import trip_generation
+import pandas as pd
+import os
+
+st.title("🚶 Trip Generation")
+
+if "city" not in st.session_state:
+    st.error("Please generate the synthetic city first.")
+    st.stop()
+
+city = st.session_state["city"]
+
+if st.button("Run Trip Generation"):
+    P, A = trip_generation(city.taz)
+    st.session_state["productions"] = P
+    st.session_state["attractions"] = A
+    st.success("Trip generation completed!")
+
+if "productions" in st.session_state:
+    P = st.session_state["productions"]
+    A = st.session_state["attractions"]
+
+    st.subheader("Productions")
+    st.dataframe(P)
+
+    st.subheader("Attractions (Balanced)")
+    st.dataframe(A)
+
+    os.makedirs("data", exist_ok=True)
+    P.to_csv("data/productions.csv")
+    A.to_csv("data/attractions.csv")
+    st.info("Saved to /data/")

pages/3_🌍_Trip_Distribution.py

@@ -0,0 +1,42 @@
+import streamlit as st
+from modules.gravity_model import build_all_od_matrices
+import pandas as pd
+import os
+
+st.title("🌍 Trip Distribution – Gravity Model")
+
+# --------------------------------------------------
+# CHECK PREVIOUS STEPS
+# --------------------------------------------------
+if "productions" not in st.session_state:
+    st.error("Please complete Trip Generation first.")
+    st.stop()
+
+# --------------------------------------------------
+# RUN GRAVITY MODEL
+# --------------------------------------------------
+if st.button("Run Gravity Model"):
+    P = st.session_state["productions"]
+    A = st.session_state["attractions"]
+    TT = st.session_state["city"].travel_time_matrix
+
+    od_mats = build_all_od_matrices(P, A, TT)
+
+    st.session_state["od"] = od_mats
+    st.success("Trip distribution completed!")
+
+# --------------------------------------------------
+# DISPLAY RESULTS
+# --------------------------------------------------
+if "od" in st.session_state:
+    od = st.session_state["od"]
+
+    os.makedirs("data", exist_ok=True)
+
+    for purpose, mat in od.items():
+        st.subheader(f"OD Matrix – {purpose}")
+        st.dataframe(mat)
+
+        mat.to_csv(f"data/od_{purpose}.csv")
+
+    st.info("OD matrices saved to /data/")

pages/4_🚈_Mode_Choice.py

@@ -0,0 +1,47 @@
+import streamlit as st
+from modules.mode_choice import mode_choice
+import os
+
+st.title("🚈 Mode Choice – Multinomial Logit")
+
+# -----------------------------------------
+# CHECK PREVIOUS STEPS
+# -----------------------------------------
+if "od" not in st.session_state:
+    st.error("Please run Trip Distribution first.")
+    st.stop()
+
+# -----------------------------------------
+# RUN MODE CHOICE
+# -----------------------------------------
+if st.button("Run Mode Choice"):
+    result = mode_choice(
+        st.session_state["od"],
+        st.session_state["city"].taz,
+        st.session_state["city"].travel_time_matrix
+    )
+    st.session_state["mode_choice"] = result
+    st.success("Mode choice completed!")
+
+# -----------------------------------------
+# DISPLAY RESULTS
+# -----------------------------------------
+if "mode_choice" in st.session_state:
+
+    result = st.session_state["mode_choice"]
+
+    st.subheader("Total OD Matrix (all purposes)")
+    st.dataframe(result.total_od)
+
+    # ensure save folder exists
+    os.makedirs("data", exist_ok=True)
+
+    # save & display mode-specific OD volumes
+    for m in result.volumes:
+        st.subheader(f"Mode: {m}")
+        st.dataframe(result.volumes[m])
+
+        # Save to CSV
+        result.volumes[m].to_csv(f"data/od_mode_{m}.csv")
+
+    st.info("Mode-choice outputs saved to /data/")

pages/5_🛣️_Route_Assignment.py

@@ -0,0 +1,67 @@
+# pages/5_🛣️_Route_Assignment.py
+
+import streamlit as st
+import os
+
+from modules.route_assignment import (
+    generate_synthetic_network,
+    aon_assignment,
+    frank_wolfe_ue,
+)
+
+st.title("🛣️ Route Assignment – AON & UE")
+
+# ------------------------------------------------
+# CHECK MODE CHOICE
+# ------------------------------------------------
+if "mode_choice" not in st.session_state:
+    st.error("Run Mode Choice first (Page 4).")
+    st.stop()
+
+mode_choice = st.session_state["mode_choice"]
+city = st.session_state["city"]
+taz = city.taz
+
+# ------------------------------------------------
+# CHOOSE METHOD
+# ------------------------------------------------
+assignment_type = st.selectbox(
+    "Select assignment method",
+    ["All-or-Nothing (AON)", "User Equilibrium (UE – Frank–Wolfe)"]
+)
+
+# ------------------------------------------------
+# RUN ASSIGNMENT
+# ------------------------------------------------
+if st.button("Generate Network & Run Assignment"):
+
+    # Generate or load network
+    if "network" in st.session_state:
+        network = st.session_state["network"]
+    else:
+        network = generate_synthetic_network(taz)
+        st.session_state["network"] = network
+
+    # Use car OD matrix only
+    car_od = mode_choice.volumes["car"]
+
+    if assignment_type.startswith("All"):
+        link_flows = aon_assignment(car_od, network)
+        st.session_state["link_flows"] = link_flows
+        st.success("All-or-Nothing assignment completed.")
+    else:
+        link_flows_ue = frank_wolfe_ue(car_od, network)
+        st.session_state["link_flows"] = link_flows_ue
+        st.success("User Equilibrium (Frank–Wolfe) assignment completed.")
+
+# ------------------------------------------------
+# DISPLAY RESULTS
+# ------------------------------------------------
+if "link_flows" in st.session_state:
+    st.subheader("Assigned Link Flows (sample)")
+    st.dataframe(st.session_state["link_flows"].head(12))
+
+    # Save to /data/
+    os.makedirs("data", exist_ok=True)
+    st.session_state["link_flows"].to_csv("data/link_flows.csv")
+    st.info("Link flows saved to /data/")

pages/6_🤖_AI_Enhanced_Models.py

@@ -0,0 +1,187 @@
+import streamlit as st
+import pandas as pd
+import numpy as np
+import shap
+import matplotlib.pyplot as plt
+import os
+
+from sklearn.ensemble import RandomForestRegressor, RandomForestClassifier
+from sklearn.model_selection import train_test_split
+from sklearn.metrics import mean_absolute_error, r2_score, accuracy_score
+
+st.set_page_config(layout="wide")
+st.title("🤖 AI-Enhanced Four-Step Model")
+
+st.markdown("""
+This module introduces **Machine Learning + Explainable AI (XAI)** to improve:
+- **Trip Generation (Regression Model)**
+- **Mode Choice (Classification Model)**
+- **Behavioral Interpretation using SHAP**
+
+Use this page *after* completing Steps 1–5.
+""")
+
+# -------------------------------------------------------
+# CHECK DATA
+# -------------------------------------------------------
+if "city" not in st.session_state:
+    st.error("Please generate the synthetic city first (Page 1).")
+    st.stop()
+
+if "productions" not in st.session_state:
+    st.error("Please complete Trip Generation (Page 2).")
+    st.stop()
+
+if "mode_choice" not in st.session_state:
+    st.error("Please complete Mode Choice (Page 4).")
+    st.stop()
+
+# Load needed data
+taz = st.session_state["city"].taz
+productions = st.session_state["productions"]
+mode_choice_result = st.session_state["mode_choice"]
+
+# -------------------------------------------------------
+# SECTION 1 — AI Trip Generation (Regression)
+# -------------------------------------------------------
+st.header("🚶 AI-based Trip Generation (Regression)")
+
+purpose = st.selectbox(
+    "Select Trip Purpose to Model",
+    ["HBW", "HBE", "HBS"]
+)
+
+X = taz[[
+    "population", "households", "workers", "students",
+    "income", "car_ownership_rate", "land_use_mix",
+    "service_jobs", "industrial_jobs", "retail_jobs"
+]]
+
+y = productions[purpose]
+
+if st.button("Train AI Trip Generation Model"):
+    X_train, X_test, y_train, y_test = train_test_split(
+        X, y, test_size=0.25, random_state=42
+    )
+
+    model = RandomForestRegressor(
+        n_estimators=300,
+        max_depth=10,
+        random_state=42
+    )
+    model.fit(X_train, y_train)
+
+    y_pred = model.predict(X_test)
+
+    mae = mean_absolute_error(y_test, y_pred)
+    r2 = r2_score(y_test, y_pred)
+
+    st.success("AI Regression Model Trained!")
+    st.write(f"**MAE:** {mae:.2f}")
+    st.write(f"**R²:** {r2:.3f}")
+
+    st.session_state["ai_tripgen_model"] = model
+
+    st.subheader("🔍 SHAP Explanation of Trip Generation Model")
+    explainer = shap.Explainer(model, X_train)
+    shap_values = explainer(X_train)
+
+    shap.plots.bar(shap_values, max_display=10, show=False)
+    fig = plt.gcf()
+    st.pyplot(fig)
+
+# -------------------------------------------------------
+# SECTION 2 — AI Mode Choice (Classification)
+# -------------------------------------------------------
+st.header("🚈 AI-based Mode Choice (Classification)")
+
+vol = mode_choice_result.volumes
+P = mode_choice_result.probabilities
+
+rows = []
+zones = list(taz.index)
+TT = st.session_state["city"].travel_time_matrix
+
+for i in zones:
+    for j in zones:
+        if i == j:
+            continue
+
+        probs = [
+            P["car"].loc[i, j],
+            P["metro"].loc[i, j],
+            P["bus"].loc[i, j]
+        ]
+
+        # Normalize probabilities (avoid zero-sum)
+        s = sum(probs)
+        if s == 0:
+            continue
+        probs = [p / s for p in probs]
+
+        label = np.random.choice(["car", "metro", "bus"], p=probs)
+
+        rows.append({
+            "origin": i,
+            "destination": j,
+            "travel_time": TT.loc[i, j],
+            "car_ownership": float(taz.loc[i, "car_ownership_rate"]),
+            "cost_car": 2 + 0.1 * TT.loc[i, j],
+            "cost_metro": 15,
+            "cost_bus": 8,
+            "label": label
+        })
+
+df_mc = pd.DataFrame(rows)
+
+feature_cols = ["travel_time", "car_ownership", "cost_car", "cost_metro", "cost_bus"]
+X_mc = df_mc[feature_cols]
+y_mc = df_mc["label"]
+
+if st.button("Train AI Mode Choice Classifier"):
+    X_train, X_test, y_train, y_test = train_test_split(
+        X_mc, y_mc, test_size=0.25, random_state=42, stratify=y_mc
+    )
+
+    clf = RandomForestClassifier(
+        n_estimators=300,
+        max_depth=12,
+        class_weight="balanced",
+        random_state=42
+    )
+    clf.fit(X_train, y_train)
+
+    y_pred = clf.predict(X_test)
+    acc = accuracy_score(y_test, y_pred)
+
+    st.success("AI Mode Choice Classifier Trained!")
+    st.write(f"**Accuracy:** {acc:.3f}")
+
+    st.session_state["ai_modechoice_model"] = clf
+
+    st.subheader("🔍 SHAP Explanation for Mode Choice")
+
+    explainer = shap.Explainer(clf, X_train)
+    shap_values = explainer(X_train)
+
+    shap.plots.bar(shap_values, max_display=10, show=False)
+    fig2 = plt.gcf()
+    st.pyplot(fig2)
+
+# -------------------------------------------------------
+# SECTION 3 — Summary
+# -------------------------------------------------------
+st.header("📘 Interpretation Summary")
+
+st.markdown("""
+### ✔ Completed:
+- **AI Regression for Trip Generation**
+- **AI Classification for Mode Choice**
+- **SHAP-based Explainability**
+
+### ✔ Enables:
+- Hybrid classical–AI modelling  
+- Behavioral insights  
+- Scenario sensitivity  
+- Publishable Q1-grade figures  
+""")

pages/7_📦_Export_Results.py

@@ -0,0 +1,157 @@
+import streamlit as st
+import pandas as pd
+import os
+import zipfile
+from io import BytesIO
+
+st.set_page_config(layout="wide")
+st.title("📦 Export Results")
+
+st.markdown("""
+This module allows you to **download full outputs** from all steps of the Four-Step Model:
+
+- Synthetic City (TAZ data)
+- Trip Generation
+- Trip Distribution (OD matrices)
+- Mode Choice (volumes + probabilities)
+- Route Assignment (link flows)
+- AI Model Outputs (regression, classification)
+""")
+
+# Ensure data folder exists
+os.makedirs("data", exist_ok=True)
+
+# ------------------------------------------------------
+# Helper: Save CSV to buffer
+# ------------------------------------------------------
+def make_csv_download(df: pd.DataFrame, filename: str):
+    csv = df.to_csv().encode("utf-8")
+    st.download_button(
+        label=f"⬇ Download {filename}",
+        data=csv,
+        file_name=filename,
+        mime="text/csv"
+    )
+
+# ------------------------------------------------------
+# Helper: Create ZIP file dynamically
+# ------------------------------------------------------
+def build_zip_file():
+    buffer = BytesIO()
+    with zipfile.ZipFile(buffer, "w", zipfile.ZIP_DEFLATED) as z:
+
+        if "city" in st.session_state:
+            city = st.session_state["city"]
+            z.writestr("taz_attributes.csv", city.taz.to_csv())
+            z.writestr("distance_matrix.csv", city.distance_matrix.to_csv())
+            z.writestr("travel_time_matrix.csv", city.travel_time_matrix.to_csv())
+
+        if "productions" in st.session_state:
+            z.writestr("productions.csv", st.session_state["productions"].to_csv())
+        if "attractions" in st.session_state:
+            z.writestr("attractions.csv", st.session_state["attractions"].to_csv())
+
+        if "od" in st.session_state:
+            for p, df in st.session_state["od"].items():
+                z.writestr(f"od_{p}.csv", df.to_csv())
+
+        if "mode_choice" in st.session_state:
+            mc = st.session_state["mode_choice"]
+            z.writestr("total_od.csv", mc.total_od.to_csv())
+            for m, df in mc.volumes.items():
+                z.writestr(f"od_mode_{m}.csv", df.to_csv())
+            for m, df in mc.probabilities.items():
+                z.writestr(f"mode_prob_{m}.csv", df.to_csv())
+
+        if "link_flows" in st.session_state:
+            link_flows = st.session_state["link_flows"]
+            z.writestr("link_flows.csv", link_flows.to_csv())
+
+        # AI models not serializable → export predictions & metadata only
+        if "ai_tripgen_model" in st.session_state:
+            model = st.session_state["ai_tripgen_model"]
+            city = st.session_state["city"]
+            preds = model.predict(city.taz[[
+                "population","households","workers","students",
+                "income","car_ownership_rate","land_use_mix",
+                "service_jobs","industrial_jobs","retail_jobs"
+            ]])
+            pred_df = pd.DataFrame(preds, index=city.taz.index,
+                                   columns=["AI_TripGen_Pred"])
+            z.writestr("ai_trip_generation_predictions.csv", pred_df.to_csv())
+
+        if "ai_modechoice_model" in st.session_state:
+            clf = st.session_state["ai_modechoice_model"]
+            z.writestr("ai_modechoice_classes.txt",
+                       "\n".join(list(clf.classes_)))
+
+    buffer.seek(0)
+    return buffer
+
+# ------------------------------------------------------
+# DISPLAY DOWNLOAD SECTION
+# ------------------------------------------------------
+
+st.header("📁 Download Individual Outputs")
+
+# Synthetic City
+if "city" in st.session_state:
+    st.subheader("🏙️ Synthetic City")
+    make_csv_download(st.session_state["city"].taz, "taz_attributes.csv")
+    make_csv_download(st.session_state["city"].distance_matrix, "distance_matrix.csv")
+    make_csv_download(st.session_state["city"].travel_time_matrix, "travel_time_matrix.csv")
+else:
+    st.info("Synthetic city not generated yet.")
+
+# Trip Generation
+if "productions" in st.session_state:
+    st.subheader("🚶 Trip Generation")
+    make_csv_download(st.session_state["productions"], "productions.csv")
+    make_csv_download(st.session_state["attractions"], "attractions.csv")
+
+# Trip Distribution
+if "od" in st.session_state:
+    st.subheader("🌍 Trip Distribution – OD Matrices")
+    for purpose, df in st.session_state["od"].items():
+        make_csv_download(df, f"od_{purpose}.csv")
+
+# Mode Choice
+if "mode_choice" in st.session_state:
+    st.subheader("🚈 Mode Choice – Volumes & Probabilities")
+    mc = st.session_state["mode_choice"]
+    make_csv_download(mc.total_od, "total_od.csv")
+    for m, df in mc.volumes.items():
+        make_csv_download(df, f"od_mode_{m}.csv")
+    for m, df in mc.probabilities.items():
+        make_csv_download(df, f"mode_prob_{m}.csv")
+
+# Route Assignment
+if "link_flows" in st.session_state:
+    st.subheader("🛣️ Route Assignment – Link Flows")
+    make_csv_download(st.session_state["link_flows"], "link_flows.csv")
+
+# AI Models
+if "ai_tripgen_model" in st.session_state or "ai_modechoice_model" in st.session_state:
+    st.subheader("🤖 AI Model Outputs")
+
+    if "ai_tripgen_model" in st.session_state:
+        st.write("• AI Trip Generation model predictions available")
+
+    if "ai_modechoice_model" in st.session_state:
+        st.write("• AI Mode Choice classifier classes available")
+
+# ------------------------------------------------------
+# ZIP EXPORT
+# ------------------------------------------------------
+
+st.header("📦 Download EVERYTHING (ZIP)")
+
+if st.button("Create ZIP Package"):
+    zip_buffer = build_zip_file()
+    st.download_button(
+        label="⬇ Download Zip File",
+        data=zip_buffer,
+        file_name="TripAI_outputs.zip",
+        mime="application/zip"
+    )
+    st.success("ZIP file prepared!")

pages/8_⚙️_Policy_Scenarios.py

@@ -0,0 +1,294 @@
+import streamlit as st
+import numpy as np
+import pandas as pd
+import os
+
+from modules.gravity_model import build_all_od_matrices
+from modules.route_assignment import generate_synthetic_network, aon_assignment
+
+st.set_page_config(layout="wide")
+st.title("⚙️ Policy Scenario Engine")
+
+st.markdown("""
+Use this page to test **policy scenarios** on top of the synthetic four-step model:
+
+- 🚈 **Metro Improvement**: faster travel time, lower fare  
+- 🚗 **Congestion Charge**: extra cost for car trips into CBD zones  
+- 🏙️ **Transit-Oriented Development (TOD)**: increase attractions in selected TAZs  
+
+The engine compares **Baseline vs Scenario** in terms of:
+- Mode shares (Car / Metro / Bus)
+- Car link flows (AON assignment)
+""")
+
+# ------------------------------------------------------
+# CHECK REQUIRED STATE
+# ------------------------------------------------------
+required_keys = ["city", "productions", "attractions", "od", "mode_choice"]
+missing = [k for k in required_keys if k not in st.session_state]
+
+if missing:
+    st.error(f"Please complete previous steps first. Missing: {', '.join(missing)}")
+    st.stop()
+
+city = st.session_state["city"]
+taz = city.taz
+productions = st.session_state["productions"]
+attractions_base = st.session_state["attractions"]
+od_base = st.session_state["od"]
+mode_choice_base = st.session_state["mode_choice"]
+tt_car_base = city.travel_time_matrix.copy()
+
+zones = list(taz.index)
+
+# ------------------------------------------------------
+# HELPER: MODE SHARE CALCULATION
+# ------------------------------------------------------
+def compute_mode_shares(mode_volumes: dict, total_od: pd.DataFrame) -> pd.DataFrame:
+    total_trips = total_od.values.sum()
+    rows = []
+    for m, mat in mode_volumes.items():
+        trips = mat.values.sum()
+        share = trips / total_trips if total_trips > 0 else 0
+        rows.append({"mode": m, "trips": trips, "share": share})
+    return pd.DataFrame(rows)
+
+# ------------------------------------------------------
+# SIDEBAR – POLICY CONTROLS
+# ------------------------------------------------------
+st.sidebar.header("Policy Controls")
+
+st.sidebar.subheader("🚈 Metro Improvement")
+metro_time_reduction_pct = st.sidebar.slider(
+    "Metro travel time reduction (%)", 0, 50, 20
+)
+metro_fare_change_pct = st.sidebar.slider(
+    "Metro fare change (%)", -50, 50, -20
+)
+
+st.sidebar.subheader("🚗 Congestion Charge (Car)")
+congestion_charge = st.sidebar.slider(
+    "Extra generalized cost for car entering CBD", 0.0, 50.0, 20.0, step=1.0
+)
+
+default_cbd = zones[:5] if len(zones) >= 5 else zones
+cbd_zones = st.sidebar.multiselect(
+    "CBD zones (destinations)", options=zones, default=default_cbd
+)
+
+st.sidebar.subheader("🏙️ TOD – Modify Attractions")
+apply_tod = st.sidebar.checkbox("Apply TOD", value=False)
+tod_increase_pct = st.sidebar.slider(
+    "Attraction increase (%)", 0, 100, 30
+)
+tod_zones = st.sidebar.multiselect(
+    "TOD zones", options=zones, default=zones[:3] if len(zones) >= 3 else zones
+)
+
+st.sidebar.markdown("---")
+run_button = st.sidebar.button("▶ Run Scenario")
+
+# ------------------------------------------------------
+# BASELINE SUMMARY
+# ------------------------------------------------------
+st.header("📊 Baseline Summary")
+
+baseline_shares = compute_mode_shares(
+    mode_choice_base.volumes, mode_choice_base.total_od
+)
+
+col1, col2 = st.columns(2)
+
+with col1:
+    st.subheader("Baseline Mode Shares")
+    st.dataframe(baseline_shares.style.format({"trips": "{:.1f}", "share": "{:.3f}"}))
+
+with col2:
+    if "link_flows" in st.session_state:
+        st.subheader("Baseline Car Link Flows (sample)")
+        st.dataframe(st.session_state["link_flows"].head(10))
+    else:
+        st.info("Baseline link flows not stored. Run Route Assignment page.")
+
+# ------------------------------------------------------
+# BUILD POLICY TIME/COST MATRICES
+# ------------------------------------------------------
+def build_policy_time_cost_matrices(
+        tt_car_base: pd.DataFrame,
+        metro_time_reduction_pct: float,
+        metro_fare_change_pct: float,
+        congestion_charge: float,
+        cbd_zones: list
+):
+    """
+    Build modified travel time and cost matrices under policy scenario.
+    """
+    tt_car = tt_car_base.copy()
+
+    # Base functions: metro faster, bus slower
+    tt_metro = tt_car * 0.8 * (1 - metro_time_reduction_pct / 100.0)
+    tt_bus = tt_car * 1.3
+
+    # Distance proxy
+    dist_proxy = tt_car / 60 * 30
+
+    cost_car = 2 + 0.12 * dist_proxy
+    cost_metro = 15 * (1 + metro_fare_change_pct / 100.0)
+    cost_bus = 8 + 0.03 * dist_proxy
+
+    # FIX: apply congestion charge vectorized
+    cost_car.loc[:, cbd_zones] += congestion_charge
+
+    return (
+        {"car": tt_car, "metro": tt_metro, "bus": tt_bus},
+        {"car": cost_car, "metro": cost_metro, "bus": cost_bus}
+    )
+
+# ------------------------------------------------------
+# POLICY MODE CHOICE (Multinomial Logit)
+# ------------------------------------------------------
+def policy_mode_choice(
+        od_mats: dict,
+        taz: pd.DataFrame,
+        tt_car_base: pd.DataFrame,
+        metro_time_reduction_pct: float,
+        metro_fare_change_pct: float,
+        congestion_charge: float,
+        cbd_zones: list,
+        beta_time: float = -0.06,
+        beta_cost: float = -0.03,
+        beta_car_own: float = 0.5
+):
+    zones = tt_car_base.index
+
+    # Total OD (sum over purposes)
+    total_od = sum(od_mats.values())
+    total_od = total_od.loc[zones, zones]
+
+    # Updated time/cost
+    time_mats, cost_mats = build_policy_time_cost_matrices(
+        tt_car_base,
+        metro_time_reduction_pct,
+        metro_fare_change_pct,
+        congestion_charge,
+        cbd_zones
+    )
+
+    # Car ownership
+    car_own = taz["car_ownership_rate"].reindex(zones).to_numpy()
+    car_own_matrix = np.repeat(car_own[:, None], len(zones), axis=1)
+
+    modes = ["car", "metro", "bus"]
+    utilities = {}
+
+    for mode in modes:
+        tt = time_mats[mode].to_numpy()
+        cc = cost_mats[mode].to_numpy()
+
+        if mode == "car":
+            U = beta_time * tt + beta_cost * cc + beta_car_own * car_own_matrix
+        else:
+            U = beta_time * tt + beta_cost * cc
+
+        utilities[mode] = U
+
+    # Probabilities
+    exp_sum = sum(np.exp(U) for U in utilities.values())
+    probabilities = {
+        mode: pd.DataFrame(np.exp(U) / np.maximum(exp_sum, 1e-12), index=zones, columns=zones)
+        for mode, U in utilities.items()
+    }
+
+    # Mode flows
+    volumes = {
+        mode: pd.DataFrame(
+            total_od.to_numpy() * probabilities[mode].to_numpy(),
+            index=zones, columns=zones
+        )
+        for mode in modes
+    }
+
+    return probabilities, volumes, total_od
+
+# ------------------------------------------------------
+# RUN SCENARIO
+# ------------------------------------------------------
+if run_button:
+    st.header("🧪 Scenario Results")
+
+    # 1) TOD → Modify attractions
+    if apply_tod:
+        st.subheader("🏙️ TOD Applied — Recomputing OD")
+
+        A_scenario = attractions_base.copy(deep=True)
+        factor = 1 + tod_increase_pct / 100.0
+
+        for z in tod_zones:
+            if z in A_scenario.index:
+                A_scenario.loc[z, ["HBW", "HBS"]] *= factor
+
+        # FIX: consistent call
+        od_scenario = build_all_od_matrices(productions, A_scenario, tt_car_base)
+    else:
+        st.subheader("🏙️ TOD NOT applied — using baseline OD")
+        od_scenario = od_base
+
+    # 2) Policy Mode Choice
+    st.subheader("🚈 Mode Choice under Policy Scenario")
+    probs_scen, vols_scen, total_od_scen = policy_mode_choice(
+        od_scenario,
+        taz,
+        tt_car_base,
+        metro_time_reduction_pct,
+        metro_fare_change_pct,
+        congestion_charge,
+        cbd_zones
+    )
+
+    # 3) Mode share comparison
+    scenario_shares = compute_mode_shares(vols_scen, total_od_scen)
+
+    colA, colB = st.columns(2)
+    with colA:
+        st.markdown("#### Baseline Mode Shares")
+        st.dataframe(baseline_shares.style.format({"trips": "{:.1f}", "share": "{:.3f}"}))
+    with colB:
+        st.markdown("#### Scenario Mode Shares")
+        st.dataframe(scenario_shares.style.format({"trips": "{:.1f}", "share": "{:.3f}"}))
+
+    # 4) AON Car Assignment
+    st.subheader("🛣️ Scenario Car Assignment (AON)")
+
+    if "network" in st.session_state:
+        network = st.session_state["network"]
+    else:
+        network = generate_synthetic_network(taz)
+
+    car_od_scen = vols_scen["car"]
+    link_flows_scen = aon_assignment(car_od_scen, network)
+    st.session_state["link_flows_scenario"] = link_flows_scen
+
+    # FIX: save to data folder
+    os.makedirs("data", exist_ok=True)
+    link_flows_scen.to_csv("data/link_flows_scenario.csv")
+
+    st.markdown("**Scenario Car Link Flows (sample)**")
+    st.dataframe(link_flows_scen.head(10))
+
+    # 5) Summary Numbers
+    st.subheader("📉 Key Comparison")
+
+    baseline_car = mode_choice_base.volumes["car"].values.sum()
+    scenario_car = vols_scen["car"].values.sum()
+
+    st.write(f"**Baseline car trips:** {baseline_car:,.1f}")
+    st.write(f"**Scenario car trips:** {scenario_car:,.1f}")
+
+    if baseline_car > 0:
+        pct = 100 * (scenario_car - baseline_car) / baseline_car
+        st.write(f"**Change in car trips:** {pct:+.2f}%")
+
+    st.success("Scenario evaluation completed. Use Export page to download results.")
+
+else:
+    st.info("Adjust policy parameters on the left, then click **Run Scenario**.")

pages/9_📈_Visualization_Dashboard.py

@@ -0,0 +1,207 @@
+import streamlit as st
+import pandas as pd
+import numpy as np
+import matplotlib.pyplot as plt
+import seaborn as sns
+import os
+
+st.set_page_config(layout="wide")
+st.title("📈 Visualization Dashboard")
+
+st.markdown("""
+This dashboard provides **research-grade visualizations** for:
+- Mode share comparison (Baseline vs Scenario)
+- OD heatmaps
+- Car flow changes on network links
+- TAZ-level spatial indicators  
+
+All figures are exportable in 600 DPI for Q1-grade publications.
+""")
+
+# ------------------------------------------------------
+# CHECK REQUIRED STATE
+# ------------------------------------------------------
+if "city" not in st.session_state:
+    st.error("Generate synthetic city first.")
+    st.stop()
+
+if "mode_choice" not in st.session_state:
+    st.error("Complete Mode Choice first.")
+    st.stop()
+
+city = st.session_state["city"]
+taz = city.taz
+
+# Baseline
+mode_base = st.session_state["mode_choice"]
+car_flow_base = st.session_state.get("link_flows", None)
+
+# Scenario check
+scenario_exists = (
+    "vols_scen" in st.session_state and
+    "total_od_scen" in st.session_state and
+    "link_flows_scenario" in st.session_state
+)
+
+# ------------------------------------------------------
+# Helper: Export figure in 600 DPI
+# ------------------------------------------------------
+def export_fig(fig, filename):
+    fig.savefig(filename, dpi=600, bbox_inches="tight")
+    with open(filename, "rb") as f:
+        st.download_button(
+            label="⬇ Download Figure",
+            data=f,
+            file_name=filename,
+            mime="image/png"
+        )
+    st.success("Figure exported in 600 DPI!")
+
+# ======================================================
+# SECTION 1: MODE SHARE COMPARISON
+# ======================================================
+st.header("🚈 Mode Share Comparison (Baseline vs Scenario)")
+
+def compute_mode_shares(mode_volumes, total_od):
+    total_trips = total_od.values.sum()
+    rows = []
+    for m, mat in mode_volumes.items():
+        trips = mat.values.sum()
+        share = trips / total_trips if total_trips > 0 else 0
+        rows.append([m, trips, share])
+    return pd.DataFrame(rows, columns=["Mode", "Trips", "Share"])
+
+baseline_shares = compute_mode_shares(
+    mode_base.volumes, mode_base.total_od
+)
+
+if scenario_exists:
+    vols_scen = st.session_state["vols_scen"]
+    total_od_scen = st.session_state["total_od_scen"]
+    scenario_shares = compute_mode_shares(vols_scen, total_od_scen)
+
+colA, colB = st.columns(2)
+
+with colA:
+    st.subheader("Baseline Mode Shares")
+    st.dataframe(baseline_shares.style.format({"Trips": "{:,.1f}", "Share": "{:.3f}"}))
+
+with colB:
+    if scenario_exists:
+        st.subheader("Scenario Mode Shares")
+        st.dataframe(scenario_shares.style.format({"Trips": "{:,.1f}", "Share": "{:.3f}"}))
+    else:
+        st.info("Run a policy scenario to enable comparison.")
+
+# Bar chart
+fig, ax = plt.subplots(figsize=(8, 5))
+ax.bar(baseline_shares["Mode"], baseline_shares["Share"], label="Baseline")
+
+if scenario_exists:
+    ax.bar(
+        np.arange(len(scenario_shares)) + 0.3,
+        scenario_shares["Share"],
+        width=0.3,
+        label="Scenario"
+    )
+
+ax.set_ylabel("Mode Share")
+ax.set_title("Baseline vs Scenario Mode Shares")
+ax.legend()
+st.pyplot(fig)
+
+export_fig(fig, "mode_share_comparison.png")
+
+# ======================================================
+# SECTION 2: OD HEATMAPS
+# ======================================================
+st.header("🌍 OD Heatmaps (Baseline & Scenario)")
+
+od_base = st.session_state["od"]
+purpose = st.selectbox("Select Trip Purpose", list(od_base.keys()))
+
+# Baseline heatmap
+st.subheader(f"Baseline OD – {purpose}")
+
+fig2, ax2 = plt.subplots(figsize=(6, 5))
+sns.heatmap(od_base[purpose], cmap="viridis", ax=ax2)
+ax2.set_title(f"Baseline OD – {purpose}")
+st.pyplot(fig2)
+export_fig(fig2, f"baseline_od_{purpose}.png")
+
+# Scenario heatmap
+if scenario_exists:
+    od_scenario = st.session_state.get("od_scenario", None)
+
+    if isinstance(od_scenario, dict) and purpose in od_scenario:
+        od_scen_matrix = od_scenario[purpose]
+    else:
+        od_scen_matrix = od_base[purpose]
+
+    st.subheader(f"Scenario OD – {purpose}")
+
+    fig3, ax3 = plt.subplots(figsize=(6, 5))
+    sns.heatmap(od_scen_matrix, cmap="viridis", ax=ax3)
+    ax3.set_title(f"Scenario OD – {purpose}")
+    st.pyplot(fig3)
+    export_fig(fig3, f"scenario_od_{purpose}.png")
+
+# ======================================================
+# SECTION 3: CAR FLOW COMPARISON
+# ======================================================
+st.header("🚗 Car Link Flows (Baseline vs Scenario)")
+
+if car_flow_base is None:
+    st.info("Baseline link flows unavailable. Run Route Assignment first.")
+else:
+    st.subheader("Baseline Link Flows")
+    st.dataframe(car_flow_base.head(10))
+
+    if scenario_exists:
+        car_flow_scen = st.session_state["link_flows_scenario"]
+
+        st.subheader("Scenario Link Flows")
+        st.dataframe(car_flow_scen.head(10))
+
+        # Safe merged comparison
+        merged = car_flow_base.copy()
+        merged["scenario"] = car_flow_scen.iloc[:, -1]
+        merged["change"] = merged["scenario"] - merged.iloc[:, -1]
+
+        fig4, ax4 = plt.subplots(figsize=(10, 5))
+        ax4.bar(
+            merged.index,
+            merged["change"],
+            color=["red" if x > 0 else "green" for x in merged["change"]]
+        )
+        ax4.set_title("Change in Car Link Flows")
+        ax4.set_ylabel("Δ Flow (veh/h)")
+        st.pyplot(fig4)
+
+        export_fig(fig4, "car_link_flow_change.png")
+
+# ======================================================
+# SECTION 4: TAZ SPATIAL MAPS
+# ======================================================
+st.header("🗺️ TAZ-Level Spatial Indicators")
+
+indicator = st.selectbox(
+    "Select variable to map",
+    ["population", "workers", "students", "land_use_mix", "cars"]
+)
+
+fig5, ax5 = plt.subplots(figsize=(6, 6))
+scatter = ax5.scatter(
+    taz["x_km"], taz["y_km"],
+    c=taz[indicator],
+    s=220,
+    cmap="plasma",
+    edgecolors="black"
+)
+plt.colorbar(scatter, ax=ax5, label=indicator)
+ax5.set_title(f"TAZ Map – {indicator.capitalize()}")
+st.pyplot(fig5)
+
+export_fig(fig5, f"taz_map_{indicator}.png")
+
+st.success("Visualization dashboard ready.")