Migration models

Bases: ABC

Abstract base class for migration models. If creating a custom migration model, users must create a child class which inherits from this class. See Parameters for an explanation of the constructor parameters.

Migration are used to define a distance function \(d(a,b)\) between each pair of sites a and b. The probability that cell \(c\) migrates from \(a\) to \(b\) is given as

\[\begin{split}\alpha_c(a, b) = \left\{\begin{array}{lr} 0 & \text{if } a = b, \\ \frac{1}{d(a,b)} \cdot \epsilon & \text{otherwise}\end{array}\right\},\end{split}\]

where \(\epsilon\) is a per-generation baseline migration rate.

Parameters:

libraries (BaseLibrary, List[BaseLibrary]) – The primary site selection library, or a list of libraries (one for each site). Required.
params (Parameters, optional)
nsites (int, optional)
growth_rate (float, optional)
max_growth_rate_multiplier (int, float, optional)
capacities (int, List[int], optional)
epsilon (float, optional)
t_max (int, optional)
N0 (int, optional)

exp_pop

A list of lists, one for each site, containing the expected population size for each generation t=0,…,t_max.

Type:: List[list]

dists

The pairwise distances between anatomical sites, in order of the upper triangular indices.

Type:: array

points

If initialized with random distances, contains the 2d coordinates of each site used to derive the distances.

Type:: array

create_random_metastatic_libraries(method: str = 'random', params: Parameters | None = None, alter_prop: float | None = None, CN_coeff: float | None = None)

Creates site-specific selection libraries. The anatomy class defaults to using the same selection library for all sites, and this method is only used if site-specific selection is desired. There are two options for the method parameter: ‘random’ or ‘distance’. If random, the number of selection coefficients in each metastatic site will differ from the primary site with a ratio near alter_prop. If distance, the number of selection coefficients that differ between all pairs of sites will roughly align with the pairwise distance matrix created with the initialize_distance method See Parameters for an explanation of the parameters.

Parameters:

method (str) – The method used to create the metastatic libraries. Must be either ‘random’ or ‘distance’.
params (Parameters, optional)
alter_prop (float, optional)
CN_coeff (float, optional)

abstractmethod get_oneway_transition_probabilities(clone)

Method which returns an array of the migation probabilities between the clone and all sites at the current generation

Parameters:: clone (Clone, optional) – The clone.
Returns:: The migration probabilities.
Return type:: list

abstractmethod get_total_transition_probability(clone)

Method which returns the total probability that a clone migrates to any other site.

Parameters:: clone (Clone, optional) – The clone.
Returns:: The total migration probability.
Return type:: float

initialize_distances(method='random', matrix=None, path=None)

Method used to initialize the organotropism priors.

Parameters:

method (str) – The method used to initialize the distances. Either ‘random’ or ‘precomputed’. If precomputed, must provide either a matrix or path. Note that if precomputed, the distance between a and itself must be 0.
matrix (list, np.ndarray) – A pairwise distance matrix. Must either be square or 1d containing just the upper triangular indices in order.
path (str) – Instead of passing a python object, users can also provide a path to a file containing the distance matrix. Each row of the matrix should be on a separate line, and values should be separated by 0s.

class sistem.anatomy.SimpleAnatomy(libraries: BaseLibrary | List[BaseLibrary] | None, **kwargs)

The simplest migration model. Use for simulating single-site experiments, or if you want an identical fixed migration probability to each site for every cell at every generation (\(d(a,b)=1\) for all \(a,b\)).

get_oneway_transition_probabilities(clone)

Method which returns an array of the migation probabilities between the clone and all sites at the current generation

Parameters:: clone (Clone, optional) – The clone.
Returns:: The migration probabilities.
Return type:: list

get_total_transition_probability(clone)

Method which returns the total probability that a clone migrates to any other site.

Parameters:: clone (Clone, optional) – The clone.
Returns:: The total migration probability.
Return type:: float

class sistem.anatomy.StaticAnatomy(libraries: BaseLibrary | List[BaseLibrary] | None, **kargs)

The static migration model.

In this model, the probabiltiy of migrations from site \(a\) to site \(b\) depend on the distance \(d(a,b)\), but are the same for each cell in the site at each generation.

get_oneway_transition_probabilities(clone)

Method which returns an array of the migation probabilities between the clone and all sites at the current generation

Parameters:: clone (Clone, optional) – The clone.
Returns:: The migration probabilities.
Return type:: list

get_total_transition_probability(clone)

Method which returns the total probability that a clone migrates to any other site.

Parameters:: clone (Clone, optional) – The clone.
Returns:: The total migration probability.
Return type:: float

initialize_distances(method='random', matrix=None, path=None)

Method used to initialize the organotropism priors.

Parameters:

method (str) – The method used to initialize the distances. Either ‘random’ or ‘precomputed’. If precomputed, must provide either a matrix or path. Note that if precomputed, the distance between a and itself must be 0.
matrix (list, np.ndarray) – A pairwise distance matrix. Must either be square or 1d containing just the upper triangular indices in order.
path (str) – Instead of passing a python object, users can also provide a path to a file containing the distance matrix. Each row of the matrix should be on a separate line, and values should be separated by 0s.

class sistem.anatomy.GenotypeAnatomy(libraries: BaseLibrary | List[BaseLibrary] | None, **kargs)

The genotype migration model.

In this model, the probability of cell \(c\) migrating from site \(a\) to site \(b\) increases as \(c\) gains beneficial mutations with respect to the selection landscape of \(b\). In particular, distance is defined as

\[d(a,b) = \Big(\log{\frac{s_b(c)}{\hat{s}_{b}}}\Big)^{-1},\]

where \(\hat{s}_{b}\) is the fitness of a non-mutated cell in site \(b\). In other words, the probability that cell \(c\) successfully migrates to \(a\) site \(b\) increases as the cell acquires beneficial mutations. When used in conjunction with site-specific selection libraries, migration probabilities can also reflect compatibility with the the fitness landscape \(b\).

get_oneway_transition_probabilities(clone)

Method which returns an array of the migation probabilities between the clone and all sites at the current generation

Parameters:: clone (Clone, optional) – The clone.
Returns:: The migration probabilities.
Return type:: list

get_total_transition_probability(clone)

Method which returns the total probability that a clone migrates to any other site.

Parameters:: clone (Clone, optional) – The clone.
Returns:: The total migration probability.
Return type:: float