Coalescent.jl

Coalescent

Coalescent simulation and analysis with flexible markup of demographic processes and sampling patterns.

This module provides tools for:

• Simulating coalescent trees
• Handling structured population models
• Solving ordinary differential equations for population dynamics
• Managing sample configuration

SimTree

Represents a simulated coalescent tree.

Fields

• parent::Array{Union{Nothing,Int}}: Parent nodes
• child::Array{Union{Nothing,Int}}: Child nodes
• n::Int: Number of tips
• nNode::Int: Number of internal nodes
• edgelength::Array{Union{Nothing,Float64}}: Edge lengths
• heights::Array{Union{Nothing,Float64}}: Node heights
• tiplabs::Array{Union{Nothing,String}}: Tip labels
• shs::Array{Union{Nothing,Float64}}: Sample heights
• descendants::Union{Nothing,BitMatrix}: Descendant matrix
• daughters::Union{Nothing,Vector{Tuple{Int, Int, Int, Int}}}: Daughter nodes
• demes::Union{Nothing,Vector{String}}: Demes for each node

tonewick(o)

Convert a SimTree to a Newick format string.

Arguments

• o::SimTree: The SimTree to convert

Returns

• String: Newick format representation of the tree

ModelFGY

Represents a structured Forward-in-time Genealogy (FGY) model for coalescent simulations.

Fields

• modelname::String: Name of the model
• birthrxn::Array{Reaction}: Birth reactions in the model
• migrationrxn::Array{Reaction}: Migration reactions in the model
• deathrxn::Array{Reaction}: Death reactions in the model
• nondemerxn::Array{Reaction}: Non-deme reactions in the model
• demes::Array{String}: Names of demes in the model
• nondemes::Union{Nothing,Array{String}}: Names of non-deme variables
• numberdemes::Int: Number of demes
• numbernondemes::Int: Number of non-deme variables
• initial::Dict{String,Number}: Initial conditions for variables
• t0::Float64: Initial time
• tfin::Float64: Final time
• parameters::Union{Nothing,Dict{String,Number}}: Model parameters
• helperexprs::Union{Nothing,Array{Expr}}: Helper expressions for the model

SampleConfiguration

Represents a configuration for sampling in coalescent simulations.

Fields

• sconf::Array{Tuple{Union{Nothing,String}, Float64}}: Array of tuples containing deme (or nothing) and sampling time

solveodes(model::ModelFGY; odemethod = :(Rosenbrock23()), res::Union{Missing,Int64} = missing)

Solve the ordinary differential equations (ODEs) defined by the given model.

Arguments

• model::ModelFGY: The structured FGY model containing the ODEs to solve

Keywords

• odemethod = :(Rosenbrock23()): The ODE solver method to use
• res::Union{Missing,Int64} = missing: The number of time points to return in the solution

Returns

• ODESolution: The solution of the ODEs

SimTree(Ne::Float64, n::Int64)::SimTree

Simulate a coalescent tree with constant Ne and n samples at time 0, without specifying tmrcaguess.

Arguments

• Ne::Float64: Constant effective population size
• n::Int64: Number of samples

Returns

• SimTree: The simulated coalescent tree

SimTree(Ne::Float64, sampletimes::Array{Float64}, p...;  tmrcaguess::Union{Nothing,Float64}=nothing, algorithm=ALGO_MARKOV)::SimTree

Simulate a coalescent tree with constant Ne and flexible sampling times.

Arguments

• Ne::Float64: Constant effective population size
• sampletimes::Array{Float64}: Array of sample times
• tmrcaguess::Float64: Initial guess for the time to most recent common ancestor
• p...: Additional parameters (unused for constant Ne)

Keywords

• algorithm::String = ALGO_STATIONARY: Algorithm to use for simulation (ALGOSTATIONARY or ALGOMARKOV)

Returns

• SimTree: The simulated coalescent tree

SimTree(Ne::Function, sampletimes::Array{Float64}, p...; tmrcaguess::Union{Nothing,Float64}=nothing, algorithm=ALGO_STATIONARY)::SimTree

Simulate a coalescent tree with flexible Ne function and sampling times.

Arguments

• Ne::Function: Effective population size function
• sampletimes::Array{Float64}: Array of sample times
• tmrcaguess::Float64: Initial guess for the time to most recent common ancestor
• p...: Additional parameters for the Ne function

Keywords

• algorithm::String = ALGO_MARKOV: Algorithm to use for simulation (ALGOSTATIONARY or ALGOMARKOV)

Returns

• SimTree: The simulated coalescent tree

SimTree(Ne::Function, n::Int64,p...; tmrcaguess::Union{Nothing,Float64}=nothing, algorithm=ALGO_MARKOV)::SimTree

Simulate a coalescent tree with flexible Ne function and n samples at time 0.

Arguments

• Ne::Function: Effective population size over time function
• n::Int64: Number of samples
• tmrcaguess::Float64: Initial guess for the time to most recent common ancestor
• p...: Additional parameters for the Ne function

Keywords

• algorithm::String = ALGO_MARKOV: Algorithm to use for simulation (ALGOSTATIONARY or ALGOMARKOV)

Returns

• SimTree: The simulated coalescent tree

SimTree(model::ModelFGY, sample::SampleConfiguration; computedescendants = false)

Simulate a coalescent tree based on a given model and sampling configuration.

Arguments

• model::ModelFGY: The structured FGY model to simulate
• sample::SampleConfiguration: The sampling configuration for the simulation

Keywords

• computedescendants::Bool = false: Whether to compute descendants for each node
• odemethod = :(Tsit5()): ODE solver for the cumulative hazard of genealogical events. The hazard does not depend on the ODE state, so the problem is not stiff. Solvers that differentiate with ForwardDiff, such as Rosenbrock23() or AutoTsit5(Rosenbrock23()), can fail with a MethodError
• ytol::Float64 = 1e-6: Lower bound on deme size relative to the number of lineages, for numerical stability of the rates

Returns

• SimTree: A simulated coalescent tree

ModelFGY(; confstr::String)

Constructor for ModelFGY from a YAML configuration string.

Arguments

• confstr::String: String defining model in YAML format

Returns

• ModelFGY: The constructed model

ModelFGY(conffn::String)

Constructor for ModelFGY from a YAML configuration file.

Arguments

• conffn::String: Path to the YAML configuration file

Returns

• ModelFGY: The constructed model

SampleConfiguration(conffn::String)

Create a SampleConfiguration from a YAML configuration file.

Arguments

• conffn::String: Path to the YAML configuration file

Returns

• SampleConfiguration: The constructed sampling configuration

SampleConfiguration(; confstr::String)

Create a SampleConfiguration from a YAML configuration string.

Arguments

• confstr::String: YAML configuration string defining the sampling scheme

Returns

• SampleConfiguration: The constructed sampling configuration

tonewick(o)

Convert a SimTree to a Newick format string.

Arguments

• o::SimTree: The SimTree to convert

Returns

• String: Newick format representation of the tree

distancematrix(t)::Matrix{Float64}

Compute the distance matrix for a SimTree.

Arguments

• t::SimTree: The SimTree to compute distances for

Returns

• Matrix{Float64}: The computed distance matrix

solveodes(model::ModelFGY; odemethod = :(Rosenbrock23()), res::Union{Missing,Int64} = missing)

Solve the ordinary differential equations (ODEs) defined by the given model.

Arguments

• model::ModelFGY: The structured FGY model containing the ODEs to solve

Keywords

• odemethod = :(Rosenbrock23()): The ODE solver method to use
• res::Union{Missing,Int64} = missing: The number of time points to return in the solution

Returns

• ODESolution: The solution of the ODEs