Skip to content

CLAUDE.md

Latest commit

 

History

History
108 lines (75 loc) · 5.58 KB

CLAUDE.md

File metadata and controls

108 lines (75 loc) · 5.58 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.

Three files carry a # Generated by CodiumAI marker on line 1 — test_poi_autogen.py, test_nii_wrapper_auto.py and test_poi_global.py. There is no generator script in the repo; they were committed once and have been hand-edited since, so treat them as ordinary (if oddly styled) test files.

House style for new tests, as followed by every file in unit_tests/: unittest.TestCase classes (no pytest fixtures, no conftest.py), with self.subTest(...) for table-driven cases, tempfile.TemporaryDirectory() for scratch files, and optional heavy dependencies guarded with importlib.util.find_spec plus @unittest.skipUnless (see test_mesh3D.py). New tests must stay Python 3.9-compatible — CI runs a 3.9 leg, so no itertools.pairwise (use TPTBox.core.compat.pairwise), no zip(..., strict=...) (use compat.zip_strict) and no match statements.

[tool.coverage.report].omit in pyproject.toml is curated: it lists only code a unit test cannot legitimately reach (vendored nnU-Net internals, nnU-Net training drivers, the dead vendored deepali engine, the NAKO dataset pipelines, nipy-dependent scripts). Code that is merely awkward to test does not belong there.

Sub-package notes

  • TPTBox/registration/ – see CLAUDE_reg.md for a registration-focused overview: the class map, coordinate-system invariants (RAS vs LPS, transform directions), the design of Deepali_Point_Registration and Template_Registration2, and a Deepali-vs-SimpleITK benchmark on CPU.

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