genome_instrumentation
Data structures to annotate genomes with.
Modules
Strata storage implementations for use with HereditaryStratigraphicColumn. |
Forwarded Modules
Modules defined elsewhere made available in this namespace for convenience. To view documentation for these modules, use the search bar or navigate to the source package manually.
|
Built-in mutable sequence. |
Classes
Genetic annotation to enable phylogenetic inference. |
|
Packages multiple HereditaryStratigraphicColumn instances together. |
|
Packages stratigraph data associated with a particular generation. |
|
Interchangeable backing container for HereditaryStratigraphicColumn. |
|
Interchangeable backing container for HereditaryStratigraphicColumn. |
|
Interchangeable backing container for HereditaryStratigraphicColumn. |
- class HereditaryStratigraphicColumn
Genetic annotation to enable phylogenetic inference.
Primary end-user facing interface for hstrat library. Should be bundled with digital genomes and propagated via the CloneDescendant method when passing those genomes from parent to offspring. Provides basis for phylogenetic analysis of distributed digital evolution populations.
Naming conventions are derived by analogy to Geological “Stratigraphy” (i.e., <https://en.wikipedia.org/wiki/Stratigraphy>). The “hereditary stratigraphy” system provided by this software works by associating an identifier, referred to as a “stratum,” with each elapsed generation along a line of descent. This allows two “columns” to be aligned to detect the generation of their most recent common ancestor: strata before the MRCA will be identical and strata after will differ.
Stratum retention policy and stratum differentia bit width can be configured to tune the time and space complexity of the column, trading-off with uncertainty induced on estimates of phylogenetic distance back to the most common recent ancestor of two columns.
Arbitrary user-defined data can be associated with strata by optional argument to the CloneDescendant method. (Note that a first stratum is deposited during column initialization, so an optional annotation argument may also be provided then.)
- CalcMinImplausibleSpuriousConsecutiveDifferentiaCollisions(significance_level: float) int[source]
Determine amount of evidence required to indicate shared ancestry.
Calculates how many differentia collisions are required to reject the null hypothesis that columns do not share common ancestry at those ranks at significance level significance_level.
Deprecated since version 1.6.0: Use calc_min_implausible_spurious_differentia_collisions_between
- CalcProbabilityDifferentiaCollision() float[source]
How likely are differentia collisions?
Calculates the probability of two randomly-differentiated differentia being identical by coincidence.
Deprecated since version 1.6.0: Use calc_probability_differentia_collision_between
- Clone() HereditaryStratigraphicColumn[source]
Create an independent copy of the column.
Contains identical data but may be freely altered without affecting data within this column.
- CloneDescendant(stratum_annotation: Any | None = None) HereditaryStratigraphicColumn[source]
Return a cloned column that has had an additional stratum deposited.
Does not alter self.
Parameters
- stratum_annotation: any, optional
Optional object to store as an annotation. Allows arbitrary user- provided to be associated with this stratum deposition in the line of descent.
- CloneNthDescendant(num_stratum_depositions: int) HereditaryStratigraphicColumn[source]
Return a cloned column that has had n additional strata deposited.
Does not alter self.
Parameters
- num_stratum_depositions: int
How many generations should clone column be descended?
- DepositStrata(num_stratum_depositions: int) None[source]
Elapse n generations.
Parameters
- num_stratum_depositions: int
How many generations to elapse?
- DepositStratum(annotation: Any | None = None) None[source]
Elapse a generation.
Parameters
- annotation: any, optional
Optional object to store as an annotation. Allows arbitrary user- provided to be associated with this stratum deposition in the line of descent.
- GetColumnIndexOfRank(rank: int) int | None[source]
Map generation of deposition to column position.
What is the index position within retained strata of the stratum deposited at rank r? Returns None if no stratum with rank r is present within the store.
- GetNumDiscardedStrata() int[source]
How many deposited strata have been discarded?
Determined by number of generations elapsed and the configured column retention policy.
- GetNumStrataDeposited() int[source]
How many strata have been depostited on the column?
Note that a first stratum is deposited on the column during initialization.
- GetNumStrataRetained() int[source]
How many strata are currently stored within the column?
May be fewer than the number of strata deposited if strata have been discarded as part of the configured stratum retention policy.
- GetRankAtColumnIndex(index: int) int[source]
Map column position to generation of deposition.
What is the deposition rank of the stratum positioned at index i among retained strata? Index order is from most ancient (index 0) to most recent.
- GetStratumAtColumnIndex(index: int) HereditaryStratum[source]
Get the stratum positioned at index i among retained strata.
Index order is from most ancient (index 0) to most recent.
- GetStratumAtRank(rank: int) HereditaryStratum | None[source]
Get the stratum deposited at generation g.
Returns None if stratum with rank g is not retained.
- IterRankDifferentiaZip(copyable: bool = False) Iterator[Tuple[int, int]][source]
Iterate over ranks of retained strata and their differentia.
If copyable, return an iterator that can be copied to produce a new fully-independent iterator at the same position.
Equivalent to zip(col.IterRetainedRanks(), col.IterRetainedDifferentia()), but may be more efficient.
- IterRetainedDifferentia() Iterator[int][source]
Iterate over differentia of strata stored in the column.
Differentia yielded from most ancient to most recent.
- IterRetainedRanks() Iterator[int][source]
Iterate over deposition ranks of strata stored in the column.
The store may be altered during iteration without iterator invalidation, although subsequent updates will not be reflected in the iterator.
- IterRetainedStrata() Iterator[HereditaryStratum][source]
Iterate over strata stored in the column. Strata yielded from most ancient to most recent.
- __init__(stratum_retention_policy: Any = perfect_resolution_algo.Policy(policy_spec=perfect_resolution_algo.PolicySpec()), *, always_store_rank_in_stratum: bool = True, stratum_differentia_bit_width: int = 64, initial_stratum_annotation: Any | None = None, stratum_ordered_store: Callable[[...], HereditaryStratumOrderedStoreBase] | Tuple[HereditaryStratumOrderedStoreBase, int] | None = None, stratum_ordered_store_factory: Callable[[...], HereditaryStratumOrderedStoreBase] | Tuple[HereditaryStratumOrderedStoreBase, int] | None = None)[source]
Initialize column to track a new line of descent.
Deposits a first stratum, so GetNumStrataDeposited() will return 1 after initialization even though the user has not yet called DepositStratum().
Parameters
- stratum_retention_policyany
Policy struct that implements stratum retention policy by specifying the set of strata ranks that should be pruned from a hereditary stratigraphic column when the nth stratum is deposited.
- always_store_rank_in_stratumbool, optional
Should the deposition rank be stored as a data member of generated strata, even if not strictly necessary?
- stratum_differentia_bit_widthint, optional
The bit width of the generated differentia. Default 64, allowing for 2^64 distinct values.
- initial_stratum_annotation: any, optional
Optional object to store as an annotation. Allows arbitrary user- provided to be associated with the first stratum deposition in the line of descent.
- stratum_ordered_store: callable or tuple of store and count, optional
One of: * callable to generate a container that implements the necessary interface to store strata within the column; can be configured for performance reasons, but has no semantic effect. * instance of one aforementioned container along with a deposition count * None, in which case a default-initialized container will be used
stratum_ordered_store_factory: deprecated, alias of stratum_ordered_store.
Notes
If no condemner or predicate functor specifying a stratum retention policy is provided, the perfect resolution policy where all strata are retained is used.
- class HereditaryStratigraphicColumnBundle
Packages multiple HereditaryStratigraphicColumn instances together.
Allows packaged columns to conveniently advance in sync along a line of descent with a similar interface to an individual HereditaryStratigraphicColumn.
- Clone() HereditaryStratigraphicColumnBundle[source]
Create a copy of the bundle.
Copy contains identical data but may be freely altered without affecting data within this bundle.
- CloneDescendant(stratum_annotation: Any | None = None) HereditaryStratigraphicColumnBundle[source]
Return a cloned bundle that has had an additional stratum deposited.
Does not alter self.
Parameters
- stratum_annotation: any, optional
Optional object to store as an annotation. Allows arbitrary user- provided to be associated with this stratum deposition in the line of descent.
- DepositStratum(annotation: Any | None = None) None[source]
Elapse a generation on all constituent columns.
Parameters
- annotation: any, optional
Optional object to store as an annotation. Allows arbitrary user- provided to be associated with this stratum’s generation in its line of descent.
- GetNumStrataDeposited() int[source]
How many strata have been deposited on constituent columns?
Should be identical across constituent columns.
- __init__(columns: Dict[str, HereditaryStratigraphicColumn])[source]
Construct bundle.
Parameters
- columnsdict
HereditaryStratigraphicColumn objects to bundle together, each associated with a unique names as its key.
- class HereditaryStratum
Packages stratigraph data associated with a particular generation.
Includes differentia “fingerprint” associated with a particular generation of a line of descent and possibly additional metadata, including optional user-provided annotation.
- GetDepositionRank() int | None[source]
Get the deposition order rank associated with this stratum, if stored.
Deposition rank is the number of strata deposited on a column before self. Deposition rank may not be stored if the stratum retention policy supports calculation of deposition rank from column index.
- GetDifferentia() int[source]
Access differentia.
Returns the randomly-generated value that distinguishes this stratum from others generated at the same rank in other hereditary columns.
- __init__(*, annotation: Any | None = None, differentia_bit_width: int = 64, deposition_rank: int | None = None, differentia: int | None = None)[source]
Construct the stratum.
Randomly generates and stores a differentia “fingerprint” alongside other metadata, if provided.
Parameters
- annotation: any, optional
Optional object to store as an annotation. Allows arbitrary user- provided to be associated with this stratum’s generation in its line of descent.
- differentia_bit_width: int, optional
The bit width of the generated differentia. Default 64, allowing for 2^64 distinct values.
- deposition_rankint, optional
The position of the stratum being deposited within the sequence of strata deposited into the column. Precisely, the number of strata that have been deposited before stratum.
- class HereditaryStratumOrderedStoreDict
Interchangeable backing container for HereditaryStratigraphicColumn.
Stores deposited strata using a dict implementation. Retained strata are stored as dict values with their associated deposition ranks as keys.
Potentially useful in scenarios where large strata counts are retained or deleted strata tend to be more ancient.
- Clone() HereditaryStratumOrderedStoreDict[source]
Create an independent copy of the store.
Returned copy contains identical data but may be freely altered without affecting data within this store.
- DelRanks(ranks: Iterable[int], get_column_index_of_rank: Callable | None = None) None[source]
Purge strata with specified deposition ranks from the store.
Parameters
- ranksiterator over int
The ranks that are to be deleted.
- get_column_index_of_rankcallable, optional
Callable that returns the deposition rank of the stratum positioned at index i among retained strata. Not used in this method.
- DepositStratum(rank: int | None, stratum: HereditaryStratum) None[source]
Insert a new stratum into the store.
Parameters
- ranktyping.Optional[int]
The position of the stratum being deposited within the sequence of strata deposited into the column. Precisely, the number of strata that have been deposited before stratum.
- stratumHereditaryStratum
The stratum to deposit.
- GetColumnIndexOfRank(rank: int) int | None[source]
Map column position ot deposition generation.
What is the index position within retained strata of the stratum deposited at rank r? Returns None if no stratum with rank r is present within the store.
- GetNumStrataRetained() int[source]
How many strata are present in the store?
May be fewer than the number of strata deposited if deletions have occured.
- GetRankAtColumnIndex(index: int) int[source]
Map deposition generation to column position.
What is the deposition rank of the stratum positioned at index i among retained strata? Index order is from most ancient (index 0) to most recent.
- GetStratumAtColumnIndex(index: int, get_rank_at_column_index: Callable | None = None) HereditaryStratum[source]
Get the stratum positioned at index i among retained strata.
Index order is from most ancient (index 0) to most recent.
Parameters
- ranksiterator over int
The ranks that are to be deleted.
- get_column_index_of_rankcallable, optional
Callable that returns the index position within retained strata of the stratum deposited at rank r.
- IterRankDifferentiaZip(get_rank_at_column_index: Callable | None = None, start_column_index: int = 0) Iterator[Tuple[int, int]][source]
Iterate over differentia and corresponding deposition ranks.
Values yielded as tuples. Guaranteed ordered from most ancient to most recent.
Parameters
- get_rank_at_column_indexcallable, optional
Callable that returns the deposition rank of the stratum positioned at index i among retained strata.
- start_column_indexcallable, optional
Number of strata to skip over before yielding first result from the iterator. Default 0, meaning no strata are skipped over.
- IterRetainedRanks() Iterator[int][source]
Iterate over deposition ranks of strata present in the store from most ancient to most recent.
The store may be altered during iteration without iterator invalidation, although subsequent updates will not be reflected in the iterator.
- IterRetainedStrata() Iterator[HereditaryStratum][source]
Iterate over stored strata from most ancient to most recent.
- class HereditaryStratumOrderedStoreList
Interchangeable backing container for HereditaryStratigraphicColumn.
Stores deposited strata using a list implementation. Retained strata are stored from most ancient (index 0, front) to most recent (back). Cloned stores instantiate an independent list (although strata are not deepcopied themselves).
Potentially useful in scenarios where moderate strata counts are retained, many strata are deposited without column cloning, deleted strata tend to be more recent (i.e., not more ancient and toward the front of the list), or many comparisons to estimate most recent common ancestor are made between stratigraphic columns.
- Clone() HereditaryStratumOrderedStoreList[source]
Create an independent copy of the store.
Returned copy contains identical data but may be freely altered without affecting data within this store.
- DelRanks(ranks: Iterator[int], get_column_index_of_rank: Callable | None = None) None[source]
Purge strata with specified deposition ranks from the store.
Parameters
- ranksiterator over int
The ranks that are to be deleted.
- get_column_index_of_rankcallable, optional
Callable that returns the deposition rank of the stratum positioned at index i among retained strata.
- DepositStratum(rank: int | None, stratum: HereditaryStratum) None[source]
Insert a new stratum into the store.
Parameters
- ranktyping.Optional[int]
The position of the stratum being deposited within the sequence of strata deposited into the column. Precisely, the number of strata that have been deposited before stratum.
- stratumHereditaryStratum
The stratum to deposit.
- GetColumnIndexOfRank(rank: int) int | None[source]
Map from column position to deposition generation
What is the index position within retained strata of the stratum deposited at rank r? Returns None if no stratum with rank r is present within the store.
- GetNumStrataRetained() int[source]
How many strata are present in the store?
May be fewer than the number of strata deposited if deletions have occured.
- GetRankAtColumnIndex(index: int) int[source]
Map from deposition generation to column position.
What is the deposition rank of the stratum positioned at index i among retained strata? Index order is from most ancient (index 0) to most recent.
- GetStratumAtColumnIndex(index: int, get_rank_at_column_index: Callable | None = None) HereditaryStratum[source]
Get the stratum positioned at index i among retained strata.
Index order is from most ancient (index 0) to most recent.
Parameters
- ranksiterator over int
The ranks that are to be deleted.
- get_column_index_of_rankcallable, optional
Callable that returns the index position within retained strata of the stratum deposited at rank r.
- IterRankDifferentiaZip(get_rank_at_column_index: Callable | None = None, start_column_index: int = 0) Iterator[Tuple[int, int]][source]
Iterate over differentia and corresponding deposition ranks.
Values yielded as tuples. Guaranteed ordered from most ancient to most recent.
Parameters
- get_rank_at_column_indexcallable, optional
Callable that returns the deposition rank of the stratum positioned at index i among retained strata.
- start_column_indexcallable, optional
Number of strata to skip over before yielding first result from the iterator. Default 0, meaning no strata are skipped over.
- IterRetainedRanks() Iterator[int][source]
Iterate over deposition ranks of strata present in the store from most ancient to most recent.
The store may be altered during iteration without iterator invalidation, although subsequent updates will not be reflected in the iterator.
- IterRetainedStrata() Iterator[HereditaryStratum][source]
Iterate over stored strata from most ancient to most recent.
- class HereditaryStratumOrderedStoreTree
Interchangeable backing container for HereditaryStratigraphicColumn.
Stores deposited strata as a linked tree. Retained strata pertinent to the store are essentially a linear linked list reaching from tree leaf (most recent stratum) back to the tree root (most ancient stratum). Cloned stores directly share common components of the tree and then branch out different leaves as subsequent strata are deposited. Stratum deletion results in the entire strata sequence more recent than the deleted stratum being copied into an independent branch for the store that requested the deletion.
Potentially useful in scenarios where stratum deletions are uncommon (i.e., the perfect resolution stratum retention policy) or column cloning occurs heavily without much stratum deposition.
- Clone() HereditaryStratumOrderedStoreTree[source]
Create an independent copy of the store.
Returned copy contains identical data but may be freely altered without affecting data within this store.
- DelRanks(ranks: Iterator[int], get_column_index_of_rank: Callable | None = None) None[source]
Purge strata with specified deposition ranks from the store.
Parameters
- ranksiterator over int
The ranks that are to be deleted.
- get_column_index_of_rankcallable, optional
Callable that returns the deposition rank of the stratum positioned at index i among retained strata.
- DepositStratum(rank: int | None, stratum: HereditaryStratum) None[source]
Insert a new stratum into the store.
Parameters
- ranktyping.Optional[int]
The position of the stratum being deposited within the sequence of strata deposited into the column. Precisely, the number of strata that have been deposited before stratum.
- stratumHereditaryStratum
The stratum to deposit.
- GetColumnIndexOfRank(rank: int) int | None[source]
Map from column position to deposition generation.
What is the index position within retained strata of the stratum deposited at rank r? Returns None if no stratum with rank r is present within the store.
- GetNumStrataRetained() int[source]
How many strata are present in the store?
May be fewer than the number of strata deposited if deletions have occured.
- GetRankAtColumnIndex(index: int) int[source]
Map from deposition generation to column position.
What is the deposition rank of the stratum positioned at index i among retained strata?
- GetStratumAtColumnIndex(index: int, get_rank_at_column_index: Callable | None = None) HereditaryStratum[source]
Get the stratum positioned at index i among retained strata.
Index order is from most ancient (index 0) to most recent.
Parameters
- ranksiterator over int
The ranks that are to be deleted.
- get_column_index_of_rankcallable, optional
Callable that returns the index position within retained strata of the stratum deposited at rank r.
- IterRankDifferentiaZip(get_rank_at_column_index: Callable | None = None, start_column_index: int = 0) Iterator[Tuple[int, int]][source]
Iterate over differentia and corresponding depsotion rank.
Values yielded as tuples. Guaranteed ordered from most ancient to most recent.
Parameters
- get_rank_at_column_indexcallable, optional
Callable that returns the deposition rank of the stratum positioned at index i among retained strata.
- start_column_indexcallable, optional
Number of strata to skip over before yielding first result from the iterator. Default 0, meaning no strata are skipped over.
- IterRetainedRanks() Iterator[int][source]
Iterate over deposition ranks of strata present in the store from most ancient to most recent.
The store may be altered during iteration without iterator invalidation, although subsequent updates will not be reflected in the iterator.
- IterRetainedStrata() Iterator[HereditaryStratum][source]
Iterate over stored strata from most ancient to most recent.