GarbageCollectingPhyloTracker

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.

__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.

Methods

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.