voxelops 0.1.0__tar.gz

voxelops-0.1.0/.claude/settings.local.json

@@ -0,0 +1,18 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(tree:*)",
+      "Bash(uv lock:*)",
+      "Bash(make:*)",
+      "Bash(python -m py_compile:*)",
+      "Bash(python:*)",
+      "Bash(git add:*)",
+      "Bash(git commit:*)",
+      "Bash(git push)",
+      "Bash(git push:*)",
+      "Bash(.venv/bin/pip list:*)",
+      "Bash(git pull:*)",
+      "Bash(git stash:*)"
+    ]
+  }
+}

voxelops-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,47 @@
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+    - uses: actions/checkout@v3
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v4
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install ".[dev]"
+
+    - name: Lint with ruff
+      run: |
+        pip install ruff
+        ruff check .
+
+    - name: Test with pytest
+      run: |
+        pytest
+
+    - name: Upload coverage reports to Codecov
+      uses: codecov/codecov-action@671740ac38dd9b0130fbe1cec585b89eea48d3de
+      with:
+        token: ${{ secrets.CODECOV_TOKEN }}
+        slug: GalKepler/VoxelOps
+
+    - name: Build documentation
+      run: |
+        pip install ".[docs]"
+        make -C docs html

voxelops-0.1.0/.gitignore

@@ -0,0 +1,56 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Virtual environments
+venv/
+env/
+ENV/
+.venv
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+logs/
+
+# Development
+.mypy_cache/
+.ruff_cache/
+
+heuristic.py
+bids_filters.json
+qsirecon_spec.yaml

voxelops-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,18 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+  - repo: https://github.com/psf/black
+    rev: 24.3.0
+    hooks:
+      - id: black
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.3.4
+    hooks:
+      - id: ruff
+        args: [--fix, --exit-non-zero-on-fix]
+      - id: ruff-format

voxelops-0.1.0/.python-version

@@ -0,0 +1 @@
+3.11

voxelops-0.1.0/.readthedocs.yaml

@@ -0,0 +1,20 @@
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+
+sphinx:
+  configuration: docs/conf.py
+  
+python:
+  install:
+    - requirements: docs/requirements.txt
+    - method: pip
+      path: .
+
+formats:
+  - htmlzip
+  - pdf
+  - epub

voxelops-0.1.0/.uvignore

@@ -0,0 +1,13 @@
+# uv ignore file - exclude directories from uv operations
+.git/
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.coverage
+htmlcov/
+dist/
+build/
+*.egg-info/
+.vscode/
+.idea/

voxelops-0.1.0/ARCHITECTURE.md

@@ -0,0 +1,217 @@
+# VoxelOps Architecture
+
+## Design Principles
+
+1. **Simplicity** -- Functions, not classes. Dicts, not complex objects.
+2. **Clarity** -- Typed dataclass schemas for every input, output, and configuration.
+3. **Reproducibility** -- The exact Docker command is stored in every execution record.
+4. **Database-Friendly** -- Results are plain dicts, trivial to persist anywhere.
+5. **Extensibility** -- New procedures follow the same pattern, easy to add.
+
+## Directory Structure
+
+```
+VoxelOps/
+    src/voxelops/
+        __init__.py                  # Package exports, version
+        exceptions.py                # Exception hierarchy
+        runners/
+            __init__.py              # Runner exports
+            _base.py                 # Shared: run_docker, validate_input_dir, validate_participant
+            heudiconv.py             # DICOM -> BIDS
+            qsiprep.py               # Diffusion preprocessing
+            qsirecon.py              # Diffusion reconstruction
+            qsiparc.py               # Parcellation (via parcellate, not Docker)
+        schemas/
+            __init__.py              # Schema exports
+            heudiconv.py             # HeudiconvInputs / Outputs / Defaults
+            qsiprep.py               # QSIPrepInputs / Outputs / Defaults
+            qsirecon.py              # QSIReconInputs / Outputs / Defaults
+            qsiparc.py               # QSIParcInputs / Outputs / Defaults
+        utils/
+            __init__.py
+            bids.py                  # BIDS post-processing (IntendedFor, fmap cleanup)
+    examples/
+        dicom_to_bids.py             # HeudiConv example
+        qsiprep.py                   # QSIPrep example
+        qsirecon.py                  # QSIRecon example
+        qsiparc.py                   # QSIParc example
+    notebooks/
+        01_heudiconv_basics.ipynb    # Step-by-step tutorials
+        02_qsiprep_basics.ipynb
+        03_qsirecon_basics.ipynb
+        04_qsiparc_basics.ipynb
+        05_full_pipeline.ipynb
+    tests/                           # Pytest test suite
+    docs/                            # Sphinx documentation source
+    pyproject.toml                   # Build config, dependencies
+```
+
+## Code Organization
+
+### Runners (`runners/`)
+
+Each runner is a function that:
+
+1. Accepts an `Inputs` dataclass and optional `Defaults` config
+2. Validates inputs (directory exists, participant found)
+3. Builds a Docker command (or calls `parcellate` directly for QSIParc)
+4. Executes via `run_docker()` (or `run_parcellations()`)
+5. Returns an execution record dict with expected outputs
+
+```python
+def run_procedure(
+    inputs: ProcedureInputs,
+    config: Optional[ProcedureDefaults] = None,
+    **overrides,
+) -> Dict[str, Any]:
+    config = config or ProcedureDefaults()
+
+    for key, value in overrides.items():
+        if hasattr(config, key):
+            setattr(config, key, value)
+
+    validate_input_dir(inputs.input_dir)
+    validate_participant(inputs.input_dir, inputs.participant)
+
+    output_dir = inputs.output_dir or default_path
+    expected_outputs = ProcedureOutputs.from_inputs(inputs, output_dir)
+
+    cmd = ["docker", "run", "--rm", ...]
+    result = run_docker(cmd, "tool_name", inputs.participant, log_dir)
+
+    result["inputs"] = inputs
+    result["config"] = config
+    result["expected_outputs"] = expected_outputs
+    return result
+```
+
+### Schemas (`schemas/`)
+
+Each procedure defines three dataclasses:
+
+**Inputs** -- required parameters with `__post_init__` path coercion:
+
+```python
+@dataclass
+class ProcedureInputs:
+    input_dir: Path
+    participant: str
+    output_dir: Optional[Path] = None
+
+    def __post_init__(self):
+        self.input_dir = Path(self.input_dir)
+        if self.output_dir:
+            self.output_dir = Path(self.output_dir)
+```
+
+**Outputs** -- generated from inputs via `from_inputs()` classmethod:
+
+```python
+@dataclass
+class ProcedureOutputs:
+    output_dir: Path
+    participant_dir: Path
+
+    @classmethod
+    def from_inputs(cls, inputs, output_dir):
+        return cls(
+            output_dir=output_dir,
+            participant_dir=output_dir / f"sub-{inputs.participant}",
+        )
+```
+
+**Defaults** -- configuration with brain bank standard values:
+
+```python
+@dataclass
+class ProcedureDefaults:
+    nprocs: int = 8
+    mem_mb: int = 16000
+    docker_image: str = "tool/image:latest"
+```
+
+### Base Utilities (`runners/_base.py`)
+
+Three shared functions:
+
+- `validate_input_dir(path, dir_type)` -- raises `InputValidationError` if missing or not a directory
+- `validate_participant(input_dir, participant, prefix)` -- raises `InputValidationError` if participant subdir not found
+- `run_docker(cmd, tool_name, participant, log_dir, capture_output)` -- executes subprocess, builds execution record, writes JSON log, raises `ProcedureExecutionError` on failure
+
+### BIDS Utilities (`utils/bids.py`)
+
+Post-processing for HeudiConv output:
+
+- `post_process_heudiconv_output()` -- orchestrates three steps after DICOM conversion
+- `verify_fmap_epi_files()` -- checks fieldmap NIfTI + JSON exist
+- `add_intended_for_to_fmaps()` -- writes `IntendedFor` into fmap JSON sidecars
+- `remove_bval_bvec_from_fmaps()` -- hides spurious `.bvec`/`.bval` files from fmap dirs
+
+### Exceptions (`exceptions.py`)
+
+```
+YALabProcedureError              (base, aliased as ProcedureError)
+    ProcedureExecutionError
+        DockerExecutionError
+    ProcedureConfigurationError
+        FreeSurferLicenseError
+    InputValidationError
+    OutputCollectionError
+    BIDSValidationError
+    DependencyError
+```
+
+## Execution Flow
+
+```
+User calls run_procedure(inputs, config)
+    -> Validate inputs
+    -> Generate expected outputs
+    -> Build Docker command
+    -> run_docker() executes subprocess
+    -> Build execution record dict
+    -> Attach inputs, config, expected_outputs
+    -> Return dict
+```
+
+## Execution Record Structure
+
+```python
+{
+    "tool": str,
+    "participant": str,
+    "command": List[str],
+    "exit_code": int,
+    "start_time": str,              # ISO format
+    "end_time": str,
+    "duration_seconds": float,
+    "duration_human": str,
+    "success": bool,
+    "log_file": str,                # Path to JSON log (if log_dir provided)
+    "stdout": str,                  # If capture_output=True
+    "stderr": str,
+    "error": str,                   # If failed
+    "inputs": ProcedureInputs,
+    "config": ProcedureDefaults,
+    "expected_outputs": ProcedureOutputs,
+}
+```
+
+## Adding a New Procedure
+
+1. **Schema** -- create `schemas/your_procedure.py` with `Inputs`, `Outputs`, `Defaults`
+2. **Runner** -- create `runners/your_procedure.py` with `run_your_procedure()`
+3. **Exports** -- add to `schemas/__init__.py`, `runners/__init__.py`, and `__init__.py`
+4. **Tests** -- create `tests/test_runners_your_procedure.py` and `tests/test_schemas_your_procedure.py`
+5. **Example** -- add `examples/your_procedure.py`
+
+## Key Design Decisions
+
+| Decision | Rationale |
+|----------|-----------|
+| Dataclasses for schemas | Type hints for IDE support, automatic `__init__` and `__repr__` |
+| Functions, not classes | Simpler, no state, no inheritance, easier to test |
+| Command stored in record | Perfect reproducibility -- just rerun the command |
+| Minimal dependencies | Faster installs, fewer breaking changes, no Nipype lock-in |
+| No output validation | Docker container handles that; keep this package simple |

voxelops-0.1.0/LICENSE

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

voxelops-0.1.0/Makefile

@@ -0,0 +1,130 @@
+.PHONY: help install install-dev install-all test test-cov format lint clean lock upgrade venv
+
+help:  ## Show this help message
+	@echo "Usage: make [target]"
+	@echo ""
+	@echo "Targets:"
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-15s\033[0m %s\n", $$1, $$2}'
+
+venv:  ## Create virtual environment
+	uv venv
+	@echo ""
+	@echo "Virtual environment created. Activate with:"
+	@echo "  source .venv/bin/activate  # macOS/Linux"
+	@echo "  .venv\\Scripts\\activate     # Windows"
+
+install:  ## Install package in editable mode
+	uv pip install -e .
+
+install-dev:  ## Install package with dev dependencies
+	uv pip install -e ".[dev]"
+
+install-all:  ## Install package with all optional dependencies
+	uv pip install -e ".[dev,notebooks,config]"
+
+test:  ## Run tests
+	pytest
+
+test-cov:  ## Run tests with coverage report
+	pytest --cov=yalab_procedures --cov-report=term-missing --cov-report=html
+	@echo ""
+	@echo "Coverage report generated in htmlcov/index.html"
+
+format:  ## Format code with black
+	black src tests examples
+
+format-check:  ## Check code formatting without changes
+	black --check src tests examples
+
+lint:  ## Lint code with ruff
+	ruff check src tests examples
+
+lint-fix:  ## Lint and auto-fix issues
+	ruff check src tests examples --fix
+
+qa: format-check lint test  ## Run all quality checks
+
+lock:  ## Update lock file
+	uv lock
+
+upgrade:  ## Upgrade all dependencies
+	uv lock --upgrade
+	@echo ""
+	@echo "Dependencies upgraded. Run 'make install-dev' to install updates."
+
+sync:  ## Sync environment with lock file
+	uv pip sync
+
+clean:  ## Remove build artifacts and cache files
+	rm -rf build/
+	rm -rf dist/
+	rm -rf *.egg-info
+	rm -rf .pytest_cache
+	rm -rf .coverage
+	rm -rf htmlcov/
+	find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
+	find . -type f -name "*.pyc" -delete
+
+clean-venv:  ## Remove virtual environment
+	rm -rf .venv
+
+notebook:  ## Start Jupyter notebook server
+	jupyter notebook notebooks/
+
+lab:  ## Start Jupyter lab server
+	jupyter lab notebooks/
+
+docs:  ## Open main documentation files
+	@echo "Documentation files:"
+	@echo "  README.md - Main documentation"
+	@echo "  DEVELOPMENT.md - Development guide"
+	@echo "  UV_QUICKSTART.md - Quick start with uv"
+	@echo "  ARCHITECTURE.md - Architecture documentation"
+	@echo "  notebooks/README.md - Notebook examples"
+
+setup: venv install-dev  ## Complete setup: create venv and install dev dependencies
+	@echo ""
+	@echo "Setup complete! Don't forget to activate the virtual environment:"
+	@echo "  source .venv/bin/activate"
+
+# Development workflow targets
+dev-start:  ## Start development session (activate venv, show status)
+	@echo "Development environment ready!"
+	@echo ""
+	@echo "Quick commands:"
+	@echo "  make test      - Run tests"
+	@echo "  make format    - Format code"
+	@echo "  make lint      - Lint code"
+	@echo "  make qa        - Run all quality checks"
+	@echo ""
+
+# CI targets
+ci: format-check lint test  ## Run CI checks (format, lint, test)
+	@echo ""
+	@echo "✅ All CI checks passed!"
+
+# Build targets
+build:  ## Build distribution packages
+	uv build
+
+publish-test:  ## Publish to Test PyPI
+	uv publish --publish-url https://test.pypi.org/legacy/
+
+publish:  ## Publish to PyPI
+	uv publish
+
+# Info targets
+info:  ## Show package and environment info
+	@echo "Package: yalab-procedures"
+	@echo "Version: $$(grep '^version = ' pyproject.toml | cut -d'"' -f2)"
+	@echo ""
+	@echo "Python: $$(python --version 2>&1)"
+	@echo "uv: $$(uv --version 2>&1)"
+	@echo ""
+	@echo "Virtual environment:"
+	@if [ -d .venv ]; then \
+		echo "  Status: ✅ Exists"; \
+		echo "  Path: $$(pwd)/.venv"; \
+	else \
+		echo "  Status: ❌ Not created (run 'make venv')"; \
+	fi