# lakshyakushwahaaiml2023-ops/marginsense architecture

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

- Interactive diagram: https://gitdiagram.com/lakshyakushwahaaiml2023-ops/marginsense
- Repository: https://github.com/lakshyakushwahaaiml2023-ops/marginsense

## Overview

MarginSense is a patient-specific radiotherapy planning and research pipeline: it turns MRI/segmentation data into a physics-informed cell-density prediction, estimates ensemble uncertainty, and uses those estimates to support asymmetric treatment margins while protecting CSF/OAR regions. The graph also preserves conventional and GliODIL/PINN comparisons, evaluation, upload preprocessing, and visualization. Evidence is limited to the README and sampled source/index references; unsampled implementation links are omitted where their caller is not shown.

Main entry points: [`data/processed`](https://github.com/lakshyakushwahaaiml2023-ops/marginsense/tree/main/data/processed) (Processed patient volumes), [`src/models/amortized_pinn.py`](https://github.com/lakshyakushwahaaiml2023-ops/marginsense/blob/main/src/models/amortized_pinn.py) (Amortized PINN), [`src/evaluate_pipeline.py`](https://github.com/lakshyakushwahaaiml2023-ops/marginsense/blob/main/src/evaluate_pipeline.py) (Pipeline evaluation), [`src/evaluate_uncertainty.py`](https://github.com/lakshyakushwahaaiml2023-ops/marginsense/blob/main/src/evaluate_uncertainty.py) (Ensemble uncertainty)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Patient data"]
  node_mri["MRI and labels"]
  node_preprocess["Dataset preprocessing<br/>[preprocess.py]"]
  node_uploadprep["Upload preprocessing"]
  node_patientdata[("Processed patient volumes")]
  node_features["Patient features"]
end

subgraph group_modeling["Modeling"]
  node_network["Amortized PINN<br/>[amortized_pinn.py]"]
  node_train["Single-model training<br/>[train.py]"]
  node_ensembletrain["Ensemble training<br/>[train_ensemble.py]"]
  node_checkpoints[("Model checkpoints")]
  node_uq["Ensemble uncertainty"]
end

subgraph group_clinical["Planning and evaluation"]
  node_margin["Margin optimization<br/>[server.py]"]
  node_evaluation["Pipeline evaluation"]
  node_vanilla["Vanilla PINN baseline"]
  node_gliodil["GliODIL baseline"]
  node_uniform["Uniform margin baseline"]
  node_comparison["Model comparison<br/>[compare_models.py]"]
  node_results[("Predictions and reports")]
end

subgraph group_application["Upload and visualization"]
  node_webapp["Planning interface<br/>[server.py]"]
  node_export["Visualization data export<br/>[export_json.py]"]
  node_meshes["3D mesh export<br/>[export_meshes.py]"]
  node_viewer["3D viewer<br/>[index.html]"]
  node_vizdata["Viewer data client<br/>[data.js]"]
end

node_clinician(("Clinician"))

node_clinician -->|"submits patient"| node_webapp
node_mri -->|"preprocesses"| node_preprocess
node_mri -->|"uploads scans"| node_uploadprep
node_preprocess -->|"writes volumes"| node_patientdata
node_uploadprep -->|"writes bundle"| node_patientdata
node_preprocess -->|"uses features"| node_features
node_uploadprep -->|"uses features"| node_features
node_train -->|"trains"| node_network
node_ensembletrain -->|"trains"| node_network
node_train -->|"loads volumes"| node_patientdata
node_ensembletrain -->|"loads volumes"| node_patientdata
node_train -.->|"saves weights"| node_checkpoints
node_ensembletrain -.->|"saves weights"| node_checkpoints
node_network -->|"uses covariates"| node_features
node_uq -->|"evaluates"| node_network
node_uq -->|"loads volumes"| node_patientdata
node_uq -->|"loads ensemble"| node_checkpoints
node_uq -->|"writes uncertainty"| node_results
node_margin -->|"reads predictions"| node_results
node_margin -.->|"reads patient data"| node_patientdata
node_evaluation -->|"evaluates model"| node_network
node_evaluation -->|"runs training"| node_train
node_evaluation -->|"runs baseline"| node_vanilla
node_evaluation -->|"runs baseline"| node_gliodil
node_evaluation -.->|"writes metrics"| node_results
node_comparison -.->|"compares margins"| node_uniform
node_webapp -->|"starts preprocessing"| node_uploadprep
node_webapp -->|"uses features"| node_features
node_export -->|"loads model"| node_network
node_export -->|"reads volumes"| node_patientdata
node_export -->|"reads predictions"| node_results
node_export -->|"uses margin baseline"| node_uniform
node_webapp -.->|"serves interface"| node_viewer
node_viewer -.->|"uses viewer data"| node_vizdata
node_meshes -.->|"provides 3D assets"| node_viewer

click node_preprocess "https://github.com/lakshyakushwahaaiml2023-ops/marginsense/blob/main/src/preprocess.py"
click node_uploadprep "https://github.com/lakshyakushwahaaiml2023-ops/marginsense/blob/main/src/preprocess_upload.py"
click node_patientdata "https://github.com/lakshyakushwahaaiml2023-ops/marginsense/tree/main/data/processed"
click node_features "https://github.com/lakshyakushwahaaiml2023-ops/marginsense/blob/main/src/compute_features.py"
click node_network "https://github.com/lakshyakushwahaaiml2023-ops/marginsense/blob/main/src/models/amortized_pinn.py"
click node_train "https://github.com/lakshyakushwahaaiml2023-ops/marginsense/blob/main/src/training/train.py"
click node_ensembletrain "https://github.com/lakshyakushwahaaiml2023-ops/marginsense/blob/main/src/training/train_ensemble.py"
click node_checkpoints "https://github.com/lakshyakushwahaaiml2023-ops/marginsense/tree/main/outputs"
click node_uq "https://github.com/lakshyakushwahaaiml2023-ops/marginsense/blob/main/src/evaluate_uncertainty.py"
click node_margin "https://github.com/lakshyakushwahaaiml2023-ops/marginsense/blob/main/src/viz/server.py"
click node_evaluation "https://github.com/lakshyakushwahaaiml2023-ops/marginsense/blob/main/src/evaluate_pipeline.py"
click node_vanilla "https://github.com/lakshyakushwahaaiml2023-ops/marginsense/blob/main/src/baseline_vanilla_pinn.py"
click node_gliodil "https://github.com/lakshyakushwahaaiml2023-ops/marginsense/blob/main/src/baseline_gliodil.py"
click node_uniform "https://github.com/lakshyakushwahaaiml2023-ops/marginsense/blob/main/src/baseline_uniform_margin.py"
click node_comparison "https://github.com/lakshyakushwahaaiml2023-ops/marginsense/blob/main/src/compare_models.py"
click node_webapp "https://github.com/lakshyakushwahaaiml2023-ops/marginsense/blob/main/src/viz/server.py"
click node_export "https://github.com/lakshyakushwahaaiml2023-ops/marginsense/blob/main/src/viz/export_json.py"
click node_meshes "https://github.com/lakshyakushwahaaiml2023-ops/marginsense/blob/main/src/viz/export_meshes.py"
click node_viewer "https://github.com/lakshyakushwahaaiml2023-ops/marginsense/blob/main/src/viz/index.html"
click node_vizdata "https://github.com/lakshyakushwahaaiml2023-ops/marginsense/blob/main/src/viz/data.js"
click node_results "https://github.com/lakshyakushwahaaiml2023-ops/marginsense/tree/main/outputs"

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_mri,node_preprocess,node_uploadprep,node_patientdata,node_features toneBlue
class node_network,node_train,node_ensembletrain,node_checkpoints,node_uq toneAmber
class node_margin,node_evaluation,node_vanilla,node_gliodil,node_uniform,node_comparison,node_results toneMint
class node_webapp,node_export,node_meshes,node_viewer,node_vizdata toneRose
class node_clinician toneIndigo
```

## Components

### Patient data

- **MRI and labels**
- [Dataset preprocessing](https://github.com/lakshyakushwahaaiml2023-ops/marginsense/blob/main/src/preprocess.py): `src/preprocess.py`
- [Upload preprocessing](https://github.com/lakshyakushwahaaiml2023-ops/marginsense/blob/main/src/preprocess_upload.py): `src/preprocess_upload.py`
- [Processed patient volumes](https://github.com/lakshyakushwahaaiml2023-ops/marginsense/tree/main/data/processed): `data/processed`
- [Patient features](https://github.com/lakshyakushwahaaiml2023-ops/marginsense/blob/main/src/compute_features.py): `src/compute_features.py`

### Modeling

- [Amortized PINN](https://github.com/lakshyakushwahaaiml2023-ops/marginsense/blob/main/src/models/amortized_pinn.py): `src/models/amortized_pinn.py`
- [Single-model training](https://github.com/lakshyakushwahaaiml2023-ops/marginsense/blob/main/src/training/train.py): `src/training/train.py`
- [Ensemble training](https://github.com/lakshyakushwahaaiml2023-ops/marginsense/blob/main/src/training/train_ensemble.py): `src/training/train_ensemble.py`
- [Model checkpoints](https://github.com/lakshyakushwahaaiml2023-ops/marginsense/tree/main/outputs): `outputs`
- [Ensemble uncertainty](https://github.com/lakshyakushwahaaiml2023-ops/marginsense/blob/main/src/evaluate_uncertainty.py): `src/evaluate_uncertainty.py`

### Planning and evaluation

- [Margin optimization](https://github.com/lakshyakushwahaaiml2023-ops/marginsense/blob/main/src/viz/server.py): `src/viz/server.py`
- [Pipeline evaluation](https://github.com/lakshyakushwahaaiml2023-ops/marginsense/blob/main/src/evaluate_pipeline.py): `src/evaluate_pipeline.py`
- [Vanilla PINN baseline](https://github.com/lakshyakushwahaaiml2023-ops/marginsense/blob/main/src/baseline_vanilla_pinn.py): `src/baseline_vanilla_pinn.py`
- [GliODIL baseline](https://github.com/lakshyakushwahaaiml2023-ops/marginsense/blob/main/src/baseline_gliodil.py): `src/baseline_gliodil.py`
- [Uniform margin baseline](https://github.com/lakshyakushwahaaiml2023-ops/marginsense/blob/main/src/baseline_uniform_margin.py): `src/baseline_uniform_margin.py`
- [Model comparison](https://github.com/lakshyakushwahaaiml2023-ops/marginsense/blob/main/src/compare_models.py): `src/compare_models.py`
- [Predictions and reports](https://github.com/lakshyakushwahaaiml2023-ops/marginsense/tree/main/outputs): `outputs`

### Upload and visualization

- [Planning interface](https://github.com/lakshyakushwahaaiml2023-ops/marginsense/blob/main/src/viz/server.py): `src/viz/server.py`
- [Visualization data export](https://github.com/lakshyakushwahaaiml2023-ops/marginsense/blob/main/src/viz/export_json.py): `src/viz/export_json.py`
- [3D mesh export](https://github.com/lakshyakushwahaaiml2023-ops/marginsense/blob/main/src/viz/export_meshes.py): `src/viz/export_meshes.py`
- [3D viewer](https://github.com/lakshyakushwahaaiml2023-ops/marginsense/blob/main/src/viz/index.html): `src/viz/index.html`
- [Viewer data client](https://github.com/lakshyakushwahaaiml2023-ops/marginsense/blob/main/src/viz/data.js): `src/viz/data.js`

### Other components

- **Clinician**

## Connections

- Clinician → Planning interface: submits patient (evidence: `README.md`)
- MRI and labels → Dataset preprocessing: preprocesses (evidence: `README.md`)
- MRI and labels → Upload preprocessing: uploads scans (evidence: `src/preprocess_upload.py`)
- Dataset preprocessing → Processed patient volumes: writes volumes (evidence: `src/preprocess.py`)
- Upload preprocessing → Processed patient volumes: writes bundle (evidence: `src/preprocess_upload.py`)
- Dataset preprocessing → Patient features: uses features (evidence: `src/preprocess.py`)
- Upload preprocessing → Patient features: uses features (evidence: `src/preprocess_upload.py`)
- Single-model training → Amortized PINN: trains (evidence: `src/training/train.py`)
- Ensemble training → Amortized PINN: trains (evidence: `src/training/train_ensemble.py`)
- Single-model training → Processed patient volumes: loads volumes (evidence: `src/training/train.py`)
- Ensemble training → Processed patient volumes: loads volumes (evidence: `src/training/train_ensemble.py`)
- Single-model training → Model checkpoints: saves weights
- Ensemble training → Model checkpoints: saves weights
- Amortized PINN → Patient features: uses covariates (evidence: `src/models/amortized_pinn.py`)
- Ensemble uncertainty → Amortized PINN: evaluates (evidence: `src/evaluate_uncertainty.py`)
- Ensemble uncertainty → Processed patient volumes: loads volumes (evidence: `src/evaluate_uncertainty.py`)
- Ensemble uncertainty → Model checkpoints: loads ensemble (evidence: `src/evaluate_uncertainty.py`)
- Ensemble uncertainty → Predictions and reports: writes uncertainty (evidence: `src/evaluate_uncertainty.py`)
- Margin optimization → Predictions and reports: reads predictions (evidence: `src/viz/server.py`)
- Margin optimization → Processed patient volumes: reads patient data
- Pipeline evaluation → Amortized PINN: evaluates model (evidence: `src/evaluate_pipeline.py`)
- Pipeline evaluation → Single-model training: runs training (evidence: `src/evaluate_pipeline.py`)
- Pipeline evaluation → Vanilla PINN baseline: runs baseline (evidence: `src/evaluate_pipeline.py`)
- Pipeline evaluation → GliODIL baseline: runs baseline (evidence: `src/evaluate_pipeline.py`)
- Pipeline evaluation → Predictions and reports: writes metrics
- Model comparison → Uniform margin baseline: compares margins
- Planning interface → Upload preprocessing: starts preprocessing (evidence: `src/viz/server.py`)
- Planning interface → Patient features: uses features (evidence: `src/viz/server.py`)
- Visualization data export → Amortized PINN: loads model (evidence: `src/viz/export_json.py`)
- Visualization data export → Processed patient volumes: reads volumes (evidence: `src/viz/export_json.py`)
- Visualization data export → Predictions and reports: reads predictions (evidence: `src/viz/export_json.py`)
- Visualization data export → Uniform margin baseline: uses margin baseline (evidence: `src/viz/export_json.py`)
- Planning interface → 3D viewer: serves interface
- 3D viewer → Viewer data client: uses viewer data
- 3D mesh export → 3D viewer: provides 3D assets
