# pawere/spectra-estimation-dmri architecture

> Architecture diagram of the GitHub repository pawere/spectra-estimation-dmri, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pawere/spectra-estimation-dmri
- Repository: https://github.com/pawere/spectra-estimation-dmri

## Overview

##### Project type and purpose
- This is a Python library and command‐line pipeline for Bayesian estimation of diffusivity spectra in prostate gland diffusion MRI. There is no web UI—this is a computational research tool packaged under `src/spectra_estimation_dmri/`. It loads curated JSON data, applies sampling‐based inference (Gibbs, variational), then produces CSV/PDF outputs for analysis.

##### File structure
- Top‐level:
- `pyproject.toml`, `uv.lock`: build/config
- `src/spectra_estimation_dmri/`: main package
- `output/`: generated results (auto‐created, gitignored)
- Under `src/spectra_estimation_dmri/`:
- `data/`: JSON inputs & metadata CSVs
- `configs.yaml`: sampling & pipeline settings
- `utils/`: data preprocessing & plotting helpers
- `models/`: sampling algorithms divided into
– `samplers/base.py` (abstract sampler interface)
– `samplers/gibbs_sampler.py`, `variational_sampler.py`, etc.
– `old/`: legacy implementations
- `testing/`: simulation scripts (`simulation.py`) and unit tests
- `eval/`: evaluation scripts generating statistics and combined plots

##### README for insights
- Confirms the library approach, external deps (cvxopt + SuiteSparse, uv, Python ≥ 3.13).
- Usage entry point: `python -m spectra_estimation_dmri.testing.simulation`
- Describes curated inputs (`processed_patient_dict.json`) and metadata files for lesion grading.

##### Main components and their interactions
a. Components:
1. Data Layer
– JSON & CSV files under `data/jsons/` and `data/meta/`
– `configs.yaml` for parameterization
2. Preprocessing Utilities
– `utils/process_img_data.py` loads and structures JSONs
– `utils/generate_analysis_datasets.py` generates intermediate datasets
3. Sampling Models
– Base interface (`models/samplers/base.py`)
– Concrete samplers (Gibbs, slice, MVVB, hierarchical variational)
4. Evaluation & Analysis
– `eval/eval.py` reads sampler outputs, computes combined stats
– plotting helpers (`utils/plotting.py`)
5. Test & Simulation Harness
– `testing/simulation.py` orchestrates full pipeline runs
6. Output Store
– Top‐level `output/` with subfolders `gibbs/`, `eval/`, `testing/` producing CSVs and PDF plots

b. Relationships & interactions:
- The Simulation Harness invokes Preprocessing -> Sampling Models -> Evaluation -> Plotting.
- Configs drive both data preprocessing and sampler behavior.
- Models emit raw spectra estimates (CSV), which flow into Evaluation scripts.
- Utils modules are shared by multiple stages for consistency.

c. Architectural patterns & principles:
- Modular package structure: separation of concerns (data, models, utils, eval, tests)
- Dependency‐inversion in sampler design: all samplers conform to a common base interface
- Resource access via `importlib.resources` (no hard‐coded file paths)
- Config‐driven execution via YAML

d. Key technologies & frameworks:
- Python 3.13+ packaging (`pyproject.toml`, editable install)
- Numerical libraries: NumPy, SciPy, cvxopt (with SuiteSparse)
- Plotting: Matplotlib or similar (in `utils/plotting.py`)
- YAML for configuration

##### Detail
- Submodule boundaries (e.g., `src/spectra_estimation_dmri/models/samplers/`)
- `output/` directory broken into its `gibbs/`, `eval/`, `testing/` subfolders

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Entry Point
    Simulation["Simulation Harness\n(python -m spectra_estimation_dmri.testing.simulation)"]:::processing

    %% Data & Configs
    subgraph "Input Data & Configs"
        direction TB
        DataJSON[/"JSON Inputs"/]:::data
        DataMeta1[/"patient_gleason_grading.csv"/]:::data
        DataMeta2[/"prostate_rois.csv"/]:::data
        Configs["configs.yaml"]:::config
        BuildConfig["pyproject.toml"]:::config
    end

    %% Preprocessing Stage
    subgraph "Preprocessing Stage"
        direction TB
        Preprocess1["process_img_data.py"]:::processing
        Preprocess2["generate_analysis_datasets.py"]:::processing
    end

    %% Inference Engines
    subgraph "Sampling Models"
        direction TB
        BaseSampler(["Base Sampler Interface"]):::sampler
        Gibbs(["Gibbs Sampler"]):::sampler
        Variational(["Variational Sampler"]):::sampler
        Hierarchical(["Hierarchical Variational Sampler"]):::sampler
        Slice(["Slice Sampler 2D"]):::sampler
        Legacy(["Legacy Implementations"]):::sampler
    end

    %% Evaluation & Plotting
    subgraph "Evaluation & Plotting"
        direction TB
        Eval["eval.py"]:::eval
        Plotting["plotting.py"]:::processing
    end

    %% Output Artifacts
    subgraph "Output Store"
        direction TB
        OutGibbs["output/gibbs/"]:::output
        OutEval["output/eval/"]:::output
        OutTesting["output/testing/"]:::output
    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        NumpySciPy["NumPy/SciPy"]:::external
        CVXSuite["cvxopt + SuiteSparse"]:::external
        Matplotlib["Matplotlib"]:::external
    end

    %% Connections
    Simulation --> DataJSON
    Simulation --> DataMeta1
    Simulation --> DataMeta2
    Simulation --> Configs
    Simulation --> BuildConfig
    DataJSON --> Preprocess1
    DataMeta1 --> Preprocess1
    DataMeta2 --> Preprocess1
    Configs --> Preprocess1
    Preprocess1 --> Preprocess2
    Configs --> BaseSampler
    Preprocess2 --> BaseSampler
    BaseSampler --> Gibbs
    BaseSampler --> Variational
    BaseSampler --> Hierarchical
    BaseSampler --> Slice
    BaseSampler --> Legacy
    Gibbs --> OutGibbs
    Variational --> OutGibbs
    Hierarchical --> OutGibbs
    Slice --> OutGibbs
    OutGibbs --> Eval
    Eval --> Plotting
    Plotting --> OutEval
    Simulation --> OutTesting
    NumpySciPy -.-> BaseSampler
    CVXSuite -.-> BaseSampler
    Matplotlib -.-> Plotting

    %% Click Events
    click DataJSON "https://github.com/pawere/spectra-estimation-dmri/tree/main/src/spectra_estimation_dmri/data/jsons/"
    click DataMeta1 "https://github.com/pawere/spectra-estimation-dmri/blob/main/src/spectra_estimation_dmri/data/meta/patient_gleason_grading.csv"
    click DataMeta2 "https://github.com/pawere/spectra-estimation-dmri/blob/main/src/spectra_estimation_dmri/data/meta/prostate_rois.csv"
    click Configs "https://github.com/pawere/spectra-estimation-dmri/blob/main/src/spectra_estimation_dmri/configs.yaml"
    click BuildConfig "https://github.com/pawere/spectra-estimation-dmri/blob/main/pyproject.toml"
    click Preprocess1 "https://github.com/pawere/spectra-estimation-dmri/blob/main/src/spectra_estimation_dmri/utils/process_img_data.py"
    click Preprocess2 "https://github.com/pawere/spectra-estimation-dmri/blob/main/src/spectra_estimation_dmri/utils/generate_analysis_datasets.py"
    click Plotting "https://github.com/pawere/spectra-estimation-dmri/blob/main/src/spectra_estimation_dmri/utils/plotting.py"
    click BaseSampler "https://github.com/pawere/spectra-estimation-dmri/blob/main/src/spectra_estimation_dmri/models/samplers/base.py"
    click Gibbs "https://github.com/pawere/spectra-estimation-dmri/blob/main/src/spectra_estimation_dmri/models/samplers/gibbs_sampler.py"
    click Variational "https://github.com/pawere/spectra-estimation-dmri/blob/main/src/spectra_estimation_dmri/models/samplers/variational_sampler.py"
    click Hierarchical "https://github.com/pawere/spectra-estimation-dmri/blob/main/src/spectra_estimation_dmri/models/samplers/hierarchicalvariational_sampler.py"
    click Slice "https://github.com/pawere/spectra-estimation-dmri/blob/main/src/spectra_estimation_dmri/models/samplers/slice_sampler_2d.py"
    click Legacy "https://github.com/pawere/spectra-estimation-dmri/tree/main/src/spectra_estimation_dmri/models/old/"
    click Eval "https://github.com/pawere/spectra-estimation-dmri/blob/main/src/spectra_estimation_dmri/eval/eval.py"
    click Simulation "https://github.com/pawere/spectra-estimation-dmri/blob/main/src/spectra_estimation_dmri/testing/simulation.py"
    click Tests "https://github.com/pawere/spectra-estimation-dmri/blob/main/src/spectra_estimation_dmri/testing/test.py"
    click OutGibbs "https://github.com/pawere/spectra-estimation-dmri/tree/main/output/gibbs/"
    click OutEval "https://github.com/pawere/spectra-estimation-dmri/tree/main/output/eval/"
    click OutTesting "https://github.com/pawere/spectra-estimation-dmri/tree/main/output/testing/"

    %% Styles
    classDef data fill:#bbdefb,stroke:#0d47a1,color:#0d47a1;
    classDef config fill:#e1bee7,stroke:#4a148c,color:#4a148c;
    classDef processing fill:#c8e6c9,stroke:#1b5e20,color:#1b5e20;
    classDef sampler fill:#ffe0b2,stroke:#e65100,color:#e65100;
    classDef eval fill:#d1c4e9,stroke:#4527a0,color:#4527a0;
    classDef output fill:#eeeeee,stroke:#616161,color:#424242;
    classDef external fill:#f5f5f5,stroke:#9e9e9e,color:#616161;
```
