kmer: k-mer spectrum of a sequence column

In vectra: Columnar Query Engine for Larger-than-RAM Data

k-mer spectrum of a sequence column

Description

Counts every fixed-length subsequence (k-mer) of a nucleotide string column, grouped by zero or more key columns. The result is one row per distinct (group, k-mer): the grouping columns, a kmer column, and an integer count. This is the set-wise counterpart to the per-row seq_expressions family — it materializes the whole spectrum, so it is a blocking step like summarise(), but the k-mer table is the only state held, not the input.

Usage

kmer(x, seq, k = 4, by = NULL, canonical = FALSE)

Arguments

x	A vectra_node object.
seq	The sequence column (unquoted). Defaults to seq, the column tbl_fasta() and tbl_fastq() produce.
k	k-mer length, an integer in 1:32 (default 4).
by	Grouping column(s): an unquoted name, c(col1, col2), or a character vector. NULL (default) counts one spectrum over the whole input.
canonical	If TRUE, collapse each k-mer with its reverse complement (default FALSE).

Details

Each k-mer is packed into 2 bits per base (A/C/G/T) and counted in a native hash table, so k is limited to 1:32. A window containing any non-ACGT base (N, an IUPAC ambiguity code, or a gap) is skipped, matching the convention of dedicated k-mer counters. With canonical = TRUE, a k-mer and its reverse complement are counted together under the lexicographically smaller of the two — the usual choice for strand-agnostic data.

Row order in the result is unspecified; pipe into arrange() for a stable order.

Value

A vectra_node with the grouping columns, a kmer column, and a count column.

See Also

seq_expressions, tbl_fasta()

Examples

f <- tempfile(fileext = ".vtr")
write_vtr(data.frame(id = c("a", "b"),
                     seq = c("ACGTACGT", "AAAAT"),
                     stringsAsFactors = FALSE), f)
tbl(f) |> kmer(seq, k = 3, by = id) |> arrange(id, kmer) |> collect()
unlink(f)

vectra documentation built on July 10, 2026, 5:08 p.m.