version: "1.0.0" name: tangermeme description: Use for any task involving the tangermeme library — post-training analysis of genomic sequence-to-function (S2F) deep learning models. Triggers on predictions, DeepLIFT/SHAP attributions, marginalization/ablation/spacing of motifs, saturation mutagenesis (ISM), variant effect scoring, sequence design, seqlet calling, loading loci/FASTA/bigWig/MEME/VCF, or wrapping a PyTorch genomic model for these analyses. This is a router skill — read the relevant file under references/ for details and footguns before writing tangermeme code.

tangermeme

tangermeme answers the "what did my genomic model learn, and what do I do with it after training" question. It provides atomic sequence operations, batched prediction, attribution, perturbation experiments, and sequence design — all deliberately assumption-free (any PyTorch model, any alphabet, raw outputs returned rather than distances).

This skill is a router. Each topic below has a detailed reference file with the exact signatures and footguns. Read the relevant reference file before writing code — do not rely on memory of the API, because several functions have non-obvious defaults (silent wrong-output selection, variable-length returns, reproducibility traps).

Two cross-cutting concepts (read these first if unsure)

• [The `func=` plug-point](references/func-pattern.md) — ablate,

marginalize, space, variant_effect.*, and product.* (where it is the first positional argument) all accept func(model, X, args=, **kwargs). Swapping predict for deep_lift_shap turns a "predictions before/after" experiment into an "attributions before/after" one. Covers the additional_func_kwargs collision trap. This is what makes the library compose.

• [Wrapping models](references/model-wrapping.md) — tangermeme assumes

y = model(X) returns a single tensor with layout (batch, channels, length). Real multi-input / multi-output models must be wrapped first. Read this before attribution or design on any non-trivial model. Data preprocessing or output post-processing should be handled in custom wrappers rather than in custom functions.

Task → reference file

Quick orientation (the rest of the library)

These are well-covered by the official tutorials and are mostly single-call ops — no dedicated reference file, but here is where to look:

• tangermeme.predict.predict — batched, memory-efficient inference. Returns the

model's parameter dtype (override with dtype=) and upcasts each batch from X, so int8 sequences go straight in; multi-output models return a list. Satisfies the func= contract.

• tangermeme.ersatz — atomic sequence ops: insert, substitute,

multisubstitute, delete, shuffle, dinucleotide_shuffle (most motif-add ops substitute, preserving length; start/end confine shuffles to a region).

• tangermeme.utils — one_hot_encode (returns int8), characters,

random_one_hot, reverse_complement (single sequence), pwm_consensus, set_seed, gc_content, etc.

• tangermeme.pisa.pisa — per-position (PISA) attribution reusing the DLS hooks.

Footguns: some paths return tensors on the input device, not CPU; and it does not upcast X, so pass float — it is the one entry point int8 fails on.

• tangermeme.kmers — k-mer counts, batched k-mers, gapped k-mers.

(Motif scanning — FIMO/TOMTOM — is not in tangermeme; it lives in the external memelite / memesuite-lite package. annotate_seqlets wraps TOMTOM internally.)

Conventions used throughout

• Tensor layout: (batch, channels, length); channels = one-hot alphabet axis

(default ['A','C','G','T']).

• Variable naming: X/y observed, X_bar/y_bar designed/target,

y_hat predictions, X_attr attributions.

• Device defaults: predict, deep_lift_shap, pisa, design.*,

saturation_mutagenesis, product.* take device=None → CUDA if available else CPU; the model's original device + training mode are restored afterward.

• Perturbation functions return NamedTuples (PerturbationResult, etc.) — unpack

positionally or by attribute; isinstance(result, tuple) is True.