qsiplan 0.1.0__tar.gz

qsiplan-0.1.0/.github/workflows/lint.yml

@@ -0,0 +1,41 @@
+name: Contribution checks
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+defaults:
+  run:
+    shell: bash
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  style:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      # Keep this pin in sync with the ruff rev in .pre-commit-config.yaml
+      # and the dev pin in pyproject.toml. Unpinned, CI silently follows new
+      # ruff releases and goes red without a code change.
+      - run: pipx run --spec ruff==0.15.21 ruff check .
+      - run: pipx run --spec ruff==0.15.21 ruff format --diff .
+
+  codespell:
+    name: Check for spelling errors
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+      - name: Codespell
+        uses: codespell-project/actions-codespell@v2

qsiplan-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,46 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  # The release runs the same suite as every push/PR, re-run on the exact
+  # tagged commit. publish depends on it, so a red tag never reaches PyPI.
+  tests:
+    uses: ./.github/workflows/reusable-tests.yml
+    secrets: inherit
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # hatch-vcs derives the version from the tag
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - run: pipx run build
+      - run: pipx run twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: [tests, build]
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/qsiplan
+    permissions:
+      id-token: write  # OIDC token for Trusted Publishing (no stored secret)
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

qsiplan-0.1.0/.github/workflows/reusable-tests.yml

@@ -0,0 +1,34 @@
+name: reusable tests
+
+on:
+  workflow_call:
+    secrets:
+      CODECOV_TOKEN:
+        required: false
+
+jobs:
+  pytest:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.11', '3.12', '3.13']
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - name: Install with test extras
+        run: pip install -e '.[tests]' pytest-cov
+      - name: Run the suite with coverage
+        run: pytest tests --cov=qsiplan --cov-report=term --cov-report=xml --cov-fail-under=85
+      - name: Smoke the CLI entry point
+        run: qsiplan --help
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: ./coverage.xml
+          flags: py${{ matrix.python-version }}
+          fail_ci_if_error: false

qsiplan-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,15 @@
+name: tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: tests-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  tests:
+    uses: ./.github/workflows/reusable-tests.yml
+    secrets: inherit

qsiplan-0.1.0/.gitignore

@@ -0,0 +1,35 @@
+# Byte-compiled / caches
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.hypothesis/
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+.eggs/
+
+# Version file, if hatch-vcs versioning is adopted
+qsiplan/_version.py
+
+# Coverage
+htmlcov/
+.coverage
+.coverage.*
+coverage.xml
+
+# Environments
+.venv/
+env/
+.tox/
+
+# Editors / OS
+.idea/
+.vscode/
+.ipynb_checkpoints/
+*.swp
+*.DS_Store
+
+# Rendered preview pages from local qsiplan runs
+grouping*.html

qsiplan-0.1.0/LICENSE

@@ -0,0 +1,27 @@
+Copyright (c) 2015-2018, the PennLINC developers team.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* 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.
+
+* Neither the name of qsiprep 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.

qsiplan-0.1.0/PKG-INFO

@@ -0,0 +1,61 @@
+Metadata-Version: 2.5
+Name: qsiplan
+Version: 0.1.0
+Summary: Plan and explain QSIPrep's diffusion-MRI preprocessing from BIDS metadata
+Project-URL: Homepage, https://github.com/PennLINC/qsiprep
+Author: The PennLINC developers
+License: Copyright (c) 2015-2018, the PennLINC developers team.
+        All rights reserved.
+        
+        Redistribution and use in source and binary forms, with or without
+        modification, are permitted provided that the following conditions are met:
+        
+        * Redistributions of source code must retain the above copyright notice, this
+          list of conditions and the following disclaimer.
+        
+        * 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.
+        
+        * Neither the name of qsiprep 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.
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: nibabel
+Requires-Dist: numpy
+Requires-Dist: pybids
+Provides-Extra: tests
+Requires-Dist: niworkflows; extra == 'tests'
+Requires-Dist: pytest; extra == 'tests'
+Description-Content-Type: text/markdown
+
+# QSIPlan
+
+[![tests](https://github.com/PennLINC/QSIPlan/actions/workflows/tests.yml/badge.svg)](https://github.com/PennLINC/QSIPlan/actions/workflows/tests.yml)
+[![codecov](https://codecov.io/gh/PennLINC/QSIPlan/branch/main/graph/badge.svg)](https://codecov.io/gh/PennLINC/QSIPlan)
+
+Plan and explain [qsiprep](https://github.com/PennLINC/qsiprep)'s
+diffusion-MRI preprocessing from BIDS metadata and configuration flags.
+
+`qsiplan` groups a subject's DWI scans the way qsiprep will (distortion
+groups, fieldmap estimations, correction units, outputs), validates the
+data and curation (missing phase-encoding metadata, IntendedFor conflicts,
+shim walls, b-value mismatches...), compiles the execution plan for any
+combination of head-motion- and susceptibility-correction methods, and
+renders it all as text or as a self-contained interactive HTML page:
+
+```bash
+qsiplan /path/to/bids --html grouping.html
+```

qsiplan-0.1.0/README.md

@@ -0,0 +1,18 @@
+# QSIPlan
+
+[![tests](https://github.com/PennLINC/QSIPlan/actions/workflows/tests.yml/badge.svg)](https://github.com/PennLINC/QSIPlan/actions/workflows/tests.yml)
+[![codecov](https://codecov.io/gh/PennLINC/QSIPlan/branch/main/graph/badge.svg)](https://codecov.io/gh/PennLINC/QSIPlan)
+
+Plan and explain [qsiprep](https://github.com/PennLINC/qsiprep)'s
+diffusion-MRI preprocessing from BIDS metadata and configuration flags.
+
+`qsiplan` groups a subject's DWI scans the way qsiprep will (distortion
+groups, fieldmap estimations, correction units, outputs), validates the
+data and curation (missing phase-encoding metadata, IntendedFor conflicts,
+shim walls, b-value mismatches...), compiles the execution plan for any
+combination of head-motion- and susceptibility-correction methods, and
+renders it all as text or as a self-contained interactive HTML page:
+
+```bash
+qsiplan /path/to/bids --html grouping.html
+```

qsiplan-0.1.0/codecov.yml

@@ -0,0 +1,20 @@
+# Codecov behaves as a reporter here, never a gate: the enforced floor is
+# pytest's --cov-fail-under in CI, so both statuses are informational and
+# nothing goes red because of an upload or rounding quirk.
+coverage:
+  status:
+    project:
+      default:
+        informational: true
+    patch:
+      default:
+        informational: true
+
+comment:
+  layout: "condensed_header, diff, flags"
+  # One comment after all three matrix uploads, not three drafts.
+  after_n_builds: 3
+
+codecov:
+  notify:
+    after_n_builds: 3

qsiplan-0.1.0/pyproject.toml

@@ -0,0 +1,94 @@
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[project]
+name = "qsiplan"
+dynamic = ["version"]
+description = "Plan and explain QSIPrep's diffusion-MRI preprocessing from BIDS metadata"
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.11"
+authors = [{ name = "The PennLINC developers" }]
+dependencies = [
+    "pybids",
+    "nibabel",
+    "numpy",
+]
+
+[project.optional-dependencies]
+tests = [
+    "pytest",
+    "niworkflows",
+]
+
+[project.scripts]
+qsiplan = "qsiplan.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/PennLINC/qsiprep"
+
+[tool.hatch.build.targets.wheel]
+packages = ["qsiplan"]
+
+[tool.hatch.version]
+source = "vcs"
+fallback-version = "0.1.0"
+
+[tool.hatch.build.hooks.vcs]
+version-file = "qsiplan/_version.py"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.coverage.run]
+branch = true
+source = ["qsiplan"]
+
+[tool.coverage.report]
+show_missing = true
+
+[tool.ruff]
+line-length = 99
+extend-exclude = ["qsiplan/_version.py"]
+
+[tool.ruff.lint]
+extend-select = [
+  "F",
+  "E",
+  "W",
+  "I",
+  "UP",
+  "YTT",
+  "S",
+  "BLE",
+  "B",
+  "A",
+  "C4",
+  "DTZ",
+  "T10",
+  "EXE",
+  "FA",
+  "ISC",
+  "ICN",
+  "PT",
+  "Q",
+]
+ignore = [
+  "ISC001",  # conflicts with the formatter
+  "S311",  # random is never used for cryptography here
+]
+
+[tool.ruff.lint.flake8-quotes]
+inline-quotes = "single"
+
+[tool.ruff.lint.extend-per-file-ignores]
+"tests/*.py" = ["S101"]
+
+[tool.ruff.format]
+quote-style = "single"
+
+[tool.codespell]
+skip = '.git,*.html,*.svg,*.lock'
+# te: the TE (echo time) abbreviation in prose and golden reports
+ignore-words-list = 'te'

qsiplan-0.1.0/qsiplan/__init__.py

@@ -0,0 +1,220 @@
+"""BIDS-native grouping of DWI scans for preprocessing.
+
+This package decides, per subject, from BIDS metadata alone:
+
+1. Which DWI files share susceptibility distortions (distortion groups).
+2. Which files jointly estimate each fieldmap (``B0FieldIdentifier``).
+3. Which fieldmap corrects which DWI file (``B0FieldSource``).
+4. Which files are concatenated in the outputs (``MultipartID``).
+
+Curated sidecar metadata is used verbatim; everything the user did not curate
+is inferred and tagged with its provenance. The output,
+:class:`~.models.DWIGrouping`, describes the *data* - how any given
+processing backend arranges that data is the business of adapters and the
+previews in :mod:`~.report`.
+
+Run ``qsiplan /path/to/bids`` to print the grouping and
+per-selection processing previews for a dataset.
+
+Adding a new estimation method
+------------------------------
+The (method x selection) behavior matrix is deliberately spelled out as prose
+branches rather than a rules table, because the preview text is the product.
+The cost is that a new :class:`~.models.CorrectionMethod` touches five places
+(SYNB0 is the worked example in each):
+
+1. :class:`~.models.CorrectionMethod` - add the member.
+2. ``inference.py`` - produce it: ``_classify_method`` for curated sources
+   and/or a step in ``resolve_fieldmapless``; rank it in ``_METHOD_RANK``.
+3. ``methods.py`` - which :class:`~.methods.SdcTool` consumes it (the
+   capability registries), and ``plan.py`` - its stage sequence per HMC
+   method, and whether an infeasible selection is an error or a degradation.
+4. ``report.py`` - ``_METHOD_LABELS``, ``MethodGroups``/``_ids_by_kind``,
+   a narration branch in each ``_describe_*`` function, and its
+   ``_stage_text`` sentence.
+5. Tests - a scenario skeleton, inference assertions, plan-stage assertions,
+   and regenerated golden reports (``QSIPREP_REGEN_GROUPING_REPORTS=1``).
+"""
+
+try:
+    from ._version import __version__
+except ImportError:  # pragma: no cover - not yet built from a git checkout
+    __version__ = '0+unknown'
+
+from .adapters import (
+    PreprocUnit,
+    assembly_to_sidecar,
+    concatenation_scheme,
+    to_preproc_units,
+    unit_to_sidecar,
+)
+from .inference import build_grouping
+from .interactive import render_html, render_report_segment
+from .metadata import index_subject
+from .methods import (
+    HMC_CAPABILITIES,
+    SDC_CAPABILITIES,
+    HmcMethod,
+    MethodSelection,
+    SdcTool,
+    canonical_selection,
+    selection_for_config,
+)
+from .models import (
+    ConcatenationGroup,
+    CorrectionMethod,
+    DistortionGroup,
+    DistortionSignature,
+    DWIGrouping,
+    FieldmapEstimation,
+    FileRecord,
+    GroupingPolicy,
+    Provenance,
+)
+from .plan import ExecutionPlan, OutputAssembly, PlanStage, ProcessingRun, compile_plan
+from .report import describe_processing, full_report, report_text
+from .validation import BACKENDS, GroupingError, GroupingIssue, check_backend, raise_for_errors
+
+__all__ = [
+    'BACKENDS',
+    'HMC_CAPABILITIES',
+    'SDC_CAPABILITIES',
+    'ConcatenationGroup',
+    'DistortionGroup',
+    'DistortionSignature',
+    'DWIGrouping',
+    'CorrectionMethod',
+    'FieldmapEstimation',
+    'FileRecord',
+    'GroupingError',
+    'GroupingIssue',
+    'GroupingPolicy',
+    'HmcMethod',
+    'MethodSelection',
+    'PreprocUnit',
+    'Provenance',
+    'SdcTool',
+    'assembly_to_sidecar',
+    'build_dwi_grouping',
+    'canonical_selection',
+    'check_backend',
+    'compile_plan',
+    'ExecutionPlan',
+    'OutputAssembly',
+    'PlanStage',
+    'ProcessingRun',
+    'concatenation_scheme',
+    'describe_processing',
+    'full_report',
+    'index_subject',
+    'render_html',
+    'render_report_segment',
+    'report_text',
+    'selection_for_config',
+    'to_preproc_units',
+    'unit_to_sidecar',
+]
+
+
+def build_dwi_grouping(
+    layout,
+    subject_data,
+    separate_all_dwis=False,
+    ignore_fieldmaps=False,
+    ignore_shims=False,
+    ignore_fov=False,
+    ignore_sdc=False,
+    force_t2wreg=False,
+    use_synb0=False,
+    use_nipreps_syn_sdc=False,
+    distortion_group_merge='concat',
+    b0_threshold=None,
+    strict=True,
+):
+    """Group one subject's DWI scans.
+
+    Parameters
+    ----------
+    layout : :class:`bids.BIDSLayout`
+        Layout of the input dataset; used only for sidecar metadata reads.
+    subject_data : dict
+        As returned by :func:`qsiprep.utils.bids.collect_data`: must contain
+        a ``'dwi'`` key listing the subject's DWI files (``'fmap'``,
+        ``'t1w'``, and ``'t2w'`` are optional - they are discovered from the
+        layout when absent).
+    separate_all_dwis : bool
+        Every DWI series becomes its own output. Fieldmap estimation still
+        happens at session scope, so single series keep their SDC.
+    ignore_fieldmaps : bool
+        Do not index ``fmap/``. The reverse phase-encoding DWI heuristic
+        still applies.
+    ignore_shims : bool
+        Treat all ShimSetting values as compatible. Use when data were
+        re-shimmed but distortion correction across shims is wanted anyway.
+    ignore_fov : bool
+        Downgrade the differing-orientation field-of-view error to a warning
+        and proceed, accepting misapplied distortion corrections. Grid-size
+        mismatches remain errors: they cannot be stacked at all.
+    ignore_sdc : bool
+        Disable susceptibility distortion correction entirely: no fieldmaps, no
+        reverse-PE heuristic, and no fieldmap-less fallback. Every series is
+        left uncorrected but is still grouped and concatenated for HMC. Stronger
+        than ``ignore_fieldmaps`` (which only skips ``fmap/``).
+    force_t2wreg : bool
+        Correct every DWI series by registering its b=0 to the subject's T2w
+        (TORTOISE T2Wreg), overriding any fieldmaps. Errors if no T2w exists.
+    use_synb0 : bool
+        Give series that have no fieldmap a SyNb0 synthetic-b=0 estimation
+        synthesized from the T1w. Never overrides a real fieldmap. Errors if
+        no T1w exists or a target series lacks PhaseEncodingDirection.
+    distortion_group_merge : str or None
+        How the corrected results of a final output's correction units are
+        combined: ``'concat'`` (default) concatenates them, ``'average'``
+        averages matched volumes (opposite-PE duplicate schemes), and
+        ``'none'`` keeps every correction unit as its own output (``None``
+        is treated as ``'concat'``).
+    use_nipreps_syn_sdc : bool
+        Correct series that have no fieldmap with the standalone niworkflows
+        SyN-SDC: a constrained ANTs SyN registration of an inverted T1w (or a
+        synthetic b=0) to a fieldmap atlas. Never overrides a real fieldmap and
+        is never combined with SyNb0 (SyNb0 wins if both are set). Errors if no
+        T1w exists or a target series lacks PhaseEncodingDirection.
+    b0_threshold : float
+        Diffusion-weighting at or below this is treated as b=0 when
+        classifying sampling schemes (default:
+        :data:`~.metadata.B0_THRESHOLD`).
+    strict : bool
+        Raise :class:`~.validation.GroupingError` if any error-severity issue
+        is found. With ``strict=False`` the grouping is returned with its
+        ``issues`` intact, which is what reports and previews want.
+
+    Returns
+    -------
+    :class:`~.models.DWIGrouping`
+    """
+    from bids.layout import parse_file_entities
+
+    records, index_issues = index_subject(
+        layout,
+        subject_data,
+        ignore_fieldmaps=ignore_fieldmaps,
+        b0_threshold=b0_threshold,
+    )
+    subject_id = parse_file_entities(records[0].path)['subject']
+    grouping = build_grouping(
+        records,
+        subject_id=subject_id,
+        separate_all_dwis=separate_all_dwis,
+        ignore_fieldmaps=ignore_fieldmaps,
+        ignore_shims=ignore_shims,
+        ignore_fov=ignore_fov,
+        ignore_sdc=ignore_sdc,
+        force_t2wreg=force_t2wreg,
+        use_synb0=use_synb0,
+        use_nipreps_syn_sdc=use_nipreps_syn_sdc,
+        distortion_group_merge=distortion_group_merge,
+        extra_issues=index_issues,
+    )
+    if strict:
+        raise_for_errors(grouping)
+    return grouping

qsiplan-0.1.0/qsiplan/__main__.py

@@ -0,0 +1,8 @@
+"""Alias for the ``qsiprep-group`` command line tool (qsiplan.cli)."""
+
+import sys
+
+from qsiplan.cli import main
+
+if __name__ == '__main__':
+    sys.exit(main())

qsiplan-0.1.0/qsiplan/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = None