Running an MCMC routine

pints.mcmc_sample(log_pdf, chains, x0, sigma0=None, transformation=None, method=None)

Sample from a pints.LogPDF using a Markov Chain Monte Carlo (MCMC) method.

Parameters:

• log_pdf (pints.LogPDF) – A LogPDF function that evaluates points in the parameter space.
• chains (int) – The number of MCMC chains to generate.
• x0 – A sequence of starting points. Can be a list of lists, a 2-dimensional array, or any other structure such that x0[i] is the starting point for chain i.
• sigma0 – An optional initial covariance matrix, i.e., a guess of the covariance in logpdf around the points in x0 (the same sigma0 is used for each point in x0). Can be specified as a (d, d) matrix (where d is the dimension of the parameterspace) or as a (d, ) vector, in which case diag(sigma0) will be used.
• transformation (pints.Transformation) – An optional pints.Transformation to allow the sampler to work in a transformed parameter space. If used, points shown or returned to the user will first be detransformed back to the original space.
• method (class) – The class of MCMCSampler to use. If no method is specified, HaarioBardenetACMC is used.

class pints.MCMCController(log_pdf, chains, x0, sigma0=None, transformation=None, method=None)

Samples from a pints.LogPDF using a Markov Chain Monte Carlo (MCMC) method.

The method to use (either a SingleChainMCMC class or a MultiChainMCMC class) is specified at runtime. For example:

mcmc = pints.MCMCController(
    log_pdf, 3, x0, method=pints.HaarioBardenetACMC)

Properties related to the number if iterations, parallelisation, and logging can be set directly on the MCMCController object, e.g.:

mcmc.set_max_iterations(1000)

Sampler specific properties must be set on the internal samplers themselves, e.g.:

for sampler in mcmc.samplers():
    sampler.set_target_acceptance_rate(0.2)

Finally, to run an MCMC routine, call:

chains = mcmc.run()

By default, an MCMCController run will write regular progress updates to screen. This can be disabled using set_log_to_screen(). To write a similar progress log to a file, use set_log_to_file(). To store the chains and/or evaluations generated by run() to a file, use set_chain_filename() and set_log_pdf_filename().

Parameters:

• log_pdf (pints.LogPDF) – A LogPDF function that evaluates points in the parameter space.
• chains (int) – The number of MCMC chains to generate.
• x0 – A sequence of starting points. Can be a list of lists, a 2-dimensional array, or any other structure such that x0[i] is the starting point for chain i.
• sigma0 – An optional initial covariance matrix, i.e., a guess of the covariance in logpdf around the points in x0 (the same sigma0 is used for each point in x0). Can be specified as a (d, d) matrix (where d is the dimension of the parameter space) or as a (d, ) vector, in which case diag(sigma0) will be used.
• transformation (pints.Transformation) – An optional pints.Transformation to allow the sampler to work in a transformed parameter space. If used, points shown or returned to the user will first be detransformed back to the original space.
• method (class) – The class of MCMCSampler to use. If no method is specified, HaarioBardenetACMC is used.

chains()

Returns the chains generated by run().

The returned array has shape (n_chains, n_iterations, n_parameters).

If the controller has not run yet, or if chain storage to memory is disabled, this method will return None.

initial_phase_iterations()

For methods that require an initial phase (e.g. an adaptation-free phase for the adaptive covariance MCMC method), this returns the number of iterations that the initial phase will take.

For methods that do not require an initial phase, a NotImplementedError is raised.

log_pdfs()

Returns the LogPDF evaluations generated by run().

If a LogPosterior was used, the returned array will have shape (n_chains, n_iterations, 3), and for each sample the LogPDF, LogLikelihood, and LogPrior will be stored. For all other cases, only the full LogPDF evaluations are returned, in an array of shape (n_chains, n_iterations).

If the controller has not run yet, or if storage of evaluations to memory is disabled (default), this method will return None.

max_iterations()

Returns the maximum iterations if this stopping criterion is set, or None if it is not. See set_max_iterations().

method_needs_initial_phase()

Returns true if this sampler has been created with a method that has an initial phase (see MCMCSampler.needs_initial_phase().)

n_evaluations()

Returns the number of evaluations performed during the last run, or None if the controller hasn’t run yet.

parallel()

Returns the number of parallel worker processes this routine will be run on, or False if parallelisation is disabled.

run()

Runs the MCMC sampler(s) and returns the result.

By default, this method returns an array of shape (n_chains, n_iterations, n_parameters). If storing chains to memory has been disabled with set_chain_storage(), then None is returned instead.

sampler()

Returns the underlying MultiChainMCMC object, or raises an error if SingleChainMCMC objects are being used.

See also: samplers().

samplers()

Returns a list containing the underlying sampler objects.

If a SingleChainMCMC method was selected, this will be a list containing as many SingleChainMCMC objects as the number of chains. If a MultiChainMCMC method was selected, this will be a list containing a single MultiChainMCMC instance.

set_chain_filename(chain_file)

Write chains to disk as they are generated.

If a chain_file is specified, a CSV file will be created for each chain, to which samples will be written as they are accepted. To disable logging of chains, set chain_file=None.

Filenames for each chain file will be derived from chain_file, e.g. if chain_file='chain.csv' and there are 2 chains, then the files chain_0.csv and chain_1.csv will be created. Each CSV file will start with a header (e.g. "p0","p1","p2",...) and contain a sample on each subsequent line.

set_chain_storage(store_in_memory=True)

Store chains in memory as they are generated.

By default, all generated chains are stored in memory as they are generated, and returned by run(). This method allows this behaviour to be disabled, which can be useful for very large chains which are already stored to disk (see set_chain_filename()).

set_initial_phase_iterations(iterations=200)

For methods that require an initial phase (e.g. an adaptation-free phase for the adaptive covariance MCMC method), this sets the number of iterations that the initial phase will take.

For methods that do not require an initial phase, a NotImplementedError is raised.

set_log_interval(iters=20, warm_up=3)

Changes the frequency with which messages are logged.

Parameters:

• iters (int) – A log message will be shown every iters iterations.
• warm_up (int) – A log message will be shown every iteration, for the first warm_up iterations.

set_log_pdf_filename(log_pdf_file)

Write LogPDF evaluations to disk as they are generated.

If an evaluation_file is specified, a CSV file will be created for each chain, to which LogPDF evaluations will be written for every accepted sample. To disable this feature, set evaluation_file=None. If the LogPDF being evaluated is a LogPosterior, the individual likelihood and prior will also be stored.

Filenames for each evaluation file will be derived from evaluation_file, e.g. if evaluation_file='evals.csv' and there are 2 chains, then the files evals_0.csv and evals_1.csv will be created. Each CSV file will start with a header (e.g. "logposterior","loglikelihood","logprior") and contain the evaluations for i-th accepted sample on the i-th subsequent line.

set_log_pdf_storage(store_in_memory=False)

Store LogPDF evaluations in memory as they are generated.

By default, evaluations of the LogPDF are not stored. This method can be used to enable storage of the evaluations for the accepted samples. After running, evaluations can be obtained using evaluations().

set_log_to_file(filename=None, csv=False)

Enables progress logging to file when a filename is passed in, disables it if filename is False or None.

The argument csv can be set to True to write the file in comma separated value (CSV) format. By default, the file contents will be similar to the output on screen.

set_log_to_screen(enabled)

Enables or disables progress logging to screen.

set_max_iterations(iterations=10000)

Adds a stopping criterion, allowing the routine to halt after the given number of iterations.

This criterion is enabled by default. To disable it, use set_max_iterations(None).

set_parallel(parallel=False)

Enables/disables parallel evaluation.

If parallel=True, the method will run using a number of worker processes equal to the detected cpu core count. The number of workers can be set explicitly by setting parallel to an integer greater than 0. Parallelisation can be disabled by setting parallel to 0 or False.

time()

Returns the time needed for the last run, in seconds, or None if the controller hasn’t run yet.

class pints.MCMCSampling(log_pdf, chains, x0, sigma0=None, transformation=None, method=None)

Deprecated alias for MCMCController.

chains()

Returns the chains generated by run().

The returned array has shape (n_chains, n_iterations, n_parameters).

If the controller has not run yet, or if chain storage to memory is disabled, this method will return None.

initial_phase_iterations()

For methods that require an initial phase (e.g. an adaptation-free phase for the adaptive covariance MCMC method), this returns the number of iterations that the initial phase will take.

For methods that do not require an initial phase, a NotImplementedError is raised.

log_pdfs()

Returns the LogPDF evaluations generated by run().

If a LogPosterior was used, the returned array will have shape (n_chains, n_iterations, 3), and for each sample the LogPDF, LogLikelihood, and LogPrior will be stored. For all other cases, only the full LogPDF evaluations are returned, in an array of shape (n_chains, n_iterations).

If the controller has not run yet, or if storage of evaluations to memory is disabled (default), this method will return None.

max_iterations()

Returns the maximum iterations if this stopping criterion is set, or None if it is not. See set_max_iterations().

method_needs_initial_phase()

Returns true if this sampler has been created with a method that has an initial phase (see MCMCSampler.needs_initial_phase().)

n_evaluations()

Returns the number of evaluations performed during the last run, or None if the controller hasn’t run yet.

parallel()

Returns the number of parallel worker processes this routine will be run on, or False if parallelisation is disabled.

run()

Runs the MCMC sampler(s) and returns the result.

By default, this method returns an array of shape (n_chains, n_iterations, n_parameters). If storing chains to memory has been disabled with set_chain_storage(), then None is returned instead.

sampler()

Returns the underlying MultiChainMCMC object, or raises an error if SingleChainMCMC objects are being used.

See also: samplers().

samplers()

Returns a list containing the underlying sampler objects.

If a SingleChainMCMC method was selected, this will be a list containing as many SingleChainMCMC objects as the number of chains. If a MultiChainMCMC method was selected, this will be a list containing a single MultiChainMCMC instance.

set_chain_filename(chain_file)

Write chains to disk as they are generated.

If a chain_file is specified, a CSV file will be created for each chain, to which samples will be written as they are accepted. To disable logging of chains, set chain_file=None.

Filenames for each chain file will be derived from chain_file, e.g. if chain_file='chain.csv' and there are 2 chains, then the files chain_0.csv and chain_1.csv will be created. Each CSV file will start with a header (e.g. "p0","p1","p2",...) and contain a sample on each subsequent line.

set_chain_storage(store_in_memory=True)

Store chains in memory as they are generated.

By default, all generated chains are stored in memory as they are generated, and returned by run(). This method allows this behaviour to be disabled, which can be useful for very large chains which are already stored to disk (see set_chain_filename()).

set_initial_phase_iterations(iterations=200)

For methods that require an initial phase (e.g. an adaptation-free phase for the adaptive covariance MCMC method), this sets the number of iterations that the initial phase will take.

For methods that do not require an initial phase, a NotImplementedError is raised.

set_log_interval(iters=20, warm_up=3)

Changes the frequency with which messages are logged.

Parameters:

• iters (int) – A log message will be shown every iters iterations.
• warm_up (int) – A log message will be shown every iteration, for the first warm_up iterations.

set_log_pdf_filename(log_pdf_file)

Write LogPDF evaluations to disk as they are generated.

If an evaluation_file is specified, a CSV file will be created for each chain, to which LogPDF evaluations will be written for every accepted sample. To disable this feature, set evaluation_file=None. If the LogPDF being evaluated is a LogPosterior, the individual likelihood and prior will also be stored.

Filenames for each evaluation file will be derived from evaluation_file, e.g. if evaluation_file='evals.csv' and there are 2 chains, then the files evals_0.csv and evals_1.csv will be created. Each CSV file will start with a header (e.g. "logposterior","loglikelihood","logprior") and contain the evaluations for i-th accepted sample on the i-th subsequent line.

set_log_pdf_storage(store_in_memory=False)

Store LogPDF evaluations in memory as they are generated.

By default, evaluations of the LogPDF are not stored. This method can be used to enable storage of the evaluations for the accepted samples. After running, evaluations can be obtained using evaluations().

set_log_to_file(filename=None, csv=False)

Enables progress logging to file when a filename is passed in, disables it if filename is False or None.

The argument csv can be set to True to write the file in comma separated value (CSV) format. By default, the file contents will be similar to the output on screen.

set_log_to_screen(enabled)

Enables or disables progress logging to screen.

set_max_iterations(iterations=10000)

Adds a stopping criterion, allowing the routine to halt after the given number of iterations.

This criterion is enabled by default. To disable it, use set_max_iterations(None).

set_parallel(parallel=False)

Enables/disables parallel evaluation.

If parallel=True, the method will run using a number of worker processes equal to the detected cpu core count. The number of workers can be set explicitly by setting parallel to an integer greater than 0. Parallelisation can be disabled by setting parallel to 0 or False.

time()

Returns the time needed for the last run, in seconds, or None if the controller hasn’t run yet.