jmschrei/tangermeme/data

tangermeme

Post-training analysis of any PyTorch sequence model: batched prediction, attribution, perturbation experiments, sequence design, on raw outputs with no distance baked in. This file routes; the reference files hold the signatures, defaults and silent failures. Read the file for the task before writing code: several defaults select the wrong output, return a variable number of objects, or run zero iterations without a word.

Task to reference file

The one script, scripts/audit_deeplift.py (path relative to this skill's root), lists the operations in a model's forward pass that DeepLIFT has no rule for and measures summation-to-delta relative to the output scale; run it before trusting attributions of an unfamiliar architecture.

Conventions

• Layout (batch, channels, length), channels the one-hot alphabet, default

ACGT. X/y observed, X_bar/y_bar designed or target, y_hat predictions, X_attr attributions.

• predict(model, X, args=None, func=None, batch_size=32, dtype=None, device=None)

upcasts each batch from int8 and returns the model's dtype; a multi-output model returns a list. device=None means CUDA if available on every function that takes it; the model's device and train/eval mode are restored afterward. The first GPU call in a process pays 15 to 35 s of warm-up.

• Perturbation functions return NamedTuples (PerturbationResult(y_before, y_after),

SpaceResult, AttributionReferencesResult); unpack positionally or by attribute. extract_loci returns one to four objects depending on its arguments.

• PackedSequence (tangermeme.utils): four-letter sequences at 2 bits a

base, 16x smaller than int8 one-hot, unknown characters kept as runs. Every function that takes one-hot X takes one and returns what the one-hot gives; sequences come back packed (ersatz, references, designs), predictions and attributions as tensors. kmers, gapped_kmers, gc_content, chunk and unchunk live in tangermeme.kmers and tangermeme.utils; FIMO and TOMTOM scanning live in memelite.