pyabc.population

Particles and Populations

A particle contains the sampled parameters and simulated data. A population gathers all particles collected in one SMC iteration.

class pyabc.population.Particle(m: int, parameter: Parameter, weight: float, sum_stat: dict, distance: float, accepted: bool = True, proposal_id: int = 0, preliminary: bool = False)

Bases: object

An (accepted or rejected) particle, containing the information that will also be stored in the database. Stores all summary statistics that were generated during the creation of this particle, and a flag indicating whether this particle was accepted or not.

Parameters:

• m – The model index.

• parameter – The model specific parameter.

• weight – The weight of the particle. 0 <= weight <= 1.

• sum_stat – Model simulation.

• distance – Distance of simulated and measured data.

• accepted – True if particle was accepted, False if not.

• proposal_id – An identifier for the proposal the particle was generated from. This allows grouping particles accordingly.

• preliminary – Whether this particle is only preliminarily accepted. Must be False eventually for all particles.

• note:: (..) – There are two different ways of weighting particles: First, the weights can be calculated as emerges from the importance sampling. Second, the weights of particles belonging to one model can be summed to, after normalization, find model probabilities. Then, the weights of all particles belonging to one model can be summed to one. Weighting is transferred to the second way in _normalize_weights() in order to also have access to model probabilities. This mode is also stored in the database. If one needs access to the first weighting scheme later on again, one has to perform backwards transformation, multiplying the weights with the model probabilities.

__init__(m: int, parameter: Parameter, weight: float, sum_stat: dict, distance: float, accepted: bool = True, proposal_id: int = 0, preliminary: bool = False)

class pyabc.population.Population(particles: List[Particle])

Bases: object

A population contains a list of particles and offers standardized access to them. Upon initialization, the particle weights are normalized and model probabilities computed as described in _normalize_weights.

Parameters:

particles – Particles that constitute the accepted population.

__init__(particles: List[Particle])

calculate_model_probabilities()

Compute the model probabilities and ensure normalization.

Computes model weights as relative sums of particles belonging to a model. Also ensures that the total weight is 1, raising if this was not the case before already since usually normalization should happen already for the entire sample including rejected particles.

get_accepted_sum_stats() → List[dict]

Return a list of all accepted summary statistics.

get_for_keys(keys)

Get dataframe of population values. Possible entries of keys: weight, distance, sum_stat, parameter.

Returns:

• Dictionary where the keys are associated to same-ordered lists

• of the corresponding values.

get_model_probabilities() → DataFrame

Get probabilities of the individual models.

Returns:

model_probabilities – The model probabilities.

Return type:

List

get_particles_by_model() → Dict[int, List[Particle]]

Get particles by model.

Returns:

particles_by_model – A dictionary with the models as keys and a list of particles for each model as values.

Return type:

dict

get_weighted_distances() → DataFrame

Create DataFrame of (distance, weight)’s. The particle weights are multiplied by the model probabilities. The weights thus sum to 1.

Returns:

weighted_distances – A pd.DataFrame containing in column ‘distance’ the distances and in column ‘w’ the scaled weights.

Return type:

pd.DataFrame:

get_weighted_sum_stats() → tuple

Get weights and summary statistics.

Returns:

weights, sum_stats

Return type:

2-Tuple of lists

update_distances(distance_to_ground_truth: Callable[[dict, Parameter], float]) → None

Update the distances of all summary statistics of all particles according to the passed distance function (which is typically different from the distance function with which the original distances were computed).

Parameters:

distance_to_ground_truth – Distance function to the observed summary statistics.

class pyabc.population.Sample(record_rejected: bool = False, max_nr_rejected: int = inf, is_look_ahead: bool = False, ok: bool = True)

Bases: object

Contains all particles generated during the sampling process.

Contains all accepted particles and can also contain rejected particles if requested.

Parameters:

• record_rejected – Whether to record rejected particles as well, along with accepted ones.

• is_look_ahead – Whether this sample consists of particles generated in look-ahead mode.

• max_nr_rejected – Maximum number or rejected particles to store.

• ok – Whether the sampling process succeeded (usually in generating the requested number of particles).

__init__(record_rejected: bool = False, max_nr_rejected: int = inf, is_look_ahead: bool = False, ok: bool = True)

property all_sum_stats

Get all summary statistics.

Returns:

all_sum_stats – Concatenation of all the all_sum_stats lists of all particles added and accepted to this sample via append().

Return type:

List

append(particle: Particle)

Add new particle to the sample.

Parameters:

particle (Particle) – Sampled particle containing all information needed later.

static from_population(population: Population) → Sample

Utility function to create a dummy sample from a population.

Obviously, the sample will then only consist of accepted particles.

Parameters:

population (Population to create a sample from.)

Returns:

sample

Return type:

The generated sample containing all population particles.

get_accepted_population() → Population

Returns:

population – A population of only the accepted particles.

Return type:

Population

property n_accepted: int

returns: n_accepted – Number of accepted particles. :rtype: int

normalize_weights()

Normalize weights to sum(accepted weights) = 1.

This is done at the end of a sampling run. Normalizing rejected weights by the same factor ensures that weights stay comparable.

class pyabc.population.SampleFactory(record_rejected: bool = False, max_nr_rejected: int = inf)

Bases: object

The SampleFactory class serves as a factory class to create empty samples based on the parameters stored in the SampleFactory object.

This is the class that components (like the distance function and epsilon) should refer to when they want to influence the sampling process.

Parameters:

record_rejected (bool) – Corresponds to Sample.record_rejected.

__call__(is_look_ahead: bool = False)

Create a new empty sample.

__init__(record_rejected: bool = False, max_nr_rejected: int = inf)

record_rejected(record: bool = True)

Switch whether to record rejected particles.