# joshykoshy/argus architecture

> Architecture diagram of the GitHub repository joshykoshy/argus, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/joshykoshy/argus
- Repository: https://github.com/joshykoshy/argus

## Overview

Argus is a research pipeline for testing whether frequency-band models improve brain-tumour segmentation under simulated low-field MRI degradation. The main workflow prepares BraTS data, trains segmentation models, evaluates them across degradation conditions, and analyzes segmentation and volume agreement; the repository also includes a degradation-range pilot and 3D visualization. README-level workflow links are documented; several internal module connections are omitted where the supplied excerpts do not establish who calls whom.

Main entry points: [`results`](https://github.com/joshykoshy/argus/tree/master/results) (Results and tables), [`training/train_v2.py`](https://github.com/joshykoshy/argus/blob/master/training/train_v2.py) (Model training), [`evaluation/evaluate_v2.py`](https://github.com/joshykoshy/argus/blob/master/evaluation/evaluate_v2.py) (Test evaluation), [`training/prepare.py`](https://github.com/joshykoshy/argus/blob/master/training/prepare.py) (Array preparation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data preparation"]
  node_manifest["Data manifest<br/>[manifest.py]"]
  node_splits["Patient splits<br/>[splits.py]"]
  node_preprocess["Preprocessing<br/>[preprocess.py]"]
  node_prepare["Array preparation<br/>[prepare.py]"]
  node_dataset["Slice dataset<br/>[dataset.py]"]
end

subgraph group_model["Degradation and models"]
  node_degradation["MRI degradation<br/>[degradation.py]"]
  node_pilot["Degradation pilot<br/>[pilot.py]"]
  node_decomposition["Frequency bands<br/>[decomposition.py]"]
  node_unet["U-Net<br/>[unet.py]"]
  node_dual["Dual-stream U-Net<br/>[dual_stream.py]"]
  node_factory["Model factory<br/>[factory.py]"]
end

subgraph group_study["Training and evaluation"]
  node_train["Model training<br/>[train_v2.py]"]
  node_evaluate["Test evaluation<br/>[evaluate_v2.py]"]
  node_metrics["Segmentation metrics<br/>[evaluation.py]"]
end

subgraph group_analysis["Analysis and validation"]
  node_stats["Statistical analysis<br/>[stats.py]"]
  node_matlab["Morphometrics"]
  node_agreement["Volume agreement<br/>[agreement_report.m]"]
end

subgraph group_viz["3D visualization"]
  node_meshes["Surface meshes<br/>[meshes.py]"]
  node_viewer["Interactive viewer<br/>[viewer.py]"]
  node_paperfigures["Paper figures<br/>[paper_figures.py]"]
end

node_researcher(("Researcher"))
node_brats[("BraTS scans")]
node_results[("Results and tables")]
node_html["3D case views"]

node_researcher -->|"prepares data"| node_prepare
node_brats -->|"provides scans"| node_preprocess
node_manifest -.->|"identifies patients"| node_prepare
node_splits -->|"selects cohorts"| node_prepare
node_preprocess -->|"processes patients"| node_prepare
node_prepare -->|"writes training arrays"| node_train
node_dataset -.->|"supplies slices"| node_train
node_degradation -->|"augments scans"| node_train
node_decomposition -->|"provides frequency bands"| node_factory
node_unet -->|"instantiated by"| node_factory
node_dual -->|"instantiated by"| node_factory
node_factory -->|"builds models"| node_train
node_researcher -->|"trains models"| node_train
node_pilot -->|"reports pilot metrics"| node_results
node_train -->|"saves checkpoints"| node_results
node_results -->|"provides checkpoints"| node_evaluate
node_evaluate -.->|"computes measures"| node_metrics
node_evaluate -->|"writes evaluation metrics"| node_results
node_researcher -->|"evaluates test set"| node_evaluate
node_results -->|"provides metrics"| node_stats
node_stats -->|"writes statistics"| node_results
node_results -->|"provides predictions"| node_matlab
node_matlab -.->|"reports agreement"| node_agreement
node_results -.->|"provides segmentations"| node_meshes
node_meshes -->|"builds surfaces"| node_viewer
node_meshes -->|"builds surfaces"| node_paperfigures
node_evaluate -->|"exports prediction NIfTIs"| node_viewer
node_viewer -->|"writes case views"| node_html
node_researcher -->|"renders comparisons"| node_viewer

click node_manifest "https://github.com/joshykoshy/argus/blob/master/python/data/manifest.py"
click node_splits "https://github.com/joshykoshy/argus/blob/master/python/data/splits.py"
click node_preprocess "https://github.com/joshykoshy/argus/blob/master/python/data/preprocess.py"
click node_prepare "https://github.com/joshykoshy/argus/blob/master/training/prepare.py"
click node_dataset "https://github.com/joshykoshy/argus/blob/master/python/data/dataset.py"
click node_degradation "https://github.com/joshykoshy/argus/blob/master/python/physics/degradation.py"
click node_pilot "https://github.com/joshykoshy/argus/blob/master/pilot/pilot.py"
click node_decomposition "https://github.com/joshykoshy/argus/blob/master/python/physics/decomposition.py"
click node_unet "https://github.com/joshykoshy/argus/blob/master/python/models/unet.py"
click node_dual "https://github.com/joshykoshy/argus/blob/master/python/models/dual_stream.py"
click node_factory "https://github.com/joshykoshy/argus/blob/master/python/models/factory.py"
click node_train "https://github.com/joshykoshy/argus/blob/master/training/train_v2.py"
click node_evaluate "https://github.com/joshykoshy/argus/blob/master/evaluation/evaluate_v2.py"
click node_metrics "https://github.com/joshykoshy/argus/blob/master/python/metrics/evaluation.py"
click node_stats "https://github.com/joshykoshy/argus/blob/master/python/analysis/stats.py"
click node_matlab "https://github.com/joshykoshy/argus/tree/master/matlab"
click node_agreement "https://github.com/joshykoshy/argus/blob/master/matlab/agreement_report.m"
click node_meshes "https://github.com/joshykoshy/argus/blob/master/viz3d/meshes.py"
click node_viewer "https://github.com/joshykoshy/argus/blob/master/viz3d/viewer.py"
click node_paperfigures "https://github.com/joshykoshy/argus/blob/master/viz3d/paper_figures.py"
click node_results "https://github.com/joshykoshy/argus/tree/master/results"
click node_html "https://github.com/joshykoshy/argus/tree/master/figures"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_manifest,node_splits,node_preprocess,node_prepare,node_dataset,node_html toneBlue
class node_degradation,node_pilot,node_decomposition,node_unet,node_dual,node_factory,node_brats,node_results toneAmber
class node_train,node_evaluate,node_metrics toneMint
class node_stats,node_matlab,node_agreement toneRose
class node_meshes,node_viewer,node_paperfigures,node_researcher toneIndigo
```

## Components

### Data preparation

- [Data manifest](https://github.com/joshykoshy/argus/blob/master/python/data/manifest.py): `python/data/manifest.py`
- [Patient splits](https://github.com/joshykoshy/argus/blob/master/python/data/splits.py): `python/data/splits.py`
- [Preprocessing](https://github.com/joshykoshy/argus/blob/master/python/data/preprocess.py): `python/data/preprocess.py`
- [Array preparation](https://github.com/joshykoshy/argus/blob/master/training/prepare.py): `training/prepare.py`
- [Slice dataset](https://github.com/joshykoshy/argus/blob/master/python/data/dataset.py): `python/data/dataset.py`

### Degradation and models

- [MRI degradation](https://github.com/joshykoshy/argus/blob/master/python/physics/degradation.py): `python/physics/degradation.py`
- [Degradation pilot](https://github.com/joshykoshy/argus/blob/master/pilot/pilot.py): `pilot/pilot.py`
- [Frequency bands](https://github.com/joshykoshy/argus/blob/master/python/physics/decomposition.py): `python/physics/decomposition.py`
- [U-Net](https://github.com/joshykoshy/argus/blob/master/python/models/unet.py): `python/models/unet.py`
- [Dual-stream U-Net](https://github.com/joshykoshy/argus/blob/master/python/models/dual_stream.py): `python/models/dual_stream.py`
- [Model factory](https://github.com/joshykoshy/argus/blob/master/python/models/factory.py): `python/models/factory.py`

### Training and evaluation

- [Model training](https://github.com/joshykoshy/argus/blob/master/training/train_v2.py): `training/train_v2.py`
- [Test evaluation](https://github.com/joshykoshy/argus/blob/master/evaluation/evaluate_v2.py): `evaluation/evaluate_v2.py`
- [Segmentation metrics](https://github.com/joshykoshy/argus/blob/master/python/metrics/evaluation.py): `python/metrics/evaluation.py`

### Analysis and validation

- [Statistical analysis](https://github.com/joshykoshy/argus/blob/master/python/analysis/stats.py): `python/analysis/stats.py`
- [Morphometrics](https://github.com/joshykoshy/argus/tree/master/matlab): `matlab`
- [Volume agreement](https://github.com/joshykoshy/argus/blob/master/matlab/agreement_report.m): `matlab/agreement_report.m`

### 3D visualization

- [Surface meshes](https://github.com/joshykoshy/argus/blob/master/viz3d/meshes.py): `viz3d/meshes.py`
- [Interactive viewer](https://github.com/joshykoshy/argus/blob/master/viz3d/viewer.py): `viz3d/viewer.py`
- [Paper figures](https://github.com/joshykoshy/argus/blob/master/viz3d/paper_figures.py): `viz3d/paper_figures.py`

### Other components

- **Researcher**
- **BraTS scans**
- [Results and tables](https://github.com/joshykoshy/argus/tree/master/results): `results`
- [3D case views](https://github.com/joshykoshy/argus/tree/master/figures): `figures`

## Connections

- Researcher → Array preparation: prepares data (evidence: `README.md`)
- BraTS scans → Preprocessing: provides scans (evidence: `README.md`)
- Data manifest → Array preparation: identifies patients
- Patient splits → Array preparation: selects cohorts (evidence: `training/prepare.py`)
- Preprocessing → Array preparation: processes patients (evidence: `training/prepare.py`)
- Array preparation → Model training: writes training arrays (evidence: `README.md`)
- Slice dataset → Model training: supplies slices
- MRI degradation → Model training: augments scans (evidence: `README.md`)
- Frequency bands → Model factory: provides frequency bands (evidence: `python/models/factory.py`)
- U-Net → Model factory: instantiated by (evidence: `python/models/factory.py`)
- Dual-stream U-Net → Model factory: instantiated by (evidence: `python/models/factory.py`)
- Model factory → Model training: builds models (evidence: `training/train_v2.py`)
- Researcher → Model training: trains models (evidence: `README.md`)
- Degradation pilot → Results and tables: reports pilot metrics (evidence: `pilot/pilot.py`)
- Model training → Results and tables: saves checkpoints (evidence: `README.md`)
- Results and tables → Test evaluation: provides checkpoints (evidence: `README.md`)
- Test evaluation → Segmentation metrics: computes measures
- Test evaluation → Results and tables: writes evaluation metrics (evidence: `README.md`)
- Researcher → Test evaluation: evaluates test set (evidence: `README.md`)
- Results and tables → Statistical analysis: provides metrics (evidence: `README.md`)
- Statistical analysis → Results and tables: writes statistics (evidence: `README.md`)
- Results and tables → Morphometrics: provides predictions (evidence: `README.md`)
- Morphometrics → Volume agreement: reports agreement
- Results and tables → Surface meshes: provides segmentations
- Surface meshes → Interactive viewer: builds surfaces (evidence: `viz3d/viewer.py`)
- Surface meshes → Paper figures: builds surfaces (evidence: `viz3d/paper_figures.py`)
- Test evaluation → Interactive viewer: exports prediction NIfTIs (evidence: `viz3d/viewer.py`)
- Interactive viewer → 3D case views: writes case views (evidence: `viz3d/viewer.py`)
- Researcher → Interactive viewer: renders comparisons (evidence: `README.md`)
