descend_template_phylogeny_
Tools to create extant populations of hereditary stratigraph columns as if they had resulted from a given template phylogeny.
Functions
|
Generate a population of hereditary stratigraphic columns that could have resulted from the template phylogeny. |
|
Generate a population of hereditary stratigraphic instruments that could have resulted from the template phylogeny. |
|
Generate a population of hereditary stratigraphic instruments that could have resulted from the template phylogeny. |
|
Generate a population of hereditary stratigraphic instruments that could have resulted from the template phylogeny. |
|
Generate a population of hereditary stratigraphic instruments that could have resulted from the template phylogeny. |
|
Generate a population of hereditary stratigraphic instruments that could have resulted from the template phylogeny. |
|
Generate a population of hereditary stratigraphic columns that could have resulted from the template phylogeny. |
- descend_template_phylogeny(ascending_lineage_iterables: ~typing.Iterable[~typing.Iterable], descending_tree_iterable: ~typing.Iterable, get_parent: ~typing.Callable[[~typing.Any], ~typing.Any], get_stem_length: ~typing.Callable[[~typing.Any], int], seed_instrument: ~hstrat._auxiliary_lib.HereditaryStratigraphicInstrument, demark: ~typing.Callable[[~typing.Any], ~typing.Hashable] = <function demark>, progress_wrap: ~typing.Callable = <function <lambda>>) List[HereditaryStratigraphicInstrument]
Generate a population of hereditary stratigraphic columns that could have resulted from the template phylogeny.
Parameters
- ascending_lineage_iterablesiterable of phylogeny node iterables
Iterable that yields an acending lineage iterable for each extant individual from template phylogeny.
The acending lineage iterable should yield the extant individual’s phylogeny node object and then successive parent node objects until yielding the root node object.
- descending_tree_iterableiterable of phylogeny nodes
Iterable over all phylogeny node objects in template phylogeny.
The root node object must be yielded first. Then, each phylogeny node object should be yielded, with no object being yielded before its parent object. Any topologically sorted ordering is allowed, including pre-order depth-first iteration and breadth-first (a.k.a. level-order) iteration.
- get_parentfunction
Function that returns the parent node object for a phylogeny node object.
Will never be called on root node object.
- get_stem_lengthfunction
Function that returns the length of the subtending edge for a phylogeny node.
Length should be an integer value representing the number of generations elapsed between the focal node’s parent and the focal node. Will never be called on root node object.
For phylogenies including all ancestors as distinct nodes, lambda node: 1 can be specified.
- seed_instrumentHereditaryStratigraphicColumn
Hereditary stratigraphic column to seed at root node of phylogeny.
Returned hereditary stratigraphic column population will be generated as if repeatedly calling CloneDescendant() on seed_instrument. As such, specifies configuration (i.e., differentia bit width and stratum retention policy) for returned columns. May already have strata deposited, which will be incorporated into generated extant population.
- demarkfunction, default _auxiliary_lib.demark
Function that converts returned nodes to a unique hashable value.
For object-based Nodes, this might be id. For value-based Nodes, this might be an identity function.
If default, will use runtime type information to make a reasonable guess. Passing a custom value allows bypass of this slow type inspection.
- progress_wrapCallable, optional
Wrapper applied around generation iterator and row generator for final phylogeny compilation process.
Pass tqdm or equivalent to display progress bars.
Returns
- list of HereditaryStratigraphicColumn
Population of hereditary stratigraphic columns for extant lineage members.
Order of columns corresponds to order of ascending_lineage_iterables.
Notes
To improve performance, consider preprocessing template phylogeny representation to collapse unifurcation chains (i.e., converting chains of n nodes to a single node with stem length n).
Delegates to descend_template_phylogeny_naive or descend_template_phylogeny_posthoc, depending on whether retained ranks at an arbitrary generation can be calculated by the seed_instrument’s stratum retention policy.
- descend_template_phylogeny_alifestd(phylogeny_df: ~pandas.core.frame.DataFrame, seed_instrument: ~hstrat._auxiliary_lib.HereditaryStratigraphicInstrument, extant_ids: ~typing.Iterable[int] | None = None, progress_wrap: ~typing.Callable = <function <lambda>>) List[HereditaryStratigraphicInstrument]
Generate a population of hereditary stratigraphic instruments that could have resulted from the template phylogeny.
Parameters
- phylogeny_dfpandas.DataFrame
Phylogeny record as an alife-standard DataFrame.
- seed_instrumentHereditaryStratigraphicInstrument
Hereditary stratigraphic instrument to seed at root node of phylogeny.
Returned hereditary stratigraphic column population will be generated as if repeatedly calling CloneDescendant() on seed_instrument. As such, specifies configuration (i.e., differentia bit width and stratum retention policy) for returned columns. May already have strata deposited, which will be incorporated into generated extant population.
- extant_idsoptional list of int
Which organisms should hereditary stratigraphic instruments be created for?
Designates content and order of returned list of hereditary stratigraphic instrument, with id values corresponding to “id” instrument in phylogeny_df.
If None, hereditary stratigraphic instruments will be created for all phylogenetic leaves (organisms without offspring) in order of appearance in phylogeny_df.
- progress_wrapCallable, optional
Wrapper applied around generation iterator and row generator for final phylogeny compilation process.
Pass tqdm or equivalent to display progress bars.
Returns
- list of HereditaryStratigraphicInstrument
Population of hereditary stratigraphic instruments for extant lineage members (i.e., phylogeny leaf nodes).
Instruments ordered in order of appearance of corresponding extant organism id.
- descend_template_phylogeny_biopython(tree: ~Bio.Phylo.BaseTree.Tree, seed_instrument: ~hstrat._auxiliary_lib.HereditaryStratigraphicInstrument, extant_nodes: ~typing.Iterable[~Bio.Phylo.BaseTree.Clade] | None = None, progress_wrap: ~typing.Callable = <function <lambda>>) List[HereditaryStratigraphicInstrument]
Generate a population of hereditary stratigraphic instruments that could have resulted from the template phylogeny.
Parameters
- treebiopython Tree
Phylogeny record as a biopython Tree.
- seed_instrumentHereditaryStratigraphicInstrument
Hereditary stratigraphic instrument to seed at root node of phylogeny.
Returned hereditary stratigraphic instrument population will be generated as if repeatedly calling CloneDescendant() on seed_instrument. As such, specifies configuration (i.e., differentia bit width and stratum retention policy) for returned instruments. May already have strata deposited, which will be incorporated into generated extant population.
- extant_nodesoptional list of biopython Clade
Which organisms should hereditary stratigraphic instruments be created for?
Designates content and order of returned list of hereditary stratigraphic instrument.
If None, hereditary stratigraphic instruments will be created for all phylogenetic leaves (organisms without offspring) in order of appearance in tree.leaf_node_iter().
- progress_wrapCallable, optional
Wrapper applied around generation iterator and row generator for final phylogeny compilation process.
Pass tqdm or equivalent to display progress bars.
Returns
- list of HereditaryStratigraphicInstrument
Population of hereditary stratigraphic instruments for extant lineage members (i.e., phylogeny leaf nodes).
Instruments ordered in order of appearance of corresponding extant organism id.
- descend_template_phylogeny_dendropy(tree: ~dendropy.datamodel.treemodel._tree.Tree, seed_instrument: ~hstrat._auxiliary_lib.HereditaryStratigraphicInstrument, extant_nodes: ~typing.Iterable[~dendropy.datamodel.treemodel._node.Node] | None = None, progress_wrap: ~typing.Callable = <function <lambda>>) List[HereditaryStratigraphicInstrument]
Generate a population of hereditary stratigraphic instruments that could have resulted from the template phylogeny.
Parameters
- treedendropy.Tree
Phylogeny record as a dendropy Tree.
- seed_instrumentHereditaryStratigraphicInstrument
Hereditary stratigraphic instrument to seed at root node of phylogeny.
Returned hereditary stratigraphic instrument population will be generated as if repeatedly calling CloneDescendant() on seed_instrument. As such, specifies configuration (i.e., differentia bit width and stratum retention policy) for returned instruments. May already have strata deposited, which will be incorporated into generated extant population.
- extant_nodesoptional list of dendropy.Node
Which organisms should hereditary stratigraphic instruments be created for?
Designates content and order of returned list of hereditary stratigraphic instrument.
If None, hereditary stratigraphic instruments will be created for all phylogenetic leaves (organisms without offspring) in order of appearance in tree.leaf_node_iter().
- progress_wrapCallable, optional
Wrapper applied around generation iterator and row generator for final phylogeny compilation process.
Pass tqdm or equivalent to display progress bars.
Returns
- list of HereditaryStratigraphicInstrument
Population of hereditary stratigraphic instruments for extant lineage members (i.e., phylogeny leaf nodes).
Instruments ordered in order of appearance of corresponding extant organism id.
- descend_template_phylogeny_naive(ascending_lineage_iterables: ~typing.Iterable[~typing.Iterable], descending_tree_iterable: ~typing.Iterable, get_parent: ~typing.Callable[[~typing.Any], ~typing.Any], get_stem_length: ~typing.Callable[[~typing.Any], int], seed_instrument: ~hstrat._auxiliary_lib.HereditaryStratigraphicInstrument, demark: ~typing.Callable[[~typing.Any], ~typing.Hashable] = <function demark>, progress_wrap: ~typing.Callable = <function <lambda>>) List[HereditaryStratigraphicInstrument]
Generate a population of hereditary stratigraphic instruments that could have resulted from the template phylogeny.
Traverses phylogenetic tree in topological order, generating a clone instrument with get_stem_length(node) additional stratum deposits for each node (including internal nodes). Uses CloneNthDescendant() instead of n calls to CloneDescendant() to improve efficiency where get_stem_length(node) > 1.
Prefer to use descend_template_phylogeny, which will automatically delegate between naive and posthoc implementation, unless performance considerations merit manual override.
- descend_template_phylogeny_networkx(tree: ~networkx.classes.digraph.DiGraph, seed_instrument: ~hstrat._auxiliary_lib.HereditaryStratigraphicInstrument, extant_nodes: ~typing.Iterable[~typing.Any] | None = None, progress_wrap: ~typing.Callable = <function <lambda>>) List[HereditaryStratigraphicInstrument]
Generate a population of hereditary stratigraphic instruments that could have resulted from the template phylogeny.
Parameters
- treenx.DiGraph
Phylogeny record as a networkx DiGraph.
Assumes directed edges point from ancestor to descendant. Does not support non-unit edge length.
- seed_instrumentHereditaryStratigraphicInstrument
Hereditary stratigraphic instrument to seed at root node of phylogeny.
Returned hereditary stratigraphic instrument population will be generated as if repeatedly calling CloneDescendant() on seed_instrument. As such, specifies configuration (i.e., differentia bit width and stratum retention policy) for returned instruments. May already have strata deposited, which will be incorporated into generated extant population.
- extant_nodesoptional list of networkx nodes
Which organisms should hereditary stratigraphic instruments be created for?
Designates content and order of returned list of hereditary stratigraphic instrument.
If None, hereditary stratigraphic instruments will be created for all phylogenetic leaves (organisms without offspring) in order of appearance in tree.nodes.
- progress_wrapCallable, optional
Wrapper applied around generation iterator and row generator for final phylogeny compilation process.
Pass tqdm or equivalent to display progress bars.
Returns
- list of HereditaryStratigraphicInstrument
Population of hereditary stratigraphic instruments for extant lineage members (i.e., phylogeny leaf nodes).
Instruments ordered in order of appearance of corresponding extant organism id.
- descend_template_phylogeny_posthoc(ascending_lineage_iterables: ~typing.Iterable[~typing.Iterable], descending_tree_iterable: ~typing.Iterable, get_parent: ~typing.Callable[[~typing.Any], ~typing.Any], get_stem_length: ~typing.Callable[[~typing.Any], int], seed_instrument: ~hstrat._auxiliary_lib.HereditaryStratigraphicInstrument, demark: ~typing.Callable[[~typing.Any], ~typing.Hashable] = <function demark>, progress_wrap: ~typing.Callable = <function <lambda>>) List[HereditaryStratigraphicInstrument]
Generate a population of hereditary stratigraphic columns that could have resulted from the template phylogeny.
Calculates required ranks according to stratum retention policy for each extant lineage member, creating returned columns with strata at those ranks. Uses cache lookup to ensure that identical strata are provided where extant lineage members share common ancestry.
Requires seed_instrument to be HereditaryStratigraphicSurface or to be a HereditaryStratigraphicColumn with a stratum retention policy that provides IterRetainedRanks().
Prefer to use descend_template_phylogeny, which will automatically delegate to posthoc implementation if stratum retention policy requirements are met. See descend_template_phylogeny for parameter and return value details.