trie_postprocess

Implementation helpers.

Classes

AssignDestructionTimeYoungestPlusOneTriePostprocessor	Functor to assign a destruction time property to trie nodes.
AssignOriginTimeExpectedValueTriePostprocessor	Functor to assign origin time property to trie nodes using expected values over the distribution of possible differentia collisions.
AssignOriginTimeNaiveTriePostprocessor	Functor to assign origin time property to trie nodes calculated as the average of the node's rank and the minimum rank among its children.
AssignOriginTimeNodeRankTriePostprocessor	Functor to assign trie nodes' rank as their the origin time.
AssignOriginTimeSampleNaiveTriePostprocessor	Functor to assign origin time property to trie nodes sampled between the node's rank and the minimum rank among its children.
CompoundTriePostprocessor	Functor to sequentially apply multiple trie postprocessors.
PeelBackConjoinedLeavesTriePostprocessor	Functor to separate any TrieLeafNode instances that are direct siblings.
SampleAncestralRollbacksTriePostprocessor	Functor to correct for systematic overestimation of relatedness by sampling a compensatory adjustment to trie topology.

class AssignDestructionTimeYoungestPlusOneTriePostprocessor

Functor to assign a destruction time property to trie nodes.

Destruction time of leaf nodes are set to infinity. Destruction time of inner nodes is calculated as the minimum of its children’s origin times plus one.

__init__(assigned_property: str = 'destruction_time', origin_time_property: str = 'origin_time') → None

Initialize functor instance.

Parameters

assigned_propertystr, default “destruction_time”

The property name for the assigned destruction tim.

origin_time_propertystr, default “origin_time”

The property name for the node’s origin time.

__call__(trie: ~hstrat.phylogenetic_inference.tree._impl._TrieInnerNode.TrieInnerNode, p_differentia_collision: float, mutate: bool = False, progress_wrap: ~typing.Callable = <function AssignDestructionTimeYoungestPlusOneTriePostprocessor.<lambda>>) → TrieInnerNode

Assign destruction times to trie nodes based on their childrens’ origin times.

Parameters

trieTrieInnerNode

The input trie to be postprocessed.

p_differentia_collisionfloat

The multiplicative inverse of the number of possible differentia.

Not used in the current implementation.

mutatebool, default False

Are side effects on the input argument trie allowed?

progress_wraptyping.Callable, optional

Pass tqdm or equivalent to report progress.

Returns

TrieInnerNode

The postprocessed trie with assigned destruction times.

class AssignOriginTimeExpectedValueTriePostprocessor

Functor to assign origin time property to trie nodes using expected values over the distribution of possible differentia collisions.

Computes the origin time of trie nodes based on the expected value, taking into account the probability of differentia collision and the prior distribution expected for ancestor origin times.

__init__(prior: PriorBase, assigned_property: str = 'origin_time') → None

Initialize functor instance.

Parameters

priorPriorBase

The prior distribution used to calculate expected values.

assigned_propertystr, default “origin_time”

The property name for the assigned origin time.

__call__(trie: ~hstrat.phylogenetic_inference.tree._impl._TrieInnerNode.TrieInnerNode, p_differentia_collision: float, mutate: bool = False, progress_wrap: ~typing.Callable = <function AssignOriginTimeExpectedValueTriePostprocessor.<lambda>>) → TrieInnerNode

Assign origin times to trie nodes.

Parameters

trieTrieInnerNode

The input trie to be postprocessed.

p_differentia_collisionfloat

Probability of a randomly-generated differentia matching an existing differentia.

mutatebool, default False

Are side effects on the input argument trie allowed?

progress_wraptyping.Callable, optional

Pass tqdm or equivalent to report progress.

Returns

TrieInnerNode

The postprocessed trie with assigned origin times.

class AssignOriginTimeNaiveTriePostprocessor

Functor to assign origin time property to trie nodes calculated as the average of the node’s rank and the minimum rank among its children.

Optionally calculates origin time expected value over this interval for a provided prior distribution.

__init__(prior: ~hstrat.phylogenetic_inference.priors._detail._PriorBase.PriorBase = <hstrat.phylogenetic_inference.priors.ArbitraryPrior object>, assigned_property: str = 'origin_time') → None

Initialize functor instance.

Parameters

priorPriorBase, default ArbitraryPrior()

Prior distribution of ancestor origin times.

Used to calculate interval means.

assigned_propertystr, default “origin_time”

The property name for the assigned origin time.

__call__(trie: ~hstrat.phylogenetic_inference.tree._impl._TrieInnerNode.TrieInnerNode, p_differentia_collision: float, mutate: bool = False, progress_wrap: ~typing.Callable = <function AssignOriginTimeNaiveTriePostprocessor.<lambda>>) → TrieInnerNode

Assign origin times to trie nodes.

Parameters

trieTrieInnerNode

The input trie to be postprocessed.

p_differentia_collisionfloat

Probability of a randomly-generated differentia matching an existing differentia.

Not used in the current implementation.

mutatebool, default False

Are side effects on the input argument trie allowed?

progress_wraptyping.Callable, optional

Pass tqdm or equivalent to report progress.

Returns

TrieInnerNode

The postprocessed trie with assigned origin times.

class AssignOriginTimeNodeRankTriePostprocessor

Functor to assign trie nodes’ rank as their the origin time.

__init__(assigned_property: str = 'origin_time') → None

Initialize functor instance.

Parameters

assigned_propertystr, default “origin_time”

The property name for the assigned origin time.

__call__(trie: ~hstrat.phylogenetic_inference.tree._impl._TrieInnerNode.TrieInnerNode, p_differentia_collision: float, mutate: bool = False, progress_wrap: ~typing.Callable = <function AssignOriginTimeNodeRankTriePostprocessor.<lambda>>) → TrieInnerNode

Assign origin times to trie nodes.

Parameters

trieTrieInnerNode

The input trie to be postprocessed.

p_differentia_collisionfloat

Probability of a randomly-generated differentia matching an existing differentia. Not used in the current implementation.

mutatebool, default False

Are side effects on the input argument trie allowed?

progress_wraptyping.Callable, optional

Pass tqdm or equivalent to report progress.

Returns

TrieInnerNode

The postprocessed trie with assigned origin times.

class AssignOriginTimeSampleNaiveTriePostprocessor

Functor to assign origin time property to trie nodes sampled between the node’s rank and the minimum rank among its children.

A prior may be provided to customize sampling distribution used.

__init__(prior: ~hstrat.phylogenetic_inference.priors._detail._PriorBase.PriorBase = <hstrat.phylogenetic_inference.priors.ArbitraryPrior object>, assigned_property: str = 'origin_time') → None

Initialize functor instance.

Parameters

priorPriorBase, default ArbitraryPrior()

Prior distribution of ancestor origin times.

Used to calculate interval samples.

assigned_propertystr, default “origin_time”

The property name for the assigned origin time.

__call__(trie: ~hstrat.phylogenetic_inference.tree._impl._TrieInnerNode.TrieInnerNode, p_differentia_collision: float, mutate: bool = False, progress_wrap: ~typing.Callable = <function AssignOriginTimeSampleNaiveTriePostprocessor.<lambda>>) → TrieInnerNode

Assign origin times to trie nodes.

Parameters

trieTrieInnerNode

The input trie to be postprocessed.

p_differentia_collisionfloat

Probability of a randomly-generated differentia matching an existing differentia.

Not used in the current implementation.

mutatebool, default False

Are side effects on the input argument trie allowed?

progress_wraptyping.Callable, optional

Pass tqdm or equivalent to report progress.

Returns

TrieInnerNode

The postprocessed trie with assigned origin times.

class CompoundTriePostprocessor

Functor to sequentially apply multiple trie postprocessors.

Allows for the combination and sequential application of multiple trie postprocessors.

__init__(postprocessors: Iterable[TriePostprocessorBase]) → None

Initialize functor instance.

Parameters

postprocessorstyping.Iterable[TriePostprocessorBase]

The sequence of postprocess functors to be applied.

__call__(trie: ~hstrat.phylogenetic_inference.tree._impl._TrieInnerNode.TrieInnerNode, p_differentia_collision: float, mutate: bool = False, progress_wrap: ~typing.Callable = <function CompoundTriePostprocessor.<lambda>>) → TrieInnerNode

Apply stored postprocessors in sequence.

Parameters

trieTrieInnerNode

The input trie to be postprocessed.

p_differentia_collisionfloat

Probability of a randomly-generated differentia matching an existing differentia.

Forwarded to the postprocess functors.

mutatebool, default False

Are side effects on the input argument trie allowed?

progress_wraptyping.Callable, optional

Pass tqdm or equivalent to report progress.

Returns

TrieInnerNode

The postprocessed trie after applying all stored postprocessors.

class PeelBackConjoinedLeavesTriePostprocessor

Functor to separate any TrieLeafNode instances that are direct siblings.

Corrects for guaranteed-spurious differentia collisions among most-recent strata.

__call__(trie: ~hstrat.phylogenetic_inference.tree._impl._TrieInnerNode.TrieInnerNode, p_differentia_collision: float, mutate: bool = False, progress_wrap: ~typing.Callable = <function PeelBackConjoinedLeavesTriePostprocessor.<lambda>>) → TrieInnerNode

Peel apart any TrieLeafNode nodes that are direct siblings.

Without reproduction dynamics that allow columns to be cloned without stratum deposit, two hereditary stratigraphic columns can only share their most-recent strata by collision.

Clones the sibling leaves’ parent node and attaches it to the the siblings’ grandparent node. One sibling node is then grafted away from its original parent and attached onto the newly cloned parent node as a child. The original parent node is left in place with any remaining children. This process is repeated until no TrieLeafNode’s remain as direct siblings.

Parameters:

trieTrieInnerNode

The root node of the trie to be unzipped.

p_differentia_collisionfloat

The multiplicative inverse of the number of possible differentia.

This fraction of possible rollbacks are performed.

mutatebool, default False

Are side effects on the input argument trie allowed?

progress_wraptyping.Callable, optional

Pass tqdm or equivalent to report progress.

Returns

TrieInnerNode

The postprocessed trie.

class SampleAncestralRollbacksTriePostprocessor

Functor to correct for systematic overestimation of relatedness by sampling a compensatory adjustment to trie topology.

__init__(seed: int | None = None) → None

Initialize functor instance.

Parameters:

seed: int, default

Controls sampling decisions in the algorithm.

Pass an int for reproducible output across multiple function calls. The default value, 1, ensures reproducible output. Pass None to use existing RNG context directly.

__call__(trie: ~hstrat.phylogenetic_inference.tree._impl._TrieInnerNode.TrieInnerNode, p_differentia_collision: float, mutate: bool = False, progress_wrap: ~typing.Callable = <function SampleAncestralRollbacksTriePostprocessor.<lambda>>) → TrieInnerNode

Compensate for bias towards overestimating relatedness due to spurious differentia collisions.

Each rollback operation alters the tree as if a single spurious collision had occured; a single branch is adjusted to exhibit the next- most-ancient last commonality.

The number of rollback operations is calculated from the number of possible spurious collisions and the probability of spurious collision. Unzip targets are sampled randomly using the standard library random module.

Parameters:

trieTrieInnerNode

The root node of the trie to be unzipped.

p_differentia_collisionfloat

The multiplicative inverse of the number of possible differentia.

This fraction of possible rollbacks are performed.

mutatebool, default False

Are side effects on the input argument trie allowed?

progress_wraptyping.Callable, optional

Pass tqdm or equivalent to report progress.

Returns

TrieInnerNode

The postprocessed trie.

Notes:

This function assumes underlying shared genesis, so the root node of the trie is not eligible for rollback.