Reference K-mer Frequencies

cfdna ref-kmers writes <prefix>.ref_kmers.zarr. Load reference k-mer frequency Zarr stores and extract frequency tables, dense arrays, sparse matrices, and reconstructed counts.

This is loader API documentation, not command-line help. See cfdna ref-kmers for command flags and output generation.

Quick Use

Python

import cfdnalab as cfl

ref_kmers = cfl.read_ref_kmers("sample.ref_kmers.zarr")

motifs = ref_kmers.motifs_metadata()
scaling = ref_kmers.row_scaling_factors()

frequencies = ref_kmers.sparse_frequencies_matrix(motifs="ACGT")
counts = ref_kmers.data_frame(motifs="ACGT")

R

library(cfdnalab)

ref_kmers <- read_ref_kmers("sample.ref_kmers.zarr")

motif_table <- motifs(ref_kmers)
scaling <- row_scaling_factors(ref_kmers)

frequencies <- sparse_frequencies_matrix(ref_kmers, motifs = "ACGT")
counts <- ref_kmer_data_frame(ref_kmers, motifs = "ACGT")

Notes

• Reference k-mer stores contain frequencies. Count helpers reconstruct counts with row_scaling_factor.
• Sparse stores stay sparse unless a dense helper explicitly receives an allow-densify option.

Function Index

Python

Symbol	Type	Summary
read_ref_kmers	function	Open a cfDNAlab reference k-mer frequency output directory.
RefKmerFrequencies	class	Common API for global, windowed, and grouped reference k-mer outputs.
GlobalRefKmerFrequencies	class	Reference k-mer frequencies for global output.
WindowedRefKmerFrequencies	class	Reference k-mer frequencies for fixed-size or BED-window output.
GroupedRefKmerFrequencies	class	Reference k-mer frequencies for grouped BED output.

Full details: Python API.

R

Topic	Summary
read_ref_kmers	Loads a <prefix>.ref_kmers.zarr output directory created with the cfdna ref-kmers CLI tool from the main cfDNAlab rust package.
storage_mode	Return the output storage mode.
row_mode	Return the output row mode.
motif_axis_kind	Return the reference k-mer motif-axis kind.
kmer_size	Return the reference k-mer size.
canonical	Return whether reference k-mers were canonicalized.
orientation	"both" averages the reference-forward sequence and its reverse complement.
all_motifs	For full k-mer output, this means every A/C/G/T k-mer for the requested k.
assign_by	Return the reference k-mer window assignment rule.
motifs	For ordinary end-motif stores, the motif column contains motif labels.
motif_idx	Look up a motif index.
window_metadata	Return window metadata.
group_metadata	Return group metadata.
group_idx	Look up a group index.
reference_contig_footprint	Return the reference contig footprint.
row_scaling_factors	Reference k-mer outputs store frequencies.
ref_kmer_data_frame	Sparse output stores only non-zero frequencies.
dense_frequencies_matrix	Sparse output stores only non-zero frequencies.
dense_frequencies_vector	Sparse output stores only non-zero frequencies.
sparse_frequencies_matrix	Sparse output is returned without building a zero-filled dense matrix.
schema_version	Return the cfDNAlab schema version.

Full details: R API.