brkraw 0.5.0rc1__tar.gz → 0.5.1__tar.gz

brkraw-0.5.1/.github/copilot-instructions.md

@@ -0,0 +1,10 @@
+# AI coding instructions
+
+- This repository is a Python package.
+- Use the project-local virtualenv at `.venv` for Python commands.
+- Target Python version: >= 3.8 (flag compatibility issues with versions supported by `pyproject.toml`).
+- Prefer pure functions and type hints.
+- Do not introduce new dependencies unless explicitly asked.
+- Follow existing style and naming conventions.
+- Avoid large refactors unless requested.
+- Add/update tests for behavior changes when practical.

{brkraw-0.5.0rc1 → brkraw-0.5.1}/.github/workflows/publish.yml

@@ -40,42 +40,13 @@ jobs:
       - name: Install build tooling
         run: |
           python -m pip install --upgrade pip
-          python -m pip install build twine
+          python -m pip install build twine packaging
       - name: Verify version matches tag
         if: ${{ github.event_name == 'release' || (github.event_name == 'workflow_dispatch' && inputs.tag != '') }}
         env:
           TAG: ${{ steps.tag.outputs.value }}
         run: |
-          python -c 'code = """import os
-          import sys
-          import re
-          import tomllib
-          from pathlib import Path
-          from packaging.version import parse
-
-          tag = os.environ["TAG"]
-          print(f"Target Tag: {tag}")
-
-          pyproject = tomllib.loads(Path("pyproject.toml").read_text(encoding="utf-8"))
-          version = pyproject.get("project", {}).get("version")
-          if not version:
-              version_path = pyproject.get("tool", {}).get("hatch", {}).get("version", {}).get("path")
-              if not version_path:
-                  raise SystemExit("No version in pyproject.toml and no hatch version path found.")
-              text = Path(version_path).read_text(encoding="utf-8")
-              match = re.search(r"__version__\\s*=\\s*[\"\x27]([^\"]+)[\"\x27]", text)
-              if not match:
-                  raise SystemExit(f"No __version__ found in {version_path}")
-              version = match.group(1)
-          
-          print(f"Detected Package Version: {version}")
-
-          # Normalize versions and compare (handles v-prefix and alpha/beta notations)
-          if parse(tag) != parse(version):
-              raise SystemExit(f"Tag {tag} does not match package version {version}.")
-          
-          print("Version check passed!")
-          \"\"\"; exec(code)'
+          python scripts/verify_release_version.py
       - name: Build dist
         run: python -m build
       - name: Check dist metadata

{brkraw-0.5.0rc1 → brkraw-0.5.1}/.github/workflows/release.yml

@@ -68,7 +68,7 @@ jobs:
 
           notes = Path("RELEASE_NOTES.md").read_text(encoding="utf-8").strip()
           title = f"Release {tag}"
-          body = f"[Release {tag}]({release_url})\\n\\n{notes}"
+          body = f"[Release {tag}]({release_url})\n\n{notes}"
 
           query = {
               "query": """

brkraw-0.5.1/.github/workflows/release_on_merge.yml

@@ -0,0 +1,54 @@
+name: Release On Merge
+
+on:
+  pull_request:
+    types: [closed]
+    branches: [main]
+
+permissions:
+  contents: write
+
+jobs:
+  tag_release:
+    if: ${{ github.repository == 'BrkRaw/brkraw' && github.event.pull_request.merged == true && contains(github.event.pull_request.labels.*.name, 'release') }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Detect version change
+        id: version
+        run: |
+          base_sha="${{ github.event.pull_request.base.sha }}"
+          merge_sha="${{ github.event.pull_request.merge_commit_sha }}"
+          if ! git diff --name-only "$base_sha" "$merge_sha" | grep -q '^src/brkraw/__init__.py$'; then
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          version=$(python3 - <<'PY'
+          import re
+          from pathlib import Path
+
+          text = Path("src/brkraw/__init__.py").read_text(encoding="utf-8")
+          match = re.search(
+              r"^\\s*__version__(?:\\s*:\\s*[^=]+)?\\s*=\\s*['\\\"]([^'\\\"]+)['\\\"]",
+              text,
+              re.M,
+          )
+          if not match:
+              raise SystemExit("No __version__ found in src/brkraw/__init__.py")
+          print(match.group(1))
+          PY
+          )
+          echo "changed=true" >> "$GITHUB_OUTPUT"
+          echo "value=$version" >> "$GITHUB_OUTPUT"
+      - name: Create and push tag
+        if: ${{ steps.version.outputs.changed == 'true' }}
+        run: |
+          tag="${{ steps.version.outputs.value }}"
+          if git rev-parse "$tag" >/dev/null 2>&1; then
+            echo "Tag $tag already exists. Skipping."
+            exit 0
+          fi
+          git tag "$tag" "${{ github.event.pull_request.merge_commit_sha }}"
+          git push origin "$tag"

{brkraw-0.5.0rc1 → brkraw-0.5.1}/.gitignore

@@ -23,3 +23,4 @@ site/
 .idea/
 .vscode/
 *.lock
+.tmp

brkraw-0.5.1/.markdownlint.yaml

@@ -0,0 +1,6 @@
+MD007: false
+MD013:
+  line_length: 120
+  tables: false
+MD022: false
+MD032: false

brkraw-0.5.1/AGENTS.md

@@ -0,0 +1,22 @@
+# Codex instructions (repo-wide)
+
+## Environment
+- Use the project-local virtualenv at `.venv` (interpreter: `.venv/bin/python`) when running Python commands.
+- Target Python version for development: >= 3.8. If a change would break
+ versions supported by `pyproject.toml`, call it out before proceeding.
+
+## Project constraints
+- This repository is a Python package.
+- Prefer pure functions and type hints.
+- Do not introduce new dependencies unless explicitly requested.
+- Follow existing style and naming conventions.
+- Avoid large refactors unless requested.
+
+## Quality bar
+- Add or update tests for behavior changes when practical.
+- Keep user-facing CLI output stable unless explicitly requested.
+- Prefer clear errors over silent failures; avoid broad `except Exception` unless there is a strong reason.
+
+## Handy commands
+- Run tests: `.venv/bin/python -m pytest`
+- Lint/type check: only run tools already configured in the repo (do not add new tooling unless asked).

brkraw-0.5.1/CITATION.cff

@@ -0,0 +1,49 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+title: "BrkRaw: A modular toolkit for Bruker MRI raw-data handling"
+type: software
+
+authors:
+  - family-names: Lee
+    given-names: Sung-Ho
+    orcid: "https://orcid.org/0000-0001-5292-0747"
+    affiliation:
+      - "Center for Animal MRI (CAMRI), University of North Carolina at Chapel Hill, Chapel Hill, NC, United States"
+      - "Biomedical Research Imaging Center (BRIC), University of North Carolina at Chapel Hill, Chapel Hill, NC, United States"
+      - "Department of Neurology, UNC School of Medicine, Chapel Hill, NC, United States"
+  - family-names: Devenyi
+    given-names: Gabriel A.
+    orcid: "https://orcid.org/0000-0002-7766-1187"
+    affiliation:
+      - "Cerebral Imaging Centre, Douglas Mental Health University Institute, Montreal, QC, Canada"
+      - "Department of Psychiatry, McGill University, Montreal, QC, Canada"
+  - family-names: Ban
+    given-names: Woomi
+    orcid: "https://orcid.org/0000-0003-2003-717X"
+    affiliation:
+      - "Center for Animal MRI (CAMRI), University of North Carolina at Chapel Hill, Chapel Hill, NC, United States"
+      - "Biomedical Research Imaging Center (BRIC), University of North Carolina at Chapel Hill, Chapel Hill, NC, United States"
+      - "Department of Neurology, UNC School of Medicine, Chapel Hill, NC, United States"
+  - family-names: Shih
+    given-names: Yen-Yu Ian
+    orcid: "https://orcid.org/0000-0001-6529-911X"
+    affiliation:
+      - "Center for Animal MRI (CAMRI), University of North Carolina at Chapel Hill, Chapel Hill, NC, United States"
+      - "Biomedical Research Imaging Center (BRIC), University of North Carolina at Chapel Hill, Chapel Hill, NC, United States"
+      - "Department of Neurology, UNC School of Medicine, Chapel Hill, NC, United States"
+
+doi: "10.5281/zenodo.3818614"
+repository-code: "https://github.com/BrkRaw/brkraw"
+url: "https://brkraw.github.io"
+
+license: "GPL-3.0-only"
+
+keywords:
+  - Bruker
+  - MRI
+  - preclinical MRI
+  - BIDS
+  - neuroimaging
+
+version: "0.5.1"
+date-released: "2026-01-19"

{brkraw-0.5.0rc1 → brkraw-0.5.1}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: brkraw
-Version: 0.5.0rc1
+Version: 0.5.1
 Summary: Toolkit for loading Bruker Paravision datasets, mapping metadata, and exporting NIfTI
 Project-URL: Homepage, https://brkraw.github.io
 Maintainer-email: SungHo Lee <shlee@unc.edu>
 License: GNLv3
 License-File: LICENSE
 Keywords: bruker,cli,conversion,dataset,mri,neuroimaging,nifti,paravision,preclinical
-Classifier: Development Status :: 4 - Beta
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Science/Research
 Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
 Classifier: Natural Language :: English
@@ -44,11 +44,38 @@ Description-Content-Type: text/markdown
 </picture>
 <!-- markdownlint-enable MD041 MD033 MD013 -->
 
-A modular toolkit for preclinical MRI: from raw studies to reproducible outputs.
+[![DOI](https://zenodo.org/badge/245546149.svg)](https://doi.org/10.5281/zenodo.3818614)
 
-BrkRaw (v0.5.0rc1) converts raw data into standardized, neuroimaging-ready
+A modular toolkit for Bruker MRI raw-data handling.
+
+BrkRaw (v0.5.1) converts raw data into standardized, neuroimaging-ready
 datasets, with extensible rules/specs and plugin hooks.
 
 - Documentation: [brkraw.github.io](https://brkraw.github.io/)
 - Releases: [BrkRaw/brkraw releases](https://github.com/BrkRaw/brkraw/releases)
 - PyPI: [brkraw on PyPI](https://pypi.org/project/brkraw/)
+
+## Citation
+
+If you use BrkRaw in your research, please cite it.
+
+- Citation metadata: [CITATION.cff](./CITATION.cff)
+- DOI (Zenodo): [10.5281/zenodo.3818614](https://doi.org/10.5281/zenodo.3818614)
+
+### Cite as (BibTeX)
+
+<!-- BEGIN: brkraw-bibtex -->
+```biblatex
+@software{brkraw_2026,
+  author = {Lee, Sung-Ho and Devenyi, Gabriel A and Ban, Woomi and Shih, Yen-Yu Ian},
+  title = {BrkRaw: A modular toolkit for Bruker MRI raw-data handling},
+  year = {2026},
+  version = {0.5.0},
+  doi = {10.5281/zenodo.3818614},
+  url = {https://github.com/BrkRaw/brkraw},
+  note = {Documentation: https://brkraw.github.io},
+  license = {GPL-3.0-only},
+  date = {2026-01-13}
+}
+```
+<!-- END: brkraw-bibtex -->

brkraw-0.5.1/README.md

@@ -0,0 +1,43 @@
+<!-- markdownlint-disable MD041 MD033 MD013 -->
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/assets/brkraw-logo-dark.svg">
+  <source media="(prefers-color-scheme: light)" srcset="docs/assets/brkraw-logo-light.svg">
+  <img src="docs/assets/brkraw-logo-light.svg" width="220" alt="BrkRaw logo">
+</picture>
+<!-- markdownlint-enable MD041 MD033 MD013 -->
+
+[![DOI](https://zenodo.org/badge/245546149.svg)](https://doi.org/10.5281/zenodo.3818614)
+
+A modular toolkit for Bruker MRI raw-data handling.
+
+BrkRaw (v0.5.1) converts raw data into standardized, neuroimaging-ready
+datasets, with extensible rules/specs and plugin hooks.
+
+- Documentation: [brkraw.github.io](https://brkraw.github.io/)
+- Releases: [BrkRaw/brkraw releases](https://github.com/BrkRaw/brkraw/releases)
+- PyPI: [brkraw on PyPI](https://pypi.org/project/brkraw/)
+
+## Citation
+
+If you use BrkRaw in your research, please cite it.
+
+- Citation metadata: [CITATION.cff](./CITATION.cff)
+- DOI (Zenodo): [10.5281/zenodo.3818614](https://doi.org/10.5281/zenodo.3818614)
+
+### Cite as (BibTeX)
+
+<!-- BEGIN: brkraw-bibtex -->
+```biblatex
+@software{brkraw_2026,
+  author = {Lee, Sung-Ho and Devenyi, Gabriel A and Ban, Woomi and Shih, Yen-Yu Ian},
+  title = {BrkRaw: A modular toolkit for Bruker MRI raw-data handling},
+  year = {2026},
+  version = {0.5.0},
+  doi = {10.5281/zenodo.3818614},
+  url = {https://github.com/BrkRaw/brkraw},
+  note = {Documentation: https://brkraw.github.io},
+  license = {GPL-3.0-only},
+  date = {2026-01-13}
+}
+```
+<!-- END: brkraw-bibtex -->

brkraw-0.5.1/RELEASE_NOTES.md

@@ -0,0 +1,13 @@
+# Release v0.5.1
+
+Date: 2026-01-19
+Changes since 0.5.0
+
+- chore: prepare release v0.5.1 (5902a9d)
+- Handle quoted CITATION fields in release prep (bc0bbc8)
+- docs: update contributors (78d6da5)
+- Use gh pr view for release PR lookup (af9fdf1)
+- Make release PR creation compatible with gh (4a939a0)
+- Fix release PR lookup (17cf410)
+- Preserve study fields in override layout (edc67ba)
+- Fix publish version check script (719ae4c)

{brkraw-0.5.0rc1 → brkraw-0.5.1}/brkraw/__init__.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-__version__ = '0.5.0rc1'
+__version__ = '0.5.1'
 from .apps.loader import BrukerLoader
 
 

{brkraw-0.5.0rc1 → brkraw-0.5.1}/brkraw/apps/hook/core.py

@@ -7,7 +7,7 @@ import importlib.metadata
 import logging
 import re
 from pathlib import Path
-from typing import Any, Dict, List, Mapping, Optional, Sequence, Tuple, Union
+from typing import Any, Callable, Dict, List, Mapping, Optional, Sequence, Tuple, Union, cast
 
 try:
     from importlib import resources
@@ -17,7 +17,7 @@ import yaml
 
 from ...core import config as config_core
 from ...core.entrypoints import list_entry_points
-from ...specs.converter.logic import DEFAULT_GROUP
+from ...specs.hook.logic import DEFAULT_GROUP
 from ..addon import installation as addon_install
 from ..addon import dependencies as addon_deps
 from ..addon.io import write_file as _write_file
@@ -28,6 +28,41 @@ REGISTRY_FILENAME = "hooks.yaml"
 MANIFEST_NAMES = ("brkraw_hook.yaml", "brkraw_hook.yml")
 
 
+def _metadata_get(
+    dist: Optional[importlib.metadata.Distribution],
+    key: str,
+    default: Optional[str] = None,
+) -> Optional[str]:
+    """Typed helper to read distribution metadata."""
+    if dist is None:
+        return default
+    meta = cast(Mapping[str, str], dist.metadata)
+    return meta.get(key, default)
+
+
+def _packages_distributions() -> Mapping[str, List[str]]:
+    packages_distributions = getattr(importlib.metadata, "packages_distributions", None)
+    if packages_distributions is not None:
+        return cast(Callable[[], Mapping[str, List[str]]], packages_distributions)()
+
+    mapping: Dict[str, List[str]] = {}
+    for dist in importlib.metadata.distributions():
+        read_text = getattr(dist, "read_text", None)
+        top_level_text = ""
+        if callable(read_text):
+            top_level = read_text("top_level.txt")
+            if isinstance(top_level, str):
+                top_level_text = top_level
+        dist_name = _metadata_get(dist, "Name")
+        if not dist_name:
+            continue
+        for package in top_level_text.splitlines():
+            package = package.strip()
+            if package:
+                mapping.setdefault(package, []).append(dist_name)
+    return mapping
+
+
 def list_hooks(*, root: Optional[Union[str, Path]] = None) -> List[Dict[str, Any]]:
     hooks = _collect_hooks()
     registry = _load_registry(root=root)
@@ -88,13 +123,26 @@ def uninstall_hook(
     *,
     root: Optional[Union[str, Path]] = None,
     force: bool = False,
-) -> Tuple[str, Dict[str, List[str]]]:
+) -> Tuple[str, Dict[str, List[str]], bool]:
     registry = _load_registry(root=root)
     hooks = registry.get("hooks", {})
     hook_name = _resolve_hook_name(target)
     entry = hooks.get(hook_name)
+    if entry is None:
+        entry_matches = [
+            name
+            for name, data in hooks.items()
+            if target in (data.get("entrypoints") or [])
+        ]
+        if len(entry_matches) == 1:
+            hook_name = entry_matches[0]
+            entry = hooks.get(hook_name)
+        elif entry_matches:
+            names = ", ".join(sorted(entry_matches))
+            raise ValueError(f"Multiple hooks match {target}: {names}")
     if entry is None:
         raise LookupError(f"Hook not installed: {hook_name}")
+    module_missing = not list_entry_points(DEFAULT_GROUP, name=hook_name)
     removed: Dict[str, List[str]] = {
         "specs": [],
         "pruner_specs": [],
@@ -113,7 +161,7 @@ def uninstall_hook(
             removed[kind].append(relpath)
     hooks.pop(hook_name, None)
     _save_registry(registry, root=root)
-    return hook_name, removed
+    return hook_name, removed, module_missing
 
 
 def _install_hook(
@@ -347,7 +395,7 @@ def _resolve_distribution(ep: importlib.metadata.EntryPoint) -> Optional[importl
     pkg = getattr(ep, "module", "").split(".")[0]
     if not pkg:
         return None
-    mapping = importlib.metadata.packages_distributions()
+    mapping = _packages_distributions()
     dist_names = mapping.get(pkg, [])
     if not dist_names:
         return None
@@ -360,26 +408,26 @@ def _resolve_distribution(ep: importlib.metadata.EntryPoint) -> Optional[importl
 def _dist_name(dist: Optional[importlib.metadata.Distribution]) -> Optional[str]:
     if dist is None:
         return None
-    return dist.metadata.get("Name")
+    return _metadata_get(dist, "Name")
 
 
 def _dist_version(dist: Optional[importlib.metadata.Distribution]) -> str:
     if dist is None:
         return "<Unknown>"
-    return dist.metadata.get("Version", "<Unknown>")
+    return _metadata_get(dist, "Version", "<Unknown>") or "<Unknown>"
 
 
 def _dist_description(dist: Optional[importlib.metadata.Distribution]) -> str:
     if dist is None:
         return "<Unknown>"
-    return dist.metadata.get("Summary", "<Unknown>")
+    return _metadata_get(dist, "Summary", "<Unknown>") or "<Unknown>"
 
 
 def _dist_author(dist: Optional[importlib.metadata.Distribution]) -> str:
     if dist is None:
         return "<Unknown>"
     for key in ("Author", "Author-email", "Maintainer", "Maintainer-email"):
-        value = dist.metadata.get(key)
+        value = _metadata_get(dist, key)
         if value:
             return value
     return "<Unknown>"
@@ -394,7 +442,7 @@ def _load_manifest(
     manifest = _find_manifest(dist, packages=packages)
     if manifest is None:
         raise FileNotFoundError(
-            f"No hook manifest found in {dist.metadata.get('Name', '<Unknown>')}"
+            f"No hook manifest found in {_metadata_get(dist, 'Name', '<Unknown>')}"
         )
     data = _read_yaml(manifest)
     return manifest, data

{brkraw-0.5.0rc1 → brkraw-0.5.1}/brkraw/apps/loader/core.py

@@ -19,7 +19,7 @@ from pathlib import Path
 
 from ...core import config as config_core
 from ...core.config import resolve_root
-from ...specs import converter as converter_core
+from ...specs import hook as converter_core
 from ...specs.pruner import prune_dataset_to_zip
 from ...specs.rules import load_rules, select_rule_use
 from ...dataclasses import Scan, Study
@@ -350,6 +350,7 @@ class BrukerLoader:
                         override_subject_type: Optional[SubjectType] = None,
                         override_subject_pose: Optional[SubjectPose] = None,
                         flip_x: bool = False, 
+                        flatten_fg: bool = False,
                         xyz_units: XYZUNIT = 'mm', 
                         t_units: TUNIT = 'sec'):
         """Return NIfTI image(s) for a scan/reco via attached helper.
@@ -377,6 +378,7 @@ class BrukerLoader:
             override_subject_type=override_subject_type,
             override_subject_pose=override_subject_pose,
             flip_x=flip_x,
+            flatten_fg=flatten_fg,
             xyz_units=xyz_units,
             t_units=t_units,
         )
@@ -392,6 +394,7 @@ class BrukerLoader:
         override_subject_type: Optional[SubjectType] = None,
         override_subject_pose: Optional[SubjectPose] = None,
         flip_x: bool = False,
+        flatten_fg: bool = False,
         xyz_units: XYZUNIT = "mm",
         t_units: TUNIT = "sec",
         hook_args_by_name: Optional[Mapping[str, Mapping[str, Any]]] = None,
@@ -406,6 +409,7 @@ class BrukerLoader:
             override_subject_type=override_subject_type,
             override_subject_pose=override_subject_pose,
             flip_x=flip_x,
+            flatten_fg=flatten_fg,
             xyz_units=xyz_units,
             t_units=t_units,
             hook_args_by_name=hook_args_by_name,