How demonlab-biofinder/xiao_tau_simulation_sir works
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.