Working with sourmash

snipe is an alignment-free QC tool built on the edgemer .snipesig format. It can also move the K1 layer of a signature to and from a sourmash .sig, so a snipe sketch can drop into an existing k-mer workflow. snipe’s QC and native format are its own; this page covers that interoperability.

You will learn:

• How to export a .snipesig to a sourmash .sig with snipe export --format sourmash
• How to load a sourmash .sig into snipe, from the CLI and from Python (snipe.load_sourmash)
• Why a snipe-exported .sig carries the same md5 sourmash computes for the same content
• What survives the trip (K1 base k-mers) and what does not (the K2 edgemer layer)

The two formats

A .snipesig is edgemer-rich: it stores the K1 base k-mer, its K2 extension, abundance, and the complete signature header. That structure is what the sequencing-error and mutation metrics read.

A sourmash .sig is K1-only: a FracMinHash sketch of base k-mers with abundance, and nothing about the K2 extension. It is the format snipe reads and writes when a sketch needs to cross into a K1-only k-mer workflow.

Exporting to sourmash keeps the base k-mers and drops the edgemer structure. There is no round-trip back to edgemers from a K1-only file — anything that needs the K2 signal requires a full .snipesig.

Steps

1. Start from a .snipesig.

   The examples below build on phix.snipesig, a sketch of the phiX174 genome made at --scale 1 (every hash kept, so a tiny input stays unambiguous):

   snipe sketch --sample phix.fasta -o phix.snipesig --scale 1

   Its K1 checksum — the md5 that also survives a sourmash export — is reported by snipe info:

   snipe info phix.snipesig

   
   === Signature Information ===
   Version: 2.0.0
   Created: <at sketch time>
   K1 length: 51
   K2 length: 53
   K2 extension length: 2 bases
   Scale: 1
   Hash threshold: 18446744073709551615
   Hash space coverage: 100.000000%
   Theoretical sampling rate: 1/1 = 1.000000
   
   === Input Files ===
     1: phix.fasta
   
   === K-mer Statistics ===
   Unique K1 k-mers: 5336
   Total K1 abundance: 5336
   Average K1 abundance: 1.00
   Unique K2 k-mers: 5334
   Total K2 abundance: 5334
   Average K2 abundance: 1.00
   Unique k-mer edgemers: 5334
   Total edgemer abundance: 5334
   Average pair abundance: 1.00
   K1 checksum (md5): 85e65cc582d48cbf2fa1b2b7c9b552c7
   K2 checksum (md5): 91adce917f75e09fb1d6790e1619d446
   Failed K2 pairs: 2 (total abundance: 2)
   K2 extension success rate: 99.96%
   K1s processed for K2 extension: 5336
   
   === Processing Statistics ===
   Processing time: 0.02s
   Sequences processed: 1
   Total bases processed: 5386
   Average sequence length: 5386.0 bp
   K1 positions examined: 5336
   K1 hashes generated: 5336
   K1 hashes below threshold: 5336
   K1 hashes above threshold: 0
   Hash efficiency: 100.00%
   K1 with valid extensions: 5334
   K1 without extension space: 2
   

   Note K1 checksum (md5): 85e65cc582d48cbf2fa1b2b7c9b552c7. Hold on to that value; it is the identity that survives the export.

2. Export to a sourmash .sig.

   snipe export writes the K1 layer of the signature into a sourmash file. The format is auto-detected from the output extension, or you can name it explicitly with --format sourmash:

   snipe export --input phix.snipesig --format sourmash --output phix.sig

   The result is a K1-only .sig. snipe’s K1 layer uses the same canonical murmur3 hashing (seed 42, same scaled, same k-mer size) as sourmash, so the md5 snipe writes for the exported .sig is the same one sourmash computes for the same content. The 85e65cc5… from Step 1 is the md5 the exported .sig carries.

3. Load a sourmash .sig back into snipe.

   Hand snipe a sourmash .sig and it comes in as a K1-only signature, ready for the operations that only need base k-mers. From the CLI, any command that reads a signature (for example snipe info) auto-detects the sourmash format by content and extension:

   snipe info phix.sig

   From Python, snipe.load_sourmash reads it directly:

   import snipe
   
   sig = snipe.load_sourmash("phix.sig")
   print(sig.metadata["md5"])   # the same K1 md5, verified on load

   The md5 is checked in both directions: on export (snipe writing a .sig) and on load (snipe reading one). snipe.load also accepts a sourmash .sig/.sig.gz — it auto-detects and returns a K1-only signature; load_sourmash is the explicit call when you already know the input is a sourmash file.

4. Know what you can and cannot do with the loaded sketch.

   A K1-only signature supports the base-k-mer operations — set intersection, union, difference, containment-style comparisons. What it cannot do is drive the edgemer metrics: the sequencing-error and mutation rates in QC read the K2 extension, and that signal is not present in a K1-only file. For those, sketch from sequence into a full .snipesig instead of importing a .sig.

Exporting from Python

The same export is available on a Signature object. save() uses the file extension as the contract for the content — .sig / .sig.gz hold a sourmash signature, .snipesig holds a snipe signature:

import snipe

sig = snipe.load("phix.snipesig")
sig.save("phix.sig")                     # extension implies sourmash
sig.save("phix.sig", format="sourmash")  # explicit; must match the extension

An explicit format= that contradicts the extension is a FormatError — save() does not write content that mislabels the file. See the Python API reference for load_sourmash, load, and save.

What crosses the boundary

An export carries the K1 layer only; the K2 edgemer layer — and the error/mutation metrics that depend on it — stays in .snipesig and is not present in a .sig.

Recap

• snipe export --format sourmash writes the K1-only layer of a .snipesig into a sourmash .sig.
• snipe.load_sourmash (or plain snipe.load) reads a sourmash .sig back as a K1-only signature.
• The md5 matches sourmash’s for the same content — snipe’s K1 layer uses murmur3 with seed 42 over the canonical k-mer, the same as sourmash — and it is checked on both export and load.
• .snipesig is edgemer-rich; .sig is K1-only. The K2 edgemer layer, and the QC metrics built on it, does not survive the round-trip.

Next

• sourmash interoperability → — the K1 hashing compatibility in depth.
• Edgemers → — the K1/K2 pair that .snipesig keeps and .sig drops.
• export reference → — the full command surface.
• Python API reference → — load_sourmash, load, and save.