epsie.chain package

Submodules

epsie.chain.base module

Base class for Markov chains.

class epsie.chain.base.BaseChain[source]

Bases: abc.ABC

Abstract base class for Markov chains.

Provides standard functions for Chain and ParallelTemperedChain.

parameters

iteration

lastclear

scratchlen

positions

stats

acceptance

blobs

start_position

stats0

blob0

current_position

current_stats

current_blob

bit_generator

random_state

state

hasblobs

chain_id

Integer identifying the chain. Default is 0.

Type: int

abstract property acceptance: The history of all of acceptance ratios and accepted booleans, as a structred array.

abstract property bit_generator: The random bit generator being used.

abstract property blob0: Dictionary of the blob data at the start position.

abstract property blobs

The history of all of the blob data, as a structred array.

If the model does not return blobs, this is just None.

chain_id = 0

abstract clear()[source]: Clears memory of the current chain, and sets start position to the current position.

abstract property current_blob

Dictionary of the blob data of the current position.

If the model does not return blobs, just returns None.

abstract property current_position: Dictionary of the current position of the chain.

abstract property current_stats: Dictionary giving the log likelihood and log prior of the current position.

abstract property hasblobs: Whether the model returns blobs.

abstract property iteration: The number of times the chain has been stepped.

abstract property lastclear: Returns the iteration of the last time the chain memory was cleared.

property parameters: The sampled parameters, as a tuple.

abstract property positions: The history of all of the positions, as a structred array.

abstract property random_generator: Returns the random number generator.

abstract property random_state: The current state of the random bit generator.

abstract property scratchlen: The length of the scratch space used.

abstract set_state(state)[source]

Sets the state of the chain using the given dict.

Warning

Running this will clear the chain’s current memory, and replace its current position with what is saved in the state.

Parameters: state (dict) – Dictionary of state values.

abstract property start_position: Dictionary mapping parameters to their start position.

abstract property state

Returns the current state of the chain.

The state consists of everything needed such that setting a chain’s state using another’s state will result in identical results.

abstract property stats: The log likelihoods and log priors of the positions, as a structred array.

abstract property stats0: Dictionary of the log likelihood and prior at the start position.

abstract step()[source]: Evolves the chain by a single step.

epsie.chain.chain module

Classes for individual Markov chains.

class epsie.chain.chain.Chain(parameters, model, proposals, bit_generator=None, chain_id=0, beta=1.0)[source]

Bases: epsie.chain.base.BaseChain

A Markov chain.

The chain requires a model to be provided. This can be any object that can be called with keyword arguments that map parameter names to values. When called, the object must return a tuple of two or three elements. The first element must be a float representing the log likelihood at that point; the second must be a float representing the log prior at that point. Additionally, the model may return a dictionary as a third element in the tuple that maps strings to arbitrary data. This additional data will be stored as blob data.

Parameters

parameters (list or tuple) – List of the parameter names to sample.
model (object) – Any object that can be called with keyword arguments that map parameter names to values. When called, the object must a tuple of logl, logp where logp is the log prior and logl is the log likelihood at the given point. The model may optionally return a dictionary in addition that maps strings to any arbitrary data.
proposals (list of epsie.proposals instances) – List of proposal classes to use for the parameters. There must be one and only one proposal for every parameter. A single proposal may cover multiple parameters. Proposals must be instances of classes that inherit from epsie.proposals.BaseProposal.
bit_generator (epsie.BIT_GENERATOR instance, optional) – Use the given random bit generator for generating random variates. If an int or None is provided, a generator will be created instead using bit_generator as a seed.
chain_id (int, optional) – An interger identifying which chain this is. Default is 0.
beta (float, optional) – The inverse temperature of the chain. Default is 1.

parameters

iteration

lastclear

scratchlen

positions

stats

acceptance

blobs

start_position

stats0

blob0

current_position

current_stats

current_blob

bit_generator

random_state

state

hasblobs

transdimensional

chain_id

Integer identifying the chain.

Type: int or None

proposal_dist

The joint proposal used for all parameters.

Type: JointProposal

property acceptance: The history of all of acceptance ratios and accepted booleans, as a structred array.

property bit_generator: The random bit generator being used.

property blob0

The blob data of the starting position, as a dictionary.

Raises a ValueError if set_start has not been run yet.

property blobs

The history of all of the blob data, as a structured array.

If the model does not return blobs, this is just None.

clear()[source]

Clears memory of the current chain, and sets start position to the current position.

New scratch space will be created with length equal to scratch_len.

property current_blob

Dictionary of the blob data of the current position.

If the model does not return blobs, just returns None.

property current_position: Dictionary of the current position of the chain.

property current_stats: Dictionary giving the log likelihood and log prior of the current position.

property hasblobs: Whether the model returns blobs.

property iteration: The number of times the chain has been stepped.

property lastclear: Returns the iteration of the last time the chain memory was cleared.

property positions: The history of all of the positions, as a structred array.

property proposed_position: Dictionary of the current proposed position of the chain.

property random_generator: Returns the random number generator.

property random_state: Returns the current state of the bit generator.

property scratchlen: The length of the scratch space used.

set_state(state)[source]

Sets the state of the chain using the given dict.

Warning

Running this will clear the chain’s current memory, and replace its current position with what is saved in the state.

Parameters: state (dict) – Dictionary of state values.

property start_position

Dictionary mapping parameters to their start position.

If the start position hasn’t been set, raises a ValueError.

property state

Returns the current state of the chain.

The state consists of everything needed such that setting a chain’s state using another’s state will result in identical results.

property stats: The log likelihoods and log priors of the positions, as a structured array.

property stats0

Dictionary of the log likelihood and log prior at the start position.

Raises a ValueError if the start position has not been set yet.

step()[source]: Evolves the chain by a single step.

epsie.chain.chaindata module

Utilities for handling chain data.

class epsie.chain.chaindata.ChainData(parameters, dtypes=None, ntemps=1)[source]

Bases: object

Handles reading and adding data to a chain.

When initialized, a list of parameter names must be provided for which the data will be stored. Items may then be added by giving a dictionary mapping parameter names to their values. See the Examples below. If the index given where the new data should be added is larger then the length of the instance’s current memory, it will automatically be extended by the amount needed. Scratch space may be allocated ahead of time by using the extend method.

Data can be retrieved using the .data attribute, which will return the data as a numpy structred array.

Space for multiple temperatures may be specified by providing the ntemps argument. In this case, the array will have shape niterations x ntemps.

Note

Note that the temperatures are the last index. This is because numpy is row major. When stepping a chain, the collection of temperatures at a given iteration are often accessed, to write data, and to do temperature swaps. However, once the chain is complete, it is more common to access all the iterations at once for a given temperature; e.g., to calculate autocorrelation length. For this reason, it is recommended that the chain data be transposed before doing other operations and writing to disk.

Parameters

parameters (list or tuple of str) – The names of the parameters to store data for.
dtypes (dict, optional) – Dictionary mapping parameter names to types. Will default to using float for any parameters that are not provided.
ntemps (int, optional) – The number of temperatures used by the chain. Default is 1.

parameters

The names of the parameters that were given.

Type: tuple

dtypes

The data type used for each of the parameters.

Type: dict

data

Examples

Create an scratch space for two parameters, “x” and “y”. Note that, initially, the data attribute returns None, and the length is zero:

>>> from epsie.chain import ChainData
>>> chaindata = ChainData(['x', 'y'])
>>> print(len(chaindata))
0
>>> print(chaindata.data)
None

Now add some data by passing a dictionary of values. Note that the length is automatically extended to accomodate the given index, with zeroes filled in up to that point:

>>> chaindata[1] = {'x': 2.5, 'y': 1.}
>>> chaindata.data
array([(0. , 0.), (2.5, 1.)], dtype=[('x', '<f8'), ('y', '<f8')])
>>> len(chaindata)
2

Manually extend the scratch space, and fill it. Note that we can set multiple values at once using standard slicing syntax:

>>> chaindata.extend(4)
>>> chaindata[2:] = {'x': [3.5, 4.5, 5.5, 6.5], 'y': [2, 3, 4, 5]}
>>> chaindata.data
array([(0. , 0.), (2.5, 1.), (3.5, 2.), (4.5, 3.), (5.5, 4.), (6.5, 5.)],
  dtype=[('x', '<f8'), ('y', '<f8')])

Since we did not specify dtypes, the data types have all defaulted to floats. Change ‘y’ to be ints instead:

>>> chaindata.dtypes = {'y': int}
>>> chaindata.data
array([(0. , 0), (2.5, 1), (3.5, 2), (4.5, 3), (5.5, 4), (6.5, 5)],
  dtype=[('x', '<f8'), ('y', '<i8')])

Clear the memory, and set the new length to be 3:

>>> chaindata.clear(3)
>>> chaindata.data
array([(0., 0), (0., 0), (0., 0)], dtype=[('x', '<f8'), ('y', '<i8')])

asdict(index=None)[source]

Returns the data as a dictionary.

Parameters: index (slice, optional) – Only get the elements indicated by the given slice before converting to a dictionary.

clear(newlen=None)[source]

Clears the memory.

Parameters: newlen (int, optional) – If provided, will create new scratch space with the given length.

property data

Returns the saved data as a numpy structered array.

If no data has been added yet, and an initial length was not specified, returns None.

property dtypes: Dictionary mapping parameter names to their data types.

extend(n)[source]: Extends scratch space by n items.

set_len(n)[source]

Sets the data length to n.

If the data length is already > n, a ValueError is raised.

epsie.chain.chaindata.detect_dtypes(data)[source]

Convenience function to detect the dtype of some data.

Parameters: data (dict or numpy.ndarray) – Either a numpy structred array/void or a dictionary mapping parameter names to some (arbitrary) values. The values may be either arrays or atomic data. If the former, the dtype will be taken from the array’s dtype.
Returns: Dictionary mapping the parameter names to types.
Return type: dict

epsie.chain.ptchain module

Markov chains with parallel tempering.

class epsie.chain.ptchain.DynamicalAnnealer(tau=1000, nu=10, Tmax_prior=True)[source]

Bases: object

Class for dynamical parallel tempering.

This is based on the algorithm described in [1].

Parameters

tau (int, optional) – Defines the swap iteration at which adjustments have been reduced to half their initial amplitude ([1]). Default value is 1000.
nu (int, optional) – Defines the initial amplitude of adjustments ([1]). Default values is 10
Tmax_prior (bool, optional) – Whether to set the hottest chain temperature to infinity. This only rewrites the hottest chain temperature to be infty and keeps the other chains as they were. By default sets it to infinity.

References

[1] W. D. Vousden, W. M. Farr, I. Mandel, Dynamic temperature selection for parallel tempering in Markov chain Monte Carlo simulations, Monthly Notices of the Royal Astronomical Society, Volume 455, Issue 2, 11 January 2016, Pages 1919–1937, https://doi.org/10.1093/mnras/stv2422

setup_annealing(betas)[source]: Calculates the initial log diffs between temperature levels

setup_decay(tau, nu)[source]: Set up constants for the vanishing decay

class epsie.chain.ptchain.ParallelTemperedChain(parameters, model, proposals, betas=1.0, swap_interval=1, adaptive_annealer=None, bit_generator=None, chain_id=0)[source]

Bases: epsie.chain.base.BaseChain

A collection of parallel tempered Markov chains.

Parameters

parameters (list or tuple) – List of the parameter names to sample.
model (object) – Any object that can be called with keyword arguments that map parameter names to values. When called, the object must a tuple of logl, logp where logp is the log prior and logl is the log likelihood at the given point. The model may optionally return a dictionary in addition that maps strings to any arbitrary data.
proposals (list of epsie.proposals instances) – List of proposal classes to use for the parameters. There must be one and only one proposal for every parameter. A single proposal may cover multiple parameters. Proposals must be instances of classes that inherit from epsie.proposals.BaseProposal.
betas (array of floats, optional) – Array of inverse temperatures. Each beta must be in range 0 (= infinite temperature; i.e., only sample the prior) <= beta <= 1 (= coldest temperate; i.e., sample the standard posterior). Default is a single beta = 1.
swap_interval (int, optional) – For a parallel tempered chain, how often to calculate temperature swaps. Default is 1 (= swap on every iteration).
adaptive_annealer (object, optional) – Adaptive annealing that adjusts the temperature levels during runtime. By default None, meaning no annealing.
bit_generator (epsie.BIT_GENERATOR instance, optional) – Use the given random bit generator for generating random variates. If an int or None is provided, a generator will be created instead using bit_generator as a seed.
chain_id (int, optional) – An interger identifying which chain this is. Default is 0.

iteration

lastclear

scratchlen

positions

stats

acceptance

blobs

start_position

stats0

blob0

current_position

current_stats

current_blob

bit_generator

random_state

state

hasblobs

chain_id

Integer identifying the chain.

Type: int or None

property acceptance

The history of all of acceptance ratios and accepted booleans, as a structred array.

If ntemps > 1, the returned array has shape ntemps x niterations. Otherwise, the returned array has shape niterations.

property betas: Returns the betas (=1 / temperatures) used by the chain.

property bit_generator: The random bit generator being used.

property blob0

The blob data of the starting position, as a dictionary.

If hasblobs is False, just returns None. Otherwise, the values of the returned dictionary are arrays of length ntemps, ordered by increasing temperature.

Raises a ValueError if set_start has not been run yet.

property blobs

The history of all of the blob data, as a structured array.

If the model does not return blobs, this is just None.

If ntemps > 1, the returned array has shape ntemps x niterations. Otherwise, the returned array has shape niterations.

clear()[source]

Clears memory of the current chain, and sets start position to the current position.

New scratch space will be created with length equal to scratch_len.

property current_blob

Dictionary of the blob data of the current position.

If the model does not return blobs, just returns None.

property current_position: Dictionary of the current position of the chain.

property current_stats: Dictionary giving the log likelihood and log prior of the current position.

property hasblobs: Whether the model returns blobs.

property iteration: The number of times the chain has been stepped.

property lastclear: Returns the iteration of the last time the chain memory was cleared.

property ntemps: Returns the number of temperatures used by the chain.

property positions

The history of all of the positions, as a structred array.

If ntemps > 1, the returned array has shape ntemps x niterations. Otherwise, the returned array has shape niterations.

property random_generator: Returns the random number generator.

property random_state: The current state of the random bit generator.

property scratchlen: The length of the scratch space used.

set_state(state)[source]

Sets the state of the chain using the given dict.

Warning

Running this will clear the chain’s current memory, and replace its current position with what is saved in the state.

Parameters: state (dict) – Dictionary of tk -> dict mapping indices of the temperature chains to the state they should be set to.

property start_position

Dictionary mapping parameters to their start position.

If the start position hasn’t been set, raises a ValueError.

property state

Returns the current state of the chain.

The state consists of everything needed such that setting a chain’s state using another’s state will result in identical results.

Returns: Dictionary of tk -> chains[tk].state, where tk is the index of each temperature chain.
Return type: dict

property stats

The history of all of the stats, as a structred array.

If ntemps > 1, the returned array has shape ntemps x niterations. Otherwise, the returned array has shape niterations.

property stats0

Dictionary of the log likelihood and log prior at the start position.

The values of the returned dictionary are arrays of length ntemps, ordered by increasing temperature.

Raises a ValueError if the start position has not been set yet.

step()[source]: Evolves all of the temperatures by one iteration.

swap_temperatures()[source]

Computes acceptance ratio between temperatures and swaps them.

The positions, stats, and (if they exist) blobs are swapped. The acceptance is not swapped, however.

property temperature_acceptance

The history of the acceptance ratios between temperatures.

The returned array has shape ntemps-1 x (niterations/swap_interval) if ntemps > 1. Otherwise, returns None.

Note

This does not return a structured array, since there is only one field.

property temperature_swaps

The history of all of the temperature swaps.

The returned array has shape ntemps x (niterations/swap_interval) if ntemps > 1. Otherwise, returns None.

Note

This does not return a structured array, since there is only one field.

property temperatures: Returns the temperatures (= 1 / betas) used by the chain.

epsie.chain package

Submodules

epsie.chain.base module

epsie.chain.chain module

epsie.chain.chaindata module

epsie.chain.ptchain module

Module contents