perfect_tracking

Tools for perfect phylogenetic tracking.

Functions

compile_perfect_backtrack_phylogeny(population)	Compile phylogenetic history tracked using PerfectBacktrackHandle breadcrumbs.
compile_phylogeny_from_lineage_iters(population)	Compile phylogenetic history tracked using generic backtracking breadcrumbs.
iter_perfect_backtrack_lineage(handle)	Iterate up PerfectBacktrackHandle breadcrumbs for line of descent ending in handle, including handle.

Classes

DecantingPhyloTracker	Data structure to enable perfect tracking over a fixed-size population with synchronous generations.
GarbageCollectingPhyloTracker	Data structure to enable perfect tracking over a fixed-size population with synchronous generations.
PerfectBacktrackHandle	Breadcrumb for perfectly backtracking a phylogenetic chain of descent.

compile_perfect_backtrack_phylogeny(population: Iterable[PerfectBacktrackHandle]) → DataFrame

Compile phylogenetic history tracked using PerfectBacktrackHandle breadcrumbs.

Parameters

populationiterable of PerfectBactrackHandle

PerfectBacktrackHandle objects associated with extant population members.

Returns

pd.DataFrame

Phylogenetic record in alife data standards format.

compile_phylogeny_from_lineage_iters(population: Iterable[Iterable[Any]]) → DataFrame

Compile phylogenetic history tracked using generic backtracking breadcrumbs.

Parameters

populationiterable of iterable

Ascending lineage iterators associated with extant population members.

Returns

pd.DataFrame

Phylogenetic record in alife data standards format.

class DecantingPhyloTracker

Data structure to enable perfect tracking over a fixed-size population with synchronous generations.

Generally less performant than GarbageCollectingPhyloGracker; represents organism records as independent objects (which each require an independent allocations and, on lineage extinction, deletions). Uses a decanting buffer to reduce object creation overhead by only allocating record objects for organisms that produce extant lineages beyond a threshold length.

Does not include organism population loc and trait values in phylogenetic record.

CompilePhylogeny(progress_wrap=<function DecantingPhyloTracker.<lambda>>) → DataFrame

Generate full phylogenetic record of extant organisms.

Parameters

progress_wrapCallable, default identity function

Wrapper applied around record row iterator; pass tqdm or equivalent to display progress bar for compilation process.

Returns

pandas.DataFrame

Full phylogenetic record of extant organisms alife standard format.

Notes

This operation is non-destructive; further record-keeping may be performed on the tracker object afterwards.

ElapseGeneration(parent_locs: List[int]) → None

Append generational turnover to the phylogenetic record.

Parameters

parent_locsarray_like of int

Parent’s population loc for each population loc.

Position within array corresponds to post-turnover population members’ population positions. Values within array correspond to those members’ parents’ population positions within the pre- turnover population.

__init__(population_size: int, buffer_size: int = 10, share_common_ancestor: bool = True) → None

Initialize data structure to perfectly track phylogenetic history of a population.

Parameters

population_sizeint

How many locations are available within the tracked fixed-size population?

buffer_sizeint, optional

How many generations should lineages be decanted before creating record objects for organisms with extant lineages?

share_common_ancestorbool, default True

Should a dummy common ancestor be inserted as the first entry in the tracker?

If True, all initial population members will be recorded as children of this dummy ancestor. If False, all initial population members will be recorded as having no parent.

class GarbageCollectingPhyloTracker

Data structure to enable perfect tracking over a fixed-size population with synchronous generations.

Designed to provide low-overhead tracking. Instead of representing organism records as independent objects (which each require an independent allocations and, on lineage extinction, deletions), stores organism records as rows within a numpy array. Partial garbage collection at regular intervals compacts recent record entries to discard extinct lineages.

Includes organism population loc and trait values in phylogenetic record.

ApplyLocPasteovers(copyfrom_locs: array, copyto_locs: array) → None

Replace organisms at copyto_locs locations with non-descendant clones of organisms at copyfrom_locs locations.

Pasted-over organisms do not remain in the phylogenetic record. The pasted-in organism is not recorded as the child of the pasted-from organism; rather, the pasted-in organism is recorded as the child of the pasted-from organism’s parent.

Zip of parameters specifies pasteovers to perform, with the first element of zipped tuples specifying the population location to copy from and the second element specifying the population location to paste over.

Notes

The original organism at each location is copied from, ignoring any preceding pasteovers that may have placed a new organism at that location during this operation.

No repeated entries are allosed in copyto_locs.

ApplyLocSwaps(swapfrom_locs: array, swapto_locs: array) → None

Swap organisms between population locations.

Organisms’ pre-swap population locations do not remain in the phylogenetic record. Zip of parameters specifies pairs of population locations to swap.

Notes

Swaps are performed sequentially, with the most recent organism swapped to a location used for subsequent swaps from or to that location.

Parameter order is commutative.

CompilePhylogeny(progress_wrap=<function GarbageCollectingPhyloTracker.<lambda>>, loc_transforms: ~typing.Dict[str, ~typing.Callable] = mappingproxy({})) → DataFrame

Generate full phylogenetic record of extant organisms.

Parameters

progress_wrapCallable, default identity function

Wrapper applied around record row iterator; pass tqdm or equivalent to display progress bar for compilation process.

loc_transforms: Dict of str -> Callable, default empty

Specification for custom columns in returned dataframe.

Each dict item creates a new column with name corresponding to the item’s key populated with the result of mapping the item’s Callable value over organisms’ locs.

Returns

pandas.DataFrame

Full phylogenetic record of extant organisms alife standard format.

Notes

This operation is non-destructive; further record-keeping may be performed on the tracker object afterwards.

ElapseGeneration(parent_locs: List[int], traits: List[float] | None = None) → None

Append generational turnover to the phylogenetic record.

Parameters

parent_locsarray_like of int

Parent’s population loc for each population loc.

Position within array corresponds to post-turnover population members’ population positions. Values within array correspond to those members’ parents’ population positions within the pre- turnover population.

traits: array_like of float, optional

Traits of post-turnover population members.

If unspecified, post-turnover population members’ traits are recorded as NaN.

__init__(initial_population: int | array, working_buffer_size: int | None = None, share_common_ancestor: bool = True) → None

Initialize data structure to perfectly track phylogenetic history of a population.

Parameters

initial_populationint or numpy array of float

Specification of founding organisms of population. Providing an integer argument specifices population size, and founding organisms’ float phenotypic traits are recorded as NaN. Providing a numpy array of float specifies phenotypic traits of founding organisms.

working_buffer_sizeint, optional

Intermittent garbage collection depth.

How many rows back should intermittent garbage collection reach? Adjustments to this parameter only affect performance, not tracking semantics. Initial buffer size is set to 150% of working_buffer_size.

share_common_ancestorbool, default True

Should a dummy common ancestor be inserted as the first entry in the tracker?

If True, all initial population members will be recorded as children of this dummy ancestor. If False, all initial population members will be recorded as having no parent.

The dummy ancestor’s trait value is recorded as NaN and population loc is recorded as 0.

iter_perfect_backtrack_lineage(handle: PerfectBacktrackHandle) → Iterator[PerfectBacktrackHandle]

Iterate up PerfectBacktrackHandle breadcrumbs for line of descent ending in handle, including handle.

class PerfectBacktrackHandle

Breadcrumb for perfectly backtracking a phylogenetic chain of descent.

Because only backwards references are held, Python garbage collection takes care of pruning away extinct lineages.

parent: PerfectBacktrackHandle

data: Any

CreateDescendant(data: Any | None = None) → PerfectBacktrackHandle

Convenience factory method to create backtracking breadcrumbs succeeding self in line of descent.

__init__(parent: PerfectBacktrackHandle | None = None, data: Any | None = None) → None

Create backtracking breadcrumb, with parent as preceding breadcrumb in line of descent or None if associated with seed organism.