Tangermeme

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 — ablate, marginalize, space, variant_effect.*, and product.* 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 — 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; always returns float32; 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. Footgun: some paths return tensors on the input device, not CPU.
• 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.

Source: jmschrei/tangermeme — distributed by TomeVault.