asl-mri-utils 0.5.0__tar.gz

asl_mri_utils-0.5.0/.github/workflows/publish.yml

@@ -0,0 +1,48 @@
+name: publish
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tool
+        run: python3 -m pip install --upgrade build
+
+      - name: Build wheel and sdist
+        run: python3 -m build
+
+      - name: Upload build artefacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/asl-mri-utils/
+    permissions:
+      id-token: write  # required for PyPI trusted publishing (OIDC); no API token stored
+    steps:
+      - name: Download build artefacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

asl_mri_utils-0.5.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+*.egg-info/
+.pytest_cache/
+build/
+dist/
+*.nii.gz
+*.dcm

asl_mri_utils-0.5.0/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to this project are documented here. Versioning follows
+[Semantic Versioning](https://semver.org/).
+
+## 0.5.0 -- initial release
+
+- **Volume-order analysis** (`asl-mri-utils order`): recovers the true LABEL/CONTROL/M0/TI acquisition
+  order of a Siemens enhanced-DICOM ASL series directly from per-frame DICOM tags.
+- **DICOM-to-NIfTI conversion** (`asl-mri-utils convert`): wraps a local `dcm2niix`/`dcm2niix_afni`
+  install, merging per-echo output into an oxasl-ready `*_asl.nii.gz`/`*_mzero.nii.gz` with a
+  matching `*_aslcontext.tsv` and `*_oxasl_params.json`.
+- **Perfusion subtraction** (`asl-mri-utils subtract`): standard pairwise, surround, and sinc
+  subtraction (Liu & Wong 2005), with `--recommend` for design-dependent method selection.
+- **Alternative sinc estimators** (`--sinc-interp`): windowed-sinc, FFT fractional delay,
+  Gaussian process regression, and a Kalman filter/RTS smoother, each vectorised across the voxel
+  axis via shared weight matrices.
+- **Series discovery** (`asl-mri-utils discover`): finds candidate DICOM series directories under a root.
+- Full documentation with equations, citations, and worked visual examples under `docs/`.

asl_mri_utils-0.5.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sriranga Kashyap
+
+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.

asl_mri_utils-0.5.0/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.5
+Name: asl-mri-utils
+Version: 0.5.0
+Summary: Utilities for Siemens arterial spin labeling (ASL) DICOM volume-order analysis and DICOM-to-NIfTI conversion
+Project-URL: Homepage, https://github.com/srikash/asl-mri-utils
+Project-URL: Repository, https://github.com/srikash/asl-mri-utils
+Project-URL: Issues, https://github.com/srikash/asl-mri-utils/issues
+Project-URL: Documentation, https://github.com/srikash/asl-mri-utils/tree/main/docs
+Author-email: Sriranga Kashyap <srikashmri@gmail.com>
+Maintainer-email: Sriranga Kashyap <srikashmri@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: ASL,DICOM,MRI,NIfTI,Siemens,arterial spin labeling,neuroimaging,perfusion
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Requires-Python: >=3.10
+Requires-Dist: nibabel>=5.0
+Requires-Dist: numpy>=1.26
+Requires-Dist: pydicom>=3.0
+Description-Content-Type: text/markdown
+
+# asl-mri-utils
+
+A repository of utilities for ASL data post-processing.
+
+Utilities for Siemens arterial spin labeling (ASL) DICOM processing:
+
+- **Volume-order analysis** (`asl-mri-utils order`): recovers the true LABEL/CONTROL/M0/TI acquisition order
+  of a multi-TI, single- or multi-echo Siemens enhanced-DICOM ASL series directly from per-frame DICOM
+  tags (ASL Context, Siemens private ordering tag), independent of filenames or protocol names.
+- **DICOM-to-NIfTI conversion** (`asl-mri-utils convert`): wraps a locally installed `dcm2niix`/`dcm2niix_afni`
+  binary to convert a Siemens ASL series directory to NIfTI, then merges the per-echo output into a
+  single, oxasl-ready `*_asl.nii.gz` (label/control volumes, chronologically ordered) and
+  `*_mzero.nii.gz` (M0 volumes), with a matching `*_aslcontext.tsv` and an `*_oxasl_params.json`
+  recording the `(iaf, order, tis, tes, rpts)` shape for `oxasl`/`oxasl_multite`. Volume counts are
+  checked against the DICOM-derived order at every step.
+- **Perfusion subtraction** (`asl-mri-utils subtract`): computes CONTROL-LABEL difference images per
+  TI using standard pairwise, surround, or sinc subtraction (Liu & Wong 2005, *NeuroImage*
+  24:207-215). `--recommend block|event_related` picks a single method per the paper's
+  design-dependent guidance instead of listing `--methods` by hand. `--sinc-interp` swaps the
+  sinc method's estimator for an alternative bidirectional interpolator (windowed-sinc, FFT,
+  Gaussian process regression, or a Kalman filter/RTS smoother; see
+  [docs/interpolate.md](https://github.com/srikash/asl-mri-utils/blob/main/docs/interpolate.md)).
+- **Series discovery** (`asl-mri-utils discover`): finds candidate DICOM series directories under a root.
+
+Siemens-only by design: this package relies on the standard ASL DICOM tags plus a Siemens private tag for
+TI ordering, and fails loudly (specific exceptions) rather than guessing when expected tags are absent.
+
+## Contents
+
+- [docs/dicom.md](https://github.com/srikash/asl-mri-utils/blob/main/docs/dicom.md) -- Siemens tag reading, ASL Context classification rule
+- [docs/order.md](https://github.com/srikash/asl-mri-utils/blob/main/docs/order.md) -- ordering/pairing logic, `order.tsv` schema
+- [docs/discovery.md](https://github.com/srikash/asl-mri-utils/blob/main/docs/discovery.md) -- series discovery, DICM sniffing
+- [docs/convert.md](https://github.com/srikash/asl-mri-utils/blob/main/docs/convert.md) -- dcm2niix wrapping, `oxasl_params.json` fields
+- [docs/merge.md](https://github.com/srikash/asl-mri-utils/blob/main/docs/merge.md) -- chronological concatenation into oxasl-ready output
+- [docs/subtract.md](https://github.com/srikash/asl-mri-utils/blob/main/docs/subtract.md) -- Liu & Wong (2005) equations for standard/surround/sinc subtraction
+- [docs/interpolate.md](https://github.com/srikash/asl-mri-utils/blob/main/docs/interpolate.md) -- windowed-sinc, FFT, Gaussian process, and Kalman/RTS interpolation, with visual examples
+
+## Requirements
+
+A local `dcm2niix` or `dcm2niix_afni` installation is required for `asl-mri-utils convert` (not bundled).
+Locate it via `--dcm2niix-path`, the `ASL_MRI_UTILS_DCM2NIIX` environment variable, or `PATH`.
+
+## Install
+
+```
+pip install asl-mri-utils
+```
+
+For local development, from a clone of this repository:
+
+```
+pip install -e .
+```
+
+## Usage
+
+```
+asl-mri-utils order <dicom_series_dir> [<dicom_series_dir> ...] [--outdir DIR]
+asl-mri-utils order --all [ROOT] [--outdir DIR]
+asl-mri-utils convert <dicom_series_dir> --outdir DIR [--dcm2niix-path PATH] [--overwrite]
+asl-mri-utils subtract <nii> <order_tsv> [--ti N ...] [--methods standard surround sinc] [--recommend block|event_related] [--sinc-interp truncated|windowed_sinc|fft|gp|kalman] [--outdir DIR]
+asl-mri-utils discover [ROOT]
+```

asl_mri_utils-0.5.0/README.md

@@ -0,0 +1,63 @@
+# asl-mri-utils
+
+A repository of utilities for ASL data post-processing.
+
+Utilities for Siemens arterial spin labeling (ASL) DICOM processing:
+
+- **Volume-order analysis** (`asl-mri-utils order`): recovers the true LABEL/CONTROL/M0/TI acquisition order
+  of a multi-TI, single- or multi-echo Siemens enhanced-DICOM ASL series directly from per-frame DICOM
+  tags (ASL Context, Siemens private ordering tag), independent of filenames or protocol names.
+- **DICOM-to-NIfTI conversion** (`asl-mri-utils convert`): wraps a locally installed `dcm2niix`/`dcm2niix_afni`
+  binary to convert a Siemens ASL series directory to NIfTI, then merges the per-echo output into a
+  single, oxasl-ready `*_asl.nii.gz` (label/control volumes, chronologically ordered) and
+  `*_mzero.nii.gz` (M0 volumes), with a matching `*_aslcontext.tsv` and an `*_oxasl_params.json`
+  recording the `(iaf, order, tis, tes, rpts)` shape for `oxasl`/`oxasl_multite`. Volume counts are
+  checked against the DICOM-derived order at every step.
+- **Perfusion subtraction** (`asl-mri-utils subtract`): computes CONTROL-LABEL difference images per
+  TI using standard pairwise, surround, or sinc subtraction (Liu & Wong 2005, *NeuroImage*
+  24:207-215). `--recommend block|event_related` picks a single method per the paper's
+  design-dependent guidance instead of listing `--methods` by hand. `--sinc-interp` swaps the
+  sinc method's estimator for an alternative bidirectional interpolator (windowed-sinc, FFT,
+  Gaussian process regression, or a Kalman filter/RTS smoother; see
+  [docs/interpolate.md](https://github.com/srikash/asl-mri-utils/blob/main/docs/interpolate.md)).
+- **Series discovery** (`asl-mri-utils discover`): finds candidate DICOM series directories under a root.
+
+Siemens-only by design: this package relies on the standard ASL DICOM tags plus a Siemens private tag for
+TI ordering, and fails loudly (specific exceptions) rather than guessing when expected tags are absent.
+
+## Contents
+
+- [docs/dicom.md](https://github.com/srikash/asl-mri-utils/blob/main/docs/dicom.md) -- Siemens tag reading, ASL Context classification rule
+- [docs/order.md](https://github.com/srikash/asl-mri-utils/blob/main/docs/order.md) -- ordering/pairing logic, `order.tsv` schema
+- [docs/discovery.md](https://github.com/srikash/asl-mri-utils/blob/main/docs/discovery.md) -- series discovery, DICM sniffing
+- [docs/convert.md](https://github.com/srikash/asl-mri-utils/blob/main/docs/convert.md) -- dcm2niix wrapping, `oxasl_params.json` fields
+- [docs/merge.md](https://github.com/srikash/asl-mri-utils/blob/main/docs/merge.md) -- chronological concatenation into oxasl-ready output
+- [docs/subtract.md](https://github.com/srikash/asl-mri-utils/blob/main/docs/subtract.md) -- Liu & Wong (2005) equations for standard/surround/sinc subtraction
+- [docs/interpolate.md](https://github.com/srikash/asl-mri-utils/blob/main/docs/interpolate.md) -- windowed-sinc, FFT, Gaussian process, and Kalman/RTS interpolation, with visual examples
+
+## Requirements
+
+A local `dcm2niix` or `dcm2niix_afni` installation is required for `asl-mri-utils convert` (not bundled).
+Locate it via `--dcm2niix-path`, the `ASL_MRI_UTILS_DCM2NIIX` environment variable, or `PATH`.
+
+## Install
+
+```
+pip install asl-mri-utils
+```
+
+For local development, from a clone of this repository:
+
+```
+pip install -e .
+```
+
+## Usage
+
+```
+asl-mri-utils order <dicom_series_dir> [<dicom_series_dir> ...] [--outdir DIR]
+asl-mri-utils order --all [ROOT] [--outdir DIR]
+asl-mri-utils convert <dicom_series_dir> --outdir DIR [--dcm2niix-path PATH] [--overwrite]
+asl-mri-utils subtract <nii> <order_tsv> [--ti N ...] [--methods standard surround sinc] [--recommend block|event_related] [--sinc-interp truncated|windowed_sinc|fft|gp|kalman] [--outdir DIR]
+asl-mri-utils discover [ROOT]
+```

asl_mri_utils-0.5.0/docs/convert.md

@@ -0,0 +1,46 @@
+# `asl_mri_utils.convert`
+
+Wraps a local `dcm2niix`/`dcm2niix_afni` install to convert a Siemens ASL DICOM series directory to
+NIfTI, and attaches ASL ordering metadata on top.
+
+## Two layers of output
+
+- Per echo, alongside dcm2niix's own NIfTI + JSON: `"<stem>_echo<N>_order.tsv"` and
+  `"<stem>_echo<N>_aslcontext.tsv"` (the explicit `_echo<N>` tag avoids a filename collision with
+  the series-level merged output for single-echo series, where dcm2niix's own stem already equals
+  the series-level prefix). These describe dcm2niix's output as-is, M0 and any trailing unpaired
+  block included.
+- Series-level, via `asl_mri_utils.merge`: a single combined, oxasl-ordered `"<prefix>_asl.nii.gz"` and
+  `"<prefix>_mzero.nii.gz"`, built by concatenating each echo's own volumes in true chronological
+  order (M0 and the trailing unpaired block dropped, since oxasl requires an exact volume count),
+  plus `"<prefix>_oxasl_params.json"` recording the `(iaf, order, ntis, ntes, rpts)` shape and the
+  merged file paths, ready to hand to `oxasl`/`oxasl_multite` directly.
+
+## `oxasl_params.json` shape, by protocol
+
+| Shape | ntis | ntes | order (fastest→slowest) |
+|---|---|---|---|
+| single-TI, single-TE | 1 | 1 | `lr` |
+| multi-TI, single-TE | >1 | 1 | `tlr` |
+| multi-TI, multi-TE | >1 | >1 | `etlr` |
+| single-TI, multi-TE | 1 | >1 | `elr` |
+
+`iaf` is always `"tc"` (tag-then-control) for this acquisition pattern: the sequence always
+acquires a LABEL block before its paired CONTROL block.
+
+## Error handling
+
+- `NotAslSeriesError` / `NotSiemensError` / `MissingAslTagsError` before touching dcm2niix at all,
+  if the series doesn't qualify (see `asl_mri_utils.dicom`'s classification rule).
+- `Dcm2niixError` if the dcm2niix subprocess itself fails (non-zero exit).
+- `VolumeCountMismatchError` if a converted NIfTI's volume count disagrees with the DICOM-derived
+  order rows for that echo.
+
+`resolve_dcm2niix_path` checks, in order: an explicit `--dcm2niix-path`, the
+`ASL_MRI_UTILS_DCM2NIIX` environment variable, then `PATH` for `dcm2niix` and `dcm2niix_afni` in turn.
+The binary is never bundled or installed by this package.
+
+Output filenames are never predicted from a regex: the same study can produce two different
+dcm2niix postfix conventions (`_1`/`_2` for raw ASL series, `_e1`/`_e2` for Siemens-derived
+perfusion maps), so `convert.py` parses dcm2niix's own stdout (`"Convert N DICOM as <path> (...)"`)
+to enumerate the actual output files.

asl_mri_utils-0.5.0/docs/dicom.md

@@ -0,0 +1,38 @@
+# `asl_mri_utils.dicom`
+
+Per-frame Siemens enhanced-DICOM tag reading for ASL series.
+
+## Classification rule for `read_frame_info`'s return value
+
+- If `PerFrameFunctionalGroupsSequence` is absent, or ASL Technique Sequence (0018,9251) is absent
+  from the first frame, the series does not self-identify as ASL at all (localizer, B0 map,
+  MoCoSeries, a derived Perfusion_Weighted/relCBF map, and so on). This is **not** an error:
+  `read_frame_info` returns `None` and callers should skip the series silently.
+- If ASL Technique Sequence **is** present (the series claims to be ASL) but ASL Context
+  (0018,9257), Frame Content Sequence (0020,9111), or Temporal Position Index (0020,9128) is then
+  missing, that is a malformed/unexpected ASL series, not a derived map with no context.
+  `MissingAslTagsError` is raised naming the specific missing tag.
+- Echo Number (0018,0086) absence is **not** an error: it falls back to echo 1 (single-echo
+  protocols don't carry it). `ti_index` being `None` after `parse_ti_index` is also **not** an
+  error: some protocols may legitimately lack the Siemens private ordinal tag; downstream code
+  treats `ti_index=None` rows as "ungrouped by TI".
+
+## Siemens private tags used
+
+- `PRIV_PERFRAME_SEQ = (0x0021, 0x11FE)`, `PRIV_ORDER_TAG = (0x0021, 0x1106)`: the per-frame
+  private sequence and the ordinal string it carries, e.g. `"X_1_1_2_3_1_1_1_1_1_1_1_40"`, parsed
+  by `parse_ti_index` into the fourth underscore-separated field (the TI ordinal).
+- Shared block: creator `(0x0021, 0x0010)` = `"SIEMENS MR SDS 01"`, data sequence
+  `(0x0021, 0x10FE)`. Per-frame block: creator `(0x0021, 0x0011)` = `"SIEMENS MR SDI 02"`, data
+  sequence `(0x0021, 0x11FE)`. These are two separate private blocks at different tag numbers, not
+  one shared creator used in both places.
+- `verify_siemens_private_block(ds)` checks `Manufacturer` (0008,0070) and one of the two private
+  creator strings above, raising `NotSiemensError` if neither matches. Call once per series (the
+  first frame suffices) before trusting any TI-index parse.
+
+## Public functions
+
+- `parse_ti_index(private_order_string) -> int | None`
+- `verify_siemens_private_block(ds)`
+- `read_frame_info(ds) -> dict | None` -- returns
+  `{"acq_dt", "tpi", "context", "echo", "ti_index"}` per the classification rule above.

asl_mri_utils-0.5.0/docs/discovery.md

@@ -0,0 +1,21 @@
+# `asl_mri_utils.discovery`
+
+Series-folder discovery: finds candidate DICOM series directories under a root, matching the
+`"NNN-SeriesDescription"` folder-naming convention used throughout this study and verifying each
+candidate actually contains DICOM files.
+
+## Public functions
+
+- `is_dicom(path) -> bool`: checks the `"DICM"` magic bytes at offset 128 (the standard DICOM
+  preamble).
+- `discover_series(root, *, require_dcm_extension=True) -> list[Path]`: finds series directories
+  directly under `root` whose name matches `"NNN-SeriesDescription"` and that contain at least one
+  DICOM file. With `require_dcm_extension=True` (default, fast path), a directory qualifies if it
+  contains at least one `*.dcm` file. With `False`, every file in a name-matching directory is
+  sniffed for the DICM magic bytes instead, so directories work even if files haven't been given a
+  `.dcm` extension.
+
+The scan root is always an explicit argument, never inferred from the package's own install
+location: an earlier version of the underlying script hardcoded the scanning directory to wherever
+the script itself lived, which silently broke once packaged (the install directory is not the
+user's data directory).