Epsilons¶
Epsilon threshold updating strategies.
Acceptance thresholds (= epsilon) can be calculated based on the distances from the observed data, can follow a predefined list, can be constant, or can have a userdefined implementation.

class
pyabc.epsilon.
AcceptanceRateScheme
(target_rate: float = 0.3, min_rate: float = None)[source]¶ Bases:
pyabc.epsilon.temperature.TemperatureScheme
Try to keep the acceptance rate constant at a value of target_rate. Note that this scheme will fail to reduce the temperature sufficiently in later iterations, if the problem’s inherent acceptance rate is lower, but it has been observed to give big feasible temperature leaps in early iterations. In particular, this scheme can be used to propose an initial temperature.
 Parameters
target_rate (float, optional) – The target acceptance rate to match.
min_rate (float, optional) – The minimum rate below which not to apply the acceptance step scheme any more. Setting this to a value of e.g. 0.05 can make sense 1) because it may be unlikely that the acceptance rate scheme will propose a useful temperature at such low acceptance levels, and 2) to avoid uneccessary computations.

__call__
(t: int, get_weighted_distances: Callable[], pandas.core.frame.DataFrame], get_all_records: Callable[], List[dict]], max_nr_populations: int, pdf_norm: float, kernel_scale: str, prev_temperature: float, acceptance_rate: float)[source]¶ Call self as a function.

__init__
(target_rate: float = 0.3, min_rate: float = None)[source]¶ Initialize self. See help(type(self)) for accurate signature.

configure_sampler
(sampler: pyabc.sampler.base.Sampler)[source]¶ Modify the sampler. As in, and redirected from,
pyabc.epsilon.Temperature.configure_sampler()
.

class
pyabc.epsilon.
ConstantEpsilon
(constant_epsilon_value: float)[source]¶ Bases:
pyabc.epsilon.base.Epsilon
Keep epsilon constant over all populations. This acceptance threshold scheduling strategy is most likely only interesting for debugging purposes.
 Parameters
constant_epsilon_value (float) – The epsilon value for all populations

class
pyabc.epsilon.
DalyScheme
(alpha: float = 0.5, min_rate: float = 0.0001)[source]¶ Bases:
pyabc.epsilon.temperature.TemperatureScheme
This scheme is loosely based on 1, however note that it does not try to replicate it entirely. In particular, the implementation of pyABC does not allow the sampling to be stopped when encountering too low acceptance rates, such that this can only be done exposteriori here.
 Parameters
alpha (float, optional) – The ratio by which to decrease the temperature value. More specifically, the next temperature is given as (1alpha) * temperature.
min_rate (float, optional) – A minimum acceptance rate. If this rate has been violated in the previous iteration, the alpha value is decreased.
 1
Daly Aidan C., Cooper Jonathan, Gavaghan David J., and Holmes Chris. “Comparing two sequential Monte Carlo samplers for exact and approximate Bayesian inference on biological models”. Journal of The Royal Society Interface, 2017.

class
pyabc.epsilon.
Epsilon
[source]¶ Bases:
abc.ABC
Abstract epsilon base class.
This class encapsulates a strategy for setting a new epsilon for each new population.

abstract
__call__
(t: int) → float[source]¶ Get epsilon value for generation t.
 Parameters
t (int) – The time point to get the epsilon threshold for.
 Returns
eps – The epsilon for population t.
 Return type
float

configure_sampler
(sampler: pyabc.sampler.base.Sampler)[source]¶ This is called by the ABCSMC class and gives the epsilon the opportunity to configure the sampler. For example, it might request the sampler to also return rejected particles in order to adapt the epsilon to the statistics of the sample. The method is called by the ABCSMC framework before the first use of the epsilon (at the beginning of ABCSMC.run()), after initialize().
The default is to do nothing.
 Parameters
sampler (Sampler) – The sampler used in ABCSMC.

get_config
()[source]¶ Return configuration of the distance function.
 Returns
config – Dictionary describing the distance function.
 Return type
dict

initialize
(t: int, get_weighted_distances: Callable[], pandas.core.frame.DataFrame], get_all_records: Callable[], List[dict]], max_nr_populations: int, acceptor_config: dict)[source]¶ This method is called by the ABCSMC framework before the first usage of the epsilon and can be used to calibrate it to the statistics of the samples.
Default: Do nothing.
 Parameters
t (int) – The time point to initialize the epsilon for.
get_weighted_distances (Callable[[], pd.DataFrame]) – Returns on demand the distances for initializing the epsilon.
get_all_records (Callable[[], List[dict]]) – Returns on demand a list of information obtained from all particles sampled in the previous iteration.
max_nr_populations (int) – The maximum number of populations.
acceptor_config (dict) – An object provided by the Acceptor class.

to_json
()[source]¶ Return JSON encoded configuration of the distance function.
 Returns
json_str – JSON encoded string describing the distance function. The default implementation is to try to convert the dictionary returned my
get_config
. Return type
str

update
(t: int, get_weighted_distances: Callable[], pandas.core.frame.DataFrame], get_all_records: Callable[], List[dict]], acceptance_rate: float, acceptor_config: dict)[source]¶ Update epsilon value to be used as acceptance criterion for generation t.
Default: Do nothing.
 Parameters
t (int) – The generation index to update / set epsilon for. Counting is zerobased. So the first population has t=0.
get_weighted_distances (Callable[[], pd.DataFrame]) – The distances that should be used to update epsilon, as returned by Population.get_weighted_distances(). These are usually the distances of samples accepted in population t1. The distances may differ from those used for acceptance in population t1, if the distance function for population t has been updated.
get_all_records (Callable[[], List[dict]]) – Returns on demand a list of information obtained from all particles.
acceptance_rate (float) – The current generation’s acceptance rate.
acceptor_config (dict) – An object provided by the Acceptor class.

abstract

class
pyabc.epsilon.
EssScheme
(target_relative_ess: float = 0.8)[source]¶ Bases:
pyabc.epsilon.temperature.TemperatureScheme
Try to keep the effective sample size (ESS) constant.
 Parameters
target_relative_ess (float) – Targe relative effective sample size.

class
pyabc.epsilon.
ExpDecayFixedIterScheme
[source]¶ Bases:
pyabc.epsilon.temperature.TemperatureScheme
The next temperature is set as
\[T_j = T_{max}^{(nj)/n}\]where n denotes the number of populations, and j=1,…,n the iteration. This translates to
\[T_j = T_{j1}^{(nj)/(n(j1))}.\]This ensures that a temperature of 1.0 is reached after exactly the remaining number of steps.
So, in both cases the sequence of temperatures follows an exponential decay, also known as a geometric progression, or a linear progression in logspace.
Note that the formula is applied anew in each iteration. This is advantageous if also other schemes are used s.t. T_{j1} is smaller than by the above.
 Parameters
alpha (float) – Factor by which to reduce the temperature, if max_nr_populations is infinite.

class
pyabc.epsilon.
ExpDecayFixedRatioScheme
(alpha: float = 0.5, min_rate: float = 0.0001, max_rate: float = 0.5)[source]¶ Bases:
pyabc.epsilon.temperature.TemperatureScheme
The next temperature is chosen as
\[T_j = \alpha \cdot T_{j1}.\]Like the
pyabc.epsilon.ExpDecayFixedIterScheme
, this yields a geometric progression, however with a fixed ratio, irrespective of the number of iterations. If a finite number of iterations is specified in ABCSMC, there is no influence on the final jump to a temperature of 1.0.This is quite similar to the
pyabc.epsilon.DalyScheme
, although simpler in implementation. The alpha value here corresponds to a value of 1  alpha there. Parameters
alpha (float, optional) – The ratio of subsequent temperatures.
min_rate (float, optional) – A minimum acceptance rate. If this rate has been violated in the previous iteration, the alpha value is increased.
max_rate (float, optional) – Maximum rate to not be exceeded, otherwise the alpha value is decreased.

class
pyabc.epsilon.
FrielPettittScheme
[source]¶ Bases:
pyabc.epsilon.temperature.TemperatureScheme
Basically takes linear steps in logspace. See 2.
 2
Vyshemirsky, Vladislav, and Mark A. Girolami. “Bayesian ranking of biochemical system models.” Bioinformatics 24.6 (2007): 833839.

class
pyabc.epsilon.
ListEpsilon
(values: List[float])[source]¶ Bases:
pyabc.epsilon.base.Epsilon
Return epsilon values from a predefined list. For every time point enquired later, an epsilon value must exist in the list.
 Parameters
values (List[float]) – List of epsilon values.
values[t]
is the value for population t.

class
pyabc.epsilon.
ListTemperature
(values: List[float])[source]¶ Bases:
pyabc.epsilon.temperature.TemperatureBase
Pass a list of temperature values to use successively.
 Parameters
values – The array of temperatures to use successively. For exact inference, finish with 1.

class
pyabc.epsilon.
MedianEpsilon
(initial_epsilon: Union[str, int, float] = 'from_sample', median_multiplier: float = 1, weighted: bool = True)[source]¶ Bases:
pyabc.epsilon.epsilon.QuantileEpsilon
Calculate epsilon as median of the distances from the last population.

class
pyabc.epsilon.
NoEpsilon
[source]¶ Bases:
pyabc.epsilon.base.Epsilon
Implements a kind of null object as epsilon.
This can be used as a dummy epsilon when the Acceptor integrates the acceptance threshold.

class
pyabc.epsilon.
PolynomialDecayFixedIterScheme
(exponent: float = 3)[source]¶ Bases:
pyabc.epsilon.temperature.TemperatureScheme
Compute next temperature as prelast entry in
>>> np.linspace(1, (temp_base)**(1 / temp_decay_exponent), >>> t_to_go + 1) ** temp_decay_exponent)
Requires finite max_nr_populations.
Note that this is similar to the
pyabc.epsilon.ExpDecayFixedIterScheme
, which is indeed the limit for exponent > infinity. For smaller exponent, the sequence makes larger steps for low temperatures. This can be useful in cases, where lower temperatures (which are usually more expensive) can be traversed in few larger steps, however also the opposite may be true, i.e. that more steps at low temperatures are advantageous. Parameters
exponent (float, optional) – The exponent to use in the scheme.

class
pyabc.epsilon.
QuantileEpsilon
(initial_epsilon: Union[str, int, float] = 'from_sample', alpha: float = 0.5, quantile_multiplier: float = 1, weighted: bool = True)[source]¶ Bases:
pyabc.epsilon.base.Epsilon
Calculate epsilon as alphaquantile of the distances from the last population.
This strategy works even if the posterior is multimodal. Note that the acceptance threshold calculation is based on the distance to the observation, not on the parameters which generated data with that distance.
If completely different parameter sets produce equally good samples, the distances of their samples to the ground truth data should be comparable.
The idea behind weighting is that the probability p_k of obtaining a distance eps_k in the next generation should be proportional to the weight w_k of respective particle k in the current generation. Both weighted and nonweighted median should lead to correct results.
 Parameters
initial_epsilon (Union[str, int]) –
If ‘from_sample’, then the initial quantile is calculated from a sample of the current population size from the prior distribution.
If a number is given, this number is used.
alpha (float) – The alphaquantile to be used, e.g. alpha=0.5 means median.
quantile_multiplier (float) – Multiplies the quantile by that number. also applies it to the initial quantile if it is calculated from samples. However, it does not apply to the initial quantile if it is given as a number.
weighted (bool) – Flag indicating whether the new epsilon should be computed using weighted (True, default) or nonweighted (False) distances.

__call__
(t: int) → float[source]¶ Epsilon value for time t, set before via update() method.
 Returns
eps – The epsilon value for time t (throws error if not existent).
 Return type
float

__init__
(initial_epsilon: Union[str, int, float] = 'from_sample', alpha: float = 0.5, quantile_multiplier: float = 1, weighted: bool = True)[source]¶ Constructor.

get_config
()[source]¶ Return configuration of the distance function.
 Returns
config – Dictionary describing the distance function.
 Return type
dict

initialize
(t: int, get_weighted_distances: Callable[], pandas.core.frame.DataFrame], get_all_records: Callable[], List[dict]], max_nr_populations: int, acceptor_config: dict)[source]¶ This method is called by the ABCSMC framework before the first usage of the epsilon and can be used to calibrate it to the statistics of the samples.
Default: Do nothing.
 Parameters
t (int) – The time point to initialize the epsilon for.
get_weighted_distances (Callable[[], pd.DataFrame]) – Returns on demand the distances for initializing the epsilon.
get_all_records (Callable[[], List[dict]]) – Returns on demand a list of information obtained from all particles sampled in the previous iteration.
max_nr_populations (int) – The maximum number of populations.
acceptor_config (dict) – An object provided by the Acceptor class.

class
pyabc.epsilon.
Temperature
(schemes: Union[Callable, List[Callable]] = None, aggregate_fun: Callable[[List[float]], float] = None, initial_temperature: float = None, enforce_exact_final_temperature: bool = True, log_file: str = None)[source]¶ Bases:
pyabc.epsilon.temperature.TemperatureBase
This class implements a highly adaptive and configurable temperature scheme. Via the argument schemes, arbitrary temperature schemes can be passed to calculate the next generation’s temperature, via aggregate_fun one can define how to combine multiple guesses, via initial_temperature the initial temperature can be set.
 Parameters
schemes (Union[Callable, List[Callable]], optional) – Temperature schemes returning proposed temperatures for the next time point, e.g. instances of
pyabc.epsilon.TemperatureScheme
.aggregate_fun (Callable[List[float], float], optional) – The function to aggregate the schemes by, of the form
Callable[List[float], float]
. Defaults to taking the minimum.initial_temperature (float, optional) – The initial temperature. If None provided, an AcceptanceRateScheme is used.
enforce_exact_final_temperature (bool, optional) – Whether to force the final temperature (if max_nr_populations < inf) to be 1.0, giving exact inference.
log_file (str, optional) – A log file for storing data of the temperature that are currently not saved in the database. The data are saved in json format.
Properties –
 –
max_nr_populations (int) – The maximum number of iterations as passed to ABCSMC. May be inf, but not all schemes can handle that (and will complain).
temperatures (Dict[int, float]) – Times as keys and temperatures as values.

__call__
(t: int) → float[source]¶ Get epsilon value for generation t.
 Parameters
t (int) – The time point to get the epsilon threshold for.
 Returns
eps – The epsilon for population t.
 Return type
float

__init__
(schemes: Union[Callable, List[Callable]] = None, aggregate_fun: Callable[[List[float]], float] = None, initial_temperature: float = None, enforce_exact_final_temperature: bool = True, log_file: str = None)[source]¶ Constructor.

configure_sampler
(sampler: pyabc.sampler.base.Sampler)[source]¶ This is called by the ABCSMC class and gives the epsilon the opportunity to configure the sampler. For example, it might request the sampler to also return rejected particles in order to adapt the epsilon to the statistics of the sample. The method is called by the ABCSMC framework before the first use of the epsilon (at the beginning of ABCSMC.run()), after initialize().
The default is to do nothing.
 Parameters
sampler (Sampler) – The sampler used in ABCSMC.

initialize
(t: int, get_weighted_distances: Callable[], pandas.core.frame.DataFrame], get_all_records: Callable[], List[dict]], max_nr_populations: int, acceptor_config: dict)[source]¶ This method is called by the ABCSMC framework before the first usage of the epsilon and can be used to calibrate it to the statistics of the samples.
Default: Do nothing.
 Parameters
t (int) – The time point to initialize the epsilon for.
get_weighted_distances (Callable[[], pd.DataFrame]) – Returns on demand the distances for initializing the epsilon.
get_all_records (Callable[[], List[dict]]) – Returns on demand a list of information obtained from all particles sampled in the previous iteration.
max_nr_populations (int) – The maximum number of populations.
acceptor_config (dict) – An object provided by the Acceptor class.

update
(t: int, get_weighted_distances: Callable[], pandas.core.frame.DataFrame], get_all_records: Callable[], List[dict]], acceptance_rate: float, acceptor_config: dict)[source]¶ Update epsilon value to be used as acceptance criterion for generation t.
Default: Do nothing.
 Parameters
t (int) – The generation index to update / set epsilon for. Counting is zerobased. So the first population has t=0.
get_weighted_distances (Callable[[], pd.DataFrame]) – The distances that should be used to update epsilon, as returned by Population.get_weighted_distances(). These are usually the distances of samples accepted in population t1. The distances may differ from those used for acceptance in population t1, if the distance function for population t has been updated.
get_all_records (Callable[[], List[dict]]) – Returns on demand a list of information obtained from all particles.
acceptance_rate (float) – The current generation’s acceptance rate.
acceptor_config (dict) – An object provided by the Acceptor class.

class
pyabc.epsilon.
TemperatureBase
[source]¶ Bases:
pyabc.epsilon.base.Epsilon
A temperature scheme handles the decrease of the temperatures employed by a
pyabc.acceptor.StochasticAcceptor
over time.This class is not functional on its own, its derivatives must be used.

class
pyabc.epsilon.
TemperatureScheme
[source]¶ Bases:
object
A TemperatureScheme suggests the next temperature value. It is used as one of potentially multiple schemes employed in the Temperature class. This class is abstract.
 Parameters
t – The time to compute for.
get_weighted_distances – Callable to obtain the weights and kernel values to be used for the scheme.
get_all_records – Callable returning a List[dict] of all recorded particles.
max_nr_populations – The maximum number of populations that are supposed to be taken.
pdf_norm – The normalization constant c that will be used in the acceptance step.
kernel_scale – Scale on which the pdf values are (linear or logarithmic).
prev_temperature – The temperature that was used last time (or None if not applicable).
acceptance_rate – The recently obtained rate.

__call__
(t: int, get_weighted_distances: Callable[], pandas.core.frame.DataFrame], get_all_records: Callable[], List[dict]], max_nr_populations: int, pdf_norm: float, kernel_scale: str, prev_temperature: float, acceptance_rate: float)[source]¶ Call self as a function.

configure_sampler
(sampler: pyabc.sampler.base.Sampler)[source]¶ Modify the sampler. As in, and redirected from,
pyabc.epsilon.Temperature.configure_sampler()
.