Distance functions¶
Distance functions measure closeness of observed and sampled data. For custom distance functions, either pass a plain function to ABCSMC or subclass the DistanceFunction class if finer grained configuration is required.

class
pyabc.distance_functions.
AcceptAllDistance
¶ Bases:
pyabc.distance_functions.DistanceFunction
Just a mock distance function which always returns 1. So any sample should be accepted for any sane epsilon object.
Can be used for testing.

__call__
(x, y)¶ Parameters:  x (dictionary) – sample point
 y (dictionary) – measured point


class
pyabc.distance_functions.
DistanceFunction
¶ Bases:
abc.ABC
Abstract base class for distance functions.
Any other distance function should inherit from this class.

__call__
(x: dict, x_0: dict) → float¶ Abstract method. This method has to be overwritten by all concrete implementations.
Evaluate the distance of the tentatively samples particle to the measured data.
Parameters:  x (dict) – Summary statistics of the tentatively sampled parameter.
 x_0 (dict) – Summary statistics of the measured data.
Returns: distance – Attributes distance of the tentatively sampled particle from the measured data.
Return type: float

configure_sampler
(sampler: pyabc.sampler.base.Sampler)¶ This is called by the ABCSMC class and gives the distance function the opportunity to configure the sampler. For example, the distance function might request the sampler to also return rejected particles and their summary statistics in order to adapt the distance functions to the statistics of the sample.
The default is to do nothing.
Parameters: Sampler (Sampler) – The Sampler.

get_config
() → dict¶ Return configuration of the distance function.
Returns: config – Dictionary describing the distance function. Return type: dict

initialize
(sample_from_prior: List[dict])¶ This method is called by the ABCSMC framework before the first usage of the distance function and can be used to calibrate it to the statistics of the samples.
The default implementation is to do nothing.
This method is not called again when an ABC run is resumed via ABCSCM.run(), so the user has to make sure that custom distance functions are ready for calling the other methods.
Parameters: sample_from_prior (List[dict]) – List of dictionaries containing the summary statistics.

to_json
() → str¶ 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
(simulations_all: List[dict]) → bool¶ Update the distance function. Default: Do nothing.
Parameters: simulations_all – List of all simulations (summary statistics). Returns: True: If distance function has changed. False: If distance function has not changed (default).


class
pyabc.distance_functions.
DistanceFunctionWithMeasureList
(measures_to_use='all')¶ Bases:
pyabc.distance_functions.DistanceFunction
Base class for distance functions with measure list. This class is not functional on its own.
Parameters: measures_to_use (Union[str, List[str]]) –  If set to “all”, all measures are used. This is the default
 If a list is provided, the measures in the list are used.
 measures refers to the summary statistics.

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

initialize
(sample_from_prior)¶ This method is called by the ABCSMC framework before the first usage of the distance function and can be used to calibrate it to the statistics of the samples.
The default implementation is to do nothing.
This method is not called again when an ABC run is resumed via ABCSCM.run(), so the user has to make sure that custom distance functions are ready for calling the other methods.
Parameters: sample_from_prior (List[dict]) – List of dictionaries containing the summary statistics.

measures_to_use
= None¶ The measures (summary statistics) to use for distance calculation.

class
pyabc.distance_functions.
EuclideanDistance
¶ Bases:
pyabc.distance_functions.PNormDistance
Comfort class to use Euclidean norm as pnorm in PNormDistance.

class
pyabc.distance_functions.
IdentityFakeDistance
¶ Bases:
pyabc.distance_functions.DistanceFunction
A fake distance function, which just passes the summary statistics on. This class assumes, that the model already returns the distance. This can be useful in cases where simulating can be stopped early when during the simulation some condition is reached which makes it impossible to accept the particle.

__call__
(x, y)¶ Abstract method. This method has to be overwritten by all concrete implementations.
Evaluate the distance of the tentatively samples particle to the measured data.
Parameters:  x (dict) – Summary statistics of the tentatively sampled parameter.
 x_0 (dict) – Summary statistics of the measured data.
Returns: distance – Attributes distance of the tentatively sampled particle from the measured data.
Return type: float


class
pyabc.distance_functions.
MinMaxDistanceFunction
(measures_to_use='all')¶ Bases:
pyabc.distance_functions.RangeEstimatorDistanceFunction
Calculate upper and lower margins as max and min of the parameters. This works surprisingly well for normalization in simple cases

static
lower
()¶ Calculate the lower margin form a list of parameter values.
Parameters: parameter_list (List[float]) – List of values of a parameter. Returns: lower_margin – The lower margin of the range calculated from these parameters Return type: float

static
upper
()¶ Calculate the upper margin form a list of parameter values.
Parameters: parameter_list (List[float]) – List of values of a parameter. Returns: upper_margin – The upper margin of the range calculated from these parameters Return type: float

static

class
pyabc.distance_functions.
NoDistance
¶ Bases:
pyabc.distance_functions.DistanceFunction
Implements a kind of null object as distance function.

__call__
(x: dict, x_0: dict) → float¶ Abstract method. This method has to be overwritten by all concrete implementations.
Evaluate the distance of the tentatively samples particle to the measured data.
Parameters:  x (dict) – Summary statistics of the tentatively sampled parameter.
 x_0 (dict) – Summary statistics of the measured data.
Returns: distance – Attributes distance of the tentatively sampled particle from the measured data.
Return type: float


class
pyabc.distance_functions.
PCADistanceFunction
(measures_to_use='all')¶ Bases:
pyabc.distance_functions.DistanceFunctionWithMeasureList
Calculate distance in whitened coordinates.
A whitening transformation \(X\) is calculated from an initial sample. The distance is measured as euclidean distance in the transformed space. I.e
\[d(x,y) = \ Wx  Wy \\]
__call__
(x, y)¶ Abstract method. This method has to be overwritten by all concrete implementations.
Evaluate the distance of the tentatively samples particle to the measured data.
Parameters:  x (dict) – Summary statistics of the tentatively sampled parameter.
 x_0 (dict) – Summary statistics of the measured data.
Returns: distance – Attributes distance of the tentatively sampled particle from the measured data.
Return type: float

initialize
(sample_from_prior)¶ This method is called by the ABCSMC framework before the first usage of the distance function and can be used to calibrate it to the statistics of the samples.
The default implementation is to do nothing.
This method is not called again when an ABC run is resumed via ABCSCM.run(), so the user has to make sure that custom distance functions are ready for calling the other methods.
Parameters: sample_from_prior (List[dict]) – List of dictionaries containing the summary statistics.


class
pyabc.distance_functions.
PNormDistance
(p: float)¶ Bases:
pyabc.distance_functions.DistanceFunction
Use pnorm to compute distances between sets of summary statistics.
Parameters: p (float) – p for pnorm. Required p >= 1, p = math.inf allowed (infinitynorm). 
__call__
(x: dict, y: dict)¶ Abstract method. This method has to be overwritten by all concrete implementations.
Evaluate the distance of the tentatively samples particle to the measured data.
Parameters:  x (dict) – Summary statistics of the tentatively sampled parameter.
 x_0 (dict) – Summary statistics of the measured data.
Returns: distance – Attributes distance of the tentatively sampled particle from the measured data.
Return type: float

initialize
(sample_from_prior: List[dict])¶ This method is called by the ABCSMC framework before the first usage of the distance function and can be used to calibrate it to the statistics of the samples.
The default implementation is to do nothing.
This method is not called again when an ABC run is resumed via ABCSCM.run(), so the user has to make sure that custom distance functions are ready for calling the other methods.
Parameters: sample_from_prior (List[dict]) – List of dictionaries containing the summary statistics.


class
pyabc.distance_functions.
PercentileDistanceFunction
(measures_to_use='all')¶ Bases:
pyabc.distance_functions.RangeEstimatorDistanceFunction
Calculate normalization 20% and 80% from percentiles as lower and upper margins

PERCENTILE
= 20¶ The percentiles

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

static
lower
()¶ Calculate the lower margin form a list of parameter values.
Parameters: parameter_list (List[float]) – List of values of a parameter. Returns: lower_margin – The lower margin of the range calculated from these parameters Return type: float

static
upper
()¶ Calculate the upper margin form a list of parameter values.
Parameters: parameter_list (List[float]) – List of values of a parameter. Returns: upper_margin – The upper margin of the range calculated from these parameters Return type: float


class
pyabc.distance_functions.
RangeEstimatorDistanceFunction
(measures_to_use='all')¶ Bases:
pyabc.distance_functions.DistanceFunctionWithMeasureList
Abstract base class for distance functions which estimate is based on a range.
It defines the two template methods
lower
andupper
.Hence
\[d(x, y) = \sum_{i \in \text{measures}} \left  \frac{x_i  y_i}{u_i  l_i} \right \]where \(l_i\) and \(u_i\) are the lower and upper margin for measure \(i\).

__call__
(x, y)¶ Abstract method. This method has to be overwritten by all concrete implementations.
Evaluate the distance of the tentatively samples particle to the measured data.
Parameters:  x (dict) – Summary statistics of the tentatively sampled parameter.
 x_0 (dict) – Summary statistics of the measured data.
Returns: distance – Attributes distance of the tentatively sampled particle from the measured data.
Return type: float

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

initialize
(sample_from_prior)¶ This method is called by the ABCSMC framework before the first usage of the distance function and can be used to calibrate it to the statistics of the samples.
The default implementation is to do nothing.
This method is not called again when an ABC run is resumed via ABCSCM.run(), so the user has to make sure that custom distance functions are ready for calling the other methods.
Parameters: sample_from_prior (List[dict]) – List of dictionaries containing the summary statistics.

static
lower
()¶ Calculate the lower margin form a list of parameter values.
Parameters: parameter_list (List[float]) – List of values of a parameter. Returns: lower_margin – The lower margin of the range calculated from these parameters Return type: float

static
upper
()¶ Calculate the upper margin form a list of parameter values.
Parameters: parameter_list (List[float]) – List of values of a parameter. Returns: upper_margin – The upper margin of the range calculated from these parameters Return type: float


class
pyabc.distance_functions.
SimpleFunctionDistance
(function)¶ Bases:
pyabc.distance_functions.DistanceFunction
This is a wrapper around a simple function which calculates the distance. If a function is passed to the ABCSMC class, then it is converted to an instance of the SimpleFunctionDistance class.

__call__
(x, y)¶ Abstract method. This method has to be overwritten by all concrete implementations.
Evaluate the distance of the tentatively samples particle to the measured data.
Parameters:  x (dict) – Summary statistics of the tentatively sampled parameter.
 x_0 (dict) – Summary statistics of the measured data.
Returns: distance – Attributes distance of the tentatively sampled particle from the measured data.
Return type: float

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


class
pyabc.distance_functions.
WeightedEuclideanDistance
(adaptive: bool = True, scale_type: int = 0)¶ Bases:
pyabc.distance_functions.WeightedPNormDistance
Comfort class to use Euclidean norm as pnorm in WeightedPNormDistance.

class
pyabc.distance_functions.
WeightedPNormDistance
(p: float, adaptive: bool = True, scale_type: int = 0)¶ Bases:
pyabc.distance_functions.PNormDistance

configure_sampler
(sampler: pyabc.sampler.base.Sampler)¶ This is called by the ABCSMC class and gives the distance function the opportunity to configure the sampler. For example, the distance function might request the sampler to also return rejected particles and their summary statistics in order to adapt the distance functions to the statistics of the sample.
The default is to do nothing.
Parameters: Sampler (Sampler) – The Sampler.

initialize
(sample_from_prior: List[dict])¶ Initialize weights.
Parameters: sample_from_prior –

update
(all_summary_statistics_list: List[dict])¶ Update weights based on all simulations. Usually called in each iteration.
Parameters: all_summary_statistics_list – List[dict] List of all summary statistics (also those rejected).


class
pyabc.distance_functions.
ZScoreDistanceFunction
(measures_to_use='all')¶ Bases:
pyabc.distance_functions.DistanceFunctionWithMeasureList
Calculate distance as sum of ZScore over the selected measures. The measured Data is the reference for the ZScore.
Hence
\[d(x, y) = \sum_{i \in \text{measures}} \left \frac{x_iy_i}{y_i} \right\]
__call__
(x, y)¶ Abstract method. This method has to be overwritten by all concrete implementations.
Evaluate the distance of the tentatively samples particle to the measured data.
Parameters:  x (dict) – Summary statistics of the tentatively sampled parameter.
 x_0 (dict) – Summary statistics of the measured data.
Returns: distance – Attributes distance of the tentatively sampled particle from the measured data.
Return type: float


pyabc.distance_functions.
median_absolute_deviation
(data: List)¶ Calculate the sample median absolute deviation (MAD), defined as median(abs(data  median(data)).
Parameters: data (List) – List of data points. Returns: The median absolute deviation of the data. Return type: mad

pyabc.distance_functions.
standard_deviation
(data: List)¶ Calculate the sample standard deviation (SD).
Parameters: data (List) – List of data points. Returns: The standard deviation of the data points. Return type: sd

pyabc.distance_functions.
to_distance
(maybe_distance_function)¶ Parameters:  maybe_distance_function (either a callable, which takes two arguments or) –
 DistanceFunction instance (a) –