internal documentation

mappingnodes(gene tree)

Type to define an iterator over degree-2 mapping nodes in a gene tree, assuming these degree-2 nodes (other than the root) have a name to map them to nodes in a species phylogeny. See ismappingnode.

coalescence_edge(edge1, edge2, number, populationid)

Create a coalescence between edges 1 and 2: with a new parent node n numbered number and a new parent edge e above the parent node, of length 0 and numbered number. Both n.intn1 and e.inte1 are set to populationid.

convert2tree!(rootnode)

Return a HybridNetwork object tree with all nodes and edges that can be reached from rootnode. Its nodes (and edges) are already post-ordered, that is, tree.node lists all the nodes such that the first one is the root, and if v is a descendant of u, then v is listed after u.

Warning: edges that can be reached from rootnodes are assumed to be correctly directed (with correct ischild1 attribute) and that the graph is a tree. This is not checked.

If the root node is still attached to an incomplete root edge, this edge & node are first disconnected.

get_rootedgenumber(network)

1 + maximum of 0 and of all the network's edge numbers: can be used as a unique identifier of the edge above the network's root.

initializetip(species::AbstractString, individual::AbstractString,
              number::Integer, delim=""::AbstractString)

Create a leaf node and a pendant edge of length 0, incident to each other, both numbered number. Return the pendant edge. The leaf name is made by concatenating species, delim and individual.

initializetipforest(speciesnode::Node, nindividuals::Integer,
              number::Integer, delim)

Vector of pendant leaf edges, with leaves named after speciesnode, and numbered with consecutive number IDs starting at number. If nindividuals is 1, then the leaf name is simply the species name. Otherwise, then the leaf names include the individual number and the default delimiter is _. For example, if the species name is s then leaf names are: s_1, s_2, etc. by default. Pendant leaf edges have inte1 set to the number of the corresponding edge in the species network.

ismappingnode(node)

Boolean: true if node is has a single child, and has a name. Nodes mapping to a species tree node are those that satisfy these conditions. They are typically of degree 2, except for the gene tree root, which is of degree 1 if it maps to the network's root (rather than being older).

map2population!(forest, population_node, populationid, nextlineageID)

Extend each incomplete edge in the forest with a new degree-2 node n and a new incomplete edge e, with the following information to map n and e into the species phylogeny:

• e.inte1 is set to populationid, and
• n.name is set to population_node.name if this name is non-empty, or string(population_node.number) otherwise (with any negative sign replaced by the string "minus").

e.number and n.number are set to nextlineageID, which is incremented by 1 for each incomplete edge in the forest.

The forest is updated to contain the newly-created incomplete edges, replacing the old incomplete (and now complete) edges.

Output: nextlineageID, incremented by the number of newly created degree-2 lineages.

example

julia> using PhyloNetworks; net = readnewick("(A:1,B:1);");

julia> leafA = net.node[1]; edge2A_number = net.edge[1].number;

julia> f = PhyloCoalSimulations.initializetipforest(leafA, 2, 4); # 2 edges, numbered 4 & 5

julia> PhyloCoalSimulations.map2population!(f, leafA, edge2A_number, 6)
8

julia> length(f)
2

julia> f[2]
PhyloNetworks.EdgeT{PhyloNetworks.Node}:
 number:7
 length:0.0
 attached to 1 node(s) (parent first): 7

julia> [e.node[1].name for e in f]
2-element Vector{String}:
 "A"
 "A"

simulate_locuseffect!(
    rng::AbstractRNG,
    Y::Array,
    lab2index::Dict,
    gtree::PN.HybridNetwork,
    P0_name::String,
    P0_distribution::Distribution,
    transition_distribution_family
)

Simulate one trait along its gene tree gtree, starting at individuals in population named P0_name according to P0_distribution, and whose evolution, when starting at state y0 after time t, follows distribution transition_distribution_family(y0,t).

Y stores the simulated trait at the leaves: Y[i] is the trait for leaf i, where i is some fixed index for the leaf node: lab2index[leaf.name].

notes:

• the nodes' field booln5 is used to track which nodes have been simulated already. It is only used for a sanity check, only temporarily.
• if the trait is a scalar Float64, then is it stored in the gene tree itself, at each node in its field .fvalue.

simulatecoal_onepopulation!([rng::AbstractRNG,]
    lineagelist,
    population_length,
    nextlineageID,
    populationID=-1
)

Simulate the coalescent process within a single population of length given in coalescent units, starting from lineages in lineagelist. This list should be a vector of incomplete edges, that is, edges incident to a single node only.

Vector of incomplete edges, whose lengths have been increased, is modified in place. New nodes and their parent edges are created by coalescent events, numbered with consecutive integers starting at nextlineageID.

The random number generator rng is optional.

Output: nextlineageID, incremented by number of new lineages.

In lineages, edge lengths are also considered in coalescent units.

The newly created nodes and edges have their .intn1 & .inte1 attributes set to populationID, so as to track the mapping of gene lineages to populations in the species phylogeny.

examples

julia> PhyloCoalSimulations.simulatecoal_onepopulation!([], 2.0, 1)
1

julia> e1 = PhyloCoalSimulations.initializetip("s","1",1,"");

julia> e2 = PhyloCoalSimulations.initializetip("s","2",2,"");

julia> forest = [e1,e2];

julia> using Random; Random.seed!(7690);

julia> PhyloCoalSimulations.simulatecoal_onepopulation!(forest, Inf, 3);

julia> PhyloCoalSimulations.convert2tree!(forest[1].node[1])
PhyloNetworks.HybridNetwork, Rooted Network
2 edges
3 nodes: 2 tips, 0 hybrid nodes, 1 internal tree nodes.
tip labels: s2, s1
(s2:0.302,s1:0.302);