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 network with all nodes and edges that can be reached from rootnode. Warning: Assumes that edges are 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 of degree 2, has a single child, and has a name. (The root is of degree-2 but is not a mapping node).

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"

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);