# Epsilons¶

Epsilon threshold updating strategies.

Acceptance thresholds (= epsilon) can be calculated based on the distances from the observed data, can follow a pre-defined list, can be constant, or can have a user-defined 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

__call__(t: int)[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__(constant_epsilon_value: float)[source]

Constructor.

get_config()[source]

Return configuration of the distance function.

Returns

config – Dictionary describing the distance function.

Return type

dict

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 ex-posteriori here.

Parameters
• alpha (float, optional) – The ratio by which to decrease the temperature value. More specifically, the next temperature is given as (1-alpha) * 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.

__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__(alpha: float = 0.5, min_rate: float = 0.0001)[source]

Initialize self. See help(type(self)) for accurate signature.

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

__init__()[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.

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 zero-based. 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 t-1. The distances may differ from those used for acceptance in population t-1, 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.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.

__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_relative_ess: float = 0.8)[source]

Initialize self. See help(type(self)) for accurate signature.

class pyabc.epsilon.ExpDecayFixedIterScheme[source]

Bases: pyabc.epsilon.temperature.TemperatureScheme

The next temperature is set as

$T_j = T_{max}^{(n-j)/n}$

where n denotes the number of populations, and j=1,…,n the iteration. This translates to

$T_j = T_{j-1}^{(n-j)/(n-(j-1))}.$

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 log-space.

Note that the formula is applied anew in each iteration. This is advantageous if also other schemes are used s.t. T_{j-1} is smaller than by the above.

Parameters

alpha (float) – Factor by which to reduce the temperature, if max_nr_populations is infinite.

__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__()[source]

Initialize self. See help(type(self)) for accurate signature.

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_{j-1}.$

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.

__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__(alpha: float = 0.5, min_rate: float = 0.0001, max_rate: float = 0.5)[source]

Initialize self. See help(type(self)) for accurate signature.

class pyabc.epsilon.FrielPettittScheme[source]

Bases: pyabc.epsilon.temperature.TemperatureScheme

Basically takes linear steps in log-space. See 2.

2

Vyshemirsky, Vladislav, and Mark A. Girolami. “Bayesian ranking of biochemical system models.” Bioinformatics 24.6 (2007): 833-839.

__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.

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.

__call__(t: int)[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__(values: List[float])[source]

Constructor.

get_config()[source]

Return configuration of the distance function.

Returns

config – Dictionary describing the distance function.

Return type

dict

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.

__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__(values: List[float])[source]

Constructor.

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.

__init__(initial_epsilon: Union[str, int, float] = 'from_sample', median_multiplier: float = 1, weighted: bool = True)[source]

Constructor.

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.

__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__()[source]

Constructor.

class pyabc.epsilon.PolynomialDecayFixedIterScheme(exponent: float = 3)[source]

Bases: pyabc.epsilon.temperature.TemperatureScheme

Compute next temperature as pre-last 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.

__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__(exponent: float = 3)[source]

Initialize self. See help(type(self)) for accurate signature.

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 alpha-quantile of the distances from the last population.

This strategy works even if the posterior is multi-modal. 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 non-weighted 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 alpha-quantile 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 non-weighted (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.

update(t: int, get_weighted_distances: Callable[], pandas.core.frame.DataFrame], get_all_records: Callable[], List[dict]], acceptance_rate: float, acceptor_config: dict)[source]

Compute quantile of the (weighted) distances given in population, and use this to update epsilon.

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 zero-based. 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 t-1. The distances may differ from those used for acceptance in population t-1, 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.

__init__()[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().