# gezugetahun-aiml/strict-ct-fvc-forecasting-release architecture

> Architecture diagram of the GitHub repository gezugetahun-aiml/strict-ct-fvc-forecasting-release, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gezugetahun-aiml/strict-ct-fvc-forecasting-release
- Repository: https://github.com/gezugetahun-aiml/strict-ct-fvc-forecasting-release

## Overview

This is a sanitized research reproducibility release for strict CT-baseline multimodal forecasting of future FVC in pulmonary fibrosis. The main workflow is authorized researchers locally rebuilding eligibility and patient-balanced folds from OSIC data, running the frozen predictor to produce local out-of-fold (OOF) predictions, then recomputing metrics and reviewer diagnostics. Separate branches provide a clinical-only Ridge baseline and a baseline-only outer-fold sensitivity comparison. The public cohort and results are aggregate/anonymous; source-level identifiers and row-level predictions remain local. Some model internals and the sensitivity model execution are not shown, so those links rely only on documented workflow statements.

Main entry points: [`analysis/rebuild_strict_cohort_and_folds.py`](https://github.com/gezugetahun-aiml/strict-ct-fvc-forecasting-release/blob/main/analysis/rebuild_strict_cohort_and_folds.py) (Strict cohort builder), [`src/FVC_Pred_FinalStable_v10.py`](https://github.com/gezugetahun-aiml/strict-ct-fvc-forecasting-release/blob/main/src/FVC_Pred_FinalStable_v10.py) (Frozen FVC predictor), [`analysis/compare_v10_vs_R2_baseline_only_outerfolds.py`](https://github.com/gezugetahun-aiml/strict-ct-fvc-forecasting-release/blob/main/analysis/compare_v10_vs_R2_baseline_only_outerfolds.py) (Paired fold comparison), [`analysis/analyze_local_oof.py`](https://github.com/gezugetahun-aiml/strict-ct-fvc-forecasting-release/blob/main/analysis/analyze_local_oof.py) (OOF metrics)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cohort["Cohort and folds"]
  node_rebuild["Strict cohort builder"]
  node_local_cohort["Local cohort and folds"]
  node_public_cohort["Anonymous cohort manifest"]
end

subgraph group_prediction["Prediction model"]
  node_frozen_model["Frozen FVC predictor"]
  node_image_features["CT feature extraction"]
  node_clinical_experts["Clinical experts"]
  node_ensemble["Expert ensemble and calibration"]
  node_local_oof["Local OOF predictions"]
end

subgraph group_evaluation["Evaluation"]
  node_metrics["OOF metrics"]
  node_catastrophic["Expert range diagnostics"]
  node_reference_results["Aggregate reference results"]
end

subgraph group_benchmarks["Reviewer analyses"]
  node_ridge["Clinical Ridge baseline"]
  node_sensitivity["Baseline-only fold sensitivity"]
  node_comparison["Paired fold comparison"]
end

node_researcher(("Authorized researcher"))
node_osic[("OSIC data")]

node_researcher -->|"runs locally"| node_rebuild
node_osic -->|"provides train data"| node_rebuild
node_rebuild -->|"writes cohort and folds"| node_local_cohort
node_researcher -->|"runs predictor"| node_frozen_model
node_osic -->|"provides CT and clinical data"| node_frozen_model
node_image_features -.->|"supplies image features"| node_frozen_model
node_clinical_experts -.->|"contributes experts"| node_frozen_model
node_frozen_model -->|"writes predictions"| node_local_oof
node_local_oof -->|"provides predictions"| node_metrics
node_local_oof -->|"provides predictions"| node_catastrophic
node_researcher -->|"runs baseline"| node_ridge
node_ridge -->|"imports cohort and fold logic"| node_rebuild
node_researcher -->|"runs sensitivity analysis"| node_sensitivity
node_local_oof -->|"provides reference predictions"| node_comparison
node_sensitivity -->|"provides sensitivity predictions"| node_comparison
node_comparison -.->|"reports aggregate comparison"| node_reference_results
node_metrics -.->|"recomputes reported metrics"| node_reference_results
node_rebuild -.->|"described by release manifest"| node_public_cohort

click node_rebuild "https://github.com/gezugetahun-aiml/strict-ct-fvc-forecasting-release/blob/main/analysis/rebuild_strict_cohort_and_folds.py"
click node_local_cohort "https://github.com/gezugetahun-aiml/strict-ct-fvc-forecasting-release/blob/main/analysis/rebuild_strict_cohort_and_folds.py"
click node_public_cohort "https://github.com/gezugetahun-aiml/strict-ct-fvc-forecasting-release/blob/main/cohort/release_patient_manifest.csv"
click node_frozen_model "https://github.com/gezugetahun-aiml/strict-ct-fvc-forecasting-release/blob/main/src/FVC_Pred_FinalStable_v10.py"
click node_image_features "https://github.com/gezugetahun-aiml/strict-ct-fvc-forecasting-release/blob/main/src/FVC_Pred_FinalStable_v10.py"
click node_clinical_experts "https://github.com/gezugetahun-aiml/strict-ct-fvc-forecasting-release/blob/main/src/FVC_Pred_FinalStable_v10.py"
click node_ensemble "https://github.com/gezugetahun-aiml/strict-ct-fvc-forecasting-release/blob/main/src/FVC_Pred_FinalStable_v10.py"
click node_local_oof "https://github.com/gezugetahun-aiml/strict-ct-fvc-forecasting-release/blob/main/src/FVC_Pred_FinalStable_v10.py"
click node_metrics "https://github.com/gezugetahun-aiml/strict-ct-fvc-forecasting-release/blob/main/analysis/analyze_local_oof.py"
click node_catastrophic "https://github.com/gezugetahun-aiml/strict-ct-fvc-forecasting-release/blob/main/analysis/make_catastrophic_expert_range_table.py"
click node_reference_results "https://github.com/gezugetahun-aiml/strict-ct-fvc-forecasting-release/blob/main/results/primary_metrics.csv"
click node_ridge "https://github.com/gezugetahun-aiml/strict-ct-fvc-forecasting-release/blob/main/analysis/clinical_temporal_ridge_baseline.py"
click node_sensitivity "https://github.com/gezugetahun-aiml/strict-ct-fvc-forecasting-release/tree/main/analysis"
click node_comparison "https://github.com/gezugetahun-aiml/strict-ct-fvc-forecasting-release/blob/main/analysis/compare_v10_vs_R2_baseline_only_outerfolds.py"

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_rebuild,node_local_cohort,node_public_cohort toneBlue
class node_frozen_model,node_image_features,node_clinical_experts,node_ensemble,node_local_oof,node_osic toneAmber
class node_metrics,node_catastrophic,node_reference_results toneMint
class node_ridge,node_sensitivity,node_comparison toneRose
class node_researcher toneIndigo
```

## Components

### Cohort and folds

- [Strict cohort builder](https://github.com/gezugetahun-aiml/strict-ct-fvc-forecasting-release/blob/main/analysis/rebuild_strict_cohort_and_folds.py): `analysis/rebuild_strict_cohort_and_folds.py`
- [Local cohort and folds](https://github.com/gezugetahun-aiml/strict-ct-fvc-forecasting-release/blob/main/analysis/rebuild_strict_cohort_and_folds.py): `analysis/rebuild_strict_cohort_and_folds.py`
- [Anonymous cohort manifest](https://github.com/gezugetahun-aiml/strict-ct-fvc-forecasting-release/blob/main/cohort/release_patient_manifest.csv): `cohort/release_patient_manifest.csv`

### Prediction model

- [Frozen FVC predictor](https://github.com/gezugetahun-aiml/strict-ct-fvc-forecasting-release/blob/main/src/FVC_Pred_FinalStable_v10.py): `src/FVC_Pred_FinalStable_v10.py`
- [CT feature extraction](https://github.com/gezugetahun-aiml/strict-ct-fvc-forecasting-release/blob/main/src/FVC_Pred_FinalStable_v10.py): `src/FVC_Pred_FinalStable_v10.py`
- [Clinical experts](https://github.com/gezugetahun-aiml/strict-ct-fvc-forecasting-release/blob/main/src/FVC_Pred_FinalStable_v10.py): `src/FVC_Pred_FinalStable_v10.py`
- [Expert ensemble and calibration](https://github.com/gezugetahun-aiml/strict-ct-fvc-forecasting-release/blob/main/src/FVC_Pred_FinalStable_v10.py): `src/FVC_Pred_FinalStable_v10.py`
- [Local OOF predictions](https://github.com/gezugetahun-aiml/strict-ct-fvc-forecasting-release/blob/main/src/FVC_Pred_FinalStable_v10.py): `src/FVC_Pred_FinalStable_v10.py`

### Evaluation

- [OOF metrics](https://github.com/gezugetahun-aiml/strict-ct-fvc-forecasting-release/blob/main/analysis/analyze_local_oof.py): `analysis/analyze_local_oof.py`
- [Expert range diagnostics](https://github.com/gezugetahun-aiml/strict-ct-fvc-forecasting-release/blob/main/analysis/make_catastrophic_expert_range_table.py): `analysis/make_catastrophic_expert_range_table.py`
- [Aggregate reference results](https://github.com/gezugetahun-aiml/strict-ct-fvc-forecasting-release/blob/main/results/primary_metrics.csv): `results/primary_metrics.csv`

### Reviewer analyses

- [Clinical Ridge baseline](https://github.com/gezugetahun-aiml/strict-ct-fvc-forecasting-release/blob/main/analysis/clinical_temporal_ridge_baseline.py): `analysis/clinical_temporal_ridge_baseline.py`
- [Baseline-only fold sensitivity](https://github.com/gezugetahun-aiml/strict-ct-fvc-forecasting-release/tree/main/analysis): `analysis`
- [Paired fold comparison](https://github.com/gezugetahun-aiml/strict-ct-fvc-forecasting-release/blob/main/analysis/compare_v10_vs_R2_baseline_only_outerfolds.py): `analysis/compare_v10_vs_R2_baseline_only_outerfolds.py`

### Other components

- **Authorized researcher**
- **OSIC data**

## Connections

- Authorized researcher → Strict cohort builder: runs locally (evidence: `README.md`)
- OSIC data → Strict cohort builder: provides train data (evidence: `README.md`)
- Strict cohort builder → Local cohort and folds: writes cohort and folds (evidence: `analysis/rebuild_strict_cohort_and_folds.py`)
- Authorized researcher → Frozen FVC predictor: runs predictor (evidence: `README.md`)
- OSIC data → Frozen FVC predictor: provides CT and clinical data (evidence: `src/FVC_Pred_FinalStable_v10.py`)
- CT feature extraction → Frozen FVC predictor: supplies image features (evidence: `src/FVC_Pred_FinalStable_v10.py`)
- Clinical experts → Frozen FVC predictor: contributes experts (evidence: `src/FVC_Pred_FinalStable_v10.py`)
- Frozen FVC predictor → Local OOF predictions: writes predictions (evidence: `README.md`)
- Local OOF predictions → OOF metrics: provides predictions (evidence: `analysis/analyze_local_oof.py`)
- Local OOF predictions → Expert range diagnostics: provides predictions (evidence: `analysis/make_catastrophic_expert_range_table.py`)
- Authorized researcher → Clinical Ridge baseline: runs baseline (evidence: `README.md`)
- Clinical Ridge baseline → Strict cohort builder: imports cohort and fold logic (evidence: `analysis/clinical_temporal_ridge_baseline.py`)
- Authorized researcher → Baseline-only fold sensitivity: runs sensitivity analysis (evidence: `README.md`)
- Local OOF predictions → Paired fold comparison: provides reference predictions (evidence: `analysis/compare_v10_vs_R2_baseline_only_outerfolds.py`)
- Baseline-only fold sensitivity → Paired fold comparison: provides sensitivity predictions (evidence: `README.md`)
- Paired fold comparison → Aggregate reference results: reports aggregate comparison
- OOF metrics → Aggregate reference results: recomputes reported metrics (evidence: `README.md`)
- Strict cohort builder → Anonymous cohort manifest: described by release manifest (evidence: `README.md`)