Nested Sampling

Contents

Nested Sampling#

Nested Sampling Engine#

Orchestrates the nested-sampling run with support for nestle, PyMultiNest, and UltraNest back-ends.

class ForMoSA.nested_sampling.nested_sampling.NestedSampling(algorithm, npoints, logL_type, config_NS, observations, subgrids, parameters, wave_fit=None, interp_method='linear', bounds_lsq=None, logger=None, log_level='INFO')[source]#

Bases: object

ForMoSA Nested_Sampling class, which provides easy access to the parameters of the nested sampling algorithm

Parameters:

  • algorithm (NestedAlgorithm) – Algorithm used for the nested sampling (‘nestle’, ‘ultranest’ or ‘pymultinest’)

  • npoints (int) – Number of living points used for the nested sampling

  • logL_type (list[LogLikelihoodType]) – List of loglikelihood types used in the nested sampling

  • config_NS (Config_NS) – Instance of class Config_NS containing parameters of ns algorithms for each of the algorithm

  • observations (ObservationSet) – Instance of ObservationSet

  • subgrids (SubGridSet) – Instance of SubGridSet

  • parameters (ParameterSet) – Instance of ParameterSet

  • wave_fit (list[str] | None) – List of wavelength grid used for fitting

  • interp_method (str) – Interpolation method (‘linear’, ‘cubic’, ‘spline’, …)

  • bounds_lsq (list[tuple[float, float]] | None) – List of bounds used for the least squares (used for high contrast)

  • logger (Logger | None) – Logger

  • log_level (str) – Level of the Logger

Notes

Authors: Allan Denis

property algorithm: str#

Algorithm.

property logL_type: list#

logL functions.

property observations: ObservationSet#

Set of observations.

property subgrids: SubGridSet#

Set of subgrids.

property parameters: ParameterSet#

Priors parameters.

property config_NS: Config_NS#

Config_NS.

property interp_method: str#

Interpolation method.

property wave_fit: str#

Wavelengths for fitting.

property bounds_lsq: list[float]#

Bounds for the Least Squares estimation.

property ns_params: dict#

Dictionary of NS algo.

property npoints: int#

Nested sampling number of living points.

property restricted_observations: ObservationSet#

Set of restricted observations according to wave_fit.

property restricted_subgrids: SubGridSet#

Set of restricted subgrids according to wave_fit.

property results: NSResults#

Results.

property logger: Logger#

Logger.

property to_dict: dict#

Dictionary representation of NestedSampling.

classmethod from_dict(data, observations, subgrids, logger=None, log_level='INFO')[source]#

Reconstruct an instance of NestedSampling from a dictionary of NestedSampling.

Parameters:

  • data (dict) – Dictionary representation NestedSampling parameters

  • observations (ObservationSet) – Instance of ObservationSet

  • subgrids (SubGridSet) – Instance of SubGridSet

  • logger (Logger | None) – Logger

  • log_level (str) – Level of the Logger

Return type:

NestedSampling

Returns:

‘NestedSampling’ – An instance of class NestedSampling

Notes

Authors: Allan Denis

classmethod from_json(path, observations, subgrids, logger=None, log_level='INFO')[source]#

Reconstruct an instance of NestedSampling from the folder containing the NestedSampling parameters.

Parameters:

  • path (str | PathLike) – Dictionary representation NestedSampling parameters

  • observations (ObservationSet) – Instance of ObservationSet

  • subgrids (SubGridSet) – Instance of SubGridSet

  • logger (Logger | None) – Logger

  • log_level (str) – Level of the Logger

Return type:

NestedSampling

Returns:

‘NestedSampling’ – An instance of class NestedSampling

Notes

Authors: Allan Denis

run(results_path)[source]#

Method to run the nested sampling algorithm using the model, observation and nested sampling parameters.

Parameters:

results_path (str | PathLike) – Path of the output

Return type:

None

Notes

Authors: Simon Petrus, Matthieu Ravet and Allan Denis

loglike(theta)[source]#

Compute the loglikelihood for given parameters of the nested sampling.

Parameters:

theta (ndarray[float]) – Values randomly drawn by the Nested Sampling

Return type:

float

Returns:

logL (float) – Final loglikelihood

prior_transform(theta)[source]#

ransform theta in [0,1]^N into physical values for free parameters.

Parameters:

theta (ndarray[float]) – List of the parameters drawn by the nested sampling algorithm

Return type:

ndarray[float]

Returns:

np.ndarray[float] – Transformed values

Notes

Authors: Allan Denis

build_models_from_theta(theta)[source]#

Build the models from the values of the free parameters drawn by the Nested Sampling

Parameters:

theta (ndarray[float]) – List of values picked by the Nested Sampling for the free parameters

Return type:

list[ObservedModel]

Returns:

list[ObservedModel] – List of instances of class ObservedModel

Notes

Authors: Allan Denis

save_results(results_path, **kwargs)[source]#

Method to save the results to the path results_path

Parameters:

  • results_path (str | PathLike) – Path to save the results to

  • (wav_fit (**kwargs = Additional parameters)

  • interp_method

  • bounds_lsq)

Return type:

None

Notes

Authors: Allan Denis

load_results(results_path)[source]#

Method to load the results from the path results_paths

Parameters:

results_path (str | PathLike) – Path to save the results to

Return type:

None

Notes

Authors: Allan Denis

NS Analysis#

Post-processing of nested-sampling products: best-fit reconstruction, CCF computation, RV–v sin i maps, and confidence intervals.

class ForMoSA.nested_sampling.ns_analysis.NSAnalysis(ns, logger=None, log_level='INFO')[source]#

Bases: object

Class used to subsequent analysis of nested sampling products. It includes the reconstructions of models, best fit, computations of ccf, …

Parameters:

Notes

Authors: Allan Denis

property logger: Logger#

Logger.

property ns: NestedSampling#

Instance of NestedSampling.

property best_fit: list[ObservedModel]#

Best fit.

property native_best_fit: ObservedModel#

Best fit parameters applied to the native model.

build_models_from_theta(theta)[source]#

Build the models from the values of the free parameters drawn by the Nested Sampling

Parameters:

theta (np.ndarray[float]) – List of values picked by the Nested Sampling for the free parameters

Returns:

list[ObservedModel] – List of instances of class ObservedModel

Notes

Authors: Allan Denis

best_fit_interval(perc=0.68)[source]#

Confidence interval of the native best fit.

Parameters:

perc (float) – Percentile value between 0 and 1 (0.68 for 1 sigma, 0.95 for 2 sigmas)

Return type:

tuple[ObservedModel, ObservedModel]

Returns:

tuple[ObservedModel, ObservedModel] – lower and higher values of the flux for the confidence interval

Notes

Authors: Allan Denis

compute_ccf(rv_grid, index=0, theta=None)[source]#

Compute and optionally plot the Cross-Correlation Function (CCF).

Parameters:

  • rv_grid (ndarray) – Grid of radial velocity values (in km/s)

  • index (int) – Index of observation used for the ccf computation

  • theta (list | None) – List of free values of the parameters. If not provided, the best fitted parameters are used

Return type:

dict[str, ndarray]

Returns:

dict[str, np.ndarray] – Dictionary of CCF results keyed by observation name

Notes

Authors: Bhavesh Rajpoot and Allan Denis

compute_rv_vsini_map(rv_grid, vsini_grid, index=0, theta=None)[source]#

Compute and optionally plot the RV vs v.sin(i) loglikelihood map.

Parameters:

  • rv_grid (ndarray) – Grid of radial velocity values (in km/s)

  • vsini_grid (ndarray) – Grid of v.sin(i) values (in km/s)

  • index (int) – Index of observation used for the ccf computation

  • theta (list | None) – List of free values of the parameters. If not provided, the best fitted parameters are used

Return type:

dict[str, ndarray]

Returns:

dict[str, np.ndarray] – Dictionary of RV-vsini map results keyed by observation name

Notes

Authors: Bhavesh Rajpoot and Allan Denis

Results#

Data container that stores the raw output of a nested-sampling run.

class ForMoSA.nested_sampling.results.NSResults(samples, weights, logl, logvol, logz, free_parameters, burn_in=0)[source]#

Bases: object

Dataclass to handle reading and storing results of the Nested Sampling algorithm

Notes

Authors: Allan Denis

Parameters:
samples: ndarray#
weights: ndarray#
logl: ndarray#
logvol: ndarray#
logz: list[float, float]#
free_parameters: list[str]#
burn_in: int = 0#
property to_dict: dict#

Dictionary view of the results.

property median_parameters: dict[str, float]#

Weighted posterior median for each parameter.

property param_samples_dict: dict[str, float]#

Samples of each parameter.

property best_logL: float#

Averaged value of logL.

classmethod from_dict(data)[source]#

Load NSResults from dictionary.

Parameters:

  • data (dict) – Dictionary of NSResults

  • free_parameters (list[str]) – List of free parameters names

Return type:

NSResults

Returns:

NSResults – Instance of class NSResults

Notes

Authors: Allan Denis

classmethod from_nestle(res, free_parameters)[source]#

Return an instance of NSResults based on the results of a Nestle algorithm.

Parameters:

  • res (dict) – Dictionary containing Nested Sampling results

  • free_parameters (list[str]) – List of free parameters names

Return type:

NSResults

Returns:

NestleResults – An instance of NSResults

Notes

Authors: Allan Denis

classmethod from_pymultinest(results_path, free_parameters)[source]#

Return an instance of NSResults based on the results of a PyMultinest algorithm.

Parameters:

  • results_path (str) – Path to the PyMultiNest output folder containing RAW_stats.dat, RAW_ev.dat, RAW_.txt

  • free_parameters (list[str]) – List of free parameters names

Return type:

NSResults

Returns:

NSResults – An instance of NSResults

Notes

Authors: Allan Denis

classmethod from_ultranest(res, free_parameters)[source]#

Construct an instance of UltraNestResults from the UltraNest output folder.

Parameters:

  • res (dict) – Dictionary containing Nested Sampling results

  • free_parameters (list[str]) – List of free parameters names

Return type:

NSResults

Returns:

NSResults – An instance of NSResults

Notes

Authors: Allan Denis

summary(sigma=1, include_map=True)[source]#

Print a summary of the posterior distributions.

Parameters:

  • sigma (int) – Credible interval (1 or 2 sigma)

  • include_map (bool) – hether to include MAP estimate

Return type:

str

Returns:

str – Summary

Notes

Authors: Allan Denis

Prior Functions#

Low-level prior sampling functions used internally by the prior classes.

ForMoSA.utils.prior_functions.uniform_prior(bounds, theta)[source]#

Uniform prior for nested sampling.

Parameters:

  • bounds (list) – Uniform prior boundaries

  • theta (float) – Parameter value between 0 and 1

Return type:

float

Returns:

float – Evaluated prior

Notes

Authors: Simon Petrus

ForMoSA.utils.prior_functions.loguniform_prior(prior_fct_arg, theta)[source]#

LogUniform prior for nested sampling.

Parameters:

  • prior_fct_arg (list) – Loguniform prior boundaries.

  • theta (float) – Parameter values randomly picked by the nested sampling

Return type:

float

Returns:

float – Evaluated prior

Notes

Authors: Simon Petrus

ForMoSA.utils.prior_functions.gaussian_prior(mean, std, theta)[source]#

Gaussian prior for nested sampling.

Parameters:

  • mean (float) – Gaussian prior mean

  • std (float) – Gaussian prior standard deviation

  • theta (float) – Parameter values randomly picked by the nested sampling

Returns:

float – Evaluated prior

Notes

Authors: Simon Petrus

Likelihood Functions#

Log-likelihood functions available for nested sampling.

ForMoSA.utils.logL_functions.logL_chi2(delta_flx, err, full=False)[source]#

Function to compute logL based on the classical chi2 under the assumption of gaussian and spectrally uncorrelated noise.

Parameters:

  • delta_flx (array) – residual data-model as a function of wavelength

  • err (array) – error (=standard deviation) of the observed spectrum as a function of wavelength

  • full (bool) – True or False to add the usual constant terms

Returns:

float – the loglikelihood value

Notes

Authors: Matthieu Ravet

ForMoSA.utils.logL_functions.logL_chi2_covariance(delta_flx, cov, inv_cov, full=False)[source]#

Function to compute logL based on the generalized chi2 under the assumption of gaussian and spectrally correlated noise.

Parameters:

  • delta_flx (array) – residual data-model as a function of wavelength

  • cov (n-array) – Covariance matrix of the observed spectrum as a function of wavelength

  • inv_cov (n-array) – inverse of the covariance matrix of the observed spectrum as a function of wavelength

  • full (bool) – True or False to add the usual constant terms

Returns:

float – the loglikelihood value

Notes

Authors: Matthieu Ravet

ForMoSA.utils.logL_functions.logL_chi2_noisescaling(delta_flx, err, full=False)[source]#

Function to compute logL based on the chi2 with a fitted noise scaling s (marginalized) under the assumption of gaussian and spectrally uncorrelated noise.

Parameters:

  • delta_flx (array) – residual data-model as a function of wavelength

  • err (array) – error (=standard deviation) of the observed spectrum as a function of wavelength

  • full (bool) – True or False to add the usual constant terms

Returns:

float – the loglikelihood value

Notes

Authors: Allan Denis and Matthieu Ravet

ForMoSA.utils.logL_functions.logL_chi2_noisescaling_covariance(delta_flx, cov, inv_cov, full=False)[source]#

Function to compute logL based on the chi2 with a fitted noise scaling s (marginalized) under the assumption of gaussian and spectrally correlated noise.

Parameters:

  • delta_flx (array) – residual data-model as a function of wavelength

  • cov (n-array) – Covariance matrix of the observed spectrum as a function of wavelength

  • inv_cov (n-array) – inverse of the covariance matrix of the observed spectrum as a function of wavelength

  • full (bool) – True or False to add the usual constant terms

Returns:

float – the loglikelihood value

Notes

Authors: Allan Denis and Matthieu Ravet

ForMoSA.utils.logL_functions.logL_CCF_Brogi(flx_obs, flx_mod)[source]#

Function to compute logL based on the CCF mapping from Brogi et al. 2019 under the assumption of gaussian and spectrally constant noise.

Parameters:

  • flx_obs (array) – flux of the observation as a function of wavelength

  • flx_mod (array) – flux of the model as a function of wavelength

Returns:

float – the loglikelihood value

Notes

Authors: Matthieu Ravet

ForMoSA.utils.logL_functions.logL_CCF_Zucker(flx_obs, flx_mod)[source]#

Function to compute logL based on the CCF mapping from Zucker 2003 under the assumption of gaussian and spectrally constant noise.

Parameters:

  • flx_obs (array) – flux of the observation as a function of wavelength

  • flx_mod (array) – flux of the model as a function of wavelength

Returns:

float – the loglikelihood value

Notes

Authors: Matthieu Ravet

ForMoSA.utils.logL_functions.logL_CCF_custom(flx_obs, flx_mod, err_obs)[source]#

Function to compute logL based on the custom CCF mapping from Me under the assumption of gaussian and spectrally constant noise.

Parameters:

  • flx_obs (array) – flux of the observation as a function of wavelength

  • flx_mod (array) – flux of the model as a function of wavelength

  • err_obs (array) – errors of the observation as a function of wavelength

Returns:

float – the loglikelihood value

Notes

Authors: Matthieu Ravet

Contents