# biswadev-9/thesis architecture

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

- Interactive diagram: https://gitdiagram.com/biswadev-9/thesis
- Repository: https://github.com/biswadev-9/thesis

## Overview

This is a configurable research pipeline for four-class brain MRI classification, not a deployed inference product. Its principal workflow prepares and audits a deduplicated, stratified dataset; trains image-classification branches; extracts and caches frozen features for fusion; then evaluates and explains the assembled classifier. The README also documents preprocessing and imbalance comparisons, baselines, external and degradation evaluation, ablations, and statistical reporting. Arrows follow the documented workflow; unsampled stage internals are represented by their existing source directories.

Main entry points: [`src/models/full_pipeline.py`](https://github.com/biswadev-9/thesis/blob/main/src/models/full_pipeline.py) (Image-to-logits pipeline), [`src/data/components/split_builder.py`](https://github.com/biswadev-9/thesis/blob/main/src/data/components/split_builder.py) (Stratified split table), [`src/data/bt_mri_datamodule.py`](https://github.com/biswadev-9/thesis/blob/main/src/data/bt_mri_datamodule.py) (MRI datamodule), [`src/analysis/ablation_study.py`](https://github.com/biswadev-9/thesis/blob/main/src/analysis/ablation_study.py) (Ablation and comparisons)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data preparation"]
  node_split_audit["Deduplication and audit<br/>[split_builder.py]"]
  node_split_table["Stratified split table<br/>[split_builder.py]"]
  node_preprocessing_studies["Preprocessing comparison"]
  node_imbalance_studies["Imbalance comparison<br/>[imbalance_study.py]"]
  node_image_cache["Processed image cache<br/>[prepare_dataset.py]"]
  node_mri_data["MRI datamodule"]
end

subgraph group_experiments["Model experiments"]
  node_training["Model training<br/>[train.py]"]
  node_baseline_models["CNN and Transformer baselines<br/>[backbones.py]"]
  node_classical_branch["Classical feature branch<br/>[backbones.py]"]
  node_adaptive_branch["Multiscale quantum branch<br/>[quantum.py]"]
  node_feature_extraction["Frozen feature extraction"]
  node_feature_cache["Split feature caches"]
  node_fusion_studies["Fusion and loss studies<br/>[fusion_study.py]"]
  node_fusion_head["Final fusion classifier<br/>[fusion.py]"]
  node_full_pipeline["Image-to-logits pipeline<br/>[full_pipeline.py]"]
end

subgraph group_assessment["Evaluation and explanation"]
  node_evaluation["Internal and external evaluation<br/>[eval.py]"]
  node_robustness["Degradation evaluation<br/>[robustness.py]"]
  node_explainability["Explainability analysis<br/>[explainability.py]"]
end

subgraph group_research["Study analysis"]
  node_embeddings["Embedding analysis<br/>[embeddings.py]"]
  node_ablation["Ablation and comparisons<br/>[ablation_study.py]"]
  node_rq_mapping["Research-question mapping<br/>[rq_mapping.py]"]
  node_statistics["Statistical reporting"]
  node_study_reports["Study reports and results"]
end

node_researcher(("Researcher"))
node_raw_mri["Raw MRI images"]
node_external_data["External MRI data"]

node_researcher -->|"prepares study data"| node_split_audit
node_raw_mri -->|"scans and deduplicates"| node_split_audit
node_split_audit -->|"writes splits"| node_split_table
node_split_table -->|"supplies split data"| node_preprocessing_studies
node_split_table -->|"supplies split data"| node_imbalance_studies
node_split_table -->|"selects images"| node_image_cache
node_raw_mri -->|"filters images"| node_image_cache
node_split_table -->|"defines splits"| node_mri_data
node_image_cache -->|"provides processed images"| node_mri_data
node_mri_data -->|"provides batches"| node_training
node_training -->|"trains"| node_baseline_models
node_training -->|"trains"| node_classical_branch
node_training -->|"trains"| node_adaptive_branch
node_mri_data -->|"provides batches"| node_feature_extraction
node_classical_branch -->|"extracts features"| node_feature_extraction
node_adaptive_branch -->|"extracts features"| node_feature_extraction
node_feature_extraction -->|"writes split features"| node_feature_cache
node_feature_cache -->|"supplies cached features"| node_fusion_studies
node_fusion_studies -->|"selects and trains"| node_fusion_head
node_classical_branch -->|"assembles branch"| node_full_pipeline
node_adaptive_branch -->|"assembles branch"| node_full_pipeline
node_fusion_head -->|"assembles classifier"| node_full_pipeline
node_mri_data -->|"provides internal data"| node_evaluation
node_external_data -->|"provides external data"| node_evaluation
node_full_pipeline -->|"predicts for evaluation"| node_evaluation
node_full_pipeline -->|"predicts degraded inputs"| node_robustness
node_full_pipeline -->|"provides gradients and outputs"| node_explainability
node_classical_branch -->|"provides representations"| node_embeddings
node_baseline_models -->|"supports comparisons"| node_ablation
node_evaluation -->|"supplies results"| node_ablation
node_robustness -->|"supplies results"| node_ablation
node_explainability -->|"supports research questions"| node_rq_mapping
node_ablation -->|"maps comparisons"| node_rq_mapping
node_ablation -->|"supplies predictions"| node_statistics
node_statistics -->|"produces reports"| node_study_reports
node_rq_mapping -->|"summarizes findings"| node_study_reports

click node_split_audit "https://github.com/biswadev-9/thesis/blob/main/src/data/components/split_builder.py"
click node_split_table "https://github.com/biswadev-9/thesis/blob/main/src/data/components/split_builder.py"
click node_preprocessing_studies "https://github.com/biswadev-9/thesis/blob/main/src/analysis/preprocessing_study.py"
click node_imbalance_studies "https://github.com/biswadev-9/thesis/blob/main/src/analysis/imbalance_study.py"
click node_image_cache "https://github.com/biswadev-9/thesis/blob/main/src/prepare_dataset.py"
click node_mri_data "https://github.com/biswadev-9/thesis/blob/main/src/data/bt_mri_datamodule.py"
click node_training "https://github.com/biswadev-9/thesis/blob/main/src/train.py"
click node_baseline_models "https://github.com/biswadev-9/thesis/blob/main/src/models/components/backbones.py"
click node_classical_branch "https://github.com/biswadev-9/thesis/blob/main/src/models/components/backbones.py"
click node_adaptive_branch "https://github.com/biswadev-9/thesis/blob/main/src/models/components/quantum.py"
click node_feature_extraction "https://github.com/biswadev-9/thesis/blob/main/src/extract_features.py"
click node_feature_cache "https://github.com/biswadev-9/thesis/blob/main/src/extract_features.py"
click node_fusion_studies "https://github.com/biswadev-9/thesis/blob/main/src/analysis/fusion_study.py"
click node_fusion_head "https://github.com/biswadev-9/thesis/blob/main/src/models/components/fusion.py"
click node_full_pipeline "https://github.com/biswadev-9/thesis/blob/main/src/models/full_pipeline.py"
click node_evaluation "https://github.com/biswadev-9/thesis/blob/main/src/eval.py"
click node_robustness "https://github.com/biswadev-9/thesis/blob/main/src/analysis/robustness.py"
click node_explainability "https://github.com/biswadev-9/thesis/blob/main/src/analysis/explainability.py"
click node_embeddings "https://github.com/biswadev-9/thesis/blob/main/src/analysis/embeddings.py"
click node_ablation "https://github.com/biswadev-9/thesis/blob/main/src/analysis/ablation_study.py"
click node_rq_mapping "https://github.com/biswadev-9/thesis/blob/main/src/analysis/rq_mapping.py"
click node_statistics "https://github.com/biswadev-9/thesis/blob/main/src/analysis/statistical_report.py"
click node_study_reports "https://github.com/biswadev-9/thesis/blob/main/src/analysis/statistical_report.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_split_audit,node_split_table,node_preprocessing_studies,node_imbalance_studies,node_image_cache,node_mri_data toneBlue
class node_training,node_baseline_models,node_classical_branch,node_adaptive_branch,node_feature_extraction,node_feature_cache,node_fusion_studies,node_fusion_head,node_full_pipeline toneAmber
class node_evaluation,node_robustness,node_explainability toneMint
class node_embeddings,node_ablation,node_rq_mapping,node_statistics,node_study_reports toneRose
class node_researcher,node_raw_mri,node_external_data toneIndigo
```

## Components

### Data preparation

- [Deduplication and audit](https://github.com/biswadev-9/thesis/blob/main/src/data/components/split_builder.py): `src/data/components/split_builder.py`
- [Stratified split table](https://github.com/biswadev-9/thesis/blob/main/src/data/components/split_builder.py): `src/data/components/split_builder.py`
- [Preprocessing comparison](https://github.com/biswadev-9/thesis/blob/main/src/analysis/preprocessing_study.py): `src/analysis/preprocessing_study.py`
- [Imbalance comparison](https://github.com/biswadev-9/thesis/blob/main/src/analysis/imbalance_study.py): `src/analysis/imbalance_study.py`
- [Processed image cache](https://github.com/biswadev-9/thesis/blob/main/src/prepare_dataset.py): `src/prepare_dataset.py`
- [MRI datamodule](https://github.com/biswadev-9/thesis/blob/main/src/data/bt_mri_datamodule.py): `src/data/bt_mri_datamodule.py`

### Model experiments

- [Model training](https://github.com/biswadev-9/thesis/blob/main/src/train.py): `src/train.py`
- [CNN and Transformer baselines](https://github.com/biswadev-9/thesis/blob/main/src/models/components/backbones.py): `src/models/components/backbones.py`
- [Classical feature branch](https://github.com/biswadev-9/thesis/blob/main/src/models/components/backbones.py): `src/models/components/backbones.py`
- [Multiscale quantum branch](https://github.com/biswadev-9/thesis/blob/main/src/models/components/quantum.py): `src/models/components/quantum.py`
- [Frozen feature extraction](https://github.com/biswadev-9/thesis/blob/main/src/extract_features.py): `src/extract_features.py`
- [Split feature caches](https://github.com/biswadev-9/thesis/blob/main/src/extract_features.py): `src/extract_features.py`
- [Fusion and loss studies](https://github.com/biswadev-9/thesis/blob/main/src/analysis/fusion_study.py): `src/analysis/fusion_study.py`
- [Final fusion classifier](https://github.com/biswadev-9/thesis/blob/main/src/models/components/fusion.py): `src/models/components/fusion.py`
- [Image-to-logits pipeline](https://github.com/biswadev-9/thesis/blob/main/src/models/full_pipeline.py): `src/models/full_pipeline.py`

### Evaluation and explanation

- [Internal and external evaluation](https://github.com/biswadev-9/thesis/blob/main/src/eval.py): `src/eval.py`
- [Degradation evaluation](https://github.com/biswadev-9/thesis/blob/main/src/analysis/robustness.py): `src/analysis/robustness.py`
- [Explainability analysis](https://github.com/biswadev-9/thesis/blob/main/src/analysis/explainability.py): `src/analysis/explainability.py`

### Study analysis

- [Embedding analysis](https://github.com/biswadev-9/thesis/blob/main/src/analysis/embeddings.py): `src/analysis/embeddings.py`
- [Ablation and comparisons](https://github.com/biswadev-9/thesis/blob/main/src/analysis/ablation_study.py): `src/analysis/ablation_study.py`
- [Research-question mapping](https://github.com/biswadev-9/thesis/blob/main/src/analysis/rq_mapping.py): `src/analysis/rq_mapping.py`
- [Statistical reporting](https://github.com/biswadev-9/thesis/blob/main/src/analysis/statistical_report.py): `src/analysis/statistical_report.py`
- [Study reports and results](https://github.com/biswadev-9/thesis/blob/main/src/analysis/statistical_report.py): `src/analysis/statistical_report.py`

### Other components

- **Researcher**
- **Raw MRI images**
- **External MRI data**

## Connections

- Researcher → Deduplication and audit: prepares study data
- Raw MRI images → Deduplication and audit: scans and deduplicates
- Deduplication and audit → Stratified split table: writes splits
- Stratified split table → Preprocessing comparison: supplies split data
- Stratified split table → Imbalance comparison: supplies split data
- Stratified split table → Processed image cache: selects images
- Raw MRI images → Processed image cache: filters images
- Stratified split table → MRI datamodule: defines splits
- Processed image cache → MRI datamodule: provides processed images
- MRI datamodule → Model training: provides batches
- Model training → CNN and Transformer baselines: trains
- Model training → Classical feature branch: trains
- Model training → Multiscale quantum branch: trains
- MRI datamodule → Frozen feature extraction: provides batches
- Classical feature branch → Frozen feature extraction: extracts features
- Multiscale quantum branch → Frozen feature extraction: extracts features
- Frozen feature extraction → Split feature caches: writes split features
- Split feature caches → Fusion and loss studies: supplies cached features
- Fusion and loss studies → Final fusion classifier: selects and trains
- Classical feature branch → Image-to-logits pipeline: assembles branch
- Multiscale quantum branch → Image-to-logits pipeline: assembles branch
- Final fusion classifier → Image-to-logits pipeline: assembles classifier
- MRI datamodule → Internal and external evaluation: provides internal data
- External MRI data → Internal and external evaluation: provides external data
- Image-to-logits pipeline → Internal and external evaluation: predicts for evaluation
- Image-to-logits pipeline → Degradation evaluation: predicts degraded inputs
- Image-to-logits pipeline → Explainability analysis: provides gradients and outputs
- Classical feature branch → Embedding analysis: provides representations
- CNN and Transformer baselines → Ablation and comparisons: supports comparisons
- Internal and external evaluation → Ablation and comparisons: supplies results
- Degradation evaluation → Ablation and comparisons: supplies results
- Explainability analysis → Research-question mapping: supports research questions
- Ablation and comparisons → Research-question mapping: maps comparisons
- Ablation and comparisons → Statistical reporting: supplies predictions
- Statistical reporting → Study reports and results: produces reports
- Research-question mapping → Study reports and results: summarizes findings