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 distribution for \(S < 0\) and a uniform distribution for \(S \geq 0\). |
|
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
Parametrization.get_pdf()is only evaluated whenlinearized=False, but every subclass is required to define it.Methods:
Initialize parametrization.
Get probability distribution function of DFE.
Get cumulative 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’
- abstract get_pdf(**kwargs) Callable[[ndarray], ndarray][source]#
Get probability distribution function of DFE.
- Returns:
Function that accepts an array of selection coefficients and returns their probability density
- abstract get_cdf(**kwargs) Callable[[ndarray], ndarray][source]#
Get cumulative distribution function of DFE.
- Returns:
Function that accepts an array of selection coefficients and returns their cumulative probability
- plot(params: dict, intervals: Sequence = array([-inf, -100., -10., -1., 0., 1., inf]), file: str = None, show: bool = True, title: str = 'discretized DFE', ax: Axes = None) Axes[source]#
Plot the discretized DFE.
-
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) Callable[[ndarray], ndarray][source]#
Get PDF.
- Parameters:
- 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) Callable[[ndarray], ndarray][source]#
Get CDF.
- Parameters:
- 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.
- 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
BaseInference.compare_nested_models()will not 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
- static get_pdf(S_mean: float, b: float, S_max: float, **kwargs) Callable[[ndarray], ndarray][source]#
Get PDF.
- static get_cdf(S_mean: float, b: float, S_max: float, **kwargs) Callable[[ndarray], ndarray][source]#
Get CDF.
- __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.
- 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 distribution for \(S < 0\) and a uniform distribution for \(S \geq 0\).
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 reciprocal of the upper limit of the uniform density on \(0 \leq S \leq 1/S_b\)
\(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 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) Callable[[ndarray], ndarray][source]#
Get PDF.
- Parameters:
- 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) Callable[[ndarray], ndarray][source]#
Get CDF.
- Parameters:
- 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.
- 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\).
Deprecated since version 1.2.0: Use
DiscreteFractionalParametrization, which has better optimization properties.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’
- get_pdf(**kwargs) Callable[[ndarray], ndarray][source]#
Get PDF.
- Parameters:
kwargs¶ – Parameter values S1, S2, …, Sk
- Returns:
Function that computes the PDF for given S values
- get_cdf(**kwargs) Callable[[ndarray], ndarray][source]#
Get CDF.
- Parameters:
kwargs¶ – Parameter values S1, S2, …, Sk
- Returns:
Function that computes the CDF for given S values
- 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 \(S_i\) in interval \(i\) is the fraction \(\hat{S}_i\) of the mass not assigned to the intervals to its left, i.e.\(S_i = \hat{S}_i \left(1 - \sum_{j<i} S_j\right), i = 1, \dots, k - 1\),
\(S_k = 1 - \sum_{j=1}^{k-1} S_j\),
where \(k\) is the number of intervals.
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 fractions of the mass not assigned to the left to representation of fractions which sum to 1.
Invert
DiscreteFractionalParametrization.to_nominal(): Convert representation of fractions which sum to 1 back to representation of fractions of the mass not assigned 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]) Dict[str, float][source]#
Convert representation of fractions of the mass not assigned to the left to representation of fractions which sum to 1.
- to_fractional(params: Dict[str, float]) Dict[str, float][source]#
Invert
DiscreteFractionalParametrization.to_nominal(): Convert representation of fractions which sum to 1 back to representation of fractions of the mass not assigned to the left.
- get_pdf(**kwargs) Callable[[ndarray], ndarray][source]#
Get PDF.
- Parameters:
kwargs¶ – Parameter values S1, S2, …, Sk-1
- Returns:
Function that computes the PDF for given S values
- get_cdf(**kwargs) Callable[[ndarray], ndarray][source]#
Get CDF.
- Parameters:
kwargs¶ – Parameter values S1, S2, …, Sk-1
- Returns:
Function that computes the CDF for given S values
- 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:
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
- get_bootstrap_dfes() List[DFE][source]#
Get DFEs for all bootstrap samples.
- Returns:
List of DFE instances for each bootstrap sample.
- 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') Tuple[ndarray, ndarray | None][source]#
Discretize the DFE with optional bootstrap confidence intervals.
- Parameters:
warn_mass¶ (
bool) – Whether to warn if the CDF does not evaluate to 0 and 1 at the outer bin edges.confidence_intervals¶ (
bool) – Whether to compute confidence intervals.ci_level¶ (
float) – Tail probability per side, so 0.05 yields a 90% interval.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.
- Returns:
Center values and (optionally) errors for each bin. The center values are the mass of the DFE in each bin, which sums to 1 for bins that cover its support, except for the median of the bootstraps, which is taken for each bin.
- 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) – Tail probability per side, so 0.05 yields a 90% interval.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) – Tail probability per side, so 0.05 yields a 90% interval.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.