threeML.bayesian package

Submodules

threeML.bayesian.autoemcee_sampler module

class threeML.bayesian.autoemcee_sampler.AutoEmceeSampler(likelihood_model=None, data_list=None, **kwargs)

Bases: UnitCubeSampler

sample(quiet=False)

Sample using the UltraNest numerical integration method :rtype:

Returns:

setup(num_global_samples=10000, num_chains=4, num_walkers=None, max_ncalls=1000000, max_improvement_loops=4, num_initial_steps=100, min_autocorr_times=0)

Sample until MCMC chains have converged.

The steps are:

1. Draw num_global_samples from prior. The highest num_walkers points are

   selected.

2. Set num_steps to num_initial_steps

3. Run num_chains MCMC ensembles for num_steps steps

4. For each walker chain, compute auto-correlation length (Convergence requires

   num_steps/autocorrelation length > min_autocorr_times)

5. For each parameter, compute geweke convergence diagnostic (Convergence

   requires |z| < 2)

6. For each ensemble, compute gelman-rubin rank convergence diagnostic

   (Convergence requires rhat<1.2)

7. If converged, stop and return results.

8. Increase num_steps by 10, and repeat from (3) up to

   max_improvement_loops times.

num_global_samples: int

Number of samples to draw from the prior to

num_chains: int

Number of independent ensembles to run. If running with MPI, this is set to the number of MPI processes.

num_walkers: int

Ensemble size. If None, max(100, 4 * dim) is used

max_ncalls: int

Maximum number of likelihood function evaluations

num_initial_steps: int

Number of sampler steps to take in first iteration

max_improvement_loops: int

Number of times MCMC should be re-attempted (see above)

min_autocorr_times: float

if positive, additionally require for convergence that the number of samples is larger than the min_autocorr_times times the autocorrelation length.

threeML.bayesian.bayesian_analysis module

class threeML.bayesian.bayesian_analysis.BayesianAnalysis(likelihood_model: Model, data_list: DataList, **kwargs)

Bases: object

property analysis_type: str

convergence_plots(n_samples_in_each_subset, n_subsets)

Compute the mean and variance for subsets of the samples, and plot them. They should all be around the same values if the MCMC has converged to the posterior distribution.

The subsamples are taken with two different strategies: the first is to slide a fixed-size window, the second is to take random samples from the chain (bootstrap)

Parameters:

• n_samples_in_each_subset – number of samples in each subset

• n_subsets – number of subsets to take for each strategy

Returns:

a matplotlib.figure instance

property data_list: DataList

data list for this analysis

Type:

return

property likelihood_model: Model

likelihood model (a Model instance)

Type:

return

property log_like_values: ndarray | None

Returns the value of the log_likelihood found by the bayesian sampler while sampling from the posterior. If you need to find the values of the parameters which generated a given value of the log. likelihood, remember that the samples accessible through the property .raw_samples are ordered in the same way as the vector returned by this method.

Returns:

a vector of log. like values

property log_marginal_likelihood: float | None

return:

marginal_likelihood.

Type:

Return the log marginal likelihood (evidence) if computed

property log_probability_values: ndarray | None

Returns the value of the log_probability (posterior) found by the bayesian sampler while sampling from the posterior. If you need to find the values of the parameters which generated a given value of the log. likelihood, remember that the samples accessible through the property .raw_samples are ordered in the same way as the vector returned by this method.

Returns:

a vector of log probabilty values

plot_chains(thin=None)

Produce a plot of the series of samples for each parameter.

Parameters:

thin – use only one sample every ‘thin’ samples

Returns:

a matplotlib.figure instance

property raw_samples: ndarray | None

Access the samples from the posterior distribution generated by the selected sampler in raw form (i.e., in the format returned by the sampler)

Returns:

the samples as returned by the sampler

restore_MAP_fit() → None

Sets the model parameters to the MAP of the probability.

restore_median_fit()

Sets the model parameters to the mean of the marginal distributions.

property results: BayesianResults | None

sample(quiet=False, **kwargs) → None

Sample the posterior of the model with the selected algorithm.

If no algorithm as been set, then the configured default algorithm we default parameters will be run

Parameters:

quiet – if True, then no output is displayed

Returns:

property sampler: SamplerBase | None

Access the instance of the sampler used to sample the posterior distribution :return: an instance of the sampler.

property samples: Dict[str, ndarray] | None

Access the samples from the posterior distribution generated by the selected sampler.

Returns:

a dictionary with the samples from the posterior distribution for each parameter

set_sampler(sampler_name: str = 'default', **kwargs)

Set the sampler :param sampler_name: (str) Name of sampler.

Parameters:

share_spectrum – (optional) Option to share the spectrum calc between detectors with the same input energy bins

threeML.bayesian.dynesty_sampler module

class threeML.bayesian.dynesty_sampler.DynestyDynamicSampler(likelihood_model=None, data_list=None, **kwargs)

Bases: UnitCubeSampler

sample(quiet: bool = False, **kwargs)

Sample using the Dynestey DynamicNestedSampler class.

Parameters:

• quiet (bool) – verbosity. Defaults to False.

• kwargs (dict) – Additional keywords that get passed to the run_nested() function.

Return type:

Returns:

setup(nlive: int = 500, history_filename=None, **kwargs)

Setup the Dynesty dynamic nested sampler. All available parameters can be found in the respective version of https://dynesty.readthedocs.io/en/v3.0.0/api.html#dynesty.dynesty.DynamicNestedSampler

Parameters:

• nlive (int) – Number of live points used during the inital nested sampling run

• history_filename (str) – Path to save the history. Defaults to None

• kwargs (dict) – Additional keyword arguments - must be same name and type as paramters in constructor of the dynesty.DynamicNestedSampler class. Defaults to the values used by dynesty.

class threeML.bayesian.dynesty_sampler.DynestyNestedSampler(likelihood_model=None, data_list=None, **kwargs)

Bases: UnitCubeSampler

sample(quiet: bool = False, **kwargs)

Sample using the Dynesty NestedSampler class

Parameters:

• quiet (bool) – verbosity. Defaults to False.

• kwargs (dict) – Additional keywords that get passed to the run_nested() function.

Return type:

Returns:

setup(nlive: int = 500, bound: Literal['multi', 'single', 'none', 'balls', 'cubes'] | None = 'multi', history_filename: str | None = None, **kwargs)

Setup the Dynesty nested sampler. All available parameters can be found in the respective version of https://dynesty.readthedocs.io/en/v3.0.0/api.html#dynesty.dynesty.NestedSampler

Parameters:

• nlive (int) – Number of live points. Defaults to 500.

• bound – Method to approximately bound the prior using the current set of live points. Options are “multi”, “single”, “none”, “balls” or “cubes”. Defaults to “multi”.

• history_filename (str) – Path to save the history. Defaults to None

• kwargs (dict) – Additional keyword arguments - must be same name and type as paramters in constructor of the dynesty.NestedSampler class. Defaults to the values used by dynesty.

class threeML.bayesian.dynesty_sampler.DynestyPool(dview)

Bases: object

A simple wrapper for dview.

map(function, tasks)

threeML.bayesian.dynesty_sampler.fill_docs(**kwargs)

threeML.bayesian.emcee_sampler module

class threeML.bayesian.emcee_sampler.EmceeSampler(likelihood_model=None, data_list=None, **kwargs)

Bases: MCMCSampler

sample(quiet=False)

setup(n_iterations: int, n_burn_in: int | None = None, n_walkers: int = 20, seed=None, **kwargs)

TODO describe function.

Parameters:

• n_iterations (int)

• n_burn_in (Optional[int])

• n_walkers (int)

• seed

Returns:

threeML.bayesian.multinest_sampler module

class threeML.bayesian.multinest_sampler.MultiNestSampler(likelihood_model: Model | None = None, data_list: DataList | None = None, **kwargs)

Bases: UnitCubeSampler

sample(quiet: bool = False)

Sample using the MultiNest numerical integration method.

Returns:

Return type:

setup(n_live_points: int = 400, chain_name: str = 'chains/fit-', resume: bool = False, importance_nested_sampling: bool = False, auto_clean: bool = False, **kwargs)

Setup the MultiNest Sampler. For details see: https://github.com/farhanferoz/MultiNest

Parameters:

• n_live_points – number of live points for the evaluation

• chain_name – the chain name

• importance_nested_sampling – use INS

• auto_clean – automatically remove multinest chains after run

Resume:

resume from previous fit

Returns:

Return type:

threeML.bayesian.nautilus_sampler module

class threeML.bayesian.nautilus_sampler.NautilusSampler(likelihood_model=None, data_list=None, **kwargs)

Bases: UnitCubeSampler

sample(quiet=False)

Sample using the UltraNest numerical integration method :rtype:

Returns:

setup(n_live: int = 2000, n_update: int | None = None, enlarge_per_dim: float = 1.1, n_points_min: int | None = None, split_threshold: int = 100, n_networks: int = 4, neural_network_kwargs: Dict[str, Any] = {}, prior_args: List[Any] = [], prior_kwargs: Dict[str, Any] = {}, likelihood_args: List[Any] = [], likelihood_kwargs: Dict[str, Any] = {}, n_batch: int = 100, n_like_new_bound: int | None = None, vectorized: bool = False, pass_dict: bool | None = None, pool: int | None = None, seed: int | None = None, filepath: str | None = None, resume: bool = True, f_live: float = 0.01, n_shell: int | None = None, n_eff: int = 10000, discard_exploration: bool = False, verbose: bool = False)

Setup the nautilus sampler.

See: https://nautilus-sampler.readthedocs.io/en/stable/index.html

Parameters:

n_live – Number of so-called live points. New bounds are constructed so

that they encompass the live points. Default is 3000. :type n_live: int :param n_update: The maximum number of additions to the live set before a new bound is created. If None, use n_live. Default is None. :type n_update: Optional[int] :param enlarge_per_dim: Along each dimension, outer ellipsoidal bounds are enlarged by this factor. Default is 1.1. :type enlarge_per_dim: float :param n_points_min: The minimum number of points each ellipsoid should have. Effectively, ellipsoids with less than twice that number will not be split further. If None, uses n_points_min = n_dim + 50. Default is None. :type n_points_min: Optional[int] :param split_threshold: hreshold used for splitting the multi-ellipsoidal bound used for sampling. If the volume of the bound prior enlarging is larger than split_threshold times the target volume, the multi-ellipsiodal bound is split further, if possible. Default is 100. :type split_threshold: int :param n_networks: Number of networks used in the estimator. Default is 4. :type n_networks: int :param neural_network_kwargs: Non-default keyword arguments passed to the constructor of MLPRegressor. :type neural_network_kwargs: Dict[Any] :param prior_args: List of extra positional arguments for prior. Only used if prior is a function. :type prior_args: List[Any] :param prior_kwargs: Dictionary of extra keyword arguments for prior. Only used if prior is a function. :type prior_kwargs: Dict[Any] :param likelihood_args: List of extra positional arguments for likelihood. :type likelihood_args: List[Any] :param likelihood_kwargs: Dictionary of extra keyword arguments for likelihood. :type likelihood_kwargs: Dict[Any] :param n_batch: Number of likelihood evaluations that are performed at each step. If likelihood evaluations are parallelized, should be multiple of the number of parallel processes. Very large numbers can lead to new bounds being created long after n_update additions to the live set have been achieved. This will not cause any bias but could reduce efficiency. Default is 100. :type n_batch: int :param n_like_new_bound: The maximum number of likelihood calls before a new bounds is created. If None, use 10 times n_live. Default is None. :type n_like_new_bound: Optional[int] :param vectorized: If True, the likelihood function can receive multiple input sets at once. For example, if the likelihood function receives arrays, it should be able to take an array with shape (n_points, n_dim) and return an array with shape (n_points). Similarly, if the likelihood function accepts dictionaries, it should be able to process dictionaries where each value is an array with shape (n_points). Default is False. :type vectorized: bool :param pass_dict: If True, the likelihood function expects model parameters as dictionaries. If False, it expects regular numpy arrays. Default is to set it to True if prior was a nautilus.Prior instance and False otherwise :type pass_dict: Optional[bool] :param pool: Pool used for parallelization of likelihood calls and sampler calculations. If None, no parallelization is performed. If an integer, the sampler will use a multiprocessing.Pool object with the specified number of processes. Finally, if specifying a tuple, the first one specifies the pool used for likelihood calls and the second one the pool for sampler calculations. Default is None. :type pool: Optional[int] :param seed: Seed for random number generation used for reproducible results accross different runs. If None, results are not reproducible. Default is None. :type seed: Optional[int] :param filepath: ath to the file where results are saved. Must have a ‘.h5’ or ‘.hdf5’ extension. If None, no results are written. Default is None. :type filepath: Optional[str] :param resume: If True, resume from previous run if filepath exists. If False, start from scratch and overwrite any previous file. Default is True. :type resume: bool :param f_live: Maximum fraction of the evidence contained in the live set before building the initial shells terminates. Default is 0.01. :type f_live: float :param n_shell: Minimum number of points in each shell. The algorithm will sample from the shells until this is reached. Default is the batch size of the sampler which is 100 unless otherwise specified. :type n_shell: Optional[int] :param n_eff: Minimum effective sample size. The algorithm will sample from the shells until this is reached. Default is 10000.

Parameters:

discard_exploration – Whether to discard points drawn in the exploration

phase. This is required for a fully unbiased posterior and evidence estimate. Default is False. :type discard_exploration: bool :param verbose: If True, print additional information. Default is False. :type verbose: bool :returns:

threeML.bayesian.nautilus_sampler.capture_arguments(func, *args, **kwargs)

threeML.bayesian.sampler_base module

class threeML.bayesian.sampler_base.MCMCSampler(likelihood_model, data_list, **kwargs)

Bases: SamplerBase

class threeML.bayesian.sampler_base.SamplerBase(likelihood_model: Model, data_list: DataList, **kwargs)

Bases: object

get_posterior(trial_values) → float

Compute the posterior for the normal sampler.

property log_like_values: ndarray | None

Returns the value of the log_likelihood found by the bayesian sampler while samplin g from the posterior. If you need to find the values of the parameters which generated a given value of the log. likelihood, remember that the samples accessible through the property .raw_samples are ordered in the same way as the vector returned by this method.

Returns:

a vector of log. like values

property log_marginal_likelihood: float | None

Return the log marginal likelihood (evidence) if computed :return:

property log_probability_values: ndarray | None

Returns the value of the log_probability (posterior) found by the bayesian sampler while sampling from the posterior. If you need to find the values of the parameters which generated a given value of the log. likelihood, remember that the samples accessible through the property .raw_samples are ordered in the same way as the vector returned by this method.

Returns:

a vector of log probabilty values

property raw_samples: ndarray | None

Access the samples from the posterior distribution generated by the selected sampler in raw form (i.e., in the format returned by the sampler)

Returns:

the samples as returned by the sampler

restore_MAP_fit() → None

Sets the model parameters to the MAP of the probability.

restore_median_fit() → None

Sets the model parameters to the median of the log probability.

property results: BayesianResults

abstract sample()

property samples: Dict[str, ndarray] | None

Access the samples from the posterior distribution generated by the selected sampler.

Returns:

a dictionary with the samples from the posterior distribution for each parameter

abstract setup() → None

class threeML.bayesian.sampler_base.UnitCubeSampler(likelihood_model, data_list, **kwargs)

Bases: SamplerBase

threeML.bayesian.sampler_base.arg_median(a)

threeML.bayesian.tutorial_material module

class threeML.bayesian.tutorial_material.BayesianAnalysisWrap(likelihood_model: Model, data_list: DataList, **kwargs)

Bases: BayesianAnalysis

sample(*args, **kwargs)

Sample the posterior of the model with the selected algorithm.

If no algorithm as been set, then the configured default algorithm we default parameters will be run

Parameters:

quiet – if True, then no output is displayed

Returns:

threeML.bayesian.tutorial_material.array_to_cmap(values, cmap, use_log=False)

Generates a color map and color list that is normalized to the values in an array. Allows for adding a 3rd dimension onto a plot.

Parameters:

• values – a list a values to map into a cmap

• cmap – the mpl colormap to use

• use_log – if the mapping should be done in log space

threeML.bayesian.tutorial_material.get_bayesian_analysis_object_complex_likelihood()

threeML.bayesian.tutorial_material.get_bayesian_analysis_object_simple_likelihood()

threeML.bayesian.tutorial_material.plot_likelihood_function(bayes, fig=None, show_prior=False)

threeML.bayesian.tutorial_material.plot_sample_path(bayes, burn_in=None, truth=None)

Parameters:

jl (JointLikelihood)

Returns:

threeML.bayesian.ultranest_sampler module

class threeML.bayesian.ultranest_sampler.UltraNestSampler(likelihood_model=None, data_list=None, **kwargs)

Bases: UnitCubeSampler

sample(quiet=False)

Sample using the UltraNest numerical integration method :rtype:

Returns:

setup(min_num_live_points: int = 400, dlogz: float = 0.5, chain_name: str | None = None, resume: str = 'overwrite', wrapped_params=None, stepsampler=None, use_mlfriends: bool = True, **kwargs)

set up the Ultranest sampler. Consult the documentation: https://johannesbuchner.github.io/UltraNest/ultranest.html?highlight=reactive# ultranest.integrator.ReactiveNestedSampler

Parameters:

• min_num_live_points (int) – minimum number of live points throughout the run

• dlogz – Target evidence uncertainty. This is the std between bootstrapped

logz integrators. :type dlogz: float :param chain_name: where to store output files :type chain_name: :param resume: (‘resume’, ‘resume-similar’, ‘overwrite’ or ‘subfolder’) – if ‘overwrite’, overwrite previous data. if ‘subfolder’, create a fresh subdirectory in log_dir. if ‘resume’ or True, continue previous run if available. Only works when dimensionality, transform or likelihood are consistent. if ‘resume-similar’, continue previous run if available. Only works when dimensionality and transform are consistent. If a likelihood difference is detected, the existing likelihoods are updated until the live point order differs. Otherwise, behaves like resume. :type resume: str :param wrapped_params: (list of bools) – indicating whether this parameter wraps around (circular parameter). :type wrapped_params: :param stepsampler: :type stepsampler: :param use_mlfriends: Whether to use MLFriends+ellipsoidal+tellipsoidal region (better for multi-modal problems) or just ellipsoidal sampling (faster for high-dimensional, gaussian-like problems). :type use_mlfriends: bool :returns:

threeML.bayesian.zeus_sampler module

class threeML.bayesian.zeus_sampler.ZeusSampler(likelihood_model=None, data_list=None, **kwargs)

Bases: MCMCSampler

sample(quiet=False)

setup(n_iterations, n_burn_in=None, n_walkers=20, seed=None)

Set up the zeus sampler.

Parameters:

• n_iterations

• n_burn_in

• n_walkers

• seed

Returns:

Module contents