Sketch a genome

Turn a FASTA file into a native .snipesig — snipe’s edgemer signature — and confirm it holds what you expect.

You will learn

• The difference between --genome (a reference, with coordinates) and --sample (reads).
• How to pick a --scale, and what k1 / k2 mean by default.
• When to add --keep-acgt.
• How to inspect the result with snipe info.

Genome vs. sample: pick the right flag

snipe sketch writes exactly one signature, but there are two ways to feed it depending on what your FASTA is:

• --genome takes exactly one reference FASTA and produces a reference-with-coordinates signature — per-chromosome coordinate data is kept so downstream QC can reason about coverage across the reference.
• --sample takes sequencing reads (FASTA/FASTQ, .gz fine, repeatable for multiple files) and produces a plain sample signature.

Both build the same underlying edgemers — K1 base k-mers paired with their K2 extensions. The distinction is the role the signature plays later: a reference is what you measure a sample against in snipe qc.

Note

--genome accepts a single reference FASTA by design — there is no “male/female reference” concept. If a chromosome (e.g. Y) lives in a separate file, handle it at QC time with snipe qc --ychr, not with multiple --genome inputs.

Steps

1. Sketch a reference genome.

   Point --genome at one FASTA and choose an output path (canonically *.snipesig, Parquet-encoded):

   snipe sketch --genome ecoli_ref.fasta -o ecoli_ref.snipesig

   This uses the defaults: k1 = 51 (the base k-mer), k2 = 53 (the extended k-mer, so the edgemer extension length is 2), and --scale 10000. The result is a reference-with-coordinates signature ready to serve as the reference in QC.

2. Or sketch reads as a sample.

   For sequencing reads, use --sample. Repeat the flag to fold several files into one signature:

   snipe sketch --sample reads_R1.fastq.gz --sample reads_R2.fastq.gz -o sample.snipesig

3. Choose a --scale (optional).

   --scale is the FracMinHash sampling factor: at the default 10000, snipe keeps roughly 1 in 10,000 of the hash space, which is plenty for whole genomes and reads while staying small. A smaller scale keeps more k-mers (finer resolution, larger signature); --scale 1 keeps everything. Signatures must share a scale to be compared. See FracMinHash & scale for the full picture.

   For a tiny genome like phiX174 (5,386 bp), the default scale would sample away almost everything — so this example uses --scale 1 to keep every k-mer:

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

   Tip

   Use --scale 1 only for tiny synthetic or single-genome inputs where you want every k-mer. At production scale, stay near the default.

4. Keep k-mer sequences with --keep-acgt (optional).

   By default a .snipesig stores hashes, not the underlying ACGT strings. Add --keep-acgt when you need the actual k-mer sequences retained in the output (at the cost of a larger file):

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

5. Inspect the signature with snipe info.

   snipe info prints the header and k-mer statistics so you can confirm the sketch matches your input:

   snipe info phix.snipesig

   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
   

   Read it top to bottom: K1 length: 51 / K2 length: 53 and Scale: 1 echo the parameters you passed; Unique K1 k-mers: 5336 and Unique k-mer edgemers: 5334 report what was captured; and Failed K2 pairs: 2 counts the K1 windows too close to the end of the sequence to form a K2 extension (a 99.96% extension success rate here). The K1/K2 pairing recorded here is what later lets snipe qc separate sequencing errors from true mutations — see QC metrics.

The Python equivalent

Everything above is available from the snipe package. sketch() returns a Signature; call .save() to write the .snipesig:

import snipe

# Sample reads -> one signature
sig = snipe.sketch(["phix.fasta"], scale=1)   # k1/k2 default to 51/53
sig.save("phix.snipesig")

# Keep the ACGT sequences
sig = snipe.sketch(["phix.fasta"], scale=1, keep_acgt=True)

For a reference genome, the entry point is sketch_reference(), which produces the reference-typed signature:

ref = snipe.sketch_reference("ecoli_ref.fasta")   # scale defaults to 10000
ref.save("ecoli_ref.snipesig")

Recap

You sketched a FASTA into a native .snipesig: --genome for a reference (with coordinates), --sample for reads. You chose a --scale (default 10000, --scale 1 for tiny inputs), relied on the default k1 = 51 / k2 = 53 edgemer, optionally kept ACGT sequences with --keep-acgt, and verified the sketch with snipe info.

Next

• QC a sequencing run → — measure a sample against the reference you just built.
• snipe sketch reference → — every flag, type, and default.
• FracMinHash & scale → — how the hash space is sampled.
• Python API → — sketch, sketch_reference, and the Signature object.