API

class phylotrackpy.systematics.Systematics

__init__(self: phylotrackpy.systematics.Systematics, calc_taxon: Callable[[object], taxon_info] = <function <lambda> at 0x7fa008a6b790>, store_active: bool = True, store_ancestors: bool = True, store_all: bool = False, store_pos: bool = False) → None

Construct a systematics manager to keep track of a phylogeny.

Parameters:

func (Callable[org_t, taxon_info_t]) – A function that takes in an organism and returns its associated taxon information.
store_active (bool) – Whether to store all taxa that are active in the population.
store_ancestors (bool) – Whether to store all taxa that are the ancestors of living organisms in the population.
store_all (bool) – Whether to store all dead taxa whose descendants have also died.
store_pos (bool) – Whether to store taxa by position.

add_org(*args, **kwargs)

Overloaded function.

add_org(self: phylotrackpy.systematics.Systematics, arg0: object) -> phylotrackpy.systematics.Taxon

Add an organism to systematics manager

add_org(self: phylotrackpy.systematics.Systematics, arg0: object, arg1: phylotrackpy.systematics.Taxon) -> phylotrackpy.systematics.Taxon

Add an organism to systematics manager

add_org_by_position(*args, **kwargs)

Overloaded function.

add_org_by_position(self: phylotrackpy.systematics.Systematics, arg0: object, arg1: phylotrackpy.systematics.WorldPosition) -> None

Add an organism to systematics manager

add_org_by_position(self: phylotrackpy.systematics.Systematics, arg0: object, arg1: phylotrackpy.systematics.WorldPosition, arg2: phylotrackpy.systematics.WorldPosition) -> None

Add an organism to systematics manager

add_snapshot_fun(self: phylotrackpy.systematics.Systematics, fun: Callable[[phylotrackpy.systematics.Taxon], str], key: str, desc: str = '') → None

This method adds a new snapshot function that will run in addition to the default functions when a snapshot is taken. A custom snapshot function should be created whenever storage and retrieval of custom taxon data is desired.

Custom snapshot functions must take a Taxon object as a single argument and return the data to be saved as a string. The second argument to this method is the key the custom information will be stored under in the snapshot file. Optionally, a short description of the custom information can be provided as its third argument.

Parameters:

fun (Callable[Taxon, str]) – Custom snapshot function, taking a Taxon object as its singular parameter, and returning the custom data as a string.
key (str) – Key to store the custom information under inside the snapshot file.
desc (str) – Optional description for the custom information.

calc_diversity(self: phylotrackpy.systematics.Systematics) → float: Calculates and returns the Shannon Diversity Index of the current extant population. This is done by weighing each active taxon by the number of organisms in it.

colless_like_index(self: phylotrackpy.systematics.Systematics) → float: Calculates and returns the Colless-like Index of the currently-active phylogenetic tree. This metric is used to measure tree balance in multifurcating trees, as described in [Mir et al., 2018]. The standard Colless Index is more well-known. However, that version is only applicable to bifurcating trees.

get_active_taxa(self: phylotrackpy.systematics.Systematics) → set[phylotrackpy.systematics.Taxon]: Returns a reference to the set of extant taxa.

get_active_taxa_reference(self: phylotrackpy.systematics.Systematics) → set[phylotrackpy.systematics.Taxon]: Returns a reference to the set of extant taxa.

get_ancestor_taxa(self: phylotrackpy.systematics.Systematics) → set[phylotrackpy.systematics.Taxon]: Returns a reference to the set of ancestor taxa. These are extinct taxa with extant descendants.

get_ave_depth(self: phylotrackpy.systematics.Systematics) → float: Returns the average phylogenetic depth of all organisms currently present in the population.

get_average_origin_time(self: phylotrackpy.systematics.Systematics, normalize: bool = False) → float

This method calculates the average origin time for the whole phylogenetic tree by iterating through its taxa.

It can optionally normalize the result to make it comparable to that of a strictly bifurcating tree–this is the kind of tree produced by traditional reconstruction methods. Normalization is achieved by multiplying the value of each taxon by its number of offspring minus one.

Parameters:: normalize (bool) – Whether to normalize result.

get_branches_to_root(self: phylotrackpy.systematics.Systematics, arg0: phylotrackpy.systematics.Taxon) → int

Given a taxon, this function calculates and returns the number of branches leading to multiple extant taxa on the path to its Most-Recent Common Ancestor (or its subtree root if none is found). Only extant taxa are considered since most phylogeny reconstruction algorithms are not designed to additionaly handle extinct taxa. This function does not count unifurcations – that is, points at which each taxon only has a single ancestor.

Parameters:: tax (Taxon) – Taxon to find branches to MRCA (or subroot) of.

get_distance_to_root(self: phylotrackpy.systematics.Systematics, arg0: phylotrackpy.systematics.Taxon) → int

Given a taxon, this function calculates and returns the distance to its Most-Recent Common Ancestor (or its subtree root if none is found). This function considers both unifurcations and extinct taxa. Consider using get_branches_to_root() instead for phylogeny reconstruction purposes.

Parameters:: tax (Taxon) – Taxon to find distance to MRCA (or subroot) of.

get_max_depth(self: phylotrackpy.systematics.Systematics) → int: Returns the lineage length (phylogenetic depth) from time zero to the active taxon with the longest lineage.

get_mean_evolutionary_distinctiveness(self: phylotrackpy.systematics.Systematics, arg0: float) → float

This method calculates the mean evolutionary distinctiveness of all extant taxa. Mean evolutionary distinctiveness is a metric that measures how distinct any given taxa is from the rest of the population, weighted by the amount of evolutionary history it represents [Isaac et al., 2007, Winter et al., 2013]. This method takes the current time as a parameter, in whichever units the systematics manager is using. Using a non-present time will produce innacurate results, since the only known state of the tree is the current one.

Parameters:: time (double) – Current time in the appropiate units (e.g., generations, seconds, etc.)

get_mean_pairwise_distance(self: phylotrackpy.systematics.Systematics, arg0: bool) → float

get_most_recent(self: phylotrackpy.systematics.Systematics) → phylotrackpy.systematics.Taxon: Returns the most recently-created taxon.

get_mrca(self: phylotrackpy.systematics.Systematics) → phylotrackpy.systematics.Taxon: Returns a temporary, non-owning object (reference) representing the Most-Recent Common Ancestor of the population.

get_next_id(self: phylotrackpy.systematics.Systematics) → int: Returns the ID of the next taxon that will be created.

get_next_parent(self: phylotrackpy.systematics.Systematics) → phylotrackpy.systematics.Taxon: Returns the taxon that corresponds to the parent of the next taxon. This will only be set if parents are being specified through calls to set_next_parent().

get_num_active(self: phylotrackpy.systematics.Systematics) → int: Returns the number of active taxa in the population.

get_num_ancestors(self: phylotrackpy.systematics.Systematics) → int: Returns the number of extinct taxa that are ancestors of living organisms currently present in the population.

get_num_outside(self: phylotrackpy.systematics.Systematics) → int: Returns the number of extinct taxa that have no living descendants. By definition, these are the taxa that are not in the current phylogenetic tree.

get_num_roots(self: phylotrackpy.systematics.Systematics) → int: Returns the number of independent phylogenies currently being tracked.

get_num_taxa(self: phylotrackpy.systematics.Systematics) → int: Returns the number of total taxa. Empirically, this is equal to the number of taxa in the current phylogenetic tree, plus the number of extinct taxa with no living descendants.

get_out_degree_distribution(self: phylotrackpy.systematics.Systematics) → dict[int, int]

This method creates a histogram of outnode degrees. In other words, it iterates through the whole phylogenetic tree and counts the number of outgoing edges for each node, returning this data in the form of a dictionary, with keys being outnode degrees and values being counts.

For example, {0:12, 1:10, 2:33} means the tree has 12 zero-furcations (leaf nodes), 10 unifurcations, and 33 bifurcations.

get_outside_taxa(self: phylotrackpy.systematics.Systematics) → set[phylotrackpy.systematics.Taxon]: Returns a reference to the set of outside taxa. These are extinct taxa with extinct descendants.

get_pairwise_distance(self: phylotrackpy.systematics.Systematics, tax: phylotrackpy.systematics.Taxon, tax2: phylotrackpy.systematics.Taxon, branch_only: bool = False) → float

This method calculates the distance between a pair of taxa. This assumes the taxa share a common ancestor.

If branch_only is set, this method will only consider distances in terms of nodes that represent branches between two extant taxa. This is potentially useful as a comparison to real-world, biological data, where non-branching nodes cannot be inferred.

Parameters:

tax (Taxon) – First taxon of pair to find distance between.
tax2 (Taxon) – Second taxon of pair to find the distance between.
branch_only (bool) – Only counts distance in terms of nodes that represent a branch between two extant taxa.

get_pairwise_distances(self: phylotrackpy.systematics.Systematics, arg0: bool) → list[float]

This method calculates distances between all pairs of extant taxa. This assumes the phylogenetic tree is fully connected.

If branch_only is set, this method will only consider distances in terms of nodes that represent branches between two extant taxa. This is potentially useful as a comparison to real-world, biological data, where non-branching nodes cannot be inferred.

Parameters:: branch_only (bool) – Only counts distance in terms of nodes that represent a branch between two extant taxa.

get_phylogenetic_diversity(self: phylotrackpy.systematics.Systematics) → int: This method calculates the sum of edges of the Minimum Spanning Tree of the currently-active phylogenetic tree [Winter et al., 2013, Faith, 1992]. Assuming all parent-child edges have a length of 1 (i.e., there are no unifurcations), this is a measure of phylogenetic diversity.

get_shared_ancestor(self: phylotrackpy.systematics.Systematics, arg0: phylotrackpy.systematics.Taxon, arg1: phylotrackpy.systematics.Taxon) → phylotrackpy.systematics.Taxon

Returns a temporary, non-owning object (reference) representing the Most-Recent Common Ancestor shared by two given taxa. The order of the taxa does not matter.

Parameters:

t1 (taxon) – Taxon to return MCRA of.
t2 (taxon) – Taxon to return MCRA of.

get_store_active(self: phylotrackpy.systematics.Systematics) → bool: Whether the Systematics Manager is configured to store all alive taxa in the population. Can be set using the set_store_active() method.

get_store_ancestors(self: phylotrackpy.systematics.Systematics) → bool: Whether the Systematics Manager is configured to store all taxa that are ancestors of living organisms in the population. Can be set using the set_store_ancestors() method.

get_store_archive(self: phylotrackpy.systematics.Systematics) → bool: Whether the Systematics Manager is configured to store extinct taxa types. Note that this is just get_store_ancestors() || get_store_outside(). Can be set using the set_store_archive() method.

get_store_outside(self: phylotrackpy.systematics.Systematics) → bool: Whether the Systematics Manager is configured to store all taxa that are ancestors of living organisms in the population. Can be set using the set_store_ancestors() method.

get_store_position(self: phylotrackpy.systematics.Systematics) → bool: Whether the Systematics Manager is configured to store taxa positions. Can be set using the set_store_position() method.

get_sum_distance(self: phylotrackpy.systematics.Systematics) → float: This method calculates the total branch length. This is a measure of community distinctness [Webb, 2000, Clark and Warwick, 1998].

get_sum_evolutionary_distinctiveness(self: phylotrackpy.systematics.Systematics, arg0: float) → float

This method calculates the sum of evolutionary distinctiveness of all extant taxa. Mean evolutionary distinctiveness is a metric that measures how distinct any given taxa is from the rest of the population, weighted by the amount of evolutionary history it represents [Isaac et al., 2007, Winter et al., 2013]. This method takes the current time as a parameter, in whichever units the systematics manager is using. Using a non-present time will produce innacurate results, since the only known state of the tree is the current one.

Parameters:: time (double) – Current time in the appropiate units (e.g., generations, seconds, etc.)

get_sum_pairwise_distance(self: phylotrackpy.systematics.Systematics, arg0: bool) → float

This method calculates the mean distance between all pairs of extant taxa, also known as the Average Taxonomic Diversity. This is a measure of community distinctness [Webb, 2000, Clark and Warwick, 1998]. This assumes the phylogenetic tree is fully connected. If this is not the case, it will return -1.

If branch_only is set, this method will only consider distances in terms of nodes that represent branches between two extant taxa. This is potentially useful as a comparison to real-world, biological data, where non-branching nodes cannot be inferred.

Parameters:: branch_only (bool) – Only counts distance in terms of nodes that represent a branch between two extant taxa.

get_taxon_at(self: phylotrackpy.systematics.Systematics, arg0: phylotrackpy.systematics.WorldPosition) → phylotrackpy.systematics.Taxon

Returns the taxon at the given location, if any. This will only work if the systematics manager is set to track positions (which can be checked with get_store_position()).

Parameters:: id (WorldPosition) – Location of taxon.

get_total_orgs(self: phylotrackpy.systematics.Systematics) → int: Returns the number of living organisms currently present in the population.

get_track_synchronous(self: phylotrackpy.systematics.Systematics) → bool: Whether the Systematics Manager is configured to track a synchronous population. The accuracy of the tracking depends on this option being correctly set. It is recommended to verify this setting before any tracking. Can be set using the set_track_synchronous() method.

get_tree_size(self: phylotrackpy.systematics.Systematics) → int: Returns the number of taxa in the current phylogenetic tree.

get_update(self: phylotrackpy.systematics.Systematics) → int: Returns the current timestep of the simulation. This time step can be overriden using the set_update() method.

get_variance_evolutionary_distinctiveness(self: phylotrackpy.systematics.Systematics, arg0: float) → float

This method calculates the variance of evolutionary distinctiveness across all extant taxa. Mean evolutionary distinctiveness is a metric that measures how distinct any given taxa is from the rest of the population, weighted by the amount of evolutionary history it represents [Isaac et al., 2007, Winter et al., 2013]. This method takes the current time as a parameter, in whichever units the systematics manager is using. Using a non-present time will produce innacurate results, since the only known state of the tree is the current one.

Parameters:: time (double) – Current time in the appropiate units (e.g., generations, seconds, etc.)

get_variance_pairwise_distance(self: phylotrackpy.systematics.Systematics, arg0: bool) → float

This method calculates the variance of distance between all pairs of extant taxa. This is a measure of phylogenetic regularity [Tucker et al., 2017]. This assumes the phylogenetic tree is fully connected. If this is not the case, it will return -1.

If branch_only is set, this method will only consider distances in terms of nodes that represent branches between two extant taxa. This is potentially useful as a comparison to real-world, biological data, where non-branching nodes cannot be inferred.

Parameters:: branch_only (bool) – Only counts distance in terms of nodes that represent a branch between two extant taxa.

is_taxon_at(self: phylotrackpy.systematics.Systematics, arg0: phylotrackpy.systematics.WorldPosition) → bool

Returns whether a taxon is present at the given location. This will only work if the systematics manager is set to track positions (which can be checked with get_store_position()).

Parameters:: id (WorldPosition) – Location to check for taxon.

load_from_file(self: phylotrackpy.systematics.Systematics, file_path: str, info_col: str = 'info', assume_leaves_extant: bool = True, adjust_total_offspring: bool = True) → None

This method loads phylogenies into the systematics manager from a given file, replacing the currently-present phylogenies, if any. It is only successful when the info_col type is convertible to the systematics manager’s ORG_INFO type. Such a phylogeny file can be obtained by calling snapshot() on a systematics manager with an active phylogeny.

Parameters:

file_path (string) – Path to file containing phylogenies to be loaded. Either absolute or relative to the Python executable.
info_col (string) – Name of file column containing taxa information. Defaults to “info”.
assume_leaves_extant (bool) – Whether leaves are assumed to be extant. Defaults to True.
adjust_total_offstring (bool) – Whether total offspring count should be adjusted for all taxa. Defaults to True.

mrca_depth(self: phylotrackpy.systematics.Systematics) → int: This function returns the depth of the Most-Recent Common Ancestor for the active population – that is, this returns the distance between the latest (i.e., newest) generation and the newest taxon that is an ancestor of the active taxa on the latest generation. If no MRCA exists, this returns -1.

on_extinct(self: phylotrackpy.systematics.Systematics, arg0: Callable[[phylotrackpy.systematics.Taxon], None]) → None

Set a custom function that is triggered every time a taxon goes extinct. The function must take a single argument: a taxon_t object representing the taxon going extinct. The custom function will be triggered near the beginning of the taxon descruction process: after its descruction time has been set, but before any information has been destroyed. This allows the user to customize the way objects are represented interlally by the systematics manager, or to implement extra bookkeeping functionality.

Parameters:: fun (Callable[[Taxon, Organism], None]) – Function to run during taxon destruction. It must take a taxon_t object corresponding to the destroyee taxon.

on_new(self: phylotrackpy.systematics.Systematics, arg0: Callable[[phylotrackpy.systematics.Taxon, object], None]) → None

Set a custom function that is triggered every time a new taxon is created. The function must take two arguments: the first must be a Taxon object that represents the newly-minted taxon, and the second must be an object representing the organism the taxon was created from. The custom function will be triggered during the taxon creation process: after its origination time has been set, but before its organism or location have been recorded. This allows the user to customize the way objects are represented interlally by the systematics manager, or to implement extra bookkeeping functionality.

Parameters:: fun (Callable[[Taxon, Organism], None]) – Function to run during new taxon creation. It must take a Taxon object corresponding to the new taxon as its first argument, and an object representing the organism the taxon was created from as its second argument.

on_prune(self: phylotrackpy.systematics.Systematics, arg0: Callable[[phylotrackpy.systematics.Taxon], None]) → None

Set a custom function that is triggered every time a taxon is pruned from the tree. This occurs when a taxon and all its descendants go extinct. The function must take a single argument: a taxon_t object representing the taxon getting pruned. The custom function will be triggered at the beginning of the taxon pruning process. This allows the user to customize the way objects are represented interlally by the systematics manager, or to implement extra bookkeeping functionality.

Parameters:: fun (Callable[[Taxon, Organism], None]) – Function to run during taxon pruning. It must take a taxon_t object corresponding to the pruned taxon.

parent(self: phylotrackpy.systematics.Systematics, arg0: phylotrackpy.systematics.Taxon) → phylotrackpy.systematics.Taxon

Returns the parent of a given taxon, if any.

Parameters:: tax (taxon) – The taxon to return the parent of.

print_lineage(self: phylotrackpy.systematics.Systematics, arg0: phylotrackpy.systematics.Taxon) → None

This method prints the complete lineage of a given taxon. The output format consists of the string “Lineage:” followed by each taxon in the lineage on a new line.

Parameters:: tax (Taxon) – Taxon to print the lineage of.

print_status(self: phylotrackpy.systematics.Systematics) → None: This method prints details about the systematics manager. It first prints all settings. Then, it prints all stored active, ancestor, and outside taxa in that order. The format for a taxon is [id | number of orgs, number of offspring | parent taxon].

remove_before(self: phylotrackpy.systematics.Systematics, arg0: int) → None

This method removes all taxa that went extinct before the given time step, and that only have ancestors taht went extinct before the given time step. While this invalidates most tree topology metrics, it is useful when limited ancestry tracking is necessary, but complete ancestry tracking is not computationally possible.

Parameters:: ud (int) – Time step before which to remove taxa.

remove_org(self: phylotrackpy.systematics.Systematics, arg0: phylotrackpy.systematics.Taxon) → bool

Notify the systematics manager that an organism has died. Use this method if you are keeping track of taxon objects yourself (rather than having the systematics manager handle it by tracking position).

Parameters:: tax (Taxon) – The taxon of the organism that died.

remove_org_after_repro(self: phylotrackpy.systematics.Systematics, arg0: phylotrackpy.systematics.Taxon) → None

Notify the systematics manager that an organism has died but that it shouldn’t record the death until the next reproduction event. You might want to do this if there’s a chance that the organism simultaneously died and reproduced (e.g. if the organism’s offspring might have replaced it in the population).

Calling remove_org_by_position in that scenario could result in a segmentation fault if it was the last organism of its taxon. It could either be incorrectly marked extinct (if the offspring is part of the same taxon) and/or incorrectly pruned (if the offspring is part of a new taxon).

Use this method if you are keeping track of taxon objects yourself (rather than having the systematics manager handle it by tracking position).

Parameters:: tax (Taxon) – The taxon of the organism that died.

remove_org_by_position(self: phylotrackpy.systematics.Systematics, arg0: phylotrackpy.systematics.WorldPosition) → bool

Notify the systematics manager that an organism has died. Use this method if you’re having the systematics manager keep track of each organism’s position and want to use the position to tell the systematics manager which organism died. Otherwise use remove_org.

Parameters:: position (WorldPosition) – The location of the organism that died.

remove_org_by_position_after_repro(self: phylotrackpy.systematics.Systematics, arg0: phylotrackpy.systematics.WorldPosition) → None

Notify the systematics manager that an organism has died but that it shouldn’t record the death until the next reproduction event. You might want to do this if there’s a chance that the organism simultaneously died and reproduced (e.g. if the organism’s offspring might have replaced it in the population).

Calling remove_org_by_position in that scenario could result in a segmentation fault if it was the last organism of its taxon. It could either be incorrectly marked extinct (if the offspring is part of the same taxon) and/or incorrectly pruned (if the offspring is part of a new taxon).

Use this method if you’re having the systematics manager keep track of each organism’s position and want to use the position to tell the systematics manager which organism died. Otherwise use remove_org_after_repro.

Parameters:: position (WorldPosition) – The location of the organism that died.

sackin_index(self: phylotrackpy.systematics.Systematics) → int: Calculates and returns the Sackin Index of the currently-active phylogenetic tree. This metric is used to measure phylogenetic tree balance. It is calcualted by adding together the depth of every leaf to its Most-Recent Common Ancestor (or its subtree root if none is found). For more information, see [Shao and Sokal, 1990].

set_calc_info_fun(self: phylotrackpy.systematics.Systematics, arg0: Callable[[object], taxon_info]) → None

Set the function used to calculate the information associated with an organism. This information is used to categorize organisms within the systematics manager. Possible information includes genotype, phenotype, genome sequence, etc. See Flexible Taxon Definitions for more information.

Parameters:: func (Callable[org_t, taxon_info_t]) – A function that takes in an organism and returns its associated information.

set_next_parent(self: phylotrackpy.systematics.Systematics, arg0: phylotrackpy.systematics.Taxon) → None

Sometimes, due to the flow of your program, you may not have access to the taxon object for the parent and the offspring at the same time. In these cases, you can use set_next_parent to tell the systematics manager what the taxon of the parent of the next offspring should be. The next time you call one of the add_org methods without a specified parent, the systematics manager will used the specified taxon as the parent for that organism.

Parameters:: tax (Taxon) – The taxon to set as the next parent.

set_next_parent_by_position(self: phylotrackpy.systematics.Systematics, arg0: phylotrackpy.systematics.WorldPosition) → None

Works just like set_next_parent except for systematics managers that are tracking based on position.

Parameters:: pos (WorldPosition) – The position in the world of the organism that should be the next parent.

set_store_active(self: phylotrackpy.systematics.Systematics, arg0: bool) → None

A setter method to configure whether to store all taxa that are active in the population. Warning: this is an advanced feature — setting this to False breaks a lot of assumptions and will most likely disrupt normal functioning of the systematics manager. There is probably not a real reason to change this setting. This option defaults to True.

Parameters:: val (bool) – Value representing whether to store all taxa that are active in the population.

set_store_ancestors(self: phylotrackpy.systematics.Systematics, arg0: bool) → None

A setter method to configure whether to store all taxa that are the ancestors of living organisms in the population. Warning: this is an advanced feature — setting this to False breaks a lot of assumptions and will most likely disrupt normal functioning of the systematics manager. As opposed to set_store_active(), there are probably some situations where this setting could be useful. This option defaults to True.

Parameters:: val (bool) – Value representing whether to store all taxa that are the ancestors of living organisms in the population.

set_store_archive(self: phylotrackpy.systematics.Systematics, arg0: bool) → None

A setter method to configure whether to store taxa types that have become extinct. Warning: this is an advanced feature — archive is handled internally. Overriding this setting could disrupt normal behavior of the systematics manager. This option defaults to True.

Parameters:: val (bool) – Value representing whether to store taxa types that have died out.

set_store_outside(self: phylotrackpy.systematics.Systematics, arg0: bool) → None

A setter method to configure whether to store all dead taxa whose descendats have also died. Warning: this is an advanced feature — this setting will use a lot of memory in most cases. This option defaults to False.

Parameters:: val (bool) – Value representing whether to store all dead taxa whose descendats have also died.

set_store_position(self: phylotrackpy.systematics.Systematics, arg0: bool) → None

A setter method to configure whether to store the position of each taxa. This option defaults to False.

See Position based tracking for more information

Parameters:: val (bool) – Value representing whether to store the position of each taxa.

set_track_synchronous(self: phylotrackpy.systematics.Systematics, arg0: bool) → None

A setter method to configure whether a synchronous population is being tracked. A synchronous population is one where parents must be extanct for their offspring to be born. As such, there are effectively two populations: a currently-active one, and one being created. This is in opposition to steady-state populations, where organisms might die as their offspring are born (for example, in a world where offspring replaces the parent). The accuracy of the systematics tracking relies on this option, so it is imperative it be configured properly. This option defaults to False.

Parameters:: val (bool) – Value representing whether a synchronous population is being tracked.

set_update(self: phylotrackpy.systematics.Systematics, arg0: int) → None

A setter method to modify the current time step. This should be used if you want PhylotrackPy to track when events occur.

Parameters:: update (int) – An integer value representing the current time step.

snapshot(self: phylotrackpy.systematics.Systematics, arg0: str) → None

This method takes a snapshot of the current state of the phylogeny and stores it to a file. This file can then be loaded through load_from_file(). Note that this assumes each taxon only has one parent taxon.

Parameters:: file_path (string) – File path to save snapshot to.

swap_positions(self: phylotrackpy.systematics.Systematics, arg0: phylotrackpy.systematics.WorldPosition, arg1: phylotrackpy.systematics.WorldPosition) → None

If you are tracking taxa by positions it is important that you notify the systematics manager any time a taxon changes position for any reason. This function allows you to do so. Assumes that all changes in position take the form of the contents of one location being replaced with the contents of a different location. If only one organism is moving, the location it is moving to is presumably empty and it is presumably leaving its former position empty. Thus, you will swap an organism with an empty space.

Parameters:

pos1 (WorldPosition) – The position of one of the organisms being swapped.
pos2 (WorldPosition) – The position of one of the organisms being swapped.

update(self: phylotrackpy.systematics.Systematics) → None: Calling this method advances the tracking by one time step. This can be useful for tracking taxon survival times, as well as population positions in synchronous generation worlds.

class phylotrackpy.systematics.Taxon

__init__(*args, **kwargs)

get_destruction_time(self: phylotrackpy.systematics.Taxon) → float: Return the time (as a float) when this taxon left the population. If the taxon is currently alive, this will be equal to float(+inf). This call will only succeed when the systematics manager has been set to track times via set_update().

get_id(self: phylotrackpy.systematics.Taxon) → int: Returns the ID (as an int) that uniquely identifies this taxon. IDs are assigned sequentially, sp higher IDs will correspond to more recent taxa.

get_info(self: phylotrackpy.systematics.Taxon) → taxon_info

get_num_offspring(self: phylotrackpy.systematics.Taxon) → int: Returns the number of new taxa that were produced by organisms corresponding to this taxon.

get_num_orgs(self: phylotrackpy.systematics.Taxon) → int: Returns the total number of currently living organisms corresponding to this taxon.

get_offspring(self: phylotrackpy.systematics.Taxon) → set[phylotrackpy.systematics.Taxon]: Returns a set holding all immediate offspring taxa. This method can be used to traverse the phylogenetic tree.

get_origination_time(self: phylotrackpy.systematics.Taxon) → float: Return the time (as a float) when this taxon first appeared in the population. This call will only succeed when the systematics manager has been set to track times via set_update().

get_parent(self: phylotrackpy.systematics.Taxon) → phylotrackpy.systematics.Taxon

get_total_offspring(self: phylotrackpy.systematics.Taxon) → int: Returns the number of direct and indirect descendants of this taxon.

get_total_orgs(self: phylotrackpy.systematics.Taxon) → int: Returns the total number of organisms that have ever lived corresponding to this taxon.

class phylotrackpy.systematics.WorldPosition

__init__(*args, **kwargs)

Overloaded function.

__init__(self: phylotrackpy.systematics.WorldPosition, arg0: int, arg1: int) -> None
__init__(self: phylotrackpy.systematics.WorldPosition, arg0: int) -> None
__init__(self: phylotrackpy.systematics.WorldPosition, arg0: tuple[int, int]) -> None

get_index(self: phylotrackpy.systematics.WorldPosition) → int: Returns the index (position within the population) represented by this WorldPosition as an int

get_pop_ID(self: phylotrackpy.systematics.WorldPosition) → int

Returns the ID (as an int) of the population that this WorldPosition is referring to.

Wondering why there might be multiple populations? It’s because WorldPosition objects are designed to gracefully handle configurations in which there are multiple separate populations (e.g. due to islands or separated generations). If you’re just using one population, the pop ID will always be 0 and that’s fine.

is_active(self: phylotrackpy.systematics.WorldPosition) → bool

Returns a boolean indicating whether this position potentially represents an “active” (i.e. “alive”) organism in the context of a generational/synchronous configuration (i.e. one in which a new generation is created on each time step and there is no overlap of organisms between generations; this configuration is commonly used in evolutionary computation and simple evolutionary models). In this case, the next generation (i.e. the one that is currently in the process of being created) is considered “inactive”. Conventionally, the population that selection is currently happening on has ID 0 and the population holding the new generation has ID 1. Thus, this method simply returns true if the population ID is 0 and false otherwise.

If you are using population IDs for a separate purpose (e.g. islands), this method will not yield accurate results.

is_valid(self: phylotrackpy.systematics.WorldPosition) → bool: -1 can be used as a sentinel value to indicate that a position is not to be used. This method returns a boolean indicating whether this position is “valid” (i.e. the index is not equal to -1).