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 [source]
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 [source]
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 [source]
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 [source]
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 [source]
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 [source]
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.