Skip to content

CLAUDE.md

Latest commit

 

History

History
95 lines (67 loc) · 4.21 KB

CLAUDE.md

File metadata and controls

95 lines (67 loc) · 4.21 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

TPTBox is a Python package for processing BIDS-compliant medical imaging datasets (CT, MRI), with a focus on torso/spine analysis. It provides NIfTI I/O, reorientation/resampling, Points of Interest (POI) computation for vertebrae, 2D/3D snapshots, registration, and segmentation integrations (SPINEPS, nnU-Net).

Commands

Installation

pip install poetry
poetry install --with dev

Running Tests

# All tests
pytest unit_tests/

# Single test file
pytest unit_tests/test_nii.py

# Single test function
pytest unit_tests/test_nii.py::test_function_name

# With coverage
coverage run --source=TPTBox -m pytest unit_tests/

Linting & Formatting

# Lint (auto-fix where possible)
ruff check . --fix

# Format
ruff format .

# Both (mirrors pre-commit behavior)
pre-commit run --all-files

CI Linting (as run in GitHub Actions)

flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics

Architecture

Core Abstractions

NII (TPTBox/core/nii_wrapper.py) — Central class wrapping nibabel NIfTI images. Handles reorientation, resampling, affine transforms, boolean masking, and mathematical operations. Nearly all image operations in the package go through NII. Math operations live in nii_wrapper_math.py as mixins.

POI (TPTBox/core/poi.py) — Points of Interest container mapping (vertebra_id, subregion_id) → 3D coordinate. Coordinates can be in voxel or world space. POI computation strategies live in TPTBox/core/poi_fun/.

BIDS_FILE / BIDS_Global_info (TPTBox/core/bids_files.py) — BIDS dataset navigator. BIDS_Global_info scans a dataset root, while BIDS_FILE represents a single file parsed according to BIDS naming entities. Constants for BIDS key/value vocabulary are in bids_constants.py.

Location / Vertebra_Instance (TPTBox/core/vert_constants.py) — Enum-like constants for vertebral anatomy (vertebra IDs, subregion labels). Used as keys into POI objects throughout the codebase.

Package Layout

TPTBox/
├── core/           # NII, POI, BIDS parsing, numpy utilities, vertebra constants
│   └── poi_fun/    # POI calculation strategies and serialization
├── spine/          # Spine-specific: 2D snapshots, statistics (distances, angles)
├── segmentation/   # SPINEPS integration, nnU-Net inference, defacing
├── registration/   # ANTs rigid/deformable, DeepALI deep learning registration
├── mesh3D/         # 3D mesh generation and rendering from segmentations
├── stitching/      # Multi-station image stitching
└── logger/         # Logging infrastructure (Logger, Print_Logger, No_Logger)

Public API is re-exported from TPTBox/__init__.py. All major classes and utility functions are importable directly from TPTBox.

Key Relationships

  • NII + POI are used together constantly: compute POIs from segmentation NIIs, then use POIs to guide further processing.
  • BIDS_Global_info iterates subjects/sessions; each subject has a Subject_Container with BIDS_FILE entries; BIDS_FILE.get_nii() returns a NII.
  • vert_constants.py defines the shared label space (Location enum) that ties segmentation labels to POI keys to snapshot rendering.
  • External tool integrations (SPINEPS, nnU-Net, ANTs, DeepALI) are optional; their imports are guarded so the core works without them.

Test Layout

Tests live in unit_tests/ (not TPTBox/tests/). TPTBox/tests/ contains test utilities and sample data (CT/MRI NIfTIs) used by the unit tests. Some generated test files are very large (>20K LOC) — they are autogenerated and should not be edited by hand.

Code Style

  • Line length: 140 characters
  • Formatter: Ruff (Black-compatible, double quotes)
  • Target Python: 3.10+ syntax, but the package supports 3.9–3.14
  • Naming: Ruff N-rules are largely ignored — mixed-case class/method names are acceptable in this codebase (medical domain conventions)
  • Complexity: McCabe max=20; research code legitimately has deep branching
  • from __future__ import annotations is used widely for forward references