# CLAUDE.md

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

## Project Overview

GIFT-wrap (`giftwrap-sc` on PyPI) is a Python toolkit for processing GIFT-seq data — cell-level resolution genotyping using gap-fill probes from spatial transcriptomics platforms (10x Flex, VisiumHD, Visium).

## Commands

```bash
# Install with all extras
uv sync --all-extras

# Build package
uv build

# Build docs
uv run mkdocs build
uv run mkdocs serve  # live preview

# Run ad-hoc tests (no pytest framework — tests live in misc/)
uv run python misc/test.py
uv run python misc/test_visiumhd_barcode_parsing.py
```

## Architecture

The project is a **multi-step processing pipeline** where each step is a standalone CLI tool, plus an orchestrator that chains them together:

```
FASTQ files + probe definitions
  → Step 1 (giftwrap-count):          Parse reads, extract barcodes/UMIs, match probes
  → Step 2 (giftwrap-correct-umis):   UMI error correction via edit distance
  → Step 3 (giftwrap-correct-gapfill): Gapfill sequence error correction
  → Step 4 (giftwrap-collect):        Aggregate into CellxFeature sparse HDF5 matrices
  → Step 5 (giftwrap-summarize):      Statistics, PDF report generation
```

`giftwrap` (pipeline.py) is the all-in-one orchestrator that invokes the individual steps as subprocesses.

### Key Modules

| Module | Role |
|--------|------|
| `utils.py` | Core: technology format definitions, barcode correction, probe parsing, multiprocessing helpers |
| `pipeline.py` | CLI orchestrator — chains all 5 steps, handles subprocess management |
| `step1_count_gapfills.py` | FASTQ parsing, probe matching using prefix trie, barcode/UMI extraction |
| `step4_collect_counts.py` | Aggregates intermediates into `counts.N.h5` sparse matrices (multiple PCR dup thresholds) |
| `analysis/tools.py` | Downstream: genotype calling, cell/gapfill filtering, WTA intersection |
| `analysis/spatial.py` | Spatial integration via `spatialdata` |
| `misc_scripts.py` | Helper CLIs: generate R scripts, technology templates, probe conversion |

### Technology Abstraction (`utils.py`)

The `TechnologyFormatInfo` abstract base class defines how barcodes and UMIs are extracted from reads. Concrete implementations:
- `FlexFormatInfo` — 10x Chromium Flex v1
- `FlexV2FormatInfo` — 10x Chromium Flex v2
- `VisiumHDFormatInfo` — VisiumHD (2-part barcode with lookup tables)
- `VisiumFormatInfo` — Standard Visium

Barcode whitelist files are stored as resources in `src/giftwrap/resources/`.

### Output Format

Each pipeline run produces `counts.N.h5` files (HDF5 sparse matrices) for different PCR duplicate thresholds N. These are AnnData-compatible and can be loaded with `anndata` or `h5py`. The `analysis/` subpackage provides tools to load and analyze these outputs.

## Optional Dependency Extras

- `[analysis]` — scanpy, igraph, numba, leidenalg, rapidfuzz (for genotype calling/clustering)
- `[spatial]` — spatialdata, spatialdata-plot, squidpy (for spatial plotting)
- `[all]` — both of the above
- `[docs]` — mkdocs + plugins for documentation builds