brkraw 0.3.11__tar.gz → 0.5.0__tar.gz

brkraw-0.5.0/.github/DISCUSSION_TEMPLATE/proposal.yml

@@ -0,0 +1,60 @@
+title: "Proposal: "
+labels: ["discussion"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for starting a discussion. For BrkRaw, most extensions should be
+        handled via addons (rules/specs/transforms/context_map) or plugins.
+  - type: input
+    id: summary
+    attributes:
+      label: Summary
+      description: One sentence overview of the proposal.
+      placeholder: "Add support for XYZ scan metadata mapping"
+    validations:
+      required: true
+  - type: textarea
+    id: context
+    attributes:
+      label: Context
+      description: Dataset type, Paravision version, and the workflow you are targeting.
+      placeholder: "PV 7.0.1, multi-echo sequence, needs custom NIfTI naming"
+    validations:
+      required: true
+  - type: dropdown
+    id: approach
+    attributes:
+      label: Preferred approach
+      description: Most changes should live outside core when possible.
+      options:
+        - Addon (rules/specs/transforms/context_map)
+        - Plugin (CLI entrypoint)
+        - Core change (Paravision compatibility only)
+        - Not sure yet
+    validations:
+      required: true
+  - type: textarea
+    id: details
+    attributes:
+      label: Details
+      description: Provide rules/specs/transforms/context_map ideas or plugin hooks.
+      placeholder: "Rules match on method=..., spec adds ..., transform normalizes ..."
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected output
+      description: What should the final behavior or artifact look like?
+      placeholder: "NIfTI names follow ..., metadata includes ..."
+    validations:
+      required: false
+  - type: textarea
+    id: references
+    attributes:
+      label: References
+      description: Links, sample data structure, or screenshots.
+      placeholder: "Link to sample dataset or docs"
+    validations:
+      required: false

brkraw-0.5.0/.github/DISCUSSION_TEMPLATE/question.yml

@@ -0,0 +1,40 @@
+title: "Question: "
+labels: ["question"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Ask anything about BrkRaw usage, addons, rules/specs/transforms, or
+        dataset compatibility.
+  - type: input
+    id: summary
+    attributes:
+      label: Question
+      description: Short question summary.
+      placeholder: "How do I map custom method parameters?"
+    validations:
+      required: true
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: BrkRaw version, Paravision version, and OS.
+      placeholder: "BrkRaw 0.5.0a3, PV 7.0.1, macOS 14"
+    validations:
+      required: false
+  - type: textarea
+    id: context
+    attributes:
+      label: Context
+      description: What you are trying to achieve and what you have tried.
+      placeholder: "Trying to ...; current output is ..."
+    validations:
+      required: true
+  - type: textarea
+    id: references
+    attributes:
+      label: References
+      description: Logs, error messages, or links.
+      placeholder: "Error stack trace or link to docs"
+    validations:
+      required: false

brkraw-0.5.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,42 @@
+---
+name: Bug report
+about: Report a reproducible problem.
+title: "[Bug] "
+labels: bug
+assignees: ""
+---
+
+## Summary
+
+Explain the bug and why it is a problem.
+
+## Steps to reproduce
+
+1.
+2.
+3.
+
+## Expected behavior
+
+Describe what should happen.
+
+## Actual behavior
+
+Describe what actually happens, including error output.
+
+## Environment
+
+- OS:
+- Python version:
+- brkraw version:
+- Installation method:
+
+## Checklist
+
+- [ ] I verified the issue on the latest main branch or release
+- [ ] I can reproduce this consistently
+- [ ] I included relevant logs or stack traces
+
+## Additional context
+
+Add any other context or screenshots here.

brkraw-0.5.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Questions / Discussions
+    url: https://github.com/BrkRaw/brkraw/discussions
+    about: Ask questions or start a discussion.

brkraw-0.5.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,34 @@
+---
+name: Feature request
+about: Suggest an idea or enhancement.
+title: "[Feature] "
+labels: enhancement
+assignees: ""
+---
+
+## Summary
+
+Explain the feature request and why it is needed.
+
+## Type of change
+
+- [ ] New feature
+- [ ] Enhancement
+- [ ] Docs update
+
+## Proposed solution
+
+Describe the preferred approach.
+
+## Alternatives considered
+
+Describe any alternatives or workarounds.
+
+## Checklist
+
+- [ ] I searched for similar issues and did not find a duplicate
+- [ ] I can describe a concrete use case
+
+## Additional context
+
+Add any other context or mockups here.

brkraw-0.5.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,31 @@
+## Summary
+
+Explain what this PR changes and why.
+
+## Type of change
+
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Refactor/maintenance
+- [ ] Docs update
+- [ ] CI/CD/workflow
+
+## Checklist
+
+- [ ] I ran tests locally (`pytest`) and they pass
+- [ ] I updated/add tests that cover this change
+- [ ] I updated documentation where relevant (README, docstrings)
+- [ ] I considered backward compatibility and breaking changes
+- [ ] I followed existing code style and conventions
+
+## How to test
+
+Provide steps or commands for reviewers to verify the change.
+
+```bash
+pytest -q
+```
+
+## Related issues
+
+Link to related issues or discussions (e.g., Fixes #123).

brkraw-0.5.0/.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.0/.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  pytest:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
+        pytest-version: ["7.4.*", "8.*"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: "pip"
+      - name: Install package
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install . pytest==${{ matrix.pytest-version }}
+      - name: Run tests
+        run: |
+          pytest -q

brkraw-0.5.0/.github/workflows/docs.yml

@@ -0,0 +1,32 @@
+name: Deploy Docs
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    if: ${{ github.repository == 'BrkRaw/brkraw' && (github.event_name != 'release' || github.event.release.prerelease == false) }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+      - name: Install MkDocs
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install mkdocs-material
+      - name: Build site
+        run: mkdocs build --strict --site-dir site
+      - name: Deploy to brkraw.github.io
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          personal_token: ${{ secrets.BRKRAW_GH_PAGES_TOKEN }}
+          external_repository: BrkRaw/brkraw.github.io
+          publish_branch: main
+          publish_dir: site

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

@@ -0,0 +1,97 @@
+name: Publish Package
+
+on:
+  workflow_dispatch:
+    inputs:
+      target:
+        description: "Publish target"
+        type: choice
+        options: [testpypi, pypi]
+        default: testpypi
+      tag:
+        description: "Tag to publish (optional, e.g. v1.2.3)"
+        required: false
+        type: string
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    if: ${{ github.repository == 'BrkRaw/brkraw' && (github.event_name != 'release' || github.event.release.prerelease == false) }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Resolve tag
+        id: tag
+        run: |
+          if [ "${{ github.event_name }}" = "workflow_dispatch" ] && [ -n "${{ inputs.tag }}" ]; then
+            echo "value=${{ inputs.tag }}" >> "$GITHUB_OUTPUT"
+          else
+            echo "value=${{ github.ref_name }}" >> "$GITHUB_OUTPUT"
+          fi
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ steps.tag.outputs.value }}
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+      - name: Install build tooling
+        run: |
+          python -m pip install --upgrade pip
+          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 scripts/verify_release_version.py
+      - name: Build dist
+        run: python -m build
+      - name: Check dist metadata
+        run: python -m twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist-artifacts
+          path: dist/
+
+  publish:
+    if: ${{ github.repository == 'BrkRaw/brkraw' && (github.event_name != 'release' || github.event.release.prerelease == false) }}
+    runs-on: ubuntu-latest
+    needs: [build]
+    permissions:
+      id-token: write
+      contents: write
+    environment:
+      name: ${{ inputs.target || 'pypi' }}
+      url: https://${{ (inputs.target == 'pypi' || github.event_name == 'release') && 'pypi.org' || 'test.pypi.org' }}/p/brkraw
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist-artifacts
+          path: dist/
+      - name: Resolve publish target
+        id: target
+        run: |
+          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
+            echo "target=${{ inputs.target }}" >> "$GITHUB_OUTPUT"
+          else
+            echo "target=pypi" >> "$GITHUB_OUTPUT"
+          fi
+      - name: Publish to TestPyPI
+        if: ${{ steps.target.outputs.target == 'testpypi' }}
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/
+          repository-url: https://test.pypi.org/legacy/
+      - name: Upload artifacts to GitHub Release
+        if: ${{ github.event_name == 'release' }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: gh release upload ${{ github.ref_name }} dist/* --clobber
+      - name: Publish to PyPI
+        if: ${{ steps.target.outputs.target == 'pypi' }}
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

brkraw-0.5.0/.github/workflows/release.yml

@@ -0,0 +1,129 @@
+name: Create Release
+
+on:
+  push:
+    tags:
+      - "*"
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Tag to release (e.g. v1.2.3)"
+        required: true
+        type: string
+
+permissions:
+  contents: write
+  discussions: write
+
+jobs:
+  release:
+    if: ${{ github.repository == 'BrkRaw/brkraw' }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Resolve tag
+        id: tag
+        run: |
+          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
+            echo "value=${{ inputs.tag }}" >> "$GITHUB_OUTPUT"
+          else
+            echo "value=${{ github.ref_name }}" >> "$GITHUB_OUTPUT"
+          fi
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ steps.tag.outputs.value }}
+      - name: Detect prerelease tag
+        id: prerelease
+        run: |
+          tag="${{ steps.tag.outputs.value }}"
+          if echo "$tag" | grep -Eq '(a|b|rc)[0-9]*$'; then
+            echo "value=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "value=false" >> "$GITHUB_OUTPUT"
+          fi
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ steps.tag.outputs.value }}
+          name: ${{ steps.tag.outputs.value }}
+          body_path: RELEASE_NOTES.md
+          prerelease: ${{ steps.prerelease.outputs.value }}
+      - name: Post release announcement
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITHUB_REPOSITORY: ${{ github.repository }}
+          TAG_NAME: ${{ steps.tag.outputs.value }}
+          RELEASE_URL: https://github.com/${{ github.repository }}/releases/tag/${{ steps.tag.outputs.value }}
+        run: |
+          python3 - <<'PY'
+          import json
+          import os
+          from pathlib import Path
+          from urllib import request
+
+          token = os.environ.get("GITHUB_TOKEN")
+          repo = os.environ["GITHUB_REPOSITORY"]
+          tag = os.environ["TAG_NAME"]
+          release_url = os.environ["RELEASE_URL"]
+          owner, name = repo.split("/")
+
+          notes = Path("RELEASE_NOTES.md").read_text(encoding="utf-8").strip()
+          title = f"Release {tag}"
+          body = f"[Release {tag}]({release_url})\n\n{notes}"
+
+          query = {
+              "query": """
+              query($owner: String!, $name: String!) {
+                repository(owner: $owner, name: $name) {
+                  id
+                  discussionCategories(first: 50) {
+                    nodes { id name }
+                  }
+                }
+              }
+              """,
+              "variables": {"owner": owner, "name": name},
+          }
+
+          req = request.Request("https://api.github.com/graphql", method="POST")
+          req.add_header("Authorization", f"Bearer {token}")
+          req.add_header("Content-Type", "application/json")
+          data = json.dumps(query).encode("utf-8")
+          with request.urlopen(req, data=data) as resp:
+              payload = json.loads(resp.read().decode("utf-8"))
+
+          repo_data = payload.get("data", {}).get("repository", {})
+          category_id = None
+          for node in repo_data.get("discussionCategories", {}).get("nodes", []):
+              if node.get("name") == "Announcements":
+                  category_id = node.get("id")
+                  break
+          if not category_id:
+              print("Announcements category not found; skipping discussion.")
+              raise SystemExit(0)
+
+          mutation = {
+              "query": """
+              mutation($repoId: ID!, $categoryId: ID!, $title: String!, $body: String!) {
+                createDiscussion(input: {repositoryId: $repoId, categoryId: $categoryId, title: $title, body: $body}) {
+                  discussion { id url }
+                }
+              }
+              """,
+              "variables": {
+                  "repoId": repo_data.get("id"),
+                  "categoryId": category_id,
+                  "title": title,
+                  "body": body,
+              },
+          }
+
+          req = request.Request("https://api.github.com/graphql", method="POST")
+          req.add_header("Authorization", f"Bearer {token}")
+          req.add_header("Content-Type", "application/json")
+          data = json.dumps(mutation).encode("utf-8")
+          with request.urlopen(req, data=data) as resp:
+              result = json.loads(resp.read().decode("utf-8"))
+          url = result.get("data", {}).get("createDiscussion", {}).get("discussion", {}).get("url")
+          if url:
+              print(f"Created discussion: {url}")
+          PY

brkraw-0.5.0/.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"^__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.0/.gitignore

@@ -0,0 +1,26 @@
+__pycache__/
+*.pyc
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.tox/
+.nox/
+.hypothesis/
+.coverage
+coverage.xml
+htmlcov/
+*.egg-info/
+build/
+dist/
+site/
+.DS_Store
+.venv
+.pycache
+.env
+.env.*
+.direnv/
+.envrc
+.idea/
+.vscode/
+*.lock
+.tmp

brkraw-0.5.0/.markdownlint.yaml

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

brkraw-0.5.0/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.0/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.0"
+date-released: "2026-01-13"