Sampler

class orbitize.sampler.MCMC(system, num_temps=20, num_walkers=1000, num_threads=1, chi2_type='standard', like='chi2_lnlike', custom_lnlike=None, prev_result_filename=None)[source]

MCMC sampler. Supports either parallel tempering or just regular MCMC. Parallel tempering will be run if num_temps > 1 Parallel-Tempered MCMC Sampler uses ptemcee, a fork of the emcee Affine-infariant sampler Affine-Invariant Ensemble MCMC Sampler uses emcee.

Warning

may not work well for multi-modal distributions

Parameters:

system (system.System) – system.System object
num_temps (int) – number of temperatures to run the sampler at. Parallel tempering will be used if num_temps > 1 (default=20)
num_walkers (int) – number of walkers at each temperature (default=1000)
num_threads (int) – number of threads to use for parallelization (default=1)
chi2_type (str, optional) – either “standard”, or “log”
like (str) – name of likelihood function in lnlike.py
custom_lnlike (func) – ability to include an addition custom likelihood function in the fit. The function looks like clnlikes = custon_lnlike(params) where params is a RxM array of fitting parameters, where R is the number of orbital paramters (can be passed in system.compute_model()), and M is the number of orbits we need model predictions for. It returns clnlikes which is an array of length M, or it can be a single float if M = 1.
prev_result_filename (str) – if passed a filename to an HDF5 file containing a orbitize.Result data, MCMC will restart from where it left off.

Written: Jason Wang, Henry Ngo, 2018

check_prior_support()[source]

Review the positions of all MCMC walkers, to verify that they are supported by the prior space. This function will raise a descriptive ValueError if any positions lie outside prior support. Otherwise, it will return nothing.

(written): Adam Smith, 2021

chop_chains(burn, trim=0)[source]

Permanently removes steps from beginning (and/or end) of chains from the Results object. Also updates curr_pos if steps are removed from the end of the chain.

Parameters:

burn (int) – The number of steps to remove from the beginning of the chains
trim (int) – The number of steps to remove from the end of the chians (optional)

Warning

Does not update bookkeeping arrays within MCMC sampler object.

(written): Henry Ngo, 2019

examine_chains(param_list=None, walker_list=None, n_walkers=None, step_range=None, transparency=1)[source]

Plots position of walkers at each step from Results object. Returns list of figures, one per parameter :param param_list: List of strings of parameters to plot (e.g. “sma1”)

If None (default), all parameters are plotted

Parameters:

walker_list – List or array of walker numbers to plot If None (default), all walkers are plotted
n_walkers (int) – Randomly select n_walkers to plot Overrides walker_list if this is set If None (default), walkers selected as per walker_list
step_range (array or tuple) – Start and end values of step numbers to plot If None (default), all the steps are plotted
transparency (int or float) – Determines visibility of the plotted function If 1 (default) results plot at 100% opacity

Returns:

Walker position plot for each parameter selected

Return type:

List of matplotlib.pyplot.Figure objects

(written): Henry Ngo, 2019

run_sampler(total_orbits, burn_steps=0, thin=1, examine_chains=False, output_filename=None, periodic_save_freq=None)[source]

Runs PT MCMC sampler. Results are stored in self.chain and self.lnlikes. Results also added to orbitize.results.Results object (self.results)

Note

Can be run multiple times if you want to pause and inspect things. Each call will continue from the end state of the last execution.

Parameters:

total_orbits (int) – total number of accepted possible orbits that are desired. This equals num_steps_per_walker x num_walkers
burn_steps (int) – optional paramter to tell sampler to discard certain number of steps at the beginning
thin (int) – factor to thin the steps of each walker by to remove correlations in the walker steps
examine_chains (boolean) – Displays plots of walkers at each step by running examine_chains after total_orbits sampled.
output_filename (str) – Optional filepath for where results file can be saved.
periodic_save_freq (int) – Optionally, save the current results into output_filename every nth step while running, where n is value passed into this variable.

Returns:

the sampler used to run the MCMC

Return type:

emcee.sampler object

validate_xyz_positions()[source]: If using the XYZ basis, walkers might be initialized in an invalid region of parameter space. This function fixes that by replacing invalid positions by new randomly generated positions until all are valid.

class orbitize.sampler.MultiNest(system, chi2_type='standard', like='chi2_lnlike', custom_lnlike=None)[source]

Implements nested sampling using the (Py)MultiNest package. In order to use this sampler, MultiNest should be manually compiled. The sampler supports multiprocessing with MPI, which requires the installation of mpi4py (e.g. as “pip install mpi4py”).

Parameters:

system (system.System) – system.System object
chi2_type (str, optional) – either “standard”, or “log”
like (str) – name of likelihood function in lnlike.py
custom_lnlike (func) – ability to include an addition custom likelihood function in the fit. The function looks like clnlikes = custon_lnlike(params) where params is a RxM array of fitting parameters, where R is the number of orbital paramters (can be passed in system.compute_model()), and M is the number of orbits we need model predictions for. It returns clnlikes which is an array of length M, or it can be a single float if M = 1.

Tomas Stolker 2024

run_sampler(n_live_points=500, output_basename='./multinest', hdf5_file=None, multinest_kwargs=None)[source]

Runs the nested sampler from the (Py)MultiNest package.

Parameters:

n_live_points (int) – Number of live points. A larger numbers results in a more finely sampled posterior and a more accurate evidence, but also a larger number of iterations is required to converge (default: 500).
output_basename (str) – Basename for the MultiNest output. Can be a folder and/or prefix for the filenames. Any (sub)folder should first be manually created.
hdf5_file (str) – HDF5 filename in which the results are stored. Setting the argument will store the results by calling the save_results method of the Results objects. This parameter was implemented because calling save_results separately after the sampling has finished, may cause an error when using MPI because only one process should write the results. The results are not stored if the argument is set to None.
multinest_kwargs (dict) – dictionary of keywords that will be passed to pymultinest.run().

Returns:

posterior samples

Return type:

numpy.array of float

class orbitize.sampler.NestedSampler(system, chi2_type='standard', like='chi2_lnlike', custom_lnlike=None)[source]

Implements nested sampling using the Dynesty package.

Parameters:

system (system.System) – system.System object
chi2_type (str, optional) – either “standard”, or “log”
like (str) – name of likelihood function in lnlike.py
custom_lnlike (func) – ability to include an addition custom likelihood function in the fit. The function looks like clnlikes = custon_lnlike(params) where params is a RxM array of fitting parameters, where R is the number of orbital paramters (can be passed in system.compute_model()), and M is the number of orbits we need model predictions for. It returns clnlikes which is an array of length M, or it can be a single float if M = 1.

Thea McKenna, Sarah Blunt, & Lea Hirsch 2024

ptform(u)[source]

Prior transform function.

Parameters:

u (array of floats) – list of samples with values 0 < u < 1.

Returns:

1D u samples transformed to a chosen Prior: Class distribution.

Return type:

numpy array of floats

run_sampler(nlive=500, static=False, bound='multi', pfrac=1.0, num_threads=1, start_method='fork', run_nested_kwargs={})[source]

Runs the nested sampler from the Dynesty package.

Parameters:

nlive (int) – Number of live points. A larger numbers results in a more finely sampled posterior and a more accurate evidence, but also a larger number of iterations is required to converge (default: 500). The value is only used by the static sampler (i.e. with static=True).
static (bool) – True if using static nested sampling, False if using dynamic.
bound (str) – Method used to approximately bound the prior using the current set of live points. Conditions the sampling methods used to propose new live points. See https://dynesty.readthedocs.io/en/latest/quickstart.html#bounding-options for complete list of options.
pfrac (float) – posterior weight, between 0 and 1. Can only be altered for the Dynamic nested sampler, otherwise this keyword is unused.
num_threads (int) – number of threads to use for parallelization (default=1)
start_method (str) – multiprocessing start method. Default “fork,” which won’t work on all OS. Change to “spawn” if you get an error, and make sure you run your orbitize! script inside an if __name__==’__main__’ condition to protect entry points.
run_nested_kwargs (dict) – dictionary of keywords to be passed into dynesty.Sampler.run_nested()

Returns:

numpy.array of float: posterior samples

int: number of iterations it took to converge

Return type:

tuple

class orbitize.sampler.OFTI(system, like='chi2_lnlike', custom_lnlike=None, chi2_type='standard')[source]

OFTI Sampler

Parameters:

system (system.System) – system.System object
like (string) – name of likelihood function in lnlike.py
custom_lnlike (func) – ability to include an addition custom likelihood function in the fit. The function looks like clnlikes = custon_lnlike(params) where params is a RxM array of fitting parameters, where R is the number of orbital paramters (can be passed in system.compute_model()), and M is the number of orbits we need model predictions for. It returns clnlikes which is an array of length M, or it can be a single float if M = 1.

Written: Isabel Angelo, Sarah Blunt, Logan Pearce, 2018

prepare_samples(num_samples)[source]

Prepare some orbits for rejection sampling. This draws random orbits from priors, and performs scale & rotate.

Parameters:: num_samples (int) – number of orbits to draw and scale & rotate for OFTI to run rejection sampling on
Returns:: array of prepared samples. The first dimension has size of num_samples. This should be passed into OFTI.reject()
Return type:: np.array

reject(samples)[source]

Runs rejection sampling on some prepared samples.

Parameters:

samples (np.array) – array of prepared samples. The first dimension has size num_samples. This should be the output of prepare_samples().

Returns:

np.array: a subset of samples that are accepted based on the data.

np.array: the log likelihood values of the accepted orbits.

Return type:

tuple

run_sampler(total_orbits, num_samples=10000, num_cores=None, OFTI_warning=60.0)[source]

Runs OFTI in parallel on multiple cores until we get the number of total accepted orbits we want.

Parameters:

total_orbits (int) – total number of accepted orbits desired by user
num_samples (int) – number of orbits to prepare for OFTI to run rejection sampling on. Defaults to 10000.
num_cores (int) – the number of cores to run OFTI on. Defaults to number of cores availabe.
OFTI_warning (float) – if OFTI doesn’t accept a single orbit before this amount of time (in seconds), print a warning suggesting to try MCMC. If None, don’t print a warning.

Returns:

array of accepted orbits. Size: total_orbits.

Return type:

np.array

Written by: Vighnesh Nagpal(2019)

class orbitize.sampler.Sampler(system, like='chi2_lnlike', custom_lnlike=None, chi2_type='standard')[source]

Abstract base class for sampler objects. All sampler objects should inherit from this class.

Written: Sarah Blunt, 2018