How pawere/spectra-estimation-dmri works
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