Initial Bayesian-DSC project

Author: Devguru-codes

.github/workflows/tests.yml

@@ -0,0 +1,25 @@
+name: Tests
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  unit-tests:
+    runs-on: windows-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+
+      - name: Run unit tests
+        run: python -m unittest discover -s tests

.gitignore

@@ -0,0 +1,28 @@
+.venv/
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+.pytest_cache/
+.coverage
+htmlcov/
+
+# CmdStan / CmdStanPy
+.cmdstan/
+cmdstan/
+src/stan_models/*.exe
+src/stan_models/*.hpp
+src/stan_models/*.o
+src/stan_models/*.d
+cmdstan-*.csv
+cmdstan-*.txt
+
+# Generated outputs
+fit_result.png
+
+# OS / editor noise
+.DS_Store
+Thumbs.db
+.vscode/
+.idea/

README.md

@@ -0,0 +1,108 @@
+# Bayesian-DSC
+
+`Bayesian-DSC` is a small portfolio project that demonstrates Bayesian fitting of Dynamic Susceptibility Contrast (DSC) MRI concentration-time curves with `CmdStanPy`. The core design goal is to compile the Stan model once when the fitter is instantiated, then reuse that compiled executable for repeated curve fitting.
+
+## Features
+
+- Uses a pre-compiled Stan gamma-variate model through `CmdStanPy`
+- Exposes a backend-swappable `BaseDSCFitter` abstraction for future PyMC or NumPyro implementations
+- Fits noisy DSC concentration-time curves with Bayesian inference
+- Returns posterior means and 95% HDI bounds for `A`, `alpha`, `beta`, `t0`, `sigma`, `CBV`, and `MTT`
+- Includes a reproducible synthetic-data simulation and plot export
+
+## Installation
+
+1. Create a virtual environment in the project root:
+
+```bash
+python -m venv .venv
+```
+
+2. Activate it.
+
+On Windows PowerShell:
+
+```powershell
+.\.venv\Scripts\Activate.ps1
+```
+
+3. Install the Python dependencies:
+
+```bash
+pip install -r requirements.txt
+```
+
+4. Install the underlying CmdStan toolchain.
+
+On Windows, the simplest option is to let `cmdstanpy` install the required compiler toolchain if needed:
+
+```bash
+python -m cmdstanpy.install_cmdstan -c
+```
+
+This downloads and builds CmdStan under the user CmdStan directory, typically `C:\Users\<username>\.cmdstan`.
+
+## Usage
+
+Run the synthetic demonstration script from the project root:
+
+```bash
+python simulate_dsc.py
+```
+
+On your Windows setup, the easiest option is the included helper script, which configures the RTools toolchain before launching the demo:
+
+```powershell
+.\run_simulation.ps1
+```
+
+The script will:
+
+- generate a synthetic DSC concentration-time curve
+- add Gaussian noise
+- compile and sample the Stan model
+- print true parameters, posterior means, and 95% HDI intervals
+- save `fit_result.png` in the project root
+
+If you prefer to avoid activating the environment explicitly on Windows, you can run:
+
+```powershell
+.\.venv\Scripts\python simulate_dsc.py
+```
+
+If Stan compilation on Windows picks up the wrong `C:\MinGW` toolchain, prefer the helper script above because it prepends the correct RTools paths automatically.
+
+## Tests
+
+Run the lightweight unit tests from the project root:
+
+```bash
+.\.venv\Scripts\python -m unittest discover -s tests
+```
+
+## Project Structure
+
+```text
+.
+|-- .gitignore
+|-- README.md
+|-- requirements.txt
+|-- run_simulation.ps1
+|-- simulate_dsc.py
+|-- tests
+|   `-- test_bayesian_fitter.py
+`-- src
+    |-- __init__.py
+    |-- bayesian_fitter.py
+    `-- stan_models
+        `-- gamma_variate.stan
+```
+
+## Notes
+
+- The first `DSCBayesianFitter` instantiation may take longer because Stan compilation happens at that point.
+- Subsequent calls to `.fit_curve(...)` on the same fitter instance reuse the already compiled executable.
+- If the Stan source is unchanged and the executable already exists, CmdStanPy can also reuse that executable on later runs.
+- If compilation or sampling fails, the wrapper safely returns `NaN` outputs instead of crashing.
+- The repository `.gitignore` excludes the local virtual environment, Python caches, CmdStan directories, and the generated `fit_result.png`.
+- On Windows systems that already have an older `C:\MinGW` toolchain installed, make sure the RTools paths provided by `cmdstanpy.install_cmdstan -c` take precedence when compiling Stan models.

requirements.txt

@@ -0,0 +1,4 @@
+numpy
+cmdstanpy
+matplotlib
+arviz

run_simulation.ps1

@@ -0,0 +1,23 @@
+param(
+    [Parameter(ValueFromRemainingArguments = $true)]
+    [string[]]$ScriptArgs
+)
+
+$ErrorActionPreference = "Stop"
+
+$projectRoot = Split-Path -Parent $MyInvocation.MyCommand.Path
+$pythonExe = Join-Path $projectRoot ".venv\Scripts\python.exe"
+$rtoolsRoot = Join-Path $env:USERPROFILE ".cmdstan\RTools40"
+
+if (-not (Test-Path $pythonExe)) {
+    throw "Virtual environment Python not found at $pythonExe"
+}
+
+if (-not (Test-Path $rtoolsRoot)) {
+    throw "RTools40 was not found at $rtoolsRoot"
+}
+
+$env:Path = (Join-Path $rtoolsRoot "usr\bin") + ";" + (Join-Path $rtoolsRoot "mingw64\bin") + ";" + $env:Path
+$env:MAKE = "mingw32-make"
+
+& $pythonExe (Join-Path $projectRoot "simulate_dsc.py") @ScriptArgs

simulate_dsc.py

@@ -0,0 +1,81 @@
+"""Run a synthetic DSC-MRI Bayesian fitting demonstration."""
+
+from __future__ import annotations
+
+import math
+from pathlib import Path
+
+import matplotlib.pyplot as plt
+import numpy as np
+
+from src.bayesian_fitter import DSCBayesianFitter, gamma_variate_curve
+
+
+def main() -> None:
+    """Generate synthetic DSC data, fit it, and save a comparison plot."""
+    rng = np.random.default_rng(seed=42)
+    t = np.linspace(0.0, 50.0, 50)
+
+    true_params = {
+        "A": 5.0,
+        "alpha": 3.0,
+        "beta": 1.5,
+        "t0": 10.0,
+    }
+
+    clean_curve = gamma_variate_curve(
+        t,
+        amplitude=true_params["A"],
+        alpha=true_params["alpha"],
+        beta=true_params["beta"],
+        t0=true_params["t0"],
+    )
+    noise_sigma = 0.35
+    c_obs = clean_curve + rng.normal(loc=0.0, scale=noise_sigma, size=t.shape)
+
+    stan_path = Path("src") / "stan_models" / "gamma_variate.stan"
+    fitter = DSCBayesianFitter(stan_file=stan_path)
+    fit_result = fitter.fit_curve(t, c_obs, num_samples=1000)
+
+    fitted_curve = gamma_variate_curve(
+        t,
+        amplitude=fit_result["A"],
+        alpha=fit_result["alpha"],
+        beta=fit_result["beta"],
+        t0=fit_result["t0"],
+    )
+    true_cbv = float(
+        true_params["A"]
+        * math.gamma(true_params["alpha"] + 1.0)
+        * (true_params["beta"] ** (true_params["alpha"] + 1.0))
+    )
+    true_mtt = float(true_params["alpha"] * true_params["beta"])
+
+    print("True parameters:")
+    for key, value in true_params.items():
+        print(f"  {key}: {value:.4f}")
+    print(f"  cbv: {true_cbv:.4f}")
+    print(f"  mtt: {true_mtt:.4f}")
+
+    print("\nPosterior means with 95% HDI:")
+    for key in ("A", "alpha", "beta", "t0", "sigma", "cbv", "mtt"):
+        print(
+            f"  {key}: {fit_result[key]:.4f} "
+            f"[{fit_result[f'{key}_hdi_lower']:.4f}, {fit_result[f'{key}_hdi_upper']:.4f}]"
+        )
+
+    plt.figure(figsize=(10, 6))
+    plt.scatter(t, c_obs, color="tab:blue", label="Noisy observations", alpha=0.8)
+    plt.plot(t, clean_curve, color="tab:green", linewidth=2, label="Ground truth")
+    plt.plot(t, fitted_curve, color="tab:red", linewidth=2, label="Posterior mean fit")
+    plt.xlabel("Time (s)")
+    plt.ylabel("Concentration")
+    plt.title("Bayesian DSC-MRI Gamma-Variate Fit")
+    plt.legend()
+    plt.tight_layout()
+    plt.savefig("fit_result.png", dpi=200)
+    plt.close()
+
+
+if __name__ == "__main__":
+    main()

src/__init__.py

@@ -0,0 +1,5 @@
+"""Bayesian-DSC package."""
+
+from .bayesian_fitter import BaseDSCFitter, DSCBayesianFitter, gamma_variate_curve
+
+__all__ = ["BaseDSCFitter", "DSCBayesianFitter", "gamma_variate_curve"]