pymcmcstat package

pymcmcstat.MCMC module

Created on Wed Jan 17, 2018

@author: prmiles

Description: This module is intended to be the main class from which to run these Markov Chain Monte Carlo type simulations. The user will create an MCMC object, initialize data, simulation options, model settings and parameters.

class pymcmcstat.MCMC.MCMC(rngseed=None, seterr={'over': 'ignore', 'under': 'ignore'})[source]

Markov Chain Monte Carlo (MCMC) simulation object.

This class type is the primary feature of this Python package. All simulations are run through this class type, and for the most part the user will interact with an object of this type. The class initialization provides the option for setting the random seed, which can be very useful for testing the functionality of the code. It was found that setting the random seed at object initialization was the simplest interface.

Args:
  • rngseed (float): Seed for numpy’s random number generator.
Attributes:
display_current_mcmc_settings()[source]

Display model settings, simulation options, and current covariance values.

Example display:

model settings:
    sos_function = <function test_ssfun at 0x1c13c5d400>
    model_function = None
    sigma2 = [1.]
    N = [100.]
    N0 = [0.]
    S20 = [1.]
    nsos = 1
    nbatch = 1
simulation options:
    nsimu = 5000
    adaptint = 100
    ntry = 2
    method = dram
    printint = 100
    lastadapt = 5000
    drscale = [5. 4. 3.]
    qcov = None
covariance:
    qcov = [[0.01   0.    ]
    [0.     0.0625]]
    R = [[0.1  0.  ]
    [0.   0.25]]
    RDR = [array([[0.1 , 0.  ],
   [0.  , 0.25]]), array([[0.02, 0.  ],
   [0.  , 0.05]])]
    invR = [array([[10.,  0.],
   [ 0.,  4.]]), array([[50.,  0.],
   [ 0., 20.]])]
    last_index_since_adaptation = 0
    covchain = None
run_simulation(use_previous_results=False)[source]

Run MCMC Simulation

Note

This is the method called by the user to run the simulation. The user must specify a data structure, setup simulation options, and define the model settings and parameters before calling this method.

Args:
  • use_previous_results (bool): Flag to indicate whether simulation is being restarted.
pymcmcstat.MCMC.print_rejection_statistics(rejected, isimu, iiadapt, verbosity)[source]

Print Rejection Statistics.

Threshold for printing is verbosity greater than or equal to 2. If the rejection counters are as follows:

  • total: 144
  • in_adaptation_interval: 92
  • outside_bounds: 0

Then we would expect the following display at the 200th simulation with an adaptation interval of 100.

i:200 (72.0,92.0,0.0)
Args:
  • isimu (int): Simulation counter
  • iiadapt (int): Adaptation counter
  • verbosity (int): Verbosity of display output.

pymcmcstat.ParallelMCMC module

Created on Tue May 1 15:58:22 2018

@author: prmiles

class pymcmcstat.ParallelMCMC.ParallelMCMC[source]

Run Parallel MCMC Simulations.

Attributes:
display_individual_chain_statistics()[source]

Display chain statistics for different chains in parallel simulation.

Example display:

****************************************
Displaying results for chain 0
Files: <parallel_dir>/chain_0

---------------------
name      :       mean        std     MC_err        tau     geweke
m         :     1.9869     0.1295     0.0107   320.0997     0.9259
b         :     3.0076     0.2489     0.0132   138.1260     0.9413
---------------------

****************************************
Displaying results for chain 1
Files: <parallel_dir>/chain_1

---------------------
name      :       mean        std     MC_err        tau     geweke
m         :     1.8945     0.4324     0.0982  2002.6361     0.3116
b         :     3.2240     1.0484     0.2166  1734.0201     0.4161
---------------------
run_parallel_simulation()[source]

Run MCMC simulations in parallel.

The code is run in parallel by using Pool. While running, you can expect a display similar to

Processing: <parallel_dir>/chain_1
Processing: <parallel_dir>/chain_0
Processing: <parallel_dir>/chain_2

The simulation is complete when you see the run time displayed.

Parallel simulation run time: 16.15234899520874 sec
setup_parallel_simulation(mcset, initial_values=None, num_cores=1, num_chain=1)[source]

Setup simulation to run in parallel.

Settings defined in mcset object will be copied into different instances in order to run parallel chains.

Args:
  • mcset (MCMC): Instance of MCMC object with serial simulation setup.
  • initial_values (ndarray): Array of initial parameter values - [num_chain,npar].
  • num_cores (int): Number of cores designated by user.
  • num_chain (int): Number of sampling chains to be generated.
pymcmcstat.ParallelMCMC.assign_number_of_cores(num_cores=1)[source]

Assign number of cores to use in parallel process

Args:
  • num_cores (int): Number of cores designated by user.
Returns:
  • num_cores (int): Number of cores designated by user or maximum number of cores available on machine.
pymcmcstat.ParallelMCMC.check_directory(directory)[source]

Check and make sure directory exists

Args:
  • directory (str): Folder/directory path name.
pymcmcstat.ParallelMCMC.check_for_restart_file(json_restart_file, chain_dir)[source]

Check if restart directory was specified.

Args:
  • json_restart_file (str): String specifying path to results directory.
  • chain_dir (str): String specifying which chain is being restarted.
pymcmcstat.ParallelMCMC.check_initial_values(initial_values, num_chain, npar, low_lim, upp_lim)[source]

Check if initial values satisfy requirements.

Args:
  • initial_values (ndarray): Array of initial parameter values - [num_chain,npar].
  • num_chain (int): Number of sampling chains to be generated.
  • npar (int): Number of model parameters.
  • low_lim (ndarray): Lower limits.
  • upp_lim (ndarray): Upper limits.
Returns:
  • initial_values (ndarray): Array of initial parameter values - [num_chain,npar].
  • num_chain (int): Number of sampling chains to be generated.
pymcmcstat.ParallelMCMC.check_options_output(options)[source]

Check output settings defined in options

Args:
Returns:
  • options (SimulationOptions): MCMC simulation options with at least binary save flag set to True.
pymcmcstat.ParallelMCMC.check_shape_of_users_initial_values(initial_values, num_chain, npar)[source]

Check shape of users initial values

Args:
  • initial_values (ndarray): Array of initial parameter values - expect [num_chain,npar]
  • num_chain (int): Number of sampling chains to be generated.
  • npar (int): Number of model parameters.
Returns:
  • num_chain (int): Number of sampling chains to be generated - equal to number of rows in initial values array.
  • initial_values
pymcmcstat.ParallelMCMC.check_users_initial_values_wrt_limits(initial_values, low_lim, upp_lim)[source]

Check users initial values wrt parameter limits

Args:
  • initial_values (ndarray): Array of initial parameter values - expect [num_chain,npar]
  • low_lim (ndarray): Lower limits.
  • upp_lim (ndarray): Upper limits.
Returns:
  • initial_values (ndarray): Array of initial parameter values - expect [num_chain,npar]
Raises:
  • SystemExit if initial values are outside parameter bounds.
pymcmcstat.ParallelMCMC.generate_initial_values(num_chain, npar, low_lim, upp_lim)[source]

Generate initial values by sampling from uniform distribution between limits

Args:
  • num_chain (int): Number of sampling chains to be generated.
  • npar (int): Number of model parameters.
  • low_lim (ndarray): Lower limits.
  • upp_lim (ndarray): Upper limits.
Returns:
  • initial_values (ndarray): Array of initial parameter values - [num_chain,npar]
pymcmcstat.ParallelMCMC.get_parameter_features(parameters)[source]

Get features of model parameters.

Args:
  • parameters (list): List of MCMC model parameter dictionaries.
Returns:
  • npar (int): Number of model parameters.
  • low_lim (ndarray): Lower limits.
  • upp_lim (ndarray): Upper limits.
pymcmcstat.ParallelMCMC.load_parallel_simulation_results(savedir)[source]

Load results from parallel simulation directory json files.

Lists in json files are converted to numpy arrays.

Args:
  • savedir (str): String indicated path to parallel directory.
Returns:
  • pres (list): Each element of list is an MCMC result dictionary.
pymcmcstat.ParallelMCMC.run_serial_simulation(mcstat)[source]

Run serial MCMC simulation

Args:
  • mcstat (MCMC.MCMC): MCMC object.
Returns:
  • results (dict): Results dictionary for serial simulation.
pymcmcstat.ParallelMCMC.unpack_mcmc_set(mcset)[source]

Unpack attributes of MCMC object.

Args:
  • mcset (MCMC): MCMC object.
Returns: