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

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