diff --git a/previews/PR19/.documenter-siteinfo.json b/previews/PR19/.documenter-siteinfo.json
index 80fc57b..6b1e61a 100644
--- a/previews/PR19/.documenter-siteinfo.json
+++ b/previews/PR19/.documenter-siteinfo.json
@@ -1 +1 @@
-{"documenter":{"julia_version":"1.11.2","generation_timestamp":"2024-12-11T21:24:37","documenter_version":"1.8.0"}}
\ No newline at end of file
+{"documenter":{"julia_version":"1.11.2","generation_timestamp":"2024-12-11T21:42:30","documenter_version":"1.8.0"}}
\ No newline at end of file
diff --git a/previews/PR19/index.html b/previews/PR19/index.html
index 9654bee..038fd4e 100644
--- a/previews/PR19/index.html
+++ b/previews/PR19/index.html
@@ -1,2 +1,2 @@
-home · PhyloCoalSimulations.jl
PhyloCoalSimulations is a Julia package to simulate phylogenies under the coalescent. It depends on PhyloNetworks for the phylogenetic data structures, and manipulation of phylogenies.
for this package and the network coalescent model with inheritance correlation: Fogg, Allman & Ané (2023). PhyloCoalSimulations: A simulator for network multispecies coalescent models, including a new extension for the inheritance of gene flow. Systematic Biology, 72(5):1171–1179. doi:10.1093/sysbio/syad030.
PhyloCoalSimulations is a Julia package to simulate phylogenies under the coalescent. It depends on PhyloNetworks for the phylogenetic data structures, and manipulation of phylogenies.
for this package and the network coalescent model with inheritance correlation: Fogg, Allman & Ané (2023). PhyloCoalSimulations: A simulator for network multispecies coalescent models, including a new extension for the inheritance of gene flow. Systematic Biology, 72(5):1171–1179. doi:10.1093/sysbio/syad030.
Documentation for PhyloCoalSimulations's internal functions. These functions are not exported and their access (API) should not be considered stable. But they can still be used, like this for example: PhyloCoalSimulations.foo() for a function named foo().
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.
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.
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.
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.
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.
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);");
+internals · PhyloCoalSimulations.jl
Documentation for PhyloCoalSimulations's internal functions. These functions are not exported and their access (API) should not be considered stable. But they can still be used, like this for example: PhyloCoalSimulations.foo() for a function named foo().
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.
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.
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.
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.
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.
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;
@@ -22,7 +22,7 @@
julia> [e.node[1].name for e in f]
2-element Vector{String}:
"A"
- "A"
Given a gene tree with labeled internal nodes that map to a species phylogeny (a species tree or a species network), this function maps each gene edge to the species edge that it is contained "within". Gene edge mappings are stored in the inte1 field of each gene tree edge, but it's best to access this mapping via population_mappedto.
Assumption: the species_network has unique node names to uniquely identify the speciation and reticulation events; and the gene_tree has degree-2 nodes with matching names, to indicate which species event each degree-2 node corresponds to.
The checknames argument takes a boolean, and, if true, then the function will check that both the species and the gene phylogeny have the same internal node names. The mapping of edges is recovered from matching names between nodes in the gene tree and nodes in the species network.
Identifier of the population (edge in the species network) that a gene tree's edge or a node is mapped onto, or nothing if not mapped. For example, coalescent nodes in gene trees map to a node in the species phylogeny, instead of mapping to an edge.
Given a gene tree with labeled internal nodes that map to a species phylogeny (a species tree or a species network), this function maps each gene edge to the species edge that it is contained "within". Gene edge mappings are stored in the inte1 field of each gene tree edge, but it's best to access this mapping via population_mappedto.
Assumption: the species_network has unique node names to uniquely identify the speciation and reticulation events; and the gene_tree has degree-2 nodes with matching names, to indicate which species event each degree-2 node corresponds to.
The checknames argument takes a boolean, and, if true, then the function will check that both the species and the gene phylogeny have the same internal node names. The mapping of edges is recovered from matching names between nodes in the gene tree and nodes in the species network.
Identifier of the population (edge in the species network) that a gene tree's edge or a node is mapped onto, or nothing if not mapped. For example, coalescent nodes in gene trees map to a node in the species phylogeny, instead of mapping to an edge.
Simulate nloci gene trees with nindividuals from each species under the multispecies network coalescent, along network net whose branch lengths are assumed to be in coalescent units (ratio: number of generations / effective population size). The coalescent model uses the infinite-population-size approximation.
The random number generator rng is optional.
Output: vector of gene trees, of length nloci.
nindividuals can be a single integer, or a dictionary listing the number of individuals to be simulated for each species.
If nodemapping is true, each simulated gene tree is augmented with degree-2 nodes that can be mapped to speciation or hybridization events. The mapping of gene tree nodes & edges to network edges is carried by their attribute .intn1 (for nodes) and .inte1 (for edges). The mapping of gene tree nodes to network nodes is carried by the .name attribute. Namely:
A degree-3 node (1 parent + 2 children) represents a coalescent event that occurred along a population edge in net. Its .intn1 attribute is set to the number of that network population edge. Its parent edge has its .inte1 attribute also set to the number of the population edge that it originated from.
The gene tree's root node (of degree 2) represents a coalescent event along the network's root edge. Its .intn1 attribute is the number assigned to the network's root edge, which is set by get_rootedgenumber as the maximum edge number + 1.
A leaf (or degree-1 node) represents an individual. It maps to a species in net. The individual leaf name is set to the species name if nindividuals is 1. Otherwise, its name is set to speciesname_i where i is the individual number in that species. Its intn1 attribute is the default -1.
A non-root degree-2 node represents a speciation or hybridization and maps to a population node in net. Its intn1 attribute is the default -1. Its name is set to network node name, if it exists. If the network node has no name, the gene tree node is given a name built from the network node number.
By default, lineages at a hybrid node come from a parent (chosen according to inheritance probabilities γ) independently across lineages. Positive dependence can be simulated with option inheritancecorrelation. For example, if this correlation is set to 1, then all lineages inherit from the same (randomly sampled) parent. More generally, the lineages' parents are simulated according to a Dirichlet process with base distribution determined by the γ values, and with concentration parameter α = (1-r)/r, that is, r = 1/(1+α), where r is the input inheritance correlation. For more details about this model, please read the package manual or refer to Fogg, Allman & Ané (2023).
Assumptions:
net must have non-missing edge lengths and γ values.
If nindividuals is a dictionary, it must have a key for all species, with the same spelling of species names in its keys as in the tip labels of net.
Simulate nloci gene trees with nindividuals from each species under the multispecies network coalescent, along network net, whose branch lengths are assumed to be in number of generations. populationsize should be a single number, assumed to be the (haploid) effective population size Nₑ, constant across the species phylogeny. Alternatively, populationsize can be a dictionary mapping the number of each edge in net to its Nₑ, including an extra edge number for the population above the root of the network.
Coalescent units are then calculated as u=g/Nₑ where g is the edge length in net (number of generations), and the coalescent model is applied using the infinite-population-size approximation.
Output: vector of gene trees with edge lengths in number of generations, calculated as g=uNₑ and then rounded to be an integer, unless round_generationnumber is false.
Warning
When populationsize Nₑ is not provided as input, all edge lengths are in coalescent units. When populationsize is given as an argument, all edge lengths are in number of generations. The second method (using # generation and Nₑ as input) is a wrapper around the first (using coalescent units).
julia> using PhyloNetworks
@@ -105,4 +105,4 @@
julia> writeMultiTopology(genetrees, stdout) # branch lengths: number of generations
(B:546.0,A:546.0);
(B:3155.0,A:3155.0);
-
When Nₑ is given as an extra input to simulatecoalescent, edge lengths in the network are assumed to be in number of generations. If Nₑ is not given as input, then edge lengths are assumed to be in coalescent units.
Settings
This document was generated with Documenter.jl version 1.8.0 on Wednesday 11 December 2024. Using Julia version 1.11.2.
