trans_mat module

itrails.trans_mat.bell_numbers(n)

Given a number ‘n’, returns the n’th Bell Number used for initializing the matrices with the correct number of rows.

Parameters:

n (int.) – number for which the Bell number is returned.

Returns:

the n’th Bell Number.

Return type:

int.

itrails.trans_mat.find_norevcoal(state_array, species, state_dict)

Given a state array and number of species, returns all possible non-reversible coalescences for each state; produces an array with (4*species + 3) columns where the first 2*species columns represent the state before the event and the next 2*species columns represent the state after the event.

Parameters:

• state_array (np.array of int with shape (Bell number, n_species*2).) – set partition array for the given number of species.

• species (int.) – number of species.

• state_dict (dict.) – dictionary mapping each state tuple to its corresponding number.

Returns:

array with non-reversible coalescences.

Return type:

np.array.

itrails.trans_mat.find_revcoal_recomb(state_array, species, state_dict)

Given a state array and number of species, returns all possible reversible coalescences (and recombinations) for each state; produces an array with (4*species + 3) columns where the first 2*species columns represent the state before the event and the next 2*species columns represent the state after the event.

Parameters:

• state_array (np.array of int with shape (Bell number, n_species*2).) – set partition array for the given number of species.

• species – number of species. :type species: int.

• state_dict (dict.) – dictionary mapping each state tuple to its corresponding number.

Returns:

array with reversible coalescences and recombinations.

Return type:

np.array.

itrails.trans_mat.get_omega_nonrev_counts(species)

Computes and returns a dictionary mapping each omega value (sum of selected mss values) to its corresponding non-reversible coalescence count (subset size minus one).

Parameters:

species (int.) – number of species.

Returns:

dictionary mapping omega values to non-reversible counts.

Return type:

nb.typed.Dict.

itrails.trans_mat.get_trans_mat(transition_mat, species, coal, rho)

Computes the CTMC transition probability matrix given a transition matrix, number of species, coal rate, and recombination rate; the matrix size is determined by the Bell number for 2*species and the diagonal is set to the negative sum of the off-diagonals.

Parameters:

• transition_mat (np.array.) – array representing the transition events.

• species (int.) – number of species.

• coal (float.) – rate for non-reversible coalescence.

• rho (float.) – rate for reversible events (recombination).

Returns:

transition probability matrix.

Return type:

np.array of float64.

itrails.trans_mat.number_array_1(state_array, species, mss, tuple_omegas=UniTuple(int64, 2), tuple_states=UniTuple(int64, 2))

For the 1-species CTMC, generates two dictionaries: an omega dictionary that tracks the location of each coalescence state (keys are tuples of minimum increasing substring sums) and a state dictionary mapping each state tuple to its index.

Parameters:

• state_array (np.array of int with shape (Bell number, n_species*2).) – array with every set partition for 1 species.

• species (int.) – number of species.

• mss (list[int].) – list of minimum increasing substring sums.

• tuple_omegas (nb.types.Tuple.) – nb.types.Tuple for the omega dictionary keys.

• tuple_states (nb.types.Tuple.) – nb.types.Tuple for the state dictionary keys.

Returns:

omega dictionary and state dictionary.

Return type:

tuple.

itrails.trans_mat.number_array_2(state_array, species, mss, tuple_omegas=UniTuple(int64, 2), tuple_states=UniTuple(int64, 4))

For the 2-species CTMC, generates two dictionaries: an omega dictionary tracking the location of each coalescence state (keys are tuples of minimum increasing substring sums) and a state dictionary mapping each state tuple to its index.

Parameters:

• state_array (np.array of int with shape (Bell number, n_species*2).) – array with every set partition for 2 species.

• species (int.) – number of species.

• mss (list[int].) – list of minimum increasing substring sums.

• tuple_omegas (nb.types.Tuple.) – nb.types.Tuple for omega dictionary keys.

• tuple_states (nb.types.Tuple.) – nb.types.Tuple for state dictionary keys.

Returns:

omega dictionary and state dictionary.

Return type:

tuple.

itrails.trans_mat.number_array_3(state_array, species, mss, tuple_omegas=UniTuple(int64, 2), tuple_states=UniTuple(int64, 6))

For the 3-species CTMC, generates two dictionaries: an omega dictionary tracking the location of each coalescence state (keys are tuples of minimum increasing substring sums) and a state dictionary mapping each state tuple to its index.

Parameters:

• state_array (np.array of int with shape (Bell number, n_species*2).) – array with every set partition for 3 species.

• species (int.) – number of species.

• mss (list[int].) – list of minimum increasing substring sums.

• tuple_omegas (nb.types.Tuple.) – nb.types.Tuple for omega dictionary keys.

• tuple_states (nb.types.Tuple.) – nb.types.Tuple for state dictionary keys.

Returns:

omega dictionary and state dictionary.

Return type:

tuple.

itrails.trans_mat.partition(collection)

Generator that creates all set partitions from a list of consecutive numbers; for a given list, it yields nested lists representing all possible partitions of its elements into at most len(collection) subsets.

Parameters:

collection (list[int].) – list of integers ranging from 1 to n.

Returns:

generator yielding lists of lists representing the partitions.

Return type:

generator.

itrails.trans_mat.set_partitions(species)

Returns the set partitions for a given number of species in the CTMC by using the bell_numbers and partition generator; the resulting numpy array reformats each partition so that each number represents one nucleotide position (e.g., partition [[1,2,3],[4,5,6]] becomes [1,1,1,2,2,2]).

Parameters:

species (int.) – number of species for which partitions are generated.

Returns:

numpy array with reformatted set partitions.

Return type:

np.array.

itrails.trans_mat.translate_to_minimum(array)

Reformats a set partition so that its values are renumbered consecutively starting from 1; for example, converts [1,2,2,2,4,4] to [1,2,2,2,3,3].

Parameters:

array (np.array of int with shape (1, n_species*2).) – set partition to reformat.

Returns:

reformatted set partition with consecutive minimum values.

Return type:

np.array of int with shape (1, n_species*2).

itrails.trans_mat.wrapper_state_1()

Wrapper function that returns the transition matrix, omega dictionary, state dictionary, and omega non-reversible counts for 1 species.

Returns:

tuple containing transition matrix, omega dictionary, state dictionary, and omega non-reversible counts for 1 species.

Return type:

tuple.

itrails.trans_mat.wrapper_state_2()

Wrapper function that returns the transition matrix, omega dictionary, state dictionary, and omega non-reversible counts for 2 species.

Returns:

tuple containing transition matrix, omega dictionary, state dictionary, and omega non-reversible counts for 2 species.

Return type:

tuple.

itrails.trans_mat.wrapper_state_3()

Wrapper function that returns the transition matrix, omega dictionary, state dictionary, and omega non-reversible counts for 3 species.

Returns:

tuple containing transition matrix, omega dictionary, state dictionary, and omega non-reversible counts for 3 species.

Return type:

tuple.

itrails.trans_mat.wrapper_state_general(species)

Wrapper function that returns the transition matrix, omega dictionary, state dictionary, and omega non-reversible counts for n species (where n must be 1, 2, or 3).

Parameters:

species (int.) – number of species (must be 1, 2, or 3).

Returns:

tuple containing transition matrix, omega dictionary, state dictionary, and omega non-reversible counts.

Return type:

tuple.