phylojunction.functionality package

Submodules

phylojunction.functionality.biogeo module

class phylojunction.functionality.biogeo.State2BitLookup(n_characters: int, n_states_per_char: int, geosse: bool = True)

Bases: object

Stash and machinery for checking and converting character compound-states into bit patterns, and vice-versa

For example, if we are thinking about regions as characters, then compound-state means different ranges (e.g., “A”, “AB”), while “state” is the number of different values a single character can take. In the case of 1-character-1-region, then the number of states is 2, because a species is either present or not in a region.

Parameters:

• n_char (int) – Number of places in bit pattern, which could be the number of atomic regions in a biogeographic system.

• n_states_per_char (int) – Number of states a bit pattern can take. Normally this number is 2, since a bit can be either on (1) or off (0).

• n_states (int)

• int2bit_dict (dict)

• bit2int_dict (dict)

bit2int_dict: Dict[str, str] = {}

get_bit(state: int, geosse: bool = True) → str

get_bit_patts() → List[str]

get_state(bit_patt: str) → int

get_widespread_bits() → Tuple[str]

int2bit_dict: Dict[str, str] = {}

n_char: int

n_states: int

n_states_per_char: int

class phylojunction.functionality.biogeo.StatesGeoCondChangeLookup(n_regions: int, geo_query: GeoFeatureQuery, requirement_fn: MyCallableType, requirement_fn_name: str)

Bases: object

disjoint_bit_patt_str_iter(widespread_bit_patt: str)

geo_query: GeoFeatureQuery

n_regions: int

state_bit_lookup_tup: Tuple[State2BitLookup]

widespread_bit_patt_lookup_dict: Dict[str, Dict[Tuple[str], Dict[Tuple[int], List[float]]]] = {}

phylojunction.functionality.event_series module

class phylojunction.functionality.event_series.EvolRelevantEventSeries(n_regions: int | None = None, event_list: List[EvolRelevantEvent] | None = None, it_idx: int = -1)

Bases: object

Series of evolution-relevant events.

This class has member methods that interrogate a series of event, truncating it depending on what the user specifies.

Parameters:

• n_regions (int) – Number of discrete (unsplittable) regions in the system.

• event_list (list) – List of EvolRelevantEvent objects.

• n_events (int) – Number of EvolRelevantEvent objects.

• it_idx (int) – Index of iteration whose stochastic maps are being used to populate the list of events.

• trunc_event_list (list) – Same as ‘event_list’, but truncated at the youngest possible event where the range of a lineage is stable with respect to a split. Truncation is not mandatory, and this class member may be identical to ‘event_list’.

add_events(event_or_events: EvolRelevantEvent | List[EvolRelevantEvent])

property event_list: List[EvolRelevantEvent]

property n_events: int

property n_regions: int

one_srdd_region() → bool

property region_origin_status: List[str]

property supported_hyp: Hypothesis

property trunc_event_list: List[EvolRelevantEvent]

update_region_status(from_region_idx: int, to_region_idx: int | None = None, status: str | None = None) → None

class phylojunction.functionality.event_series.EvolRelevantEventSeriesTabulator(ann_tr_list: List[AnnotatedTree], smap_collection: StochMapsOnTreeCollection, geofeat_query: GeoFeatureQuery | None = None, from_region_sampler: FromRegionSampler | None = None, directed_edges: bool | None = False, verbose: bool | None = False)

Bases: object

Classify and tabulate event series.

Parameters:

• ann_tr_list (AnnotatedTree) – List of AnnotatedTree objects, one per iteration in ‘smap_collection’, on which character- state changes are being mapped.

• smap_collection (StochMapsOnTreeCollection) – Collection of stochastic maps from multiple iterations.

• event_series_dict (dict) – Dictionary with node labels as keys and a list of EvolRelevantEventSeries objects as values.

• hyp_support_dict (dict) – Dictionary with Hypothesis objects as keys, and counts (int) as values.

• directed_edges (bool) – Flag specifying if edges in connectivity graph are to be treated as directed. Defaults to ‘False’.

add_paleogeo_event_series_dict(geo_cond_name: str, directed: bool = False, user_young2old: bool = True) → None

Update self.event_series_dict with paleogeographic events.

Only barriers that matter for a specific range split are considered.

Parameters:

• geo_cond_name (str)

• directed (bool) – Flag specifying if connectivity cares about edge direction or not. Defaults to ‘False’.

• user_young2old (bool) – Defaults to ‘False’.

property ann_tr_list: List[AnnotatedTree]

annotate_event_series_hypothesis() → None

Look at truncated event series and annotate hypothesis.

Side-effect:

1. Annotates event series ‘supported_hyp’ member

2. Populates self._node_count_supporting_hyp_dict

3. Populates self._hyp_support_by_node_dict

annotate_paleogeo_events() → None

Annotate paleogeo events as (de)stabilizing or not.

After paleogeographic events have been added to the event series of each internal node, we visit each one of them and annotate them according to their (de)stabilizing status with respect to the range splitting event happening at speciation. If the range does not split at speciation, the annotation is ‘N/A’.

disambiguate_range_expansion(smap: StochMap, it_idx: int) → None

Randomly disambiguate source region of range expansion.

The side-effect of this method is to populate the member ‘from_region_idx’ of StochMap of RangeExpansion type.

This disambiguation is necessary in cases where the source range includes multiple atomic regions, e.g., ABC -> ABCD. We do not know if the dispersal to D came from A, B or C.

Parameters:

• smap (StochMap) – StochMap object instance, carrying all info on a stochastic map.

• it_idx (int) – Iteration index for which to disambiguate stochastic map. Note that the index is whatever is written in the stochastic map table and in the .log file of parameter values used to disambiguate the stochastic map. The indices for those iterations must match!

property event_series_dict: Dict[str, Dict[int, EvolRelevantEventSeries]]

property hyp_support_by_node_dict: Dict[str, Dict[int, str]]

initialize_event_series_dict() → None

is_range_expansion_split_relevant(from_region_idx: int, to_region_idx: int, splitting_range1_idxs: Set[int], splitting_range2_idxs: Set[int]) → bool

Determine if range expansion split-relevant.

If the regions involved in the dispersal are both on the same side of a range split, they are not split- relevant.

Parameters:

• from_region_idx (int)

• to_region_idx (int) – Index of region receiving migrants.

• splitting_range1_idxs (set) – Set of region indices on one side of range split.

• splitting_range2_idxs (set) – Set of region indices on other side of range split.

Returns:

Boolean for whether range expasion is

split-relevant.

Return type:

(bool)

is_unstable_wrt_split(splitting_range1_idxs: Set[int], splitting_range2_idxs: Set[int], conn_graph: GeoGraph, range_idxs: List[int] | None = None) → bool

Determine if splitting range is fragile.

Checks that every region in range1_idxs is in a different communicating class from every region in range2_idxs.

Parameters:

• splitting_range1_idxs (list) – List of indices (int) of one of ranges resulting from the split.

• splitting_range2_idxs (list) – List of indices (int) of the other range resulting from the split.

• conn_graph (GeoGraph) – Connectivity graph, with each node being a region, and each edge representing the possibility of migration between two regions (i.e., gene flow).

• range_idxs (list, optional) – of all regions constituting a (i) expanding range, (ii) contracting range, or (iii) contracted range. Defaults to None.

property node_count_supporting_hyp_dict: Dict[int, Dict[str, int]]

populate_trunc_event_series() → None

Populate _truncated_event_series_dict

This method visits all event series (for all internal nodes and all iterations) and makes a deep copy of it for truncation. Then it truncates that deep copy right after specific events:

(i) First range expansion (dispersal) event that re-stabi- zes a splitting (!) range (if speciation is within region, no truncation is carried out); (ii) First barrier disappearance that reconnects a splitting (!) range (again, if speciation is within-region, no truncation is carried out).

class phylojunction.functionality.event_series.FromRegionSampler(n_char: int, n_time_slices: int, param_log_file_path: str, param_name: str)

Bases: object

property n_char: int

populate_param_value_dict(param_log_fp: str) → None

sample_from_region_idx(it_idx: int, time_slice_idx: int, potential_from_region_idx: List[int], to_region_idx: int) → int

Sample a region for an iteration.

Parameter values in a .log file can be normalized and serve as weights for sampling a ‘from’ region for dispersal stochastic maps.

Parameters:

• it_idx (int) – Index of iteration we are looking at. This is parsed from the stochastic map table file.

• time_slice_idx (int) – Index of time slice, with 0 being the present epoch.

• potential_from_region_idx – List of indices for regions from which dispersal (range expansion) may have happened.

• to_region_idx – Index for region to which dispersal (range expansion) happened.

Returns:

Sampled region index.

Return type:

(int)

property time_slice_dict_list: List[Dict[int, List[List[float]]]]

class phylojunction.functionality.event_series.Hypothesis(*values)

Bases: Enum

AMBIGUOUS = 'Ambiguous'

FOUNDER_EVENT = 'Founder event'

SPECIATION_BY_EXT = 'Speciation by extinction'

VICARIANCE = 'Vicariance'

WITHIN_REGION = 'Within-region speciation'

class phylojunction.functionality.event_series.RegionDispersalAncestry

Bases: object

Track all regions gained by dispersal

This class keeps track of all regions gained by dispersal (range expansion) both (i) over a barrier, (ii) without a barrier. The purpose of this class is quantifying what proportion (in number of regions) of the splitting range had something to do with a dispersal over a barrier.

property n_regions_gained_over_barrier: int

property n_regions_gained_w_out_barrier: int

property regions_idx_gained_over_barrier: Set[Tuple[int, float]]

phylojunction.functionality.event_series.truncate_at_split_relevant_event(event_series: EvolRelevantEventSeries)

phylojunction.functionality.evol_event module

class phylojunction.functionality.evol_event.EvolRelevantEvent(n_chars: int, age: float | None, time: float | None = None)

Bases: ABC

Evolution-relevant event.

Examples of evolution-relevant events are those represented by stochastic maps (e.g., range contraction, range expansion, extinction, dispersal) or the (paleogeographic) appearance and disappearance of barriers.

Parameters:

• n_chars (int) – Number of characters involved in event.

• age (float) – Age of event (age of present moment is 0.0).

• time (float, optional) – Time of event (0.0 at origin or root). Defaults to None.

• char_status_dict (dict) – Dictionary with integer as keys representing the position of a character in a bit pattern (e.g., if there are three regions A, B and C, 0 = A, 1 = B, 2 = C), and a RegionStatus as values. This RegionStatus represents some type of status the region is in (e.g., if the character represents a region being part of a biogeographic range, then ‘DISCONNECTED’ could mean that that region is disconnected from others relative to a range-splitting event upon speciation).

property age: float

char_status(char_pos_in_bit_patt) → bool

property char_status_dict

abstractmethod short_str() → str

property time: float

class phylojunction.functionality.evol_event.RegionStatus

Bases: object

property comm_class_id: int

phylojunction.functionality.feature_io module

class phylojunction.functionality.feature_io.BarrierAppearance(n_chars: int, age: float | None, from_node_idx: int, to_node_idx: int, time: int | None = None)

Bases: EvolRelevantEvent

Barrier appearance event.

Parameters:

• from_node_idx (int) – Integer representation of source node in barrier.

• to_node_idx (int) – Integer representation of target node in barrier.

destabilized_range: str | None

from_node_idx: int

range_bit_patt: str | None

short_str() → str

to_node_idx: int

class phylojunction.functionality.feature_io.BarrierDisappearance(n_chars: int, age: float | None, from_node_idx: int, to_node_idx: int, time: int | None = None)

Bases: EvolRelevantEvent

Barrier disappearance event.

Parameters:

• from_node_idx (int) – Integer representation of source node in barrier.

• to_node_idx (int) – Integer representation of target node in barrier.

from_node_idx: int

range_bit_patt: str | None

restabilized_range: str | None

short_str() → str

to_node_idx: int

class phylojunction.functionality.feature_io.GeoFeature(time_idx: int, feat_idx: int, feat_rel: GeoFeatureRelationship, feat_type: GeoFeatureType, feat_vals: array | None = None, feat_name: str | None = '')

Bases: object

Geographic feature class.

Parameters:

• time_idx (int) – Index of epoch when feature is measured.

• feat_idx (int) – Index of feature in its container.

• n_regions (int) – Number of atomic (i.e., unsplittable) regions in the system.

• feat_rel (GeoFeatureRelationship) – Enum object that characterizes how the feature relates one or more regions (“within” or “between)”.

• feat_type (GeoFeatureType) – Enum object carrying the type of the feature (“categorical” or “quantitative”).

• n_dim (int) – Number of dimensions in the container containing geographic feature values.

• value (NumPy.array) – Value(s) measured for geographic feature.

• name (str) – Geographic feature name.

• str_representation (str) – String representation of geographic feature for printing.

feat_idx: int

feat_rel: GeoFeatureRelationship

feat_type: GeoFeatureType

get_val_from_to(from_idx: int, to_idx: int) → float

n_dim: int

n_regions: int

name: str

str_representation: str

time_idx: int

value: array

class phylojunction.functionality.feature_io.GeoFeatureCollection(feat_summary_fp: str, age_summary_fp: str = '')

Bases: object

Collection of geographic features.

This class organizes

Parameters:

• geofeat_list (GeoFeature) – List of GeoFeature objects.

• epoch_age_end_list_young2old (list[float]) – List of age ends (float), one per epoch, going from the youngest epoch to the oldest.

• epoch_mid_age_list_young2old (list[float]) – List of age mid points (float), one per epoch, going from the youngest epoch to the oldest.

• epoch_age_start_list_young2old (list[float]) – List of age starts

• n_epochs (int) – Number of epochs

• is_timehet (bool) – Flag specifying if the geographic data is time-heterogeneous.

• feat_name_epochs_dict (dict) – Nested dictionaries. The outer dictionary has feature names (str) as keys (i.e., features must have different names), and the inner dictionaries as values. The inner dictionary has epoch indices as keys (int), and GeoFeature objects as values.

• feat_type_rel_featid_epochs_dict (dict) – Quadruple nested dictionaries. The outer keys are GeoFeatureType. The next nested keys are GeoFeatureRelationship. The third nested keys are the index (int) of the feature. The fourth and last nested keys are epoch indices (int), with values being GeoFeatures.

• region_name_idx_dict (dict) – Dictionary for converting between region names and their indices. Names (str) for keys, indices (int) for values.

• region_idx_name_dict (dict) – Dictionary for converting between region indices and their names. Indices (int) for keys, names (str) for values.

epoch_age_end_list_young2old: List[float]

epoch_age_start_list_young2old: List[float]

epoch_mid_age_list_young2old: List[float]

feat_name_epochs_dict: Dict[str, Dict[int, GeoFeature]]

feat_type_rel_featid_epochs_dict: Dict[GeoFeatureType, Dict[GeoFeatureRelationship, Dict[int, Dict[int, GeoFeature]]]]

geofeat_list: List[GeoFeature]

get_feat_by_name(feat_name: str, time_idx: int | None = None) → Tuple[float, List[float]]

get_feat_by_type_rel_id(feat_type: GeoFeatureType, feat_rel: GeoFeatureRelationship, feat_id: int, time_idx: int | None = None) → Tuple[float, List[float]]

Parameters:

• feat_type

• feat_rel

• feat_id

• time_idx – Index of epoch for which we want to get features. Note that these indices are provided by the user in the feature summary .csv file.

Returns:

Geographic feature (GeoFeature object) or

list of geographic features, depending on whether time_idx was provided.

Return type:

(GeoFeature)

is_timehet: bool

n_epochs: int

region_idx_name_dict: Dict[int, str]

region_name_idx_dict: Dict[str, int]

class phylojunction.functionality.feature_io.GeoFeatureQuery(feat_coll)

Bases: object

Parameters:

• n_regions (int) – Number of regions in the system.

• n_epochs (int) – Number of time slices (i.e., epoch) for which one has geographic features scored.

• feat_col (GeoFeatureCollection)

• geo_cond_bit_dict (dict) – Dictionary with keys being the name of a paleogeographical condition (e.g., ‘land_bridge’), and values being 1- or 2-D lists with bit patterns. Each bit in the pattern corresponds to a time slice (i.e., epoch), in whatever temporal order the user specifies in the feature and age summary files (conventionally from young to old). If the paleogeographical condition is a function of a within-region feature, the value of the dictionary is a list; if of a between-region feature, the value will be a 2-D list.

• conn_graph_list (GeoGraph) – List of connectivity graphs, one per epoch.

• geo_cond_name (str) – Name of geographic condition verified for determining the bit value within or between regions (e.g., a barrier).

static cb_feature_equals_value_is_connected(feat_col: GeoFeatureCollection, val2match: int, feat_name: str = '', feat_id: int | None = None) → List[List[str]]

Determine geographic connection from (feat.) value.

This function builds bit patterns for all pairs of regions. The bit pattern will have as many bits as there are time slices (epochs), and will be sorted according to the time indices provided in the feature summary .csv file specified by the user. So if the youngest epoch has time index 1 and the oldest has time index 3, a bit pattern ‘100’ indicates that for a given pair of regions, at the present moment (youngest epoch) there is connectivity.

Parameters:

• feat_col (GeoFeatureCollection) – A GeoFeatureCollection object containing all information available for features over time.

• val2match (int) – Categorical (feature) value that, if matched, indicate the geographic connection between two regions.

• feat_name (str) – Name of the feature.

• feat_id (int, optional) – Feature index. Defaults to ‘None’.

Returns:

Two-dimensional list of strings. These strings are

bit patterns denoting the manifestation of a geographic condition (e.g., a barrier), for each pair of regions, for each epoch.

Return type:

(list)

conn_graph_list: List[GeoGraph]

static cw_feature_equals_value(feat_col: GeoFeatureCollection, val2match: int, feat_name: str = '', feat_id: int = None) → List[str]

Determine geographic condition from (feat.) value requirement.

The feature must be ‘categorical-within’.

Parameters:

• feat_col (GeoFeatureCollection)

• val2match (int) – Categorical (feature) value that, if matched, indicate the manifestation of the geographic condition.

• feat_name (str) – Name of the feature.

• feat_id (int, optional) – Feature index. Defaults to ‘None’.

Returns:

List of strings. These strings are bit patterns

denoting the manifestation of the geographic condition for each region, in the different epochs.

Return type:

(list)

feat_coll: GeoFeatureCollection

find_epoch_idx(an_age: float) → int

Parameters:

an_age (float) – The age of an event.

Returns:

Index of epoch containing ‘an_age’ (with 0 being

present).

Return type:

(int)

geo_cond_bit_dict: Dict[str, List[List[str]] | List[str]]

geo_cond_change_back_times_dict: Dict[str, List[List[float]] | List[List[List[float]]]]

geo_cond_change_times_dict: Dict[str, List[List[float]] | List[List[List[float]]]]

geo_cond_name: str

get_comm_classes(an_age: float) → List[Set[int]]

get_geo_condition_change_back_times(geo_cond_name: str) → Dict[str, List[List[float]] | List[List[List[float]]]]

get_geo_condition_change_times(geo_cond_name: str) → Dict[str, List[List[float]] | List[List[List[float]]]]

get_geo_oldest_condition_bit(geo_cond_name)

n_regions: int

n_time_slices: int

populate_geo_cond_member_dicts(geo_cond_name: str, w_bw_bit_patterns: List[List[str]] | List[str], is_directed: bool = False, user_young2old: bool = True) → None

Populate geographic connectivity bit dictionaries

e.g., for 2 regions, 3 epochs {“altitude”: [“010”, “010”]} the 0’s represent no geographic connectivity, while 1’s represent connectivities (depending on the requirement function provided by the user).

Populates self.geo_cond_name.

Parameters:

• geo_cond_name (str) – Name of the geographic condition (e.g., “mountain range”, “ancient sea”, “riverine barrier”).

• w_bw_bit_patterns (list) – Within or between bit patterns returned from connectivity function, one bit per epoch. If within-region features, this will be a list of strings. If between-region features, this will be a 2-D list.

• is_directed (bool) – Flag specifying if connectivity graph is directed or not. Defaults to False.

• user_young2old (bool) – Flag specifying if epochs (their ages specifically) are passed from young to old. Defaults to True.

classmethod qb_feature_threshold(feat_col: GeoFeatureCollection, threshold: float, above: bool, feat_name: str = '', feat_id: int = None) → List[List[str]]

static qw_feature_threshold(feat_col: GeoFeatureCollection, threshold: float, above: bool, feat_name: str = '', feat_id: int = None) → List[List[float]]

class phylojunction.functionality.feature_io.GeoFeatureRelationship(*values)

Bases: Enum

BETWEEN = 'between'

WITHIN = 'within'

class phylojunction.functionality.feature_io.GeoFeatureType(*values)

Bases: Enum

CATEGORICAL = 'categorical'

QUANTITATIVE = 'quantitative'

class phylojunction.functionality.feature_io.GeoGraph(n_nodes: int)

Bases: object

Parameters:

• n_nodes (int)

• node_set (set)

• edge_set (set)

add_edge(node1_idx: int, node2_idx: int, is_directed: bool = False) → None

add_node(node_idx: int) → None

are_connected(node1_idx: int, node2_idx: int, range_bit_pattern: str = '') → bool

Return boolean for two nodes in the same comm class.

If two nodes are in the same communicating class AND the necessary (in-between) regions in the range are occupied, it means they are connected in the connectivity graph.

Parameters:

• node1_idx (int) – Index of node 1 (region 1).

• node2_idx (int) – Index of node 2 (region 2).

• range_bit_pattern (str) – Bit pattern of range

Returns:

If two nodes are connected

Return type:

(bool)

comm_class_set_list: List[Set[int]]

property edge_dict: Dict[int, Set[int]]

property edge_set: Set[Tuple[int]]

property n_comm_classes: int

over_barrier(node1_idx: int, node2_idx: int, directed: bool = False) → bool

Return boolean for two regions depending on barrier existence

If two nodes (i.e., each node being a region) have an edge between them, it means they are are connected directly, and thus there is no barrier between them. If they are not directly connected, there is a barrier between them.

When edge direction matters, only edges from node1 to node 2 are considered. Otherwise the edge on the opposite direction is additionally considered.

Parameters:

• node1_idx (int) – Index of node 1 (region 1).

• node2_idx (int) – Index of node 2 (region 2).

• directed (bool) – If direction of connectivity edge matters. Defaults to ‘False’.

Returns:

True if two regions have a barrier between them.

Return type:

(bool)

populate_comm_class_members() → None

Populate communicating-class-related members.

Side-effect is to populate:

1. self.comm_class_set_list

2. self._node_comm_class_dict

3. self._n_comm_classes

Communicating classes are mutually exclusive sets of nodes that are connected to each other directly or indirectly. A connection is established by a single directed edge (even if it is missing in the other direction).

class phylojunction.functionality.feature_io.MyCallableType(*args, **kwargs)

Bases: Protocol

phylojunction.functionality.stoch_map module

class phylojunction.functionality.stoch_map.NoChange(n_regions: int, state: int, state_bit_patt: str, focal_node_name: str, parent_node_name: str, child_node_name: str)

Bases: StochMap

Stochastic map class for no-change.

When nothing happens along a branch, we want to still record this for updating nodes in an AnnotatedTree object.

Parameters:

• str_representation (str) – String representation of stochastic map for printing.

• state (int) – Integer representation of node’s state.

size_of_unchanging_range: int

state: int

str_representation: str

class phylojunction.functionality.stoch_map.RangeContraction(region_lost_idx: int, n_regions: int, age: float, from_state: int, from_state_bit_patt: str, to_state: int, to_state_bit_patt: str, focal_node_name: str, parent_node_name: str, child_node_name: str, time: float | None = None)

Bases: StochMap

Stochastic map class for local (anagenetic) extinction.

When a lineage goes locally extinct, its range contracts by one region.

str_representation

String representation of stochastic map for printing.

Type:

str

size_of_contracting_range

Size of starting range.

Type:

int

size_of_final_range

Size of resulting range after dispersal.

Type:

int

region_lost_idx

Index of region that was added to the starting range (index is the position of the region in the bit pattern).

Type:

int

property previously_unstable_wrt_split: bool

region_lost_idx: int

short_str() → str

Summarize stochastic map into short string.

This is an abstract method of EvolRelevantEvent.

Returns:

Short string with all information on range expansion.

Return type:

(str)

size_of_contracting_range: int

size_of_final_range: int

str_representation: str

property unstable_after_contr_wrt_split: bool

class phylojunction.functionality.stoch_map.RangeExpansion(region_gained_idx: int, n_regions: int, age: int, from_state: int, from_state_bit_patt: str, to_state: int, to_state_bit_patt: str, focal_node_name: str, parent_node_name: str, child_node_name: str, from_region_idx: int | None = None, time: float | None = None)

Bases: StochMap

Stochastic map class for (anagenetic) dispersal.

When a lineage disperses, its range is incremented by one region.

Parameters:

• str_representation (str) – String representation of stochastic map for printing.

• size_of_expanding_range (int) – Size of starting range.

• size_of_final_range (int) – Size of resulting range after dispersal.

• region_gained_idx (int) – Index of region that was added to the starting range (index is the position of the region in the bit pattern).

• over_barrier (bool, optional) – Flag specifying if the dispersal was over a barrier. Note that even though the dispersal may have been over a barrier, it may not matter for a focal range-split (speciation) event. It may also involve regions that belong to the same communicating class.

• within_comm_class (bool, optional) – Flag specifying if the dispersal was among regions that belong to the same communicating class. Note that even if regions do not belong to the same class, the dispersal may not matter for a focal range-split (speciation) event.

• split_relevant (bool, optional) – Flag specified if dispersal matters for range split happening in the future.

• erased_by_extinction (bool, optional) – Flag specifying if the expanded range contracted in the reverse direction later on, due to extinction.

property from_region_idx: int

gained_region_is_lost_in_future()

property over_barrier: bool

property previously_unstable_wrt_split: bool

region_gained_idx: int

short_str() → str

Summarize stochastic map into short string.

This is an abstract method of EvolRelevantEvent.

Returns:

Short string with all information on range expansion.

Return type:

(str)

size_of_expanding_range: int

size_of_final_range: int

property split_relevant: bool

property stabilized_range_wrt_split: bool

str_representation: str

property within_comm_class: bool

class phylojunction.functionality.stoch_map.RangeSplitOrBirth(n_regions: int, age: float, from_state: int, from_state_bit_patt: str, to_state: int, to_state_bit_patt: str, focal_node_name: str, parent_node_name: str, child_node_name: str, child2_node_name: str, to_state2: int | None = None, to_state2_bit_patt: str | None = None, time: float | None = None)

Bases: StochMap

Stochastic map class for cladogenetic event.

Range either splits between children, e.g., ABC -> AB, C (upon b/w-region speciation)

or

One-sized range is born and inherited by only one child, e.g., ABC -> ABC, A (upon within-region speciation).

str_representation

String representation of stochastic map for printing.

Type:

str

range_split

Flag specifying if range split.

Type:

bool

size_of_splitting_node_range

Size of parent’s starting range, before split.

Type:

int

size_of_child1_range

Size of first child range.

Type:

int

size_of_child2_range

Size of second child range.

Type:

int

add_child2_info(to_state2: int, to_state2_bit_patt: str) → None

range_split: bool

short_str() → str

Summarize stochastic map into short string.

This is an abstract method of EvolRelevantEvent.

Returns:

Short string with all information on range expansion.

Return type:

(str)

size_of_child1_range: int

size_of_child2_range: int

size_of_splitting_node_range: int

property splitting_range_unstable: bool

str_representation: str

class phylojunction.functionality.stoch_map.StochMap(n_chars: int, age: float | None, from_state: int, from_state_bit_patt: str, to_state: int, to_state_bit_patt: str, focal_node_name: str, parent_node_name: str, child_node_name: str, map_type: str | None = None, time: int | None = None, from_state_idx_set: Set[int] | None = None, to_state_idx_set: Set[int] | None = None, to_state2: int | None = None, to_state2_bit_patt: str | None = None, to_state2_idx_set: Set[int] | None = None, child2_node_name: str | None = None)

Bases: EvolRelevantEvent

Parent class for a single stochastic map.

Parameters:

• from_state (int) – Integer representation of source state (i.e., source biogeographic range).

• from_state_bit_patt (str) – Bit pattern representation of source state (i.e., source biogeographic range).

• from_state_idx_set (set) – Set of indices corresponding to the position of ‘1’s in the ‘from_state_bit_patt’.

• to_state (int) – Integer representation of target state (i.e., target biogeographic range).

• to_state_bit_patt (str) – Bit pattern representation of target state (i.e., target biogeographic range).

• to_state_idx_set (set) – Set of indices corresponding to the position of ‘1’s in ‘to_state_bit_patt’, for child 1.

• to_state2 (int) – Integer representation of second target state if stochastic map is cladogenetic (i.e., second target biogeographic range).

• to_state2_bit_patt (str) – Bit pattern representation of second target state if stochastic map is cladogenetic (i.e., second target biogeographic range).

• to_state2_idx_set (set) – Set of indices corresponding to the position of ‘1’s in ‘to_state_bit_patt’, for child 2.

• focal_node_name (str) – Name of the node subtending the branch along which the stochastic map was placed.

• parent_node_name (str) – Name of the node parent to the focal node.

• child_node_name (str) – Name of the first child node of the focal node.

• child2_node_name (str) – Name of the second child node of the focal node.

• map_type (str) – Class of stochastic map (e.g., ‘expansion’,

• 'contraction'

• 'range_split'

• None. ('no_change'). Defaults to)

child2_node_name: str

child_node_name: str

focal_node_name: str

from_state: int

from_state_bit_patt: str

from_state_idx_set: Set[int]

map_type: str

parent_node_name: str

short_str() → str

to_state: int

to_state2: int

to_state2_bit_patt: str

to_state2_idx_set: Set[int]

to_state_bit_patt: str

to_state_idx_set: Set[int]

class phylojunction.functionality.stoch_map.StochMapsOnTree(iteration_idx: int, ann_tr: AnnotatedTree, state2bit_lookup: State2BitLookup, node_attr_file_path: str, stoch_map_attr_name: str)

Bases: object

Collection of stochastic maps on a single tree.

This collection of stochastic maps consists of all stochastic maps logged during a single iteration.

Parameters:

• ann_tr (AnnotatedTree) – AnnotatedTree object on which maps are placed. There should be one different tree for each StochMapsOnTree object.

• no_change_stoch_maps_dict (dict) – Dictionary with node names as keys and a single StochMap object as values.

• anagenetic_stoch_maps_dict (dict) – Dictionary with node names as keys and a list of StochMap objects as values.

• cladogenetic_stoch_maps_dict (dict) – Dictionary with node_names as keys and a single StochMap object as values.

• identical_cladogenetic_stoch_maps_dict (dict)

• iteration_idx (int)

• state2bit_lookup (State2BitLookup) – Object of class for converting between integer and bit pattern state representations.

• n_regions (int) – Total number of atomic regions in the system.

• maps_counts_dict (dict) – Dictionary with two-sized string tuples as keys (string are bit patterns for source and target ranges), and counts as values. It keeps track of how many stochastic maps of different kinds there are.

• n_no_changes (int) – Total count of no change maps.

• n_total_maps (int) – Total count of stochastic maps.

• n_anagenetic_maps (int) – Count of stochastic maps consisting of anagenetic range changes.

• n_range_exp_maps (int) – Count of range expansion stochastic maps.

• n_range_cont_maps (int) – Count of range contraction stochastic maps.

• pctg_anagenetic_maps (float) – Percentage of anagenetic stochastic maps.

• forbidden_higher_order_maps_counts_dict (dict) – Dictionary with two-sized string tuples as keys (string are bit patterns for source and target ranges), and counts as values. This dictionary keeps track of how many forbidden higher-order (more than one region is gained/lost simultaneously) maps there are.

• n_forbidden_higher_order_anagenetic_maps (int) – Count of forbidden higher-order anagenetic stochastic maps. Higher- order anagenetic changes happen when one or more regions are gained or lost simultaneously.

• pctg_forbidden_higher_order_anagenetic_maps (float) – Percentage of forbidden higher-order anagenetic stochastic maps.

• n_different_clado_maps (int) – Count of different cladogenetic stochastic maps.

• n_identical_clado_maps (int) – Count of identical cladogenetic stochastic maps.

• str_representation (str) – String representation of collection of stochastic maps for printing.

add_map(stoch_map_str_list: List[str]) → None

Add new stochastic map to bookeeping class members.

This method reads a list of strings carrying information about a stochastic map, and depending on what those strings are, the appropriate stochastic map objects are created and stored.

Side-effects of this method populate:

1. self.n_total_maps

2. self.n_no_change_maps

3. self.n_anag_maps

4. self.n_identical_clado_maps

5. self.n_different_clado_maps

6. self.n_range_exp_maps

7. self.n_cont_exp_maps

8. self.n_forbidden_higher_order_anag_maps

9. self.no_change_stoch_maps_dict

10. self.anag_stoch_maps_dict

11. self.clado_stoch_maps_dict

12. self.identical_clado_stoch_maps_dict

13. self.forbidden_higher_order_maps_counts_dict

anag_stoch_maps_dict: Dict[str, List[StochMap]]

ann_tr: AnnotatedTree

clado_stoch_maps_dict: Dict[str, StochMap]

forbidden_higher_order_maps_counts_dict: Dict[Tuple[str], int]

get_clado_distribution() → Dict[int, int]

identical_clado_stoch_maps_dict: Dict[str, List[str]]

iteration_idx: int

maps_counts_dict: Dict[Tuple[str], int]

n_anag_maps: int

n_chars: int

n_different_clado_maps: int

n_forbidden_higher_order_anag_maps: int

n_identical_clado_maps: int

n_no_change_maps: int

n_range_cont_maps: int

n_range_exp_maps: int

n_total_maps: int

no_change_stoch_maps_dict: Dict[str, StochMap]

pctg_anagenetic_maps: float

pctg_forbidden_higher_order_anag_maps: float

state2bit_lookup: State2BitLookup

str_representation: str

update_tree_attributes(stoch_map_attr_name: str, debug: bool = False) → None

Go through stochastic maps and update tree.

This function is called outside of StochMapsOnTree. It goes through the two stochastic maps dictionaries, and updates the AnnotatedTree member with respect to its (i) node’s attributes, and (ii) node_attr_dict member.

This function has no return and only side-effects.

Parameters:

stoch_map_attr_name (str) – Name of the node attribute the stochastic maps carry a value for (e.g., ‘state’)

class phylojunction.functionality.stoch_map.StochMapsOnTreeCollection(stoch_maps_file_path: str, ann_trs: List[AnnotatedTree], state2bit_lookup: State2BitLookup, stoch_map_attr_name: str = '', node_states_file_path: str = '')

Bases: object

Collection of StochMapsOnTree objects.

This class reads through a table with (normally multiple) iterations of logged stochastic maps, and maps them to one or more annotated trees – storing them as objects of StochMapsOnTree. These are in turn stored in class members.

n_char

Number of characters.

Type:

int

stoch_maps_tree_dict

Dictionary with iteration indices as keys, and StochMapsOnTree objects as values.

Type:

dict

n_stoch_map_iterations

Total number of MCMC iterations where stochastic maps were logged.

Type:

int

sorted_it_idxs

This is the sorted indices of iterations for which stochastic maps were logged. Not all iterations have maps, which is why we keep track of those who do.

Type:

int

str_representation

String representation of class instance for printing.

Type:

str

iter_mcmc_generations() → Iterator[StochMapsOnTree]

n_char: int

n_stoch_map_iterations: int

sorted_it_idxs: List[int]

stoch_maps_tree_dict: Dict[int, StochMapsOnTree]

str_representation: str

Module contents