Skip to content

USAGE.md

Latest commit

 

History

History
207 lines (158 loc) · 5.21 KB

USAGE.md

File metadata and controls

207 lines (158 loc) · 5.21 KB
Raw

BASS-Python Usage Notes

This file keeps detailed setup and run notes out of the first screen of the README.

Environment

Recommended CPU environment:

conda env create -f environment.yml
conda activate bass-dev

Optional CUDA environment on Linux or Windows with NVIDIA GPUs:

conda env create -f environment.cuda.yml
conda activate bass-dev

Sanity checks:

python -m pytest -q
python run_bass.py --help
python visualize_bass.py --help

If pyfftw fails to import, reinstall it inside the active environment:

pip install pyfftw

Missing SSIM support only disables that metric. The k-space residual path still runs.

Data Layout

No MRI data is committed to this repository. The command-line tools expect:

data/<Dataset>/
  kdata/kdata<slice>.mat
  coilmap/coilmap<slice>.mat
  recon_*/images<slice>.mat
  sampling_pattern/*.mat

Ground truth is optional. If supplied, run_bass.py reads images<slice>.mat by default and expects the key specified by --ground-truth-key, usually images.

Do not commit private, clinical, restricted, or patient-derived MRI data.

Common Commands

Single-slice run, assuming local data exists:

python run_bass.py \
  --dataname T1rho \
  --slice 31 \
  --accel 4 \
  --iterations 10 \
  --points 200 \
  --cg-iters 10 \
  --center 0.25 \
  --seed 0 \
  --save-mask --save-recon --save-history \
  --output-dir outputs/t1rho_s31

Multi-slice train/validation run:

python run_bass.py \
  --dataname T1rho \
  --train-slices 31-35 \
  --val-slices 101-105 \
  --accel 4 \
  --iterations 10 \
  --points 200 \
  --cg-iters 10 \
  --center 0.25 \
  --seed 0 \
  --add-prob 0.9 \
  --remove-prob 0.15 \
  --ground-truth data/T1rho/recon_DIC \
  --ground-truth-slices 31-35,101-105 \
  --ground-truth-key images \
  --save-mask --save-recon --save-history --save-gt \
  --output-dir outputs/t1rho_multislice

Optional PyTorch backend:

python run_bass.py \
  --dataname T1rho \
  --slice 31 \
  --accel 4 \
  --iterations 5 \
  --points 200 \
  --use-torch \
  --device cuda \
  --save-history

Use --device cpu when testing the PyTorch path without a GPU.

Important CLI Options

Flag Meaning
--data-root Root directory containing dataset folders. Default: data.
--dataname Dataset folder under --data-root.
--slice Single slice index.
--train-slices Range/list for training slices, such as 31-35.
--val-slices Range/list for validation slices.
--accel Acceleration factor.
--iterations Number of BASS iterations.
--points Max samples to add/remove per iteration.
--center Fraction of each spatial dimension kept fully sampled at the center.
--no-lock-center Allow the center region to be modified.
--mask-mode Mask layout mode when supported by the CLI.
--use-torch Use the optional PyTorch backend.
--ground-truth File or directory containing reference images.
--save-mask Save final sampling mask.
--save-recon Save final reconstruction.
--save-history Save per-iteration history as .npz.
--save-gt Save loaded ground-truth volume.
--output-dir Artifact output directory.

Artifact Names

The base mask filename is:

bass_mask_<recon-method>_<dataname>_<slice-tag>_<accel>x_<iterations>i_<seed>s.npy

Derived filenames use the same suffix:

bass_recon_...
bass_history_...npz
bass_ground_truth_...

For multi-slice runs, <slice-tag> looks like s31-35_n5.

Visualization

Summary visualization:

python visualize_bass.py \
  --history outputs/t1rho_multislice/bass_history_sense-cg_t1rho_s31-35_n5_4x_10i_0s.npz \
  --final-mask outputs/t1rho_multislice/bass_mask_sense-cg_t1rho_s31-35_n5_4x_10i_0s.npy \
  --reconstruction outputs/t1rho_multislice/bass_recon_sense-cg_t1rho_s31-35_n5_4x_10i_0s.npy \
  --ground-truth-vol outputs/t1rho_multislice/bass_ground_truth_sense-cg_t1rho_s31-35_n5_4x_10i_0s.npy \
  --mode summary \
  --compare-vd \
  --dataname T1rho \
  --slice 31 \
  --center 0.25 \
  --vd-samples 2048 \
  --vd-seed 0 \
  --cg-iters 10

--compare-vd recomputes a variable-density reconstruction with the requested sample budget and CG iterations.

Choosing --vd-samples

Use the same 2D sampling budget as the BASS run:

vd_samples = floor(H * W / accel)

Examples:

128 x 64 at 4x -> 2048
320 x 320 at 4x -> 25600

MATLAB-Parity Scripts

The scripts under matlab_parity/ are script-style reference ports. They are useful for comparing control flow and helper behavior, but they require local data.

cd matlab_parity
python DDLSP_optimize_SP_BASS_SENSE.py
python DDLSP_optimize_SP_BASS_SENSE_1D.py

Edit the configuration block at the top of each script before running. With default settings, outputs are written under data/<dataname>/sampling_pattern/ when enabled by the script configuration.

Fresh-Clone Verification

Use tests for verification when no MRI data is available:

python -m pytest tests/test_bass_algorithm.py tests/test_solvers.py tests/test_operators.py -q

The tests construct synthetic complex k-space and coil-map fixtures and do not require private datasets.