API Reference

Package DePPA

Nucleic acid oligomers aligning and PCR primers construction

AbstractDegen <: AbstractOligo

Represent the abstract supertype for oligomers that may contain degenerate (IUPAC) bases.

AbstractGapped <: AbstractDegen

Represent the abstract supertype for oligomers that may contain gap characters (-).

AbstractOligo <: AbstractString

Represent the abstract supertype for all oligomer types in DePPA.

DegenOligo(seq::AbstractString, descr::Union{AbstractString,Integer}="")

Represent a degenerate nucleic acid sequence, allowing IUPAC ambiguity codes.

GappedNonDegenIterator

Iterate over all unique non-degenerate sequences represented by a gapped oligomer, preserving gap positions.

GappedOligo(seq::AbstractString, descr::Union{AbstractString,Integer}="")

Represent a gapped nucleic acid sequence, allowing gap characters (-).

NonDegenIterator{T<:AbstractOligo}

Iterate over all unique non-degenerate sequences represented by a degenerate oligomer.

Oligo(seq::AbstractString, descr::Union{AbstractString,Integer}="")

Represent a non-degenerate nucleic acid sequence (only A, C, G, T).

Sequences are automatically converted to uppercase.

OligoView{T<:AbstractOligo} <: AbstractOligo

Represent a lightweight view into an AbstractOligo as a contiguous subsequence.

Base.:*(a::T, b::S) where {T<:AbstractOligo, S<:AbstractOligo}

Concatenate two oligomers. Returns a degenerate or gapped oligo if either of the operands is degenerate or gapped, otherwise returns a non-degenerate Oligo. Preserves and concatenates descriptions.

description(oligo::AbstractOligo) -> String

Return the description string associated with the oligomer.

getgaps(oligo::AbstractOligo) -> Vector{Pair{Int, Int}}

Return a vector of gap locations and lengths for a gapped oligomer.

See also hasgaps, GappedOligo.

hasgaps(oligo::AbstractOligo) -> Bool

Return true if the sequence contains gap characters (-), and false otherwise.

See also getgaps, GappedOligo.

n_deg_pos(oligo::AbstractOligo) -> Int

Return the number of degenerate (ambiguity) positions in the sequence.

See also n_unique_oligos, nondegens.

n_unique_oligos(oligo::AbstractOligo) -> BigInt

Return the total number of unique non-degenerate sequences represented by the oligomer.

See also n_deg_pos, nondegens.

nondegens(oligo::AbstractOligo)

Return an iterator over all unique non-degenerate sequences represented by the oligomer.

For non-degenerate sequences, return a tuple containing the sequence itself.

See also NonDegenIterator, GappedNonDegenIterator, sampleNondeg.

oligo_range(oligo::AbstractOligo) -> UnitRange{Int}

Return the index range of the oligomer or view.

sampleChar(oligo::AbstractOligo) -> Char

Return a randomly sampled character from the oligomer sequence.

See also sampleView, sampleNondeg.

sampleNondeg(oligo::AbstractOligo) -> AbstractOligo

Return a randomly sampled non-degenerate sequence from the possible variants of the oligomer.

See also nondegens, sample_max_gc, sample_min_gc.

sampleView(oligo::AbstractOligo, len::Int) -> OligoView

Return a random contiguous subsequence (view) of the specified length.

See also OligoView, sampleChar.

sample_max_gc(oligo::AbstractOligo) -> AbstractOligo

Return a non-degenerate sequence sampled from the oligomer, maximizing GC content.

See also sample_min_gc, sampleNondeg.

sample_min_gc(oligo::AbstractOligo) -> AbstractOligo

Return a non-degenerate sequence sampled from the oligomer, minimizing GC content.

See also sample_max_gc, sampleNondeg.

AbstractMSA

Abstract supertype for Multiple Sequence Alignments.

MSA <: AbstractMSA

A concrete Multiple Sequence Alignment type. Stores sequences and precomputed base frequencies.

MSA(fasta::AbstractString; kwargs...)

Construct an MSA from a FASTA file, including all sequences.

Arguments

• fasta::AbstractString: Path to the FASTA file.
• kwargs...: Keyword arguments passed to the underlying prredicate-based method.

Returns

• MSA: A new MSA object containing all sequences from the file.

MSA(predicate::Function, fasta::AbstractString; mafft::Bool=false, bootstrap::Int=0, seed=nothing)

Construct an MSA from a FASTA file.

Arguments

• predicate::Function: A ::Bool-output filtering function that is applied to sequence descriptions.
• fasta::AbstractString: Path to the FASTA file.
• mafft::Bool=false: If true, align the sequences using MAFFT (requires MAFFT_jll package to be loaded).
• bootstrap::Int=0: Number of bootstrap iterations for base frequencies.
• seed=nothing: Random seed for reproducibility.

MSA(msav::MSAView; bootstrap::Int=0, seed=nothing)

Construct a new concrete MSA by materializing the MSAView into a standalone alignment.

Arguments

• msav::MSAView: The MSA view to materialize.
• bootstrap::Int=0: Number of bootstrap iterations for computing base frequencies.
• seed=nothing: Random seed for reproducibility during bootstrap resampling.

Returns

• MSA: A new, independent MSA object containing the sliced sequences.

See also MSAView.

MSAView <: AbstractMSA

A lightweight view into an MSA, representing a submatrix of rows and columns.

getindex(msa::AbstractMSA, rows, cols)

Get a submatrix or element from an MSA using multi-dimensional indexing.

Supports:

• msa[row, col]: single element
• msa[row_range, col_range]: submatrix view
• msa[row, :]: entire row
• msa[:, col_range]: entire column range

_pairwise_distance(msa::AbstractMSA, i::Int, j::Int; ignore_gaps::Bool=true)

Calculate pairwise distance between two sequences using probabilistic matching for degenerate bases.

Arguments

• msa::AbstractMSA: The MSA.
• i::Int, j::Int: Sequence indices.
• ignore_gaps::Bool=true: Whether to skip gap positions.

Returns

• Float64: Normalized distance (0.0 to 1.0).

bval(msa::AbstractMSA) -> Int

Return the number of bootstrap iterations used to compute base frequencies.

See also root, MSA.

consensus_degen(msa::AbstractMSA, pos::Int; slack::Real=0.0)
consensus_degen(msa::AbstractMSA, interval::UnitRange{Int}; slack::Real=0.0)

Generate a degenerate consensus sequence allowing ambiguity. Bases with frequency > slack are included in the degeneracy.

Arguments

• msa::AbstractMSA: The MSA.
• pos::Int: Single position.
• interval::UnitRange{Int}: Range of positions.
• slack::Real=0.0: Minimum frequency threshold for inclusion.

Returns

• Char for a single position (IUPAC ambiguity code).
• GappedOligo for multiple positions.

See also consensus_major, get_base_count.

consensus_major(msa::AbstractMSA, pos::Int)
consensus_major(msa::AbstractMSA, interval::UnitRange{Int})

Generate a majority-rule consensus sequence using simple majority rule, ignoring gap characters.

Arguments

• msa::AbstractMSA: The MSA.
• pos::Int: Single position.
• interval::UnitRange{Int}: Range of positions.

Returns

• Char for a single position (most common base).
• GappedOligo for multiple positions.

See also consensus_degen, get_base_count.

dry_msa(msa::AbstractMSA; gap_content::Real=1.0)

Remove columns and rows with excessive gap content. Columns with no non-gap characters are always removed. Rows with gap proportion > gap_content are removed.

Arguments

• msa::AbstractMSA: The MSA.
• gap_content::Real=1.0: Maximum allowed gap proportion (default: 1.0, keep all).

Returns

• A new MSA with filtered sequences and columns.

get_base_count(msa::AbstractMSA, pos::Int)
get_base_count(msa::AbstractMSA, interval::UnitRange{Int})
get_base_count(msa::AbstractMSA)

Get base frequency counts from an MSA.

Arguments

• msa::AbstractMSA: The MSA.
• pos::Int: Single position (1-based).
• interval::UnitRange{Int}: Range of positions.
• If no position or interval is provided, returns counts for all positions.

Returns

• A vector of 4 floats (A, C, G, T probabilities) for a single position.
• A matrix view for multiple positions.

getsequence(msa::AbstractMSA, row::Int)
getsequence(msa::AbstractMSA, row::Int, col::Int)

Get a sequence or an individual position from an MSA.

Arguments

• msa::AbstractMSA: The MSA.
• row::Int: Sequence index (1-based).
• col::Int: Position index (1-based, optional).

Returns

• For getsequence(msa, row): The full sequence (GappedOligo).
• For getsequence(msa, row, col): Single character at position.

height(msa::AbstractMSA) -> Int

Return the number of sequences (rows) in the MSA. Alias for nseqs.

See also nseqs, width.

msadepth(msa::AbstractMSA, pos::Int)
msadepth(msa::AbstractMSA, interval::UnitRange{Int})
msadepth(msa::AbstractMSA)

Calculate sequence depth (coverage) at positions. Depth is the sum of base probabilities, capped at 1.0.

Arguments

• msa::AbstractMSA: The MSA.
• pos::Int: Single position.
• interval::UnitRange{Int}: Range of positions.
• If no position or interval is provided, calculate depth for all positions.

Returns

• Float64 for a single position.
• Vector{Float64} for multiple positions.

See also msadet, get_base_count.

msadet(msa::AbstractMSA, pos::Int)
msadet(msa::AbstractMSA, interval::UnitRange{Int})
msadet(msa::AbstractMSA)

Calculate sequence determinacy at positions. Determinacy is the maximum base frequency normalized by total coverage.

Arguments

• msa::AbstractMSA: The MSA.
• pos::Int: Single position.
• interval::UnitRange{Int}: Range of positions.
• If no position or interval is provided, calculate determinacy for all positions.

Returns

• Float64 for a single position (0.0 to 1.0).
• Vector{Float64} for multiple positions.

See also msadepth, get_base_count.

nseqs(msa::AbstractMSA) -> Int

Return the number of sequences (rows) in the alignment.

See also height, width.

nucleotide_diversity(msa::AbstractMSA; ignore_gaps::Bool=true, max_pairs::Int=10000)

Calculate average pairwise nucleotide diversity. Uses probabilistic distance for degenerate bases. For large MSAs (>200 sequences), samples random pairs.

Arguments

• msa::AbstractMSA: The MSA.
• ignore_gaps::Bool=true: Whether to skip gap-gap comparisons.
• max_pairs::Int=10000: Maximum pairs to sample for large MSAs.

Returns

• Float64: Average pairwise distance.

root(msa::AbstractMSA) -> MSA

Return the underlying root MSA object, resolving any MSAView layers.

See also bval, MSAView.

setMSAShowStyle!(style::Symbol)

Sets the global display style for the MSA viewer.

Valid options are:

• :bw (black and white, consensus with . for matches)
• :polymorf (colored polymorphic characters, . for consensus matches)
• :allcolors (fully colored sequences and depth histogram bars, default)

setMSAconsensusShowType!(style::Symbol)

Set the consensus sequence type displayed above the alignment in show.

Valid options:

• :degen – degenerate consensus (default, uses consensus_degen with slack=0.0)
• :major – simple majority rule consensus (uses consensus_major)

Note: Dots in :bw and :polymorf styles always mark matches to the majority consensus, regardless of this setting.

width(msa::AbstractMSA) -> Int

Return the number of columns (alignment length) in the MSA.

See also nseqs, height.

AbstractPrimer{T<:Union{Oligo,DegenOligo}}

Represent the abstract supertype for PCR primers.

See also Primer.

MiniBlastHit

Represents a single hit returned by the miniblast function.

Fields

• pos::UnitRange{Int}: The start and end positions of the match in the MSA (1-based).
• strand::Symbol: The strand of the match (:forward or :reverse).
• identity::Float64: The average match probability (0.0 to 1.0).

Primer{T} <: AbstractPrimer{T}

Represent a concrete PCR primer. Store the consensus sequence, its position in the MSA, and thermodynamic properties (Tm, ΔG, GC content).

See also AbstractPrimer, construct_primers.

Primer(msa::AbstractMSA, interval::UnitRange{Int}; kwargs...)

Construct a Primer object for a given interval in the MSA, calculating its thermodynamic properties.

If global adapters are set via setAdapters!, they are automatically appended to the 5' end. The ΔG of the full sequence (adapter + primer) is calculated at the primer's mean Tm. If the adapter worsens ΔG by more than max_dg_drop, a warning is issued.

Arguments

• msa::AbstractMSA: The multiple sequence alignment.
• interval::UnitRange{Int}: The position range of the primer in the MSA.
• is_forward::Bool=true: Design a forward (true) or reverse (false) primer.
• tail_length::Int=3: Length of the 3' tail region.
• max_samples::Int=1000: Number of samples for Monte Carlo estimation of Tm and ΔG.
• tm_conf_int=0.8: Confidence interval for Tm.
• tm_conds=:pcr: Thermodynamic conditions for Tm calculation.
• dg_temp=37.0: Temperature for ΔG calculation (used for the primer without adapter).
• slack=0.0: Minimum frequency threshold for including a base in the degenerate consensus.
• max_dg_drop::Real=1.0: Threshold for warning if the adapter worsens ΔG significantly.
• descr: Description string for the primer.

See also construct_primers, consensus_degen, setAdapters!.

Primer{T}(msa::AbstractMSA, pos::UnitRange{Int}, is_forward::Bool, consensus, tail_length::Int, tm, dg::Float64, gc::Float64, slack::Float64) where T

Constructs a Primer with type parameter {T} without specifying an adapter. Automatically converts the consensus to type T and sets the adapter field to nothing.

Primer(msa::AbstractMSA, pos::UnitRange{Int}, is_forward::Bool, consensus::T, tail_length::Int, tm, dg::Float64, gc::Float64, slack::Float64) where T

Constructs a Primer without specifying the type parameter {T} or an adapter. Infers the type T directly from the consensus sequence and sets the adapter field to nothing.

_has_nonspecific_match(primer_seq::AbstractString, msa::AbstractMSA, skip_interval; min_identity=0.75) -> Bool

Check if a degenerate primer sequence has high-probability matches outside the skip_interval in the MSA. If skip_interval is nothing, all positions in the MSA are checked. Evaluates both forward and reverse complement orientations.

best_pairs(primers::Vector{<:AbstractPrimer}; kwargs...) -> Vector{Pair{Primer{DegenOligo}}}

Find the best matching pairs of forward and reverse primers from a single vector of mixed primers.

Arguments

• primers::Vector{<:AbstractPrimer}: A list of primers containing both forward and reverse primers (e.g., output from construct_primers).
• amplicon_len::UnitRange{Int}=0:9999: Allowed range for the total amplicon length.
• max_tm_diff::Real=4.0: Maximum allowed difference in mean Tm between forward and reverse primers.
• nested_pair::Union{Nothing, Tuple{Pair{<:AbstractPrimer, <:AbstractPrimer}, Int}}=nothing: An optional tuple specifying a flanking primer pair and an offset for nested PCR design.
  • If nothing or offset == 0, performs normal pairing.
  • If offset < 0, only pairs entirely inside the flanking pair's amplicon (minus the offset margin) are considered.
  • If offset > 0, only pairs with the forward primer upstream and reverse primer downstream of the flanking amplicon (plus the offset margin) are considered.
• sortby::Symbol: rule to sort the resulting vector (:default, :tm_diff, :tm, :startpos, :length).

Returns

• Vector{Pair{Primer{DegenOligo}, Primer{DegenOligo}}}: A sorted list of valid primer pairs, ordered by the smallest difference in mean Tm.

See also construct_primers, Primer.

construct_primers(msa::AbstractMSA; kwargs...) -> Vector{Primer{DegenOligo}}

Construct a list of candidate primers (both forward and reverse) from an MSA based on thermodynamic, conservation, and specificity filters.

Arguments

• msa::AbstractMSA: The multiple sequence alignment.
• length_range::UnitRange{<:Integer}=17:23: Allowed primer lengths.
• tail_length::Integer=3: Length of the 3' tail region.
• head_degen_pos::Integer=5: Maximum allowed degenerate positions in the 5' head region.
• tail_degen_pos::Integer=0: Maximum allowed degenerate positions in the 3' tail region.
• slack::Real=0.02: Minimum frequency threshold for including a base in the degenerate consensus.
• gc_range::UnitRange{<:Integer}=40:60: Allowed GC content percentage range.
• tm_range::UnitRange{<:Integer}=55:60: Allowed melting temperature (Tm) range.
• min_delta_g::Real=-5.0: Minimum allowed free energy (ΔG) at dg_temp.
• min_msadepth::Real=0.75: Minimum sequence depth (coverage) required across the primer region.
• max_oligo_variants::Integer=100: Maximum number of unique sequences the degenerate primer can represent.
• max_samples::Integer=5000: Number of samples for Monte Carlo estimation of Tm and ΔG.
• tm_conf_int::Real=0.2: Confidence interval for Tm.
• tm_conds=:pcr: Thermodynamic conditions for Tm calculation.
• dg_temp::Real=mean(tm_range): Temperature for ΔG calculation.
• offtarget_reject_threshold::Real=0.75: Maximum allowed average match probability for off-target binding in the original MSA. If a candidate primer matches another region in the MSA (outside its target interval) with an average probability greater than or equal to this threshold, it is discarded. Checks both forward and reverse complement orientations. This threshold does not apply to negative_msa alignments — each of those carries its own individual threshold.
• adapter_pair: Optional adapter pair from GLOBAL_ADAPTERS[].
• max_dg_drop::Real=1.0: Maximum allowed ΔG drop when adapter is appended.
• negative_msa::Vector{Tuple{<:AbstractMSA, <:Real}}=Tuple{<:AbstractMSA, <:Real}[]: A vector of tuples, each containing a negative alignment and its individual off-target reject threshold. Candidate primers are checked against each alignment using its corresponding threshold, and any primer matching with an average probability greater than or equal to that threshold is discarded.
• nested_pair::Union{Nothing, Tuple{Pair{<:AbstractPrimer, <:AbstractPrimer}, Integer}}=nothing: An optional tuple specifying a flanking primer pair and an offset for nested PCR design.
  • If nothing or offset == 0, constructs primers across the entire MSA.
  • If offset < 0, constructs primers strictly inside the flanking pair's amplicon boundaries, shrunk by the absolute value of the offset.
  • If offset > 0, constructs forward primers upstream of the flanking amplicon (with the given offset) and reverse primers downstream.

Returns

• Vector{Primer{DegenOligo}}: A list of valid candidate primers (mixed forward and reverse).

See also best_pairs, Primer, consensus_degen.

export_evrogen(io::IO, primers; scale=0.04)
export_evrogen(io::IO, pairs; scale=0.04)
export_evrogen(filename::AbstractString, primers; scale=0.04)
export_evrogen(filename::AbstractString, pairs; scale=0.04)

Export primers to a text stream or file formatted for the Evrogen DNA synthesis order form (Form I).

The format used is: Name; Sequence; Scale (e.g., Primer_F_18; AGACYGACCGHGAAYTMGACCT; 0.04). IUPAC ambiguity codes are preserved, as required by Evrogen.

Arguments

• io::IO: An output stream (e.g., stdout or a buffer).
• filename::AbstractString: Path to the output text file.
• primers: A single primer or a vector of primers.
• pairs: A single primer pair or a vector of primer pairs (e.g., output from best_pairs).
• scale: Synthesis scale (e.g., 0.04, 0.2, 1.0). Defaults to 0.04.

Returns

• For IO methods: returns nothing;
• For file methods: returns the filename.

miniblast(target_msa::AbstractMSA, query::AbstractString, threshold=0.75) -> Vector{MiniBlastHit}

Search for high-probability matches of query within target_msa using a probabilistic sliding window. Evaluates both forward and reverse complement orientations of the query.

Arguments

• target_msa::AbstractMSA: The multiple sequence alignment to search within.
• query: The query sequence to search for. Can be an AbstractString (including AbstractOligo) or an AbstractPrimer. The query must not contain gaps (-).
• threshold::Real=0.75: Minimum average match probability (identity) required to report a hit.

Returns

• Vector{MiniBlastHit}: A list of matches sorted by identity (descending).

reannotated(primer::AbstractPrimer, annotation::AbstractString) -> Primer
reannotated(pair::Pair{<:AbstractPrimer, <:AbstractPrimer}, annotation::AbstractString) -> Pair{Primer}

Create a new primer (or primer pair) with the updated description (annotation). Since Julia structs are immutable, a new object is returned rather than mutating the existing one in-place.

Arguments

• primer / pair: A single primer or a primer pair.
• annotation::AbstractString: The new description string.

Returns

• A new Primer or Pair{Primer, Primer} with the updated description.

setAdapters!() -> Nothing
setAdapters!(adapters::Pair{<:Oligo, <:Oligo}) -> Nothing
setAdapters!(adapters::Pair{<:AbstractString, <:AbstractString}) -> Nothing

Set the global adapter sequences to be automatically appended to the 5' ends of primers during construct_primers.

Arguments

• (): Resets the global adapters to nothing (no adapters will be added).
• adapters::Pair{<:Oligo, <:Oligo}: A custom pair of valid Oligo sequences.
• adapters::Pair{<:AbstractString, <:AbstractString}: A custom pair of strings (will be converted to Oligo).

Details

When global adapters are set, construct_primers will automatically concatenate them to candidate primers, recalculate ΔG at the primer's mean Tm, and discard candidates where the adapter worsens ΔG by more than max_dg_drop.