Signature

Unified Python wrapper over both signature representations.

Properties

abundances

K1 abundances as a read-only uint64 numpy array (aligned with hashes). Cached identically to hashes — a read-only view of the cached buffer each access, no re-sort.

edgemer_hashes

K2 hash of each successfully-extended edgemer as a uint64 numpy array. Failed-K2 edgemers are excluded, so the length matches edgemers_count.

edgemer_stats

Edgemer-level summary {singletons, polytons, failed_k2}. The singleton/polyton split mirrors qc.rs’s reported total_singletons (K1 abundance == 1 vs > 1), i.e. K1Signature::count_singletons/ count_polytons. failed_k2 matches failed_k2_count.

edgemer_strings

Reconstructed edgemer strings (k1_sequence + k2_extension) for each successfully-extended edgemer. Errors if sequences were not retained (re-sketch with keep_acgt=True).

edgemers_count

Number of unique successfully-extended edgemers (edgemer backing only).

failed_k2_count

Number of edgemers whose K2 extension failed (edgemer backing only).

hashes

K1 hashes as a sorted, read-only uint64 numpy array (aligned with abundances). The data is materialized and sorted once, then cached; each access returns a read-only view of that cached buffer — no per-call copy or re-sort, and the view cannot be re-armed for writing.

is_edgemer

True when the signature carries edgemer (K2) data.

k

K-mer size (alias of k1).

k1

K1 (base k-mer) size.

k2

K2 (extended k-mer) size. K1-only signatures have no K2, so k2 == k1.

md5

Sourmash-interoperable MD5 checksum of the sorted unique K1 hashes — the single canonical signature identity used across snipe (the Parquet footer, info, and this getter all compute the same value). Abundance-independent and stable across a save/reload. Computed once and cached, so repeated .md5/__eq__/__hash__ lookups are O(1).

metadata

Lightweight metadata dictionary common to both backings.

name

Set the signature name (sig.name = "foo").

scale

FracMinHash scale factor (kept in the signature metadata).

size

Number of unique K1 hashes — the primary, K1-first size metric. size is always the K1-hash count and is defined for both backings (it is never an edgemer/K2 count); equivalent to len(sig).

Methods

clone()

Signature.clone(self, /)

An independent hard copy of this signature — a full deep clone with its own data, safe to mutate (e.g. via in-place set-ops) without affecting the original. Equivalent to copy.deepcopy(sig). There is deliberately no shared/“soft” copy: signatures are mutable, Rust-backed values, so sharing state would let a mutation of one silently affect the other.

containment()

Signature.containment(self, /, other)

Containment of this signature in other: |A ∩ B| / |A|. An empty self is defined as 0.0.

difference()

Signature.difference(self, /, other, inplace=False)

Difference (-). Filter op: the result follows the LEFT operand’s backing.

downsample()

Signature.downsample(self, /, scale)

Downsample to a coarser scale, returning a new signature.

edgemers()

Signature.edgemers(self, /, as_dataframe=False)

Per-edgemer records with columns (k1_hash, k1_sequence, k2_hash, k2_extension, abundance), one row per successfully-extended edgemer. Returns a list of dicts, or a pandas DataFrame when as_dataframe=True.

filter()

Signature.filter(self, /, min_abundance=None, max_abundance=None)

Filter by K1 canonical abundance, returning a new signature of the same backing.

Keeps only entries whose K1 abundance lies in the inclusive range [min_abundance, max_abundance]. Both bounds are optional and the basis is the K1 canonical abundance for BOTH backings (edgemer and K1-only) — for an edgemer signature this filters on the K1 abundance, not the K2 (edgemer) abundance.

With no arguments this is an exact identity copy: nothing is dropped. The filter is non-lossy on the K1 basis — an edgemer signature keeps every edgemer row of a passing K1, including failed-K2 (orphan) K1s, which stay as failed-K2 edgemers rather than being silently removed.

from_arrays()

Signature.from_arrays(hashes, abundances, k=51, scale=1000, k2=None, name=None)

Build a K1-only Signature directly from parallel numpy uint64 arrays of hashes and abundances. Thin composability primitive: no sketching, no file I/O. Duplicate hashes are merged by summing (saturating) their abundances, then the arrays are sorted so the K1-only backing’s strictly-sorted-unique invariant holds. Always returns a K1-only signature (is_edgemer == False).

intersect()

Signature.intersect(self, /, other, inplace=False)

Intersect (&). Filter op: the result follows the LEFT operand’s backing. Returns a new signature, or mutates in place and returns None when inplace=True.

jaccard()

Signature.jaccard(self, /, other)

Jaccard similarity over the two K1-hash sets: |A ∩ B| / |A ∪ B|. Two empty signatures are defined as 0.0.

qc()

Signature.qc(self, /, reference=None, amplicon=None, ychr=None, advanced=False, hidden=False)

Compute QC metrics, returning a pandas Series indexed by metric name.

Auto-dispatches by backing: an edgemer signature runs the full QC engine (process_sample_with_base_metrics); a K1-only signature runs the reduced engine (process_snipe_sample_with_base_metrics), where edgemer-derived metrics read the engine’s not-computable sentinel 0.0.

The Series index covers every numeric metric the visibility tier allows (default; advanced=True adds verbose metrics; hidden=True adds developer-only metrics), in METRIC_REGISTRY order. reference, amplicon, and ychr are themselves Signature objects; with no reference, reference-comparative metrics read 0.

Metrics whose names end in _(%) are returned as fractions in [0, 1] (matching the TSV values 1:1), not as percentages.

reset_abundance()

Signature.reset_abundance(self, /, value=1)

A K1-only copy of this signature with every abundance reset to value (default 1). Always K1-only (is_edgemer == False).

save()

Signature.save(self, /, path, format=None)

Save signature to file - directly wraps Rust API.

Accepts str | os.PathLike. The file EXTENSION is the contract for the file’s content: .snipesig holds ONLY a snipe signature (Parquet); .sig / .sig.gz hold ONLY a sourmash signature. .zip (sourmash, not yet writable), .tsv, and any unrecognized/missing extension -> FormatError. An explicit format= (“snipesig”/“parquet” or “sourmash”) may only be passed consistently with the extension; a format= that contradicts the extension is a FormatError — save() never writes content that mislabels the file.

sum()

Signature.sum(self, /, other, inplace=False)

Sum (+). Additive op: both operands must share the same backing.

to_k1only()

Signature.to_k1only(self, /)

A K1-only view of this signature (edgemer backings are converted to their K1-only form; K1-only backings are copied).

to_presence()

Signature.to_presence(self, /)

A K1-only presence copy: every abundance set to 1. Equivalent to reset_abundance(1).

to_sourmash()

Signature.to_sourmash(self, /, path)

Save to Sourmash format (convenience method). Accepts str | os.PathLike.

union()

Signature.union(self, /, other, inplace=False)

Union (|). Additive op: both operands must share the same backing.