qmrpy 0.1.2__tar.gz

qmrpy-0.1.2/.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: ci
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Sync dependencies
+        run: uv sync --locked --extra viz --extra dev
+
+      - name: Run tests
+        run: uv run --locked -m pytest

qmrpy-0.1.2/.gitignore

@@ -0,0 +1,43 @@
+# outputs / data
+/output/
+/data/
+/configs/local/
+docs/
+
+# upstream reference (MATLAB)
+qMRLab/
+
+# upstream/vendor worktrees (do not commit; vendored snapshot lives under src/)
+/epgpy/
+/DECAES.jl/
+
+# environments / caches
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.cache/
+.uv_cache/
+
+# packaging outputs
+dist/
+build/
+*.egg-info/
+
+# OS/editor
+.DS_Store
+Thumbs.db
+.vscode/
+.idea/
+
+# logs
+*.log
+
+# secrets (原則使わないが、万一置くなら絶対に管理しない)
+.env
+.env.*
+
+# local-only agent instructions
+AGENTS.md

qmrpy-0.1.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Kohei Sugimoto
+
+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.

qmrpy-0.1.2/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: qmrpy
+Version: 0.1.2
+Summary: Python implementation (translation) of qMRLab models for quantitative MRI.
+Project-URL: Repository, https://github.com/SugimotoKohei/qmrpy
+Project-URL: Issues, https://github.com/SugimotoKohei/qmrpy/issues
+Author: Kohei Sugimoto
+License: MIT
+License-File: LICENSE
+Keywords: MRI,diffusion,qMRI,qMRLab,relaxometry
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Requires-Python: >=3.11
+Requires-Dist: numpy>=1.26
+Requires-Dist: scipy>=1.11
+Provides-Extra: dev
+Requires-Dist: nbclient>=0.10.2; extra == 'dev'
+Requires-Dist: nbformat>=5.10.4; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: viz
+Requires-Dist: pandas>=2.3.3; extra == 'viz'
+Requires-Dist: plotnine>=0.13; extra == 'viz'
+Description-Content-Type: text/markdown
+
+# qmrpy
+
+[![PyPI](https://img.shields.io/pypi/v/qmrpy.svg)](https://pypi.org/project/qmrpy/)
+
+qMRLab（MATLAB実装）の概念・モデルを **Python** へ段階的に移植するためのリポジトリです。
+
+本プロジェクトは upstream の qMRLab（MIT License）に着想を得ており、モデル定義・検証方針は qMRLab を参照しつつ Python で再構成します。
+
+
+## 開発（ローカル）
+
+現時点では最小のパッケージ雛形のみです（今後、モデル実装を段階的に追加します）。
+
+- `uv sync --extra viz`（可視化を含める）
+- `uv sync --extra viz --extra dev`（pytest/ruff 等を含める）
+- `uv run --locked -m pytest`
+
+## パッケージ利用
+
+`uv` を使う場合の導入例：
+
+```bash
+uv add qmrpy
+```
+
+### 最小利用例
+
+```python
+import numpy as np
+from qmrpy.models.t1.vfa_t1 import VfaT1
+
+model = VfaT1(
+    tr_s=0.015,
+    flip_angles_deg=np.array([2, 5, 10, 15]),
+)
+
+signal = model.forward(m0=1.0, t1_s=1.2)
+fit = model.fit_linear(signal)
+print(fit["t1_s"], fit["m0"])
+```
+
+## ライセンス
+
+- `qmrpy` 本体：MIT（`LICENSE`）
+- 参照元 `qMRLab/`：MIT（upstream、ローカル参照用）
+- 翻訳・参考実装・vendor の詳細は `THIRD_PARTY_NOTICES.md` を参照
+
+## 第三者由来コードの扱い
+
+- `qMRLab`（MATLAB）および `DECAES.jl` の概念・アルゴリズムを翻訳/再構成しています。
+- `epgpy` は `src/epgpy/` に vendor しています。
+- ライセンス表記・出自は `THIRD_PARTY_NOTICES.md` に集約しています。

qmrpy-0.1.2/README.md

@@ -0,0 +1,52 @@
+# qmrpy
+
+[![PyPI](https://img.shields.io/pypi/v/qmrpy.svg)](https://pypi.org/project/qmrpy/)
+
+qMRLab（MATLAB実装）の概念・モデルを **Python** へ段階的に移植するためのリポジトリです。
+
+本プロジェクトは upstream の qMRLab（MIT License）に着想を得ており、モデル定義・検証方針は qMRLab を参照しつつ Python で再構成します。
+
+
+## 開発（ローカル）
+
+現時点では最小のパッケージ雛形のみです（今後、モデル実装を段階的に追加します）。
+
+- `uv sync --extra viz`（可視化を含める）
+- `uv sync --extra viz --extra dev`（pytest/ruff 等を含める）
+- `uv run --locked -m pytest`
+
+## パッケージ利用
+
+`uv` を使う場合の導入例：
+
+```bash
+uv add qmrpy
+```
+
+### 最小利用例
+
+```python
+import numpy as np
+from qmrpy.models.t1.vfa_t1 import VfaT1
+
+model = VfaT1(
+    tr_s=0.015,
+    flip_angles_deg=np.array([2, 5, 10, 15]),
+)
+
+signal = model.forward(m0=1.0, t1_s=1.2)
+fit = model.fit_linear(signal)
+print(fit["t1_s"], fit["m0"])
+```
+
+## ライセンス
+
+- `qmrpy` 本体：MIT（`LICENSE`）
+- 参照元 `qMRLab/`：MIT（upstream、ローカル参照用）
+- 翻訳・参考実装・vendor の詳細は `THIRD_PARTY_NOTICES.md` を参照
+
+## 第三者由来コードの扱い
+
+- `qMRLab`（MATLAB）および `DECAES.jl` の概念・アルゴリズムを翻訳/再構成しています。
+- `epgpy` は `src/epgpy/` に vendor しています。
+- ライセンス表記・出自は `THIRD_PARTY_NOTICES.md` に集約しています。

qmrpy-0.1.2/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,107 @@
+# Third-Party Notices
+
+このリポジトリには、第三者が著作権を有するソフトウェアの **同梱（vendor）** および
+**翻訳・参考実装** が含まれます。配布物（wheel / sdist）には、各ライセンス条項に従い
+必要な表記を含めます。
+
+## epgpy
+
+- Upstream: `epgpy`（Extended-Phase Graph (EPG) algorithm and extensions）
+- Copyright (c) 2023, py-baudin
+- License: BSD 3-Clause License
+- Vendored path: `src/epgpy/`
+
+```
+BSD 3-Clause License
+
+Copyright (c) 2023, py-baudin
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+```
+
+## qMRLab
+
+- Upstream: `qMRLab`（MATLAB 実装）
+- Copyright (c) 2017 NeuroPoly
+- License: MIT License
+- Reference path: `qMRLab/`（ローカル参照用・Git 管理外）
+- Notes: 本リポジトリは qMRLab の概念・モデル定義を **翻訳/再構成** しています。
+  qMRLab 本体や `External/` 配下の第三者コードは同梱しておらず、取り込みが発生した場合は
+  その都度ライセンス表記を追加します。
+
+```
+MIT License
+
+Copyright (c) 2017 NeuroPoly
+
+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.
+```
+
+## DECAES.jl
+
+- Upstream: `DECAES.jl`
+- Copyright (c) 2019 Jonathan Doucette
+- License: MIT License
+- Reference path: `DECAES.jl/`（ローカル参照用）
+- Notes: 一部アルゴリズム/実装の **翻訳・参考** を含む
+
+```
+Copyright (c) 2019 Jonathan Doucette
+
+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.
+```

qmrpy-0.1.2/configs/base/.gitkeep

@@ -0,0 +1 @@
+

qmrpy-0.1.2/configs/exp/.gitkeep

@@ -0,0 +1 @@
+

qmrpy-0.1.2/configs/exp/b1_dam_baseline.toml

@@ -0,0 +1,13 @@
+[run]
+tag = "b1-dam-baseline"
+seed = 0
+model = "b1_dam"
+
+[b1_dam]
+alpha_deg = 60.0
+n_samples = 200
+m0 = 1000.0
+b1_range = [0.6, 1.4]
+noise_model = "gaussian"
+noise_sigma = 10.0
+

qmrpy-0.1.2/configs/exp/epg_backend_sweep.toml

@@ -0,0 +1,21 @@
+[run]
+tag = "epg-backend-sweep"
+seed = 0
+
+[epg_backend_sweep]
+# EPG decay curve comparison: epgpy vs decaes backends
+etl = 16
+te_ms = 10.0
+
+# Grid (small by default; intended for quick diagnostics)
+alpha_deg = [90.0, 120.0, 150.0, 180.0]
+t1_s = [0.6, 1.0, 2.0]
+t2_ms = [20.0, 30.0, 50.0, 80.0, 120.0, 200.0]
+beta_deg = 180.0
+
+# Normalization for error metrics: normalize by first echo
+normalize = "first_echo"
+
+# Failure analysis: overlay top-k worst cases
+topk = 3
+

qmrpy-0.1.2/configs/exp/epg_backend_sweep_beta150.toml

@@ -0,0 +1,18 @@
+[run]
+tag = "epg-backend-sweep-beta150"
+seed = 0
+
+[epg_backend_sweep]
+etl = 16
+te_ms = 10.0
+
+alpha_deg = [90.0, 120.0, 150.0, 180.0]
+t1_s = [0.6, 1.0, 2.0]
+t2_ms = [20.0, 30.0, 50.0, 80.0, 120.0, 200.0]
+
+# Non-ideal refocusing
+beta_deg = 150.0
+
+normalize = "first_echo"
+topk = 3
+

qmrpy-0.1.2/configs/exp/epg_backend_sweep_wide.toml

@@ -0,0 +1,19 @@
+[run]
+tag = "epg-backend-sweep-wide"
+seed = 0
+
+[epg_backend_sweep]
+# Broader coverage (still intended to be a quick diagnostic):
+# - multiple ETL / TE / beta conditions
+# - moderate grid size to keep runtime reasonable
+etl = [8, 16, 32]
+te_ms = [5.0, 10.0, 20.0]
+beta_deg = [120.0, 150.0, 180.0]
+
+alpha_deg = [90.0, 120.0, 150.0, 180.0]
+t1_s = [0.6, 1.0, 2.0]
+t2_ms = [10.0, 20.0, 30.0, 50.0, 80.0, 120.0, 200.0]
+
+normalize = "first_echo"
+topk = 5
+

qmrpy-0.1.2/configs/exp/inversion_recovery_baseline.toml

@@ -0,0 +1,15 @@
+[run]
+tag = "inversion-recovery-baseline"
+seed = 0
+model = "inversion_recovery"
+
+[inversion_recovery]
+ti_ms = [350, 500, 650, 800, 950, 1100, 1250, 1400, 1700]
+n_samples = 200
+t1_range_ms = [200.0, 2000.0]
+ra = 500.0
+rb = -1000.0
+method = "magnitude"
+noise_model = "rician"
+noise_sigma = 5.0
+

qmrpy-0.1.2/configs/exp/mono_t2_baseline.toml

@@ -0,0 +1,15 @@
+[run]
+tag = "mono-t2-baseline"
+seed = 0
+model = "mono_t2"
+
+[mono_t2]
+te_ms = [10, 20, 40, 80, 160]
+n_samples = 200
+m0 = 1000.0
+t2_range_ms = [20.0, 200.0]
+noise_model = "gaussian"
+noise_sigma = 5.0
+fit_type = "exponential"
+drop_first_echo = false
+offset_term = false

qmrpy-0.1.2/configs/exp/mwf_baseline.toml

@@ -0,0 +1,26 @@
+[run]
+tag = "mwf-baseline"
+seed = 0
+model = "mwf"
+
+[mwf]
+# Standard CPMG-like protocol: 32 echos, 10ms spacing
+te_ms = [10, 20, 30, 40, 50, 60, 70, 80, 90, 100, 110, 120, 130, 140, 150, 160, 170, 180, 190, 200, 210, 220, 230, 240, 250, 260, 270, 280, 290, 300, 310, 320]
+n_samples = 100
+m0 = 1000.0
+mwf_ref = 0.15
+t2_myelin_ms = 20.0
+t2_ie_ms = 80.0
+# qMRLab-like cutoffs
+# - lower_cutoff_mw_ms: default None -> 1.5 * FirstEcho
+cutoff_ms = 40.0
+upper_cutoff_iew_ms = 200.0
+
+# NNLS T2 basis (log-spaced)
+t2_basis_range_ms = [10.0, 2000.0]
+t2_basis_n = 40
+use_weighted_geometric_mean = false
+
+noise_model = "gaussian"
+noise_sigma = 2.0  # SNR ~ 500
+regularization_alpha = 0.001

qmrpy-0.1.2/configs/exp/test_mppca.toml

@@ -0,0 +1,11 @@
+[run]
+name = "mppca_demo"
+seed = 42
+
+[mppca]
+sx = 30
+sy = 30
+sz = 10
+n_vol = 30
+snr = 20.0
+kernel = [5, 5, 5]

qmrpy-0.1.2/configs/exp/vfa_t1_b1range_gaussian.toml

@@ -0,0 +1,18 @@
+[run]
+tag = "vfa-t1-b1range-gaussian"
+seed = 0
+model = "vfa_t1"
+
+[vfa_t1]
+flip_angle_deg = [3, 8, 15, 25]
+tr_s = 0.015
+n_samples = 200
+m0 = 2000.0
+t1_range_s = [0.2, 2.0]
+b1_range = [0.8, 1.2]
+noise_model = "gaussian"
+noise_sigma = 5.0
+robust_linear = false
+huber_k = 1.345
+outlier_reject = false
+

qmrpy-0.1.2/configs/exp/vfa_t1_b1range_rician_outlier.toml

@@ -0,0 +1,18 @@
+[run]
+tag = "vfa-t1-b1range-rician-outlier"
+seed = 0
+model = "vfa_t1"
+
+[vfa_t1]
+flip_angle_deg = [3, 8, 15, 25]
+tr_s = 0.015
+n_samples = 200
+m0 = 2000.0
+t1_range_s = [0.2, 2.0]
+b1_range = [0.8, 1.2]
+noise_model = "rician"
+noise_sigma = 5.0
+robust_linear = true
+huber_k = 1.345
+outlier_reject = true
+

qmrpy-0.1.2/configs/exp/vfa_t1_baseline.toml

@@ -0,0 +1,17 @@
+[run]
+tag = "vfa-t1-baseline"
+seed = 0
+model = "vfa_t1"
+
+[vfa_t1]
+flip_angle_deg = [3, 8, 15, 25]
+tr_s = 0.015
+n_samples = 200
+m0 = 2000.0
+t1_range_s = [0.2, 2.0]
+b1 = 1.0
+noise_model = "gaussian"
+noise_sigma = 5.0
+robust_linear = false
+huber_k = 1.345
+outlier_reject = false

qmrpy-0.1.2/configs/exp/vfa_t1_rician.toml

@@ -0,0 +1,18 @@
+[run]
+tag = "vfa-t1-rician"
+seed = 0
+model = "vfa_t1"
+
+[vfa_t1]
+flip_angle_deg = [3, 8, 15, 25]
+tr_s = 0.015
+n_samples = 200
+m0 = 2000.0
+t1_range_s = [0.2, 2.0]
+b1 = 1.0
+noise_model = "rician"
+noise_sigma = 5.0
+robust_linear = false
+huber_k = 1.345
+outlier_reject = false
+

qmrpy-0.1.2/notebooks/.gitkeep

@@ -0,0 +1 @@
+