mrax 0.1.0__tar.gz

mrax-0.1.0/CITATION.cff

@@ -0,0 +1,13 @@
+cff-version: 1.2.0
+message: "If you use MRax in your research, please cite it using the metadata in this file."
+title: "MRax: JAX-based tools for quantitative MRI research"
+version: 0.1.0
+date-released: 2026-07-10
+type: software
+license: MIT
+authors:
+  - given-names: Chris
+    family-names: Lippe
+repository-code: "https://github.com/chris-lippe/MRax"
+url: "https://github.com/chris-lippe/MRax"
+abstract: "MRax is a JAX-based Python library for quantitative MRI model fitting, reconstruction, and analysis."

mrax-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Chris Lippe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mrax-0.1.0/MANIFEST.in

@@ -0,0 +1,13 @@
+include LICENSE
+include README.md
+include CITATION.cff
+include MRax_logo.png
+include pyrightconfig.json
+include requirements.txt
+include requirements-dev.txt
+recursive-include mrax *.py *.toml
+recursive-include docs *.rst *.py *.css *.html *.png
+recursive-include notebooks *.ipynb
+recursive-include tests *.py
+prune docs/_build
+global-exclude __pycache__ *.py[cod] .DS_Store

mrax-0.1.0/PKG-INFO

@@ -0,0 +1,177 @@
+Metadata-Version: 2.4
+Name: mrax
+Version: 0.1.0
+Summary: JAX-based tools for quantitative MRI model fitting, reconstruction, and analysis.
+Author: Chris Lippe
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/chris-lippe/MRax
+Project-URL: Documentation, https://chris-lippe.github.io/MRax
+Project-URL: Repository, https://github.com/chris-lippe/MRax
+Project-URL: Issues, https://github.com/chris-lippe/MRax/issues
+Keywords: MRI,JAX,quantitative imaging,reconstruction
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: jax<0.11,>=0.4.35
+Requires-Dist: optax<0.3,>=0.2.4
+Requires-Dist: numpy<3,>=2
+Requires-Dist: scipy<2,>=1.14
+Requires-Dist: ismrmrd<2,>=1.14
+Requires-Dist: nibabel<6,>=5.3
+Requires-Dist: dipy<2,>=1.10
+Requires-Dist: pypulseq<2,>=1.4
+Requires-Dist: SimpleITK<3,>=2.4
+Requires-Dist: PySide6<7,>=6.8
+Requires-Dist: pyqtgraph<0.15,>=0.13
+Requires-Dist: qtpy<3,>=2.4
+Requires-Dist: superqt<1,>=0.7
+Requires-Dist: matplotlib<4,>=3.9
+Provides-Extra: nufft
+Requires-Dist: jax-finufft<2,>=1; extra == "nufft"
+Provides-Extra: denoise-external
+Requires-Dist: bm3d<5,>=4; extra == "denoise-external"
+Requires-Dist: bm4d<5,>=4; extra == "denoise-external"
+Provides-Extra: all
+Requires-Dist: jax-finufft<2,>=1; extra == "all"
+Requires-Dist: bm3d<5,>=4; extra == "all"
+Requires-Dist: bm4d<5,>=4; extra == "all"
+Provides-Extra: docs
+Requires-Dist: sphinx<11,>=8; extra == "docs"
+Requires-Dist: myst-parser<6,>=4; extra == "docs"
+Requires-Dist: pydata-sphinx-theme<1,>=0.16; extra == "docs"
+Requires-Dist: nbsphinx<1,>=0.9; extra == "docs"
+Provides-Extra: notebooks
+Requires-Dist: jupyterlab<5,>=4; extra == "notebooks"
+Requires-Dist: scikit-image<1,>=0.25; extra == "notebooks"
+Provides-Extra: dev
+Requires-Dist: build<2,>=1.2; extra == "dev"
+Requires-Dist: coverage<8,>=7.6; extra == "dev"
+Requires-Dist: isort<7,>=5.13; extra == "dev"
+Requires-Dist: pytest<10,>=8.3; extra == "dev"
+Requires-Dist: pyright<2,>=1.1.400; extra == "dev"
+Requires-Dist: ruff<1,>=0.9; extra == "dev"
+Requires-Dist: twine<7,>=6; extra == "dev"
+Dynamic: license-file
+
+![MRax logo](MRax_logo.png)
+
+# MRax
+
+MRax is a JAX-based Python library for quantitative MRI research. It provides
+data structures for experiments and studies, differentiable signal models,
+optimization utilities, reconstruction helpers, analysis tools, and ISMRMRD-backed
+storage for images, k-space, and fitted maps.
+
+Disclaimer: MRax is intended for research use only. This is an early release, and bugs may occur.
+Coding agents were used to assist in development. Code was manually reviewed and validated on Bruker ParaVision 360 3.6 data.
+
+## Installation
+
+Install the release package from PyPI:
+
+```bash
+pip install mrax
+```
+
+The default install includes fitting, Cartesian reconstruction, import, built-in
+denoising, registration, analysis, storage, and desktop GUI support. Optional
+non-Cartesian and external denoising backends are installed explicitly:
+
+```bash
+pip install "mrax[nufft]"
+pip install "mrax[denoise-external]"
+```
+
+`jax-finufft` does not publish Windows wheels. The upstream `bm3d` and `bm4d`
+packages are licensed for non-commercial use; review their licenses before installing
+the `denoise-external` extra. Development, documentation, and notebook authoring tools
+remain outside the base runtime package.
+
+MRax uses the `mrax.*` import namespace:
+
+```python
+from mrax.core.loss_builder import run_fit
+from mrax.library import make_t2_se_model
+```
+
+Contributor extras are available for notebook and documentation workflows:
+
+```bash
+pip install "mrax[notebooks]"
+pip install "mrax[docs]"
+```
+
+For local development from a clone:
+
+```bash
+python -m pip install --upgrade pip
+python -m pip install -e ".[all,dev,docs,notebooks]"
+pytest
+```
+
+## Dev Container
+
+The repository includes one VS Code compatible dev container. Open the public clone in
+VS Code and choose **Dev Containers: Reopen in Container**. The container installs
+all runtime features plus development, documentation, and notebook tooling, then
+installs MRax in editable mode:
+
+```bash
+python -m pip install -e ".[all,dev,docs,notebooks]"
+```
+
+Inside the container, common checks are:
+
+```bash
+pytest
+sphinx-build -E -b html docs docs/_build/html
+jupyter lab notebooks
+```
+
+## Documentation Website
+
+Documentation is built with Sphinx:
+
+```bash
+python -m pip install -e ".[docs]"
+sphinx-build -E -b html docs docs/_build/html
+```
+
+## PyPI Release
+
+Build and inspect a local distribution with:
+
+```bash
+python -m pip install -e ".[all,dev,docs,notebooks]"
+python -m build
+twine check dist/*
+```
+## Quick Example
+
+```python
+import jax.numpy as jnp
+
+from mrax.core.loss_builder import run_fit
+from mrax.data_struct import DataSet, Quantity
+from mrax.library import build_default_experiment, make_t2_se_model
+
+te = jnp.asarray([8.0, 24.0, 48.0, 96.0])
+experiment = build_default_experiment(
+    "mse",
+    frame_count=te.size,
+    spatial_shape=(2, 2),
+    observables={"TE": Quantity(te, "ms")},
+)
+model = make_t2_se_model(scale=1.0)
+dataset = DataSet(data=jnp.ones((te.size, 2, 2)), name="demo")
+
+fields, losses = run_fit(experiment, model, dataset, num_steps=20, step_size=0.03)
+print(fields["t2"].si_unit, losses[-1])
+```

mrax-0.1.0/README.md

@@ -0,0 +1,115 @@
+![MRax logo](MRax_logo.png)
+
+# MRax
+
+MRax is a JAX-based Python library for quantitative MRI research. It provides
+data structures for experiments and studies, differentiable signal models,
+optimization utilities, reconstruction helpers, analysis tools, and ISMRMRD-backed
+storage for images, k-space, and fitted maps.
+
+Disclaimer: MRax is intended for research use only. This is an early release, and bugs may occur.
+Coding agents were used to assist in development. Code was manually reviewed and validated on Bruker ParaVision 360 3.6 data.
+
+## Installation
+
+Install the release package from PyPI:
+
+```bash
+pip install mrax
+```
+
+The default install includes fitting, Cartesian reconstruction, import, built-in
+denoising, registration, analysis, storage, and desktop GUI support. Optional
+non-Cartesian and external denoising backends are installed explicitly:
+
+```bash
+pip install "mrax[nufft]"
+pip install "mrax[denoise-external]"
+```
+
+`jax-finufft` does not publish Windows wheels. The upstream `bm3d` and `bm4d`
+packages are licensed for non-commercial use; review their licenses before installing
+the `denoise-external` extra. Development, documentation, and notebook authoring tools
+remain outside the base runtime package.
+
+MRax uses the `mrax.*` import namespace:
+
+```python
+from mrax.core.loss_builder import run_fit
+from mrax.library import make_t2_se_model
+```
+
+Contributor extras are available for notebook and documentation workflows:
+
+```bash
+pip install "mrax[notebooks]"
+pip install "mrax[docs]"
+```
+
+For local development from a clone:
+
+```bash
+python -m pip install --upgrade pip
+python -m pip install -e ".[all,dev,docs,notebooks]"
+pytest
+```
+
+## Dev Container
+
+The repository includes one VS Code compatible dev container. Open the public clone in
+VS Code and choose **Dev Containers: Reopen in Container**. The container installs
+all runtime features plus development, documentation, and notebook tooling, then
+installs MRax in editable mode:
+
+```bash
+python -m pip install -e ".[all,dev,docs,notebooks]"
+```
+
+Inside the container, common checks are:
+
+```bash
+pytest
+sphinx-build -E -b html docs docs/_build/html
+jupyter lab notebooks
+```
+
+## Documentation Website
+
+Documentation is built with Sphinx:
+
+```bash
+python -m pip install -e ".[docs]"
+sphinx-build -E -b html docs docs/_build/html
+```
+
+## PyPI Release
+
+Build and inspect a local distribution with:
+
+```bash
+python -m pip install -e ".[all,dev,docs,notebooks]"
+python -m build
+twine check dist/*
+```
+## Quick Example
+
+```python
+import jax.numpy as jnp
+
+from mrax.core.loss_builder import run_fit
+from mrax.data_struct import DataSet, Quantity
+from mrax.library import build_default_experiment, make_t2_se_model
+
+te = jnp.asarray([8.0, 24.0, 48.0, 96.0])
+experiment = build_default_experiment(
+    "mse",
+    frame_count=te.size,
+    spatial_shape=(2, 2),
+    observables={"TE": Quantity(te, "ms")},
+)
+model = make_t2_se_model(scale=1.0)
+dataset = DataSet(data=jnp.ones((te.size, 2, 2)), name="demo")
+
+fields, losses = run_fit(experiment, model, dataset, num_steps=20, step_size=0.03)
+print(fields["t2"].si_unit, losses[-1])
+```

mrax-0.1.0/docs/_static/custom.css

@@ -0,0 +1,227 @@
+:root {
+  --pst-color-primary: #1f77b4;
+  --pst-color-secondary: #ff7f0e;
+}
+
+.mrax-hero {
+  border: 1px solid var(--pst-color-border);
+  border-radius: 12px;
+  padding: 1.75rem;
+  margin: 0 0 2rem;
+  background:
+    linear-gradient(135deg, rgba(31, 119, 180, 0.12), rgba(255, 127, 14, 0.08)),
+    var(--pst-color-background);
+}
+
+.mrax-hero-inner {
+  display: grid;
+  grid-template-columns: 150px minmax(0, 1fr);
+  gap: 1.75rem;
+  align-items: center;
+}
+
+.mrax-hero-mark {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  min-width: 0;
+}
+
+.mrax-hero-mark img {
+  display: block;
+  width: 150px;
+  max-width: 100%;
+  height: auto;
+}
+
+.mrax-hero-title {
+  max-width: 760px;
+  margin: 0;
+  color: var(--pst-color-heading);
+  font-size: 2rem;
+  line-height: 1.1;
+  font-weight: 750;
+}
+
+.mrax-hero-copy {
+  max-width: 780px;
+  margin: 1rem 0 0;
+  font-size: 1.05rem;
+}
+
+.mrax-hero-actions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.75rem;
+  margin-top: 1.4rem;
+}
+
+.mrax-hero a.mrax-button {
+  display: inline-block;
+  border: 1px solid var(--pst-color-border);
+  border-radius: 7px;
+  padding: 0.55rem 0.85rem;
+  font-weight: 700;
+  text-decoration: none;
+  background: var(--pst-color-background);
+}
+
+.mrax-hero a.mrax-button,
+.mrax-hero a.mrax-button:visited {
+  color: var(--pst-color-primary);
+}
+
+.mrax-hero a.mrax-button:hover {
+  text-decoration: none;
+  border-color: var(--pst-color-primary);
+}
+
+.mrax-hero a.mrax-button-primary,
+.mrax-hero a.mrax-button-primary:visited {
+  background: #4bb4c5;
+  border-color: #4bb4c5;
+  color: #06131f !important;
+}
+
+.mrax-hero a.mrax-button-primary:hover {
+  background: #60c0cf;
+  border-color: #60c0cf;
+  color: #06131f !important;
+}
+
+@media (max-width: 720px) {
+  .mrax-hero {
+    padding: 1.25rem;
+  }
+
+  .mrax-hero-inner {
+    grid-template-columns: 1fr;
+    gap: 1rem;
+  }
+
+  .mrax-hero-mark {
+    justify-content: flex-start;
+  }
+
+  .mrax-hero-mark img {
+    width: 112px;
+  }
+
+  .mrax-hero-title {
+    font-size: 1.55rem;
+  }
+}
+
+/* Constrain line lengths for readability */
+.bd-article {
+  max-width: 980px;
+}
+
+/* Light card styling for lists */
+.toctree-wrapper ul {
+  list-style: none;
+  padding-left: 0;
+}
+
+.toctree-wrapper ul li {
+  background: #f8f9fb;
+  border: 1px solid #e1e5ea;
+  border-radius: 8px;
+  padding: 10px 12px;
+  margin-bottom: 8px;
+}
+
+.toctree-wrapper ul li a {
+  font-weight: 600;
+  color: var(--pst-color-primary);
+}
+
+/* Soften code blocks */
+div.highlight pre {
+  border-radius: 6px;
+}
+
+.notebook-embed {
+  margin: 16px 0;
+  border: 1px solid #e1e5ea;
+  border-radius: 8px;
+  overflow: hidden;
+  box-shadow: 0 4px 10px rgba(0, 0, 0, 0.04);
+}
+
+.notebook-embed iframe {
+  display: block;
+  width: 100%;
+  background: #fff;
+}
+
+.bd-article > section[id] + h1[id] {
+  display: none;
+}
+
+/* Header logo: larger image, hide text label */
+.navbar-brand .logo__image {
+  height: 52px;
+  max-height: 52px;
+  width: auto;
+}
+
+.navbar-brand .logo__title {
+  display: none;
+}
+
+@media (min-width: 960px) {
+  .bd-header__inner {
+    align-items: center;
+    flex-wrap: nowrap;
+  }
+
+  .navbar-header-items__start {
+    flex: 0 0 auto;
+    max-width: none;
+    width: auto;
+  }
+
+  .navbar-header-items {
+    align-items: center;
+    display: flex;
+    flex: 1 1 auto;
+    flex-wrap: nowrap;
+    max-width: none;
+    min-width: 0;
+    width: auto;
+  }
+
+  .navbar-header-items__center {
+    flex: 1 1 auto;
+    min-width: 0;
+  }
+
+  .bd-navbar-elements {
+    flex-wrap: nowrap;
+    white-space: nowrap;
+  }
+
+  .navbar-header-items__end {
+    flex: 0 0 auto;
+  }
+}
+
+/* Dark theme tweaks */
+html[data-theme="dark"] .toctree-wrapper ul li {
+  background: #1f2733;
+  border-color: #2e3a4a;
+}
+
+html[data-theme="dark"] .toctree-wrapper ul li a {
+  color: var(--pst-color-primary);
+}
+
+html[data-theme="dark"] .notebook-embed {
+  border-color: #2e3a4a;
+  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.35);
+}
+
+html[data-theme="dark"] .notebook-embed iframe {
+  background: #0f141c;
+}

mrax-0.1.0/docs/_templates/license-contact.html

@@ -0,0 +1,4 @@
+<p class="license-contact">
+  License: {{ license_name }}.
+  Contact: <a href="mailto:{{ contact_email }}">{{ contact_email }}</a>.
+</p>

mrax-0.1.0/docs/analysis.rst

@@ -0,0 +1,93 @@
+Post-fit Analysis
+=================
+
+The analysis toolbox provides reusable utilities for extracting ROI statistics, computing
+ROI timecourses, and summarizing/comparing groups from batch outputs. The API is designed
+to stay modular: ROI definitions are independent of how you load data, and group statistics
+work on long-form tables so you can extend or replace individual steps.
+
+ROI statistics
+--------------
+
+Compute per-map ROI summaries (mean, variance, etc.) from fitted parameter maps:
+
+.. code-block:: python
+
+   import numpy as np
+
+   from mrax.analysis import ROI, collect_roi_stats
+   from mrax.data_struct import load_study_results
+
+   data = load_study_results("batch_output/subj_a/study_manifest.json")
+   maps = data["experiments"]["t1_ir"]["fitted_maps"]
+
+   mask = np.zeros((16, 16), dtype=bool)
+   mask[4:12, 4:12] = True
+   roi = ROI("center", mask)
+
+   rows = collect_roi_stats(maps, [roi], stats=("mean", "variance"))
+   for row in rows:
+       print(row["map"], row["roi"], row["stat"], row["value"], row.get("unit", ""))
+
+Timecourse extraction
+---------------------
+
+Extract an ROI timecourse by reducing across spatial dimensions. If the data array is
+``(frames, x, y)`` or ``(non_spatial..., x, y)``, the ROI mask is aligned to the spatial
+axes automatically:
+
+.. code-block:: python
+
+   from mrax.analysis import extract_timecourse
+
+   mr_image = data["experiments"]["t1_ir"]["mr_image"]
+   timecourse = extract_timecourse(mr_image, roi, stat="mean")
+   print(timecourse.shape)
+
+Group summaries and comparisons
+-------------------------------
+
+Group analysis utilities build on the batch output layout. Provide group members as
+manifest paths or study folder names inside ``output_root``:
+
+.. code-block:: python
+
+   from mrax.analysis import analyze_groups
+
+   groups = {
+       "control": ["subj_a", "subj_b"],
+       "treated": ["subj_c", "subj_d"],
+   }
+
+   results = analyze_groups(
+       groups,
+       output_root="batch_output",
+       experiment_name="t1_ir",
+       rois=[roi],
+       map_names=["t1"],
+       stats=("mean",),
+   )
+
+   subject_rows = results["subject_stats"]
+   group_summary = results["group_summary"]
+   comparisons = results["comparisons"]
+
+Plotting summaries
+------------------
+
+The analysis functions return plain Python rows and arrays. Use your plotting library
+of choice to visualize the outputs. For example, the group summary table can be
+converted to a bar plot with ``matplotlib``:
+
+.. code-block:: python
+
+   import matplotlib.pyplot as plt
+
+   rows = [
+       row for row in results["group_summary"]
+       if row["map"] == "t1" and row["roi"] == "center" and row["stat"] == "mean"
+   ]
+   plt.bar([row["group"] for row in rows], [row["mean"] for row in rows])
+   plt.ylabel("T1 (ms)")
+
+See the analysis notebook for an end-to-end demo using synthetic data and batch outputs.