Running an MCMC routine¶
- pints.mcmc_sample(log_pdf, chains, x0, sigma0=None, transformation=None, method=None)[source]¶
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 chaini
.sigma0 – An optional initial covariance matrix, i.e., a guess of the covariance in
logpdf
around the points inx0
(the samesigma0
is used for each point inx0
). Can be specified as a(d, d)
matrix (whered
is the dimension of the parameterspace) or as a(d, )
vector, in which casediag(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)[source]¶
Samples from a
pints.LogPDF
using a Markov Chain Monte Carlo (MCMC) method.The method to use (either a
SingleChainMCMC
class or aMultiChainMCMC
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, useset_log_to_file()
. To store the chains and/or evaluations generated byrun()
to a file, useset_chain_filename()
andset_log_pdf_filename()
.- Parameters:
log_pdf (pints.LogPDF) – A
LogPDF
function that evaluates points in the parameter space, or a list ofLogPDF
of the same length as chains. If multiple LogPDFs are provided, each chain will call only its corresponding LogPDF. Note that if multiple LogPDFs are provided, parallel running is not possible.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 chaini
.sigma0 – An optional initial covariance matrix, i.e., a guess of the covariance in
logpdf
around the points inx0
(the samesigma0
is used for each point inx0
). Can be specified as a(d, d)
matrix (whered
is the dimension of the parameter space) or as a(d, )
vector, in which casediag(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()[source]¶
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()[source]¶
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()[source]¶
Returns the
LogPDF
evaluations generated byrun()
.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()[source]¶
Returns the maximum iterations if this stopping criterion is set, or
None
if it is not. Seeset_max_iterations()
.
- method_needs_initial_phase()[source]¶
Returns true if this sampler has been created with a method that has an initial phase (see
MCMCSampler.needs_initial_phase()
.)
- n_evaluations()[source]¶
Returns the number of evaluations performed during the last run, or
None
if the controller hasn’t run yet.
- parallel()[source]¶
Returns the number of parallel worker processes this routine will be run on, or
False
if parallelisation is disabled.
- run()[source]¶
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 withset_chain_storage()
, thenNone
is returned instead.
- sampler()[source]¶
Returns the underlying
MultiChainMCMC
object, or raises an error ifSingleChainMCMC
objects are being used.See also:
samplers()
.
- samplers()[source]¶
Returns a list containing the underlying sampler objects.
If a
SingleChainMCMC
method was selected, this will be a list containing as manySingleChainMCMC
objects as the number of chains. If aMultiChainMCMC
method was selected, this will be a list containing a singleMultiChainMCMC
instance.
- set_chain_filename(chain_file)[source]¶
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, setchain_file=None
.Filenames for each chain file will be derived from
chain_file
, e.g. ifchain_file='chain.csv'
and there are 2 chains, then the fileschain_0.csv
andchain_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)[source]¶
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 (seeset_chain_filename()
).
- set_initial_phase_iterations(iterations=200)[source]¶
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)[source]¶
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)[source]¶
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 whichLogPDF
evaluations will be written for every accepted sample. To disable this feature, setevaluation_file=None
. If theLogPDF
being evaluated is aLogPosterior
, the individual likelihood and prior will also be stored.Filenames for each evaluation file will be derived from
evaluation_file
, e.g. ifevaluation_file='evals.csv'
and there are 2 chains, then the filesevals_0.csv
andevals_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)[source]¶
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 usingevaluations()
.
- set_log_to_file(filename=None, csv=False)[source]¶
Enables progress logging to file when a filename is passed in, disables it if
filename
isFalse
orNone
.The argument
csv
can be set toTrue
to write the file in comma separated value (CSV) format. By default, the file contents will be similar to the output on screen.
- set_max_iterations(iterations=10000)[source]¶
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)[source]¶
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 settingparallel
to an integer greater than 0. Parallelisation can be disabled by settingparallel
to0
orFalse
.Parallel evaluation is only supported when a single LogPDF has been provided to the MCMC controller.
- class pints.MCMCSampling(log_pdf, chains, x0, sigma0=None, transformation=None, method=None)[source]¶
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 byrun()
.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. Seeset_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 withset_chain_storage()
, thenNone
is returned instead.
- sampler()¶
Returns the underlying
MultiChainMCMC
object, or raises an error ifSingleChainMCMC
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 manySingleChainMCMC
objects as the number of chains. If aMultiChainMCMC
method was selected, this will be a list containing a singleMultiChainMCMC
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, setchain_file=None
.Filenames for each chain file will be derived from
chain_file
, e.g. ifchain_file='chain.csv'
and there are 2 chains, then the fileschain_0.csv
andchain_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 (seeset_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 whichLogPDF
evaluations will be written for every accepted sample. To disable this feature, setevaluation_file=None
. If theLogPDF
being evaluated is aLogPosterior
, the individual likelihood and prior will also be stored.Filenames for each evaluation file will be derived from
evaluation_file
, e.g. ifevaluation_file='evals.csv'
and there are 2 chains, then the filesevals_0.csv
andevals_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 usingevaluations()
.
- set_log_to_file(filename=None, csv=False)¶
Enables progress logging to file when a filename is passed in, disables it if
filename
isFalse
orNone
.The argument
csv
can be set toTrue
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 settingparallel
to an integer greater than 0. Parallelisation can be disabled by settingparallel
to0
orFalse
.Parallel evaluation is only supported when a single LogPDF has been provided to the MCMC controller.
- time()¶
Returns the time needed for the last run, in seconds, or
None
if the controller hasn’t run yet.