pyabc.acceptor

Acceptors

Acceptors handle the acceptance step.

class pyabc.acceptor.Acceptor[source]

Bases: object

The acceptor class encodes the acceptance step. This class is abstract and cannot be invoked itself.

__call__(distance_function: Distance, eps: Epsilon, x: dict, x_0: dict, t: int, par: Parameter)[source]

Compute distance between summary statistics and evaluate whether to accept or reject. All concrete implementations must implement this method.

Parameters:

distance_function – The distance function. The user is free to use or ignore this function.
eps – The acceptance thresholds. The user is free to use or ignore this object.
x – Current summary statistics to evaluate.
x_0 – The observed summary statistics.
t – Time point for which to check.
par – The model parameters used to simulate x.

Returns:

An AcceptorResult.
.. note:: – Currently, only one value encoding the distance is returned (and stored in the database), namely that at time t, even if also other distances affect the acceptance decision, e.g. distances from previous iterations, or in general if the distance is not scalar. This is because the last distance is likely to be most informative for the further process, and because in some parts of ABC a scalar distance value is required.

__init__()[source]: Default constructor.

get_epsilon_config(t: int) → dict[source]

Create a configuration object that contains all values of interest for the update of the Epsilon object.

Parameters:: t – The timepoint for which to get the config.
Returns:: The relevant information.
Return type:: config

initialize(t: int, get_weighted_distances: Callable[[], DataFrame], distance_function: Distance, x_0: dict)[source]

Initialize. This method is called by the ABCSMC framework initially, and can be used to calibrate the acceptor to initial statistics. The default is to do nothing.

Parameters:

t – The timepoint to initialize the acceptor for.
get_weighted_distances – Returns on demand the distances for initializing the acceptor.
distance_function – Distance object. The acceptor should not modify it, but might extract some meta information.
x_0 – The observed summary statistics.

is_adaptive() → bool[source]: Whether the class is dynamically updated after each generation, based on the last generation’s available data. Default: False.

requires_calibration() → bool[source]: Whether the class requires an initial calibration, based on samples from the prior. Default: False.

update(t: int, get_weighted_distances: Callable[[], DataFrame], prev_temp: float, acceptance_rate: float)[source]

Update the acceptance criterion.

Parameters:

t – The timepoint to initialize the acceptor for.
get_weighted_distances (Callable[[], pd.DataFrame]) – The past generation’s weighted distances.
prev_temp – The past generation’s temperature.
acceptance_rate – The past generation’s acceptance rate.

class pyabc.acceptor.AcceptorResult(distance: float, accept: bool, weight: float = 1.0)[source]

Bases: dict

Result of an acceptance step.

Parameters:

distance – Distance value obtained.
accept – A flag indicating the recommendation to accept or reject. More specifically: True: The distance is below the acceptance threshold. False: The distance is above the acceptance threshold.
weight – Weight associated with the evaluation, which may need to be taken into account via importance sampling when calculating the parameter weight. Defaults to 1.0.

__init__(distance: float, accept: bool, weight: float = 1.0)[source]

class pyabc.acceptor.FunctionAcceptor(fun: Callable)[source]

Bases: Acceptor

Initialize from function.

Parameters:: fun – Callable with the same signature as the __call__ method.

__call__(distance_function, eps, x, x_0, t, par)[source]

Compute distance between summary statistics and evaluate whether to accept or reject. All concrete implementations must implement this method.

Parameters:

distance_function – The distance function. The user is free to use or ignore this function.
eps – The acceptance thresholds. The user is free to use or ignore this object.
x – Current summary statistics to evaluate.
x_0 – The observed summary statistics.
t – Time point for which to check.
par – The model parameters used to simulate x.

Returns:

An AcceptorResult.
.. note:: – Currently, only one value encoding the distance is returned (and stored in the database), namely that at time t, even if also other distances affect the acceptance decision, e.g. distances from previous iterations, or in general if the distance is not scalar. This is because the last distance is likely to be most informative for the further process, and because in some parts of ABC a scalar distance value is required.

__init__(fun: Callable)[source]: Default constructor.

static to_acceptor(maybe_acceptor: Acceptor | Callable) → Acceptor[source]

Create an acceptor object from input.

Parameters:: maybe_acceptor – Either pass a full acceptor, or a callable which is then filled into a SimpleAcceptor.
Returns:: acceptor – An Acceptor object in either case.
Return type:: Acceptor

class pyabc.acceptor.ScaledPDFNorm(factor: float = 10, alpha: float = 0.5, min_acceptance_rate: bool = 0.1)[source]

Bases: object

Finds the previously found maximum density value, but then scales it by a factor factor**T such that the probability of particles getting accepted is increased by y value of up to factor.

Some additional rules are applied to make the scheme stable. The scaling is in particular applied only after a minimum acceptance rate has been violated.

Parameters:

factor – The factor by which to effectively rescale the acceptance step’s normalization constant.
alpha – The ratio by which the subsequent temperature is assumed to be reduced relative to the current one. This is only accurate if a pyabc.ExponentialDecayFixedRatioScheme with corresponding ratio is employed.
min_acceptance_rate – The scaling is applied once the acceptance rates fall below this value for the first time.

__call__(prev_pdf_norm: float | None, get_weighted_distances: Callable[[], DataFrame], prev_temp: float | None, acceptance_rate: float, **kwargs)[source]: Call self as a function.

__init__(factor: float = 10, alpha: float = 0.5, min_acceptance_rate: bool = 0.1)[source]

class pyabc.acceptor.StochasticAcceptor(pdf_norm_method: Callable = None, apply_importance_weighting: bool = True, log_file: str = None)[source]

Bases: Acceptor

This acceptor implements a stochastic acceptance step based on a probability density, generalizing from the uniform acceptance kernel. A particle is accepted if for the simulated summary statistics x, observed summary statistics x_0 and parameters theta holds

\[\frac{\text{pdf}(x_0|x,\theta)}{c}\geq u\]

where u ~ U[0,1], and c is a normalizing constant.

The concept is based on [1]. In addition, we introduce acceptance kernel temperation and rejection control importance sampling to permit a more flexible choice and adaptation of c.

__call__(distance_function: StochasticKernel, eps, x, x_0, t, par)[source]

Compute distance between summary statistics and evaluate whether to accept or reject. All concrete implementations must implement this method.

Parameters:

distance_function – The distance function. The user is free to use or ignore this function.
eps – The acceptance thresholds. The user is free to use or ignore this object.
x – Current summary statistics to evaluate.
x_0 – The observed summary statistics.
t – Time point for which to check.
par – The model parameters used to simulate x.

Returns:

An AcceptorResult.
.. note:: – Currently, only one value encoding the distance is returned (and stored in the database), namely that at time t, even if also other distances affect the acceptance decision, e.g. distances from previous iterations, or in general if the distance is not scalar. This is because the last distance is likely to be most informative for the further process, and because in some parts of ABC a scalar distance value is required.

__init__(pdf_norm_method: Callable = None, apply_importance_weighting: bool = True, log_file: str = None)[source]

Parameters:

pdf_norm_method – Function to calculate a pdf normalization (denoted c above). Shipped are pyabc.acceptor.pdf_norm_from_kernel to use the value provided by the StochasticKernel, and pyabc.acceptor.pdf_norm_max_found (default) to always use the maximum value among accepted particles so far. Note that re-weighting based on ideas from rejection control importance sampling to handle the normalization constant being insufficient, and thus avoiding an importance sampling bias, is included either way.
apply_importance_weighting – Whether to apply weights to correct for a bias induced by samples exceeding the density normalization. This may be False usually only for testing purposes.
log_file – A log file for storing data of the acceptor that are currently not saved in the database. The data are saved in json format and can be retrieved via pyabc.storage.load_dict_from_json.

get_epsilon_config(t: int) → dict[source]: Pack the pdf normalization and the kernel scale.

initialize(t: int, get_weighted_distances: Callable[[], DataFrame], distance_function: StochasticKernel, x_0: dict)[source]: Initialize temperature and maximum pdf.

is_adaptive() → bool[source]: Whether the class is dynamically updated after each generation, based on the last generation’s available data. Default: False.

requires_calibration() → bool[source]: Whether the class requires an initial calibration, based on samples from the prior. Default: False.

update(t: int, get_weighted_distances: Callable[[], DataFrame], prev_temp: float, acceptance_rate: float)[source]

Update the acceptance criterion.

Parameters:

t – The timepoint to initialize the acceptor for.
get_weighted_distances (Callable[[], pd.DataFrame]) – The past generation’s weighted distances.
prev_temp – The past generation’s temperature.
acceptance_rate – The past generation’s acceptance rate.

class pyabc.acceptor.UniformAcceptor(use_complete_history: bool = False)[source]

Bases: Acceptor

Base acceptance on the distance function and a uniform error distribution between -eps and +eps. This is the most common acceptance criterion in ABC.

__call__(distance_function, eps, x, x_0, t, par)[source]

Compute distance between summary statistics and evaluate whether to accept or reject. All concrete implementations must implement this method.

Parameters:

distance_function – The distance function. The user is free to use or ignore this function.
eps – The acceptance thresholds. The user is free to use or ignore this object.
x – Current summary statistics to evaluate.
x_0 – The observed summary statistics.
t – Time point for which to check.
par – The model parameters used to simulate x.

Returns:

An AcceptorResult.
.. note:: – Currently, only one value encoding the distance is returned (and stored in the database), namely that at time t, even if also other distances affect the acceptance decision, e.g. distances from previous iterations, or in general if the distance is not scalar. This is because the last distance is likely to be most informative for the further process, and because in some parts of ABC a scalar distance value is required.

__init__(use_complete_history: bool = False)[source]

Parameters:: use_complete_history – Whether to compare to all previous distances and epsilons, or use only the current distance time (default). This can be of interest with adaptive distances, in order to guarantee nested acceptance regions.

pyabc.acceptor.pdf_norm_from_kernel(kernel_val: float, **kwargs)[source]: Just use the pdf_max value passed, usually originating from the distance function.

pyabc.acceptor.pdf_norm_max_found(prev_pdf_norm: float | None, get_weighted_distances: Callable[[], DataFrame], **kwargs)[source]: Take as pdf_max the maximum over the values found so far in the history, and get_weighted_distances.