Sequence Analysis & K-mers

count_kmers(
    _::Type{Kmers.Kmer{A<:BioSequences.DNAAlphabet, K}},
    sequence::BioSequences.LongSequence
) -> Any

Count the frequency of each k-mer in a DNA sequence.

Arguments

• ::Type{Kmers.Kmer{A,K}}: K-mer type with alphabet A and length K
• sequence::BioSequences.LongSequence: Input DNA sequence to analyze

Returns

A sorted dictionary mapping each k-mer to its frequency count in the sequence.

Type Parameters

• A <: BioSequences.DNAAlphabet: DNA alphabet type
• K: Length of k-mers

count_kmers(
    _::Type{Kmers.Kmer{A<:BioSequences.RNAAlphabet, K}},
    sequence::BioSequences.LongSequence
) -> Any

Count the frequency of each k-mer in an RNA sequence.

Arguments

• Kmer: Type parameter specifying the k-mer length K and RNA alphabet
• sequence: Input RNA sequence to analyze

Returns

• Dict{Kmers.Kmer, Int}: Sorted dictionary mapping each k-mer to its frequency count

count_kmers(
    _::Type{Kmers.Kmer{A<:BioSequences.AminoAcidAlphabet, K}},
    sequence::BioSequences.LongSequence
) -> OrderedCollections.OrderedDict{K, Int64} where K<:(Kmers.Kmer{BioSequences.AminoAcidAlphabet, _A, _B} where {_B, _A})

Count the frequency of amino acid k-mers in a biological sequence.

Arguments

• Kmers.Kmer{A,K}: Type parameter specifying amino acid alphabet (A) and k-mer length (K)
• sequence: Input biological sequence to analyze

Returns

A sorted dictionary mapping each k-mer to its frequency count in the sequence.

count_kmers(
    _::Type{KMER_TYPE},
    record::Union{FASTX.FASTA.Record, FASTX.FASTQ.Record}
) -> Any

Count the frequency of amino acid k-mers in a biological sequence.

Arguments

• Kmers.Kmer{A,K}: Type parameter specifying amino acid alphabet (A) and k-mer length (K)
• sequence: Input biological sequence to analyze

Returns

A sorted dictionary mapping each k-mer to its frequency count in the sequence.

count_kmers(
    _::Type{KMER_TYPE},
    records::AbstractArray{T<:Union{FASTX.FASTA.Record, FASTX.FASTQ.Record}, 1}
) -> Any

Count k-mers across multiple sequence records and return a sorted frequency table.

Arguments

• KMER_TYPE: Type parameter specifying the k-mer length (e.g., DNAKmer{3} for 3-mers)
• records: Vector of FASTA/FASTQ records to analyze

Returns

• Dict{KMER_TYPE, Int}: Sorted dictionary mapping k-mers to their frequencies

count_kmers(
    _::Type{KMER_TYPE},
    sequences::Union{FASTX.FASTA.Reader, FASTX.FASTQ.Reader}
) -> Any

Counts k-mer occurrences in biological sequences from a FASTA/FASTQ reader.

Arguments

• KMER_TYPE: Type parameter specifying the k-mer length and encoding (e.g., DNAKmer{4} for 4-mers)
• sequences: A FASTA or FASTQ reader containing the biological sequences to analyze

Returns

A dictionary mapping k-mers to their counts in the input sequences

count_kmers(
    _::Type{KMER_TYPE},
    fastx_files::AbstractArray{T<:AbstractString, 1}
) -> Any

Count k-mers across multiple FASTA/FASTQ files and merge the results.

Arguments

• KMER_TYPE: Type parameter specifying the k-mer length (e.g., DNAKmer{4} for 4-mers)
• fastx_files: Vector of paths to FASTA/FASTQ files

Returns

• Dict{KMER_TYPE, Int}: Dictionary mapping k-mers to their total counts across all files

count_kmers(
    _::Type{KMER_TYPE},
    fastx_file::AbstractString
) -> Any

Count k-mers in a FASTA/FASTQ file and return their frequencies.

Arguments

• KMER_TYPE: Type parameter specifying the k-mer type (e.g., DNAKmer{K})
• fastx_file: Path to input FASTA/FASTQ file

Returns

• Dict{KMER_TYPE, Int}: Dictionary mapping each k-mer to its frequency

count_canonical_kmers(_::Type{KMER_TYPE}, sequences) -> Any

Count canonical k-mers in biological sequences. A canonical k-mer is the lexicographically smaller of a DNA sequence and its reverse complement, ensuring strand-independent counting.

Arguments

• KMER_TYPE: Type parameter specifying the k-mer size and structure
• sequences: Iterator of biological sequences to analyze

Returns

• Dict{KMER_TYPE,Int}: Dictionary mapping canonical k-mers to their counts

fasta_list_to_dense_kmer_counts(
;
    fasta_list,
    k,
    alphabet,
    temp_dir_parent,
    count_element_type,
    result_file,
    force,
    cleanup_temp
)

Create a dense k-mer counts table for a set of FASTA files, with disk-backed temporary storage, custom element type, robust error handling, and optional output file caching.

fasta_list_to_sparse_kmer_counts(
;
    fasta_list,
    k,
    alphabet,
    temp_dir_parent,
    count_element_type,
    rarefaction_data_filename,
    rarefaction_plot_basename,
    show_rarefaction_plot,
    result_file,
    out_dir,
    force,
    rarefaction_plot_kwargs...
)

Create a sparse kmer counts table (SparseMatrixCSC) from a list of FASTA files using a 3-pass approach. Pass 1 (Parallel): Counts kmers per file and writes to temporary JLD2 files. Pass 2 (Serial): Aggregates unique kmers, max count, nnz per file, and rarefaction data from temp files. Generates and saves a k-mer rarefaction plot. Pass 3 (Parallel): Reads temporary counts again to construct the final sparse matrix.

Optionally, a results filename can be provided to save/load the output. If the file exists and force is false, the result is loaded and returned. If force is true or the file does not exist, results are computed and saved.

Output Directory Behavior

• All auxiliary output files (e.g., rarefaction data, plots) are written to a common output directory.
• By default, this is:
  • The value of out_dir if provided.
  • Otherwise, the directory containing result_file (if provided and has a directory component).
  • Otherwise, the current working directory (pwd()).
• If you provide an absolute path for an output file (e.g. rarefaction_data_filename), that path is used directly.
• If both out_dir and a relative filename are given, the file is written to out_dir.

Arguments

• fasta_list::AbstractVector{<:AbstractString}: A list of paths to FASTA files.
• k::Integer: The length of the kmer.
• alphabet::Symbol: The alphabet type (:AA, :DNA, :RNA).
• temp_dir_parent::AbstractString: Parent directory for creating the temporary working directory. Defaults to Base.tempdir().
• count_element_type::Union{Type{<:Unsigned}, Nothing}: Optional. Specifies the unsigned integer type for the counts. If nothing (default), the smallest UInt type capable of holding the maximum observed count is used.
• rarefaction_data_filename::AbstractString: Filename for the TSV output of rarefaction data. If a relative path, will be written to out_dir.
• rarefaction_plot_basename::AbstractString: Basename for the output rarefaction plots. If a relative path, will be written to out_dir.
• show_rarefaction_plot::Bool: Whether to display the rarefaction plot after generation. Defaults to true.
• result_file::Union{Nothing, AbstractString}: Optional. If provided, path to a file to save/load the full results (kmers, counts, etc) as a JLD2 file.
• out_dir::Union{Nothing, AbstractString}: Optional. Output directory for auxiliary outputs. Defaults as described above.
• force::Bool: If true, recompute and overwrite the output file even if it exists. Defaults to false.
• rarefaction_plot_kwargs...: Keyword arguments to pass to plot_kmer_rarefaction for plot customization.

Returns

• NamedTuple{(:kmers, :counts, :rarefaction_data_path)}:
  • kmers: A sorted Vector of unique kmer objects.
  • counts: A SparseArrays.SparseMatrixCSC{V, Int} storing kmer counts.
  • rarefaction_data_path: Path to the saved TSV file with rarefaction data.

Raises

• ErrorException: If input fasta_list is empty, alphabet is invalid, or required Kmer/counting functions are not found.

build_kmer_graph_next(
    kmer_type,
    observations::AbstractVector{<:Union{FASTX.FASTA.Record, FASTX.FASTQ.Record}};
    graph_mode
) -> MetaGraphsNext.MetaGraph{Int64, Graphs.SimpleGraphs.SimpleDiGraph{Int64}, Label, VertexData, EdgeData, Nothing, WeightFunction, Float64} where {Label, VertexData, EdgeData, WeightFunction}

Create a next-generation, type-stable k-mer graph using MetaGraphsNext.

This implementation uses canonical k-mers as vertices with strand-aware edges that respect biological transition constraints for both single-strand and double-strand sequences.

Arguments

• kmer_type: Type of k-mer (e.g., DNAKmer{K})
• observations: Vector of FASTA/FASTQ records
• graph_mode: SingleStrand for directional sequences, DoubleStrand for DNA (default)

Returns

• MetaGraphsNext.MetaGraph with canonical vertices and strand-aware edges

Details

• Vertices: Always canonical k-mers (lexicographically smaller of kmer/reverse_complement)
• Edges: Strand-aware transitions that respect biological constraints
• SingleStrand mode: Only forward-strand transitions allowed
• DoubleStrand mode: Both forward and reverse-complement transitions allowed

build_stranded_kmer_graph(
    kmer_type,
    observations::AbstractVector{<:Union{FASTX.FASTA.Record, FASTX.FASTQ.Record}}
) -> MetaGraphs.MetaDiGraph{T, Float64} where T<:Integer

Create a weighted, strand-specific kmer (de bruijn) graph from a set of kmers and a series of sequence observations in FASTA format.

build_directed_kmer_graph(; fastq, k, plot)

Constructs a directed graph representation of k-mer transitions from FASTQ sequencing data.

Arguments

• fastq: Path to input FASTQ file
• k: K-mer size (default: 1). Must be odd and prime. If k=1, optimal size is auto-determined
• plot: Boolean to display quality distribution plot (default: false)

Returns

MetaDiGraph with properties:

• assembly_k: k-mer size used
• kmer_counts: frequency of each k-mer
• transition_likelihoods: edge weights between k-mers
• kmermeanquality, kmertotalquality: quality metrics
• branchingnodes, unbranchingnodes: topological classification
• likelyvalidkmer_indices: k-mers above mean quality threshold
• likelysequencingartifact_indices: potential erroneous k-mers

Note

For DNA assembly, quality scores are normalized across both strands.

jellyfish_counts_to_kmer_frequency_histogram(
    jellyfish_counts_file
) -> Any
jellyfish_counts_to_kmer_frequency_histogram(
    jellyfish_counts_file,
    outfile
) -> Any

Convert a Jellyfish k-mer count file into a frequency histogram.

Arguments

• jellyfish_counts_file::String: Path to the gzipped TSV file containing Jellyfish k-mer counts
• outfile::String=replace(jellyfish_counts_file, r"\.tsv\.gz$" => ".count_histogram.tsv"): Optional output file path

Returns

• String: Path to the generated histogram file

Description

Processes a Jellyfish k-mer count file to create a frequency histogram where:

• Column 1: Number of k-mers that share the same count
• Column 2: The count they share

Uses system sorting with LC_ALL=C for optimal performance on large files.

Notes

• Requires gzip, sort, uniq, and sed command line tools
• Uses intermediate disk storage for sorting large files
• Skips processing if output file already exists

plot_kmer_frequency_spectra(
    counts;
    log_scale,
    kwargs...
) -> Plots.Plot

Plots a histogram of kmer counts against # of kmers with those counts

Returns the plot object for adding additional layers and saving

Creates a scatter plot visualizing the k-mer frequency spectrum - the relationship between k-mer frequencies and how many k-mers occur at each frequency.

Arguments

• counts::AbstractVector{<:Integer}: Vector of k-mer counts/frequencies
• log_scale::Union{Function,Nothing} = log2: Function to apply logarithmic scaling to both axes. Set to nothing to use linear scaling.
• kwargs...: Additional keyword arguments passed to StatsPlots.plot()

Returns

• Plots.Plot: A scatter plot object that can be further modified or saved

Details

The x-axis shows k-mer frequencies (how many times each k-mer appears), while the y-axis shows how many distinct k-mers appear at each frequency. Both axes are log-scaled by default using log2.