# demonlab-biofinder/xiao_tau_simulation_sir architecture

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

- Interactive diagram: https://gitdiagram.com/demonlab-biofinder/xiao_tau_simulation_sir
- Repository: https://github.com/demonlab-biofinder/xiao_tau_simulation_sir

## Overview

##### Project Type and Purpose
- A Python-based scientific simulation pipeline implementing an agent-based SIR model (Susceptible-Infectious-Recovered) for tau propagation in Alzheimer’s disease.
- Provides command-line interfaces for single runs, hyperparameter tuning, null model simulations, and automated result summarization.

##### Top-Level Components
- Input Data Layer
– data/ directory: raw and processed pickled connectomes, vulnerability CSVs, subtype tables.
– User_input_settings.txt: central configuration of model parameters, file names, epicenter lists, and regional variables.
- Execution Layer (scripts/)
– run.py: single-run CLI.
– run_hypertune.py: grid-search hyperparameter tuner.
– run_null_model.py: null-connectivity simulations + tuning.
- Core Modules (scripts/src/)
– params.py: parse CLI arguments + settings.
– init_run.py: load input_data, connectomes, vulnerability matrices.
– simulated_atrophy.py: core SIR simulation engine (spread, misfolding, synthesis, clearance).
– evaluation.py: compute fit metrics between simulated and observed atrophy.
– results_traker.py: logging, checkpointing, writing out raw simulation trajectories.
– utils.py + log_redirector.py: plotting, logging support.
- Summarization Layer (scripts/summary/)
– run_summary_one_conn.py & run_summary_all_conns.py: orchestrate aggregation of evaluation metrics across one or all connectivities.
- Output Layer
– results/ directory: per-model subfolders with simulation outputs (e.g., timecourses, metrics, plots).

##### Component Relationships & Data Flow
1. User edits User_input_settings.txt → selects input_data_name, model_name, regional variables.
2. CLI script (run.py / run_hypertune.py / run_null_model.py) invoked → params.py parses settings + CLI overrides.
3. init_run.py loads:
- Connectome matrix (SC)
- Regional vulnerability features
- Observed tau data
4. Control → simulated_atrophy.py runs SIR simulation using network spread + vulnerability parameters.
5. At each time point or parameter set: evaluation.py computes similarity metrics (e.g., correlation, RMS error).
6. results_traker.py logs outcomes (JSON/CSV), dumps simulation states, and redirects logs via log_redirector.py.
7. After all runs, summary scripts load results/ → summary.py aggregates metrics → produces figures, tables.

##### Architectural Patterns & Principles
- Pipeline / staging: clear separation between configuration, data loading, simulation engine, evaluation, tracking, summarization.
- Modularization: each major function in its own module → easy to replace or extend (e.g., swap in new regional factors).
- CLI-driven: scripts form entry points, all parameters driven by text config or flags.
- Batch vs. single-run mode: run_hypertune and run_null_model wrap multiple calls to the core simulation with varying parameters.

##### Key Technologies & Dependencies
- Python ≥3.7, numpy, pandas, scipy, scikit-learn, joblib
- matplotlib, seaborn for plotting
- abagen, Allen Brain Atlas (external data sources, preprocessed)
- Pickle for binary data exchange

##### Additional Details to Capture
- That summary scripts depend on both results/ directory structure and the original connectome data for cross-connectivity comparisons.
- Extensibility points: adding new regional factors simply adjusts params.py and User_input_settings.txt.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Configuration Layer"
        Cfg["User_input_settings.txt"]:::config
        Parser["params.py"]:::config
    end

    subgraph "Execution Layer"
        CLI_single["run.py"]:::config
        CLI_tune["run_hypertune.py"]:::config
        CLI_null["run_null_model.py"]:::config
    end

    subgraph "Data Ingestion"
        DataDir["data/"]:::data
        Loader["init_run.py"]:::data
        External["Abagen & Allen Atlas"]:::external
    end

    subgraph "Simulation Engine"
        Simulator["simulated_atrophy.py"]:::sim
    end

    subgraph "Evaluation & Tracking"
        Evaluator["evaluation.py"]:::eval
        Tracker["results_traker.py"]:::eval
        Log["log_redirector.py"]:::eval
        Utils["utils.py"]:::eval
    end

    subgraph "Summarization Layer"
        SumOne["run_summary_one_conn.py"]:::summary
        SumAll["run_summary_all_conns.py"]:::summary
        SummHelpers["summary.py"]:::summary
    end

    subgraph "Output Layer"
        ResultsDir["results/"]:::output
    end

    Cfg -->|"configuration"| CLI_single
    Cfg -->|"configuration"| CLI_tune
    Cfg -->|"configuration"| CLI_null

    CLI_single -->|"CLI args"| Parser
    CLI_tune -->|"CLI args"| Parser
    CLI_null -->|"CLI args"| Parser

    Parser -->|"parsed parameters"| Loader
    DataDir -->|"SC matrix (pkl)\nVulnerability (csv)"| Loader
    External -->|"atlas data"| Loader

    Loader -->|"loaded data"| Simulator
    Simulator -->|"simulated trajectories\n(CSV/JSON)"| Evaluator
    Evaluator -->|"metrics (CSV)"| Tracker
    Utils -.->|supports| Evaluator
    Utils -.->|supports| Tracker
    Log -.->|redirects logs| Tracker
    Tracker -->|"simulation states\nlogs"| ResultsDir

    ResultsDir -->|"results"| SumOne
    ResultsDir -->|"results"| SumAll
    SumOne -->|"uses helpers"| SummHelpers
    SumAll -->|"uses helpers"| SummHelpers
    SummHelpers -->|"figures (PNG/PDF)\ntables"| ResultsDir

    %% Loop annotations
    CLI_tune -->|subgraph loop| CLI_tune
    CLI_null -->|subgraph loop| CLI_null

    %% Click Events
    click Cfg "https://github.com/demonlab-biofinder/xiao_tau_simulation_sir/blob/main/scripts/User_input_settings.txt"
    click CLI_single "https://github.com/demonlab-biofinder/xiao_tau_simulation_sir/blob/main/scripts/run.py"
    click CLI_tune "https://github.com/demonlab-biofinder/xiao_tau_simulation_sir/blob/main/scripts/run_hypertune.py"
    click CLI_null "https://github.com/demonlab-biofinder/xiao_tau_simulation_sir/blob/main/scripts/run_null_model.py"
    click Parser "https://github.com/demonlab-biofinder/xiao_tau_simulation_sir/blob/main/scripts/src/params.py"
    click Loader "https://github.com/demonlab-biofinder/xiao_tau_simulation_sir/blob/main/scripts/src/init_run.py"
    click Simulator "https://github.com/demonlab-biofinder/xiao_tau_simulation_sir/blob/main/scripts/src/simulated_atrophy.py"
    click Evaluator "https://github.com/demonlab-biofinder/xiao_tau_simulation_sir/blob/main/scripts/src/evaluation.py"
    click Tracker "https://github.com/demonlab-biofinder/xiao_tau_simulation_sir/blob/main/scripts/src/results_traker.py"
    click Log "https://github.com/demonlab-biofinder/xiao_tau_simulation_sir/blob/main/scripts/src/log_redirector.py"
    click Utils "https://github.com/demonlab-biofinder/xiao_tau_simulation_sir/blob/main/scripts/src/utils.py"
    click DataDir "https://github.com/demonlab-biofinder/xiao_tau_simulation_sir/tree/main/data/"
    click ResultsDir "https://github.com/demonlab-biofinder/xiao_tau_simulation_sir/tree/main/results/"
    click SumOne "https://github.com/demonlab-biofinder/xiao_tau_simulation_sir/blob/main/scripts/summary/run_summary_one_conn.py"
    click SumAll "https://github.com/demonlab-biofinder/xiao_tau_simulation_sir/blob/main/scripts/summary/run_summary_all_conns.py"
    click SummHelpers "https://github.com/demonlab-biofinder/xiao_tau_simulation_sir/blob/main/scripts/summary/summary.py"

    %% Styles
    classDef config fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef data fill:#d4edda,stroke:#333,stroke-width:1px
    classDef sim fill:#ffe5b4,stroke:#333,stroke-width:1px
    classDef eval fill:#e2d6f7,stroke:#333,stroke-width:1px
    classDef summary fill:#fff3cd,stroke:#333,stroke-width:1px
    classDef output fill:#e2e3e5,stroke:#333,stroke-width:1px
    classDef external fill:#f8f9fa,stroke:#333,stroke-width:1px
```
