DFE parametrizations#
Parametric forms of the distribution of fitness effects (DFE).
Classes:
Base class for DFE parametrizations. |
|
Parametrization for mixture of a gamma and exponential distribution. |
|
Parametrization for a reflected displaced gamma distribution. |
|
Parametrization for a mixture of a gamma and discrete distribution. |
|
Parametrization for a discrete distribution. |
|
Same model as |
|
Frozen parametrization of a DFE. |
- class Parametrization(bounds: Dict[str, Tuple[float, float]] | None = None, scales: Dict[str, Literal['lin', 'log']] | None = None, x0: Dict[str, float] | None = None)[source]#
Bases:
Serializable,ABCBase class for DFE parametrizations.
Note that
get_pdf()is not required to be implemented, provided that the linearized mode of fastDFE is used (which is highly recommended).Methods:
Initialize parametrization.
Get probability distribution function of DFE.
Get probability distribution function of DFE.
Plot the discretized DFE.
Freeze parameters to create a DFE object.
Load object from file.
Unserialize object.
Save object to file.
Serialize object.
-
submodels:
Dict[str,Dict[str,float]] = {'dele': {}, 'full': {}}# The kind of submodels supported by holding some parameters fixed
- __init__(bounds: Dict[str, Tuple[float, float]] | None = None, scales: Dict[str, Literal['lin', 'log']] | None = None, x0: Dict[str, float] | None = None)[source]#
Initialize parametrization.
-
scales:
Dict[str,Literal['lin','log']] = {}# Scales over which to optimize the parameters, either ‘log’ or ‘lin’
- plot(params: dict, intervals: Sequence = array([-inf, -100., -10., -1., 0., 1., inf]), file: str = None, show: bool = True, title: str = 'discretized DFE', ax: plt.Axes = None)[source]#
Plot the discretized DFE.
- Parameters:
- Return type:
plt.Axes
- Returns:
Axes
- classmethod from_file(file: str, classes=None)#
Load object from file.
- Parameters:
classes – Classes to be used for unserialization.
file (
str) – File to load from
- Return type:
Self
-
submodels:
- class GammaExpParametrization(bounds: Dict[str, Tuple[float, float]] | None = None, scales: Dict[str, Literal['lin', 'log']] | None = None, x0: Dict[str, float] | None = None)[source]#
Bases:
ParametrizationParametrization for mixture of a gamma and exponential distribution. This corresponds to model C in polyDFE.
We have the following probability density function:
\[\phi(S; S_d, b, p_b, S_b) = (1 - p_b) f_\Gamma(-S; S_d, b) \cdot \mathbf{1}_{\{S < 0\}} + p_b f_e(S; S_b) \cdot \mathbf{1}_{\{S \geq 0\}}\]where:
\(S_d\) is the mean of the DFE for \(S < 0\)
\(b\) is the shape of the gamma distribution
\(p_b\) is the probability that \(S \geq 0\)
\(S_b\) is the mean of the DFE for \(S \geq 0\)
\(f_\Gamma(x; m, b)\) is the density of the gamma distribution with mean \(m\) and shape \(b\)
\(f_e(x; m)\) is the density of the exponential distribution with mean \(m\)
\(\mathbf{1}_{\{A\}}\) denotes the indicator function, which is 1 if \(A\) is true, and 0 otherwise.
The DFE has often been observed to be multi-modal for negative selection coefficients. A gamma distribution provides a good amount of flexibility to accommodate this. Note that all \(S\) parameters are population-scaled selection coefficients, i.e. \(S = 4N_es\).
Methods:
Get PDF.
Get CDF.
Initialize parametrization.
Freeze parameters to create a DFE object.
Load object from file.
Unserialize object.
Plot the discretized DFE.
Save object to file.
Serialize object.
-
bounds:
Dict[str,Tuple[float,float]] = {'S_b': (0.0001, 100), 'S_d': (-100000.0, -0.01), 'b': (0.01, 10), 'p_b': (0, 0.5)}# Default parameter bounds, using non-zero lower bounds for S_d and S_b due to log-scaled scales
-
scales:
Dict[str,Literal['lin','log']] = {'S_b': 'log', 'S_d': 'log', 'b': 'log', 'p_b': 'lin'}# Scales over which to optimize the parameters
-
submodels:
Dict[str,Dict[str,float]] = {'dele': {'S_b': 1, 'p_b': 0}, 'full': {}}# The kind of submodels supported by holding some parameters fixed
- static get_pdf(S_d: float, b: float, p_b: float, S_b: float, **kwargs)[source]#
Get PDF.
- Parameters:
- Return type:
- Returns:
Function that accepts an array of selection coefficients and returns their probability density
- static get_cdf(S_d: float, b: float, p_b: float, S_b: float, **kwargs)[source]#
Get CDF.
- Parameters:
- Return type:
- Returns:
Function that accepts an array of selection coefficients and returns their cumulative probability
- __init__(bounds: Dict[str, Tuple[float, float]] | None = None, scales: Dict[str, Literal['lin', 'log']] | None = None, x0: Dict[str, float] | None = None)#
Initialize parametrization.
- classmethod from_file(file: str, classes=None)#
Load object from file.
- Parameters:
classes – Classes to be used for unserialization.
file (
str) – File to load from
- Return type:
Self
- classmethod from_json(json: str, classes=None)#
Unserialize object.
- Parameters:
classes – Classes to be used for unserialization
json (
str) – JSON string
- Return type:
Self
- class DisplacedGammaParametrization(bounds: Dict[str, Tuple[float, float]] | None = None, scales: Dict[str, Literal['lin', 'log']] | None = None, x0: Dict[str, float] | None = None)[source]#
Bases:
ParametrizationParametrization for a reflected displaced gamma distribution.
We have the following probability density function:
\[\phi(S; \hat{S}, b, S_{max}) = f_\Gamma(S_{max} - S; S_{max} - \hat{S}, b) \cdot \mathbf{1}_{\{S \leq S_{max}\}}\]where:
\(\hat{S}\) is the mean of the DFE
\(b\) is the shape of the gamma distribution
\(S_{max}\) is the maximum value that \(S\) can take
\(f_\Gamma(x; m, b)\) is the density of the gamma distribution with mean \(m\) and shape \(b\)
\(\mathbf{1}_{\{A\}}\) denotes the indicator function, which is 1 if \(A\) is true, and 0 otherwise.
This parametrization uses a single gamma distribution for both positive and negative selection coefficients. This is a less flexible parametrization, which may produce results similar to the other models while requiring fewer parameters. Note that all \(S\) parameters are population-scaled selection coefficients, i.e. \(S = 4N_es\).
Warning
This model does not allow for a purely deleterious sub-parametrization, so
Inference.compare_nested_models()won’t work as expected.Methods:
Get PDF.
Get CDF.
Initialize parametrization.
Freeze parameters to create a DFE object.
Load object from file.
Unserialize object.
Plot the discretized DFE.
Save object to file.
Serialize object.
-
bounds:
Dict[str,Tuple[float,float]] = {'S_max': (0.001, 100), 'S_mean': (-100000, -0.01), 'b': (0.01, 10)}# Default parameter bounds
-
scales:
Dict[str,Literal['lin','log']] = {'S_max': 'log', 'S_mean': 'log', 'b': 'lin'}# Scales over which to optimize the parameters
-
submodels:
Dict[str,Dict[str,float]] = {'dele': {}, 'full': {}}# The kind of submodels supported by holding some parameters fixed
- __init__(bounds: Dict[str, Tuple[float, float]] | None = None, scales: Dict[str, Literal['lin', 'log']] | None = None, x0: Dict[str, float] | None = None)#
Initialize parametrization.
- classmethod from_file(file: str, classes=None)#
Load object from file.
- Parameters:
classes – Classes to be used for unserialization.
file (
str) – File to load from
- Return type:
Self
- classmethod from_json(json: str, classes=None)#
Unserialize object.
- Parameters:
classes – Classes to be used for unserialization
json (
str) – JSON string
- Return type:
Self
- class GammaDiscreteParametrization(bounds: Dict[str, Tuple[float, float]] | None = None, scales: Dict[str, Literal['lin', 'log']] | None = None, x0: Dict[str, float] | None = None)[source]#
Bases:
ParametrizationParametrization for a mixture of a gamma and discrete distribution. This corresponds to polyDFE’s model B.
We have the following probability density function:
\[\phi(S; S_d, b, p_b, S_b) = (1 - p_b) f_{\Gamma}(S; S_d, b) \cdot \mathbf{1}_{\{S < 0\}} + p_b \cdot S_b \cdot \mathbf{1}_{\{0 \leq S \leq 1 / S_b\}}\]where:
\(S_d\) is the mean of the DFE for \(S < 0\)
\(b\) is the shape of the gamma distribution
\(p_b\) is the probability that \(S \geq 0\)
\(S_b\) is the shared selection coefficient of all positively selected mutations up to \(1/S_b\)
\(f_\Gamma(x; m, b)\) is the density of the gamma distribution with mean \(m\) and shape \(b\)
This parametrization is similar to
GammaExpParametrization, but uses a constant mass for positive selection coefficients. The results should be rather similar in most cases. Note that all \(S\) parameters are population-scaled selection coefficients, i.e. \(S = 4N_es\).Methods:
Get PDF.
Get CDF.
Initialize parametrization.
Freeze parameters to create a DFE object.
Load object from file.
Unserialize object.
Plot the discretized DFE.
Save object to file.
Serialize object.
-
bounds:
Dict[str,Tuple[float,float]] = {'S_b': (0.0001, 100), 'S_d': (-100000.0, -0.01), 'b': (0.01, 10), 'p_b': (0, 0.5)}# default parameter bounds
-
scales:
Dict[str,Literal['lin','log']] = {'S_b': 'log', 'S_d': 'log', 'b': 'log', 'p_b': 'lin'}# scales over which to optimize the parameters
-
submodels:
Dict[str,Dict[str,float]] = {'dele': {'S_b': 1, 'p_b': 0}, 'full': {}}# The kind of submodels supported by holding some parameters fixed
- static get_pdf(S_d: float, b: float, p_b: float, S_b: float, **kwargs)[source]#
Get PDF.
- Parameters:
- Return type:
- Returns:
Function that accepts an array of selection coefficients and returns their probability density
- static get_cdf(S_d: float, b: float, p_b: float, S_b: float, **kwargs)[source]#
Get CDF.
- Parameters:
- Return type:
- Returns:
Function that accepts an array of selection coefficients and returns their cumulative probability
- __init__(bounds: Dict[str, Tuple[float, float]] | None = None, scales: Dict[str, Literal['lin', 'log']] | None = None, x0: Dict[str, float] | None = None)#
Initialize parametrization.
- classmethod from_file(file: str, classes=None)#
Load object from file.
- Parameters:
classes – Classes to be used for unserialization.
file (
str) – File to load from
- Return type:
Self
- classmethod from_json(json: str, classes=None)#
Unserialize object.
- Parameters:
classes – Classes to be used for unserialization
json (
str) – JSON string
- Return type:
Self
- class DiscreteParametrization(intervals: Sequence = array([-100000, -100, -10, -1, 0, 1, 1000]), bounds: Dict[str, Tuple[float, float]] | None = None, scales: Dict[str, Literal['lin', 'log']] | None = None, x0: Dict[str, float] | None = None)[source]#
Bases:
ParametrizationParametrization for a discrete distribution. This corresponds to polyDFE’s model D. By default we use 6 bins, but this can be changed by passing a different array to the constructor. The resulting parameter names are \(S_1, S_2, \dots, S_k\), where \(k\) is the number of bins.
That is, the probability density function is given by:
\(\phi(S; S_1, S_2, \dots, S_k) = \sum_{i=1}^{k} S_i/c_i \cdot \mathbf{1}_{\{S \in B_i\}}\) such that \(\sum_{i=1}^{k} S_i = 1,\)
where \(B_i\) and \(c_i\) are interval \(i\) and the width of interval \(i\), respectively.
This parametrization has the advantage of not imposing a shape on the DFE. For a reasonably fine parametrization, the number of parameters is larger than those of the other models, however. We generally also observe larger confidence intervals for this parametrization, and the optimization procedure may well be less efficient as we have to re-normalize the parameters to make sure they sum up to 1. Note that all \(S\) parameters are population-scaled selection coefficients, i.e. \(S = 4N_es\).
Methods:
Constructor.
Get PDF.
Get CDF.
Freeze parameters to create a DFE object.
Load object from file.
Unserialize object.
Plot the discretized DFE.
Save object to file.
Serialize object.
- __init__(intervals: Sequence = array([-100000, -100, -10, -1, 0, 1, 1000]), bounds: Dict[str, Tuple[float, float]] | None = None, scales: Dict[str, Literal['lin', 'log']] | None = None, x0: Dict[str, float] | None = None)[source]#
Constructor.
- Parameters:
intervals (
Sequence) – The intervals of the discrete distribution.bounds (
Optional[Dict[str,Tuple[float,float]]]) – Custom parameter bounds merging with defaultsscales (
Optional[Dict[str,Literal['lin','log']]]) – Custom scales merging with defaultsx0 (
Optional[Dict[str,float]]) – Custom initial parameters merging with defaults
-
scales:
Dict[str,Literal['lin','log']] = {}# Scales over which to optimize the parameters, either ‘log’ or ‘lin’
- classmethod from_file(file: str, classes=None)#
Load object from file.
- Parameters:
classes – Classes to be used for unserialization.
file (
str) – File to load from
- Return type:
Self
- classmethod from_json(json: str, classes=None)#
Unserialize object.
- Parameters:
classes – Classes to be used for unserialization
json (
str) – JSON string
- Return type:
Self
- class DiscreteFractionalParametrization(intervals: Sequence = array([-100000, -100, -10, -1, 0, 1, 1000]), bounds: Dict[str, Tuple[float, float]] | None = None, scales: Dict[str, Literal['lin', 'log']] | None = None, x0: Dict[str, float] | None = None)[source]#
Bases:
ParametrizationSame model as
DiscreteParametrization, but re-parametrized by \(\hat{S}_1, \hat{S}_2, \dots, \hat{S}_{k-1}\), so that the mass in the ith interval \(S_i\) is determined by the sum of masses to the left, i.e.\(S_i = \hat{S}_i \sum_{j<i} S_j, i = 1, \dots, k - 1\),
\(S_k = 1 - \sum_{j=1}^{k-1} S_j\).
This parametrization has the advantage of not imposing a shape on the DFE. For a reasonably fine parametrization, the number of parameters is larger than those of the other models, however. It is more easily optimized than
DiscreteParametrizationas it has one parameter less but its parameters are more difficult to interpret. One disadvantage with discrete parametrizations is that there may be gaps in the estimated DFE. Note that all \(S\) parameters are population-scaled selection coefficients, i.e. \(S = 4N_es\).Methods:
Constructor.
Convert representation of fraction of total mass to the left to representation of fractions which sum to 1.
Invert the to_nominal operation: Convert representation of fractions which sum to 1 back to representation of fraction of total mass to the left.
Get PDF.
Get CDF.
Freeze parameters to create a DFE object.
Load object from file.
Unserialize object.
Plot the discretized DFE.
Save object to file.
Serialize object.
- __init__(intervals: Sequence = array([-100000, -100, -10, -1, 0, 1, 1000]), bounds: Dict[str, Tuple[float, float]] | None = None, scales: Dict[str, Literal['lin', 'log']] | None = None, x0: Dict[str, float] | None = None)[source]#
Constructor.
- Parameters:
intervals (
Sequence) – The intervals of the discrete distribution.bounds (
Optional[Dict[str,Tuple[float,float]]]) – Custom parameter bounds merging with defaultsscales (
Optional[Dict[str,Literal['lin','log']]]) – Custom scales merging with defaultsx0 (
Optional[Dict[str,float]]) – Custom initial parameters merging with defaults
- fixed_params#
Fixed parameters
-
scales:
Dict[str,Literal['lin','log']] = {}# Scales over which to optimize the parameters, either ‘log’ or ‘lin’
- to_nominal(params: Dict[str, float])[source]#
Convert representation of fraction of total mass to the left to representation of fractions which sum to 1.
- to_fractional(params: Dict[str, float])[source]#
Invert the to_nominal operation: Convert representation of fractions which sum to 1 back to representation of fraction of total mass to the left.
- classmethod from_file(file: str, classes=None)#
Load object from file.
- Parameters:
classes – Classes to be used for unserialization.
file (
str) – File to load from
- Return type:
Self
- classmethod from_json(json: str, classes=None)#
Unserialize object.
- Parameters:
classes – Classes to be used for unserialization
json (
str) – JSON string
- Return type:
Self
- class DFE(params: dict, model: Parametrization = None, bootstraps: DataFrame | None = None)[source]#
Bases:
SerializableFrozen parametrization of a DFE.
Wraps a
Parametrizationinstance together with fixed parameter values.Methods:
Get DFEs for all bootstrap samples.
Evaluate the frozen PDF.
Evaluate the frozen CDF.
Discretize the DFE with optional bootstrap confidence intervals.
Load object from file.
Unserialize object.
Save object to file.
Serialize object.
Plot several DFE instances in a single discretized plot.
Plot this DFE instance in a discretized plot.
- __init__(params: dict, model: Parametrization = None, bootstraps: DataFrame | None = None)[source]#
- Parameters:
params (
dict) – Frozen parameter values.model (
Parametrization) – Parametrization instance used to generate the DFE. Defaults toGammaExpParametrization.bootstraps (
Optional[DataFrame]) – Optional bootstrap DataFrame (same format as AbstractInference.bootstraps).
-
model:
Parametrization# Underlying parametrization model
- discretize(bins: ndarray, warn_mass: bool = True, confidence_intervals: bool = True, ci_level: float = 0.05, bootstrap_type: Literal['percentile', 'bca'] = 'percentile', point_estimate: Literal['original', 'mean', 'median'] = 'mean')[source]#
Discretize the DFE with optional bootstrap confidence intervals.
- Parameters:
bins (
ndarray) – Intervals to use for discretization.warn_mass (
bool) – Whether to warn if mass is lost during discretization.confidence_intervals (
bool) – Whether to compute confidence intervals.ci_level (
float) – Confidence interval level (e.g., 0.05 for 95% CI).bootstrap_type (
Literal['percentile','bca']) – Type of bootstrap confidence intervals (‘percentile’ or ‘bca’).point_estimate (
Literal['original','mean','median']) – Whether to use ‘original’ MLE values, ‘mean’ or ‘median’ of bootstraps as point estimate.
- Return type:
- Returns:
Center values and (optionally) errors for each bin.
- classmethod from_file(file: str, classes=None)#
Load object from file.
- Parameters:
classes – Classes to be used for unserialization.
file (
str) – File to load from
- Return type:
Self
- classmethod from_json(json: str, classes=None)#
Unserialize object.
- Parameters:
classes – Classes to be used for unserialization
json (
str) – JSON string
- Return type:
Self
- static plot_many(dfes: Sequence[DFE], labels: Sequence[str] | None = None, intervals=array([-inf, -100., -10., -1., 0., 1., inf]), file=None, show=True, title='discretized DFE', ax=None, confidence_intervals: bool = True, ci_level: float = 0.05, bootstrap_type: Literal['percentile', 'bca'] = 'percentile', point_estimate: Literal['original', 'mean', 'median'] = 'mean', kwargs_legend: dict = {'prop': {'size': 8}})[source]#
Plot several DFE instances in a single discretized plot.
- Parameters:
intervals – Intervals to use for discretization.
file – File to save the plot to.
show – Whether to show the plot.
title – Title of the plot.
ax – Axes to use for the plot.
confidence_intervals (
bool) – Whether to plot confidence intervals.ci_level (
float) – Confidence interval level (e.g., 0.05 for 95% CI).bootstrap_type (
Literal['percentile','bca']) – Type of bootstrap confidence intervals (‘percentile’ or ‘bca’).point_estimate (
Literal['original','mean','median']) – Whether to use ‘original’ MLE values, ‘mean’ or ‘median’ of bootstraps as point estimate.kwargs_legend (
dict) – Additional keyword arguments for the legend.
- Returns:
Matplotlib Axes object.
- plot(intervals=array([-inf, -100., -10., -1., 0., 1., inf]), file=None, show=True, title='discretized DFE', ax=None, confidence_intervals: bool = True, ci_level: float = 0.05, bootstrap_type: Literal['percentile', 'bca'] = 'percentile', point_estimate: Literal['original', 'mean', 'median'] = 'mean', kwargs_legend: dict = {'prop': {'size': 8}})[source]#
Plot this DFE instance in a discretized plot.
- Parameters:
intervals – Intervals to use for discretization.
file – File to save the plot to.
show – Whether to show the plot.
title – Title of the plot.
ax – Axes to use for the plot.
confidence_intervals (
bool) – Whether to plot confidence intervals.ci_level (
float) – Confidence interval level (e.g., 0.05 for 95% CI).bootstrap_type (
Literal['percentile','bca']) – Type of bootstrap confidence intervals (‘percentile’ or ‘bca’).point_estimate (
Literal['original','mean','median']) – Whether to use ‘original’ MLE values, ‘mean’ or ‘median’ of bootstraps as point estimate.kwargs_legend (
dict) – Additional keyword arguments for the legend.
- Returns:
Matplotlib Axes object.