API Reference

logoplot(pfm[, background]; kwargs...)

Render a sequence logo from a position frequency matrix.

Arguments

• pfm: position frequency matrix (4 × N for DNA/RNA, 20 × N for protein), each column summing to 1.
• background: optional background frequencies (length 4 for nucleotides, 20 for protein). Defaults to a uniform background.

Keyword arguments

• protein::Bool=false: treat the PFM as a 20-row amino-acid matrix.
• rna::Bool=false: use A, C, G, U glyphs instead of A, C, G, T.
• tight::Bool=false: use tight plot limits (drops padding around the logo).
• xaxis, yaxis: toggle axis display.
• alpha, beta: glyph transparency and width scaling.
• uniform_color::Bool=false: use a single color for all glyphs.
• scale_by_frequency::Bool=false: scale letters by frequency only (stack to full height) instead of by information content.
• dpi, _margin_, pos, xrotation, and additional styling parameters are also accepted.

See also logoplot_with_highlight and save_logoplot.

logoplot_with_highlight(pfm, background, highlighted_regions; kwargs...)

Plot a sequence logo with specific regions highlighted.

Arguments

• pfm: Position frequency matrix
• background: Background frequencies
• highlighted_regions: Vector of UnitRange{Int} specifying positions to highlight
• scale_by_frequency::Bool=false: If true, scale letters by frequency only (stack to full height)
• Additional keyword arguments for customization

logoplot_with_highlight(pfm, highlighted_regions; kwargs...)

Plot a sequence logo with highlighted regions using default background frequencies.

save_logoplot(pfm, background, save_name; kwargs...)

Save a sequence logo plot to a file.

Arguments

• pfm::Matrix{Real}: Position frequency matrix (rows = characters, columns = positions)
• background::Vector{Real}: Background probabilities for each character
• save_name::String: File path to save the plot
• scale_by_frequency::Bool=false: If true, scale letters by frequency only (stack to full height)

Requirements

• pfm must be a probability matrix (each column sums to 1)
• background must be a vector of probabilities that sum to 1
• For nucleotides: background length = 4; for proteins: length = 20

Example

pfm = [0.02 1.0 0.98 0.0; 0.98 0.0 0.02 0.19; ...]
background = [0.25, 0.25, 0.25, 0.25]
save_logoplot(pfm, background, "logo.png"; dpi=65)

save_logoplot(pfm, save_name; kwargs...)

Save a sequence logo plot using default background frequencies.

This is equivalent to save_logoplot(pfm, background, save_name; kwargs...) where background is set to uniform frequencies for the sequence type.

reduce_entropy!(pfm; factor=10)

Sharpen each column of a PFM toward its dominant symbol, in place.

Each column is raised element-wise to the power factor and then renormalized to sum to 1. Larger factor values make the dominant symbol more overwhelming (lower entropy); factor=1 leaves the column unchanged. Useful for cleaning up noisy protein PFMs before plotting.

filter_counts_by_reference(counts, ref; tol=1e-9)

Keep only columns where dot(col, ref_col) ≠ sum(col). When equal, the column has single nonzero entry matching reference → remove it. Returns indices of columns to keep.

count_fragments(count_matrices, reference_pfms, starting_indices; tol=1e-9)
count_fragments(count_matrices, reference_pfms; tol=1e-9)

Filter count matrices by reference and report the resulting contiguous fragments.

Returns (total_fragments::Int, span::String), where span is a human-readable description of the fragments in global coordinates. Without starting_indices, each matrix is assumed to start at position 1.

Span examples:

• single column at 45 -> "45"
• columns 45-48 -> "45-48"
• two fragments at 45 and 51-55 -> "(45, 51-55)"

apply_count_filter(count_matrices, starting_indices, reference_pfms; tol=1e-9)

Filter count matrices by reference, returning new matrices with only non-matching columns. Updates starting indices to reflect new fragment positions.

logoplot_with_rect_gaps(count_matrices, starting_indices, total_length; kwargs...)

Plot several logo fragments positioned along a track of length total_length, joined by rectangular connector glyphs across the gaps between them.

count_matrices is a vector of per-fragment count/frequency matrices and starting_indices gives each fragment's starting position on the track. When reference_pfms (a vector of column-wise one-hot BitMatrix) is supplied and filter_by_reference=true, columns that match the reference are dropped via apply_count_filter before plotting.

Notable keyword arguments

• reference_pfms=nothing, filter_by_reference=true, filter_tolerance=1e-9: reference-based column filtering.
• ref_match_color, ref_mismatch_color: colors for reference-matching / mismatching letters.
• outside_count_matrices=nothing, outside_starting_indices=nothing, outside_reference_pfms=nothing: optional extra fragments ("outside" fragments) drawn on the same track. They are never filtered: they are merged with the fragments that survive the reference filter, sorted by starting position, and laid out by the same gap machinery (connectors, tick labels). They must not overlap the main fragments. Requires reference_pfms; the three outside arguments go together, with equal lengths, and each outside count matrix must have as many columns as its reference.
• outside_match_color="#64748B", outside_mismatch_color="#E69F00": colors for reference-matching / mismatching letters in the outside fragments, so they read apart from the main fragments (ref_match_color / ref_mismatch_color).
• rna, protein, uniform_color, dpi, xrotation, height_top, arrow_shape_scale_ratio, basic_fcn: styling of the logos and connectors.

With outside_count_matrices=nothing (the default) the plot is exactly the plot drawn without the outside arguments. The "nothing to plot after filtering" error is raised when the main fragments are filtered to nothing, even if outside fragments are given.

See also save_logo_with_rect_gaps.

save_logo_with_rect_gaps(count_matrices, starting_indices, total_length, save_name; kwargs...)

Render a gapped multi-fragment logo (see logoplot_with_rect_gaps) and save it to save_name. The output format is inferred from the file extension. Accepts the same keyword arguments as logoplot_with_rect_gaps, including reference-based column filtering and the outside fragments (outside_count_matrices, outside_starting_indices, outside_reference_pfms, outside_match_color, outside_mismatch_color). Every count matrix, main or outside, must be non-negative with positive column sums.

get_rectangle_basic(; line_scale=1.0, right=true, x_offset=0.0)

Return the basic rectangular arrow-shaft shape used as the connector glyph between logo fragments in the gap/spacer plots. line_scale scales its length, right orients the arrow head, and x_offset shifts it horizontally. Used as the default basic_fcn for logoplot_with_rect_gaps and save_logo_with_rect_gaps.