antaress.ANTARESS_general.minim_routines module

up_var_par(args, par)

Parameter conversion: parameter update

Update input parameter in list of variables.

Parameters:

TBD

Returns:

TBD

par_formatting(p_start, model_prop, priors_prop, fit_dic, fixed_args, inst, vis)

Parameter formatting: generic

Defines parameters in format relevant for fits and models, using input parameters.

Parameters:

TBD

Returns:

TBD

ln_prior_func(p_step, fixed_args)

Log(prior)

Calculates the sum of natural logarithms from selected prior probability distributions.

Parameters:

TBD

Returns:

TBD

ln_prior_func_NS(cube, fixed_args)

Prior transform function for nested sampling.

The prior transform function is used to implicitly specify the Bayesian prior for dynesty. It functions as a transformation from a space where variables are i.i.d. within the n-dimensional

unit cube (i.e. uniformly distributed from 0 to 1) to the parameter space of interest.

Parameters:

TBD

Returns:

TBD

global_ln_prior_func(p_step, fixed_args)

Global prior function.

Calculates \(\log(p)\) cumulated over the chosen priors.

See ln_prior_func() for details on prior definition.

Parameters:

TBD

Returns:

TBD

sub_ln_lkhood_func(p_step, fixed_args)

Log(likelihood)

Calculates the natural logarithm of the likelihood. Likelihood is defined as

\[L[\mathrm{step}](x) = \Pi_{x}{ \frac{1}{\sqrt{2 \pi} \sigma_\mathrm{val}^\mathrm{jitt}(x) } \exp^{ - (\frac{ y_\mathrm{mod}[\mathrm{step}](x) - y_\mathrm{val}(x) }{\sqrt{2} \sigma_\mathrm{val}^\mathrm{jitt}(x) })^2 } }\]

With

• \(y_\mathrm{mod}[\mathrm{step}]\) : model for parameter values at current step

• \(y_\mathrm{val}\) : fitted measurements

• \(\sigma_\mathrm{val}\) : error on fitted measurements

• \(\sigma_\mathrm{jitt}\): additional error term (jitter) added quadratically to measurement errors, if requested. It is then a variable parameter of the mcmc

• \(\sigma_\mathrm{val}^\mathrm{jitt} = \sqrt{ \sigma_\mathrm{val}^2 + \sigma_\mathrm{jitt}^2 }\)

Likelihood can also write as:

\[\begin{split}L[\mathrm{step}](x) &= \Pi_{x}{ \frac{1}{\sqrt{2 \pi} \sigma_\mathrm{val}^\mathrm{jitt}(x) }} \Pi_{x}{ \exp^{ - (\frac{ y_\mathrm{mod}[\mathrm{step}](x) - y_\mathrm{val}(x) }{\sqrt{2} \sigma_\mathrm{val}^\mathrm{jitt}(x) })^2 } } \\ &= \Pi_{x}{ \frac{1}{\sqrt{2 \pi} \sigma_\mathrm{val}^\mathrm{jitt}(x) }} \exp^{ - \sum_{x}{ (\frac{ y_\mathrm{mod}[\mathrm{step}](x) - y_\mathrm{val}(x) }{\sqrt{2} \sigma_\mathrm{val}^\mathrm{jitt}(x) })^2 } } \\ &= \Pi_{x}{ \frac{1}{\sqrt{2 \pi} \sigma_\mathrm{val}^\mathrm{jitt}(x) }} \exp^{ - \frac{\chi^2[\mathrm{step}]}{2} }\end{split}\]

With

\[\chi^2[\mathrm{step}] = \sum_{x}{ (\frac{ y_\mathrm{mod}[\mathrm{step}](x) - y_\mathrm{val}(x) }{\sqrt{2} \sigma_\mathrm{val}^\mathrm{jitt}(x) })^2 }\]

The ln of likelihood is used to avoid to avoid issues with large \(\chi^2\) and small exponential values. For similar reasons we use in our calculation the sum of ln rather than the ln of the product

\[\begin{split}\ln{L[\mathrm{step}]}(x) &= \ln(\Pi_{x}{ \frac{1}{\sqrt{2 \pi} \sigma_\mathrm{val}^\mathrm{jitt}(x) } }) + \ln(\exp{- \frac{\chi^2[\mathrm{step}]}{2}} ) \\ \ln{L[\mathrm{step}]}(x) &= -\sum_{x}{ \ln( \sqrt{2 \pi} \sigma_\mathrm{val}^\mathrm{jitt}(x) )} - \frac{\chi^2[\mathrm{step}]}{2}\end{split}\]

Which also writes as (yielding the form given on the emcee website)

\[\begin{split}\ln{L[\mathrm{step}]}(x) &= - \sum_{x}{ \ln( ( 2 \pi \sigma_\mathrm{val}^\mathrm{jitt}(x)^2 )^{0.5}) } - \frac{\chi^2[\mathrm{step}]}{2} \\ \ln{L[\mathrm{step}]}(x) &= - \sum_{x}{ 0.5 \ln( 2 \pi \sigma_\mathrm{val}^\mathrm{jitt}(x)^2) } - \frac{\chi^2[\mathrm{step}]}{2} \\ \ln{L[\mathrm{step}]}(x) &= - 0.5 ( \sum_{x}( \ln( 2 \pi \sigma_\mathrm{val}^\mathrm{jitt}(x)^2) ) + \chi^2[\mathrm{step}])\end{split}\]

Parameters:

TBD

Returns:

TBD

ln_lkhood_func_mcmc(p_step, fixed_args)

Log(likelihood) with MCMC

Calculates the natural logarithm of the likelihood with MCMC.

Parameters:

TBD

Returns:

TBD

ln_lkhood_func_ns(p_step, fixed_args)

Log(likelihood) with nested sampling

Calculates the natural logarithm of the likelihood with nested sampling.

Parameters:

TBD

Returns:

TBD

ln_prob_func_mcmc(p_step, fixed_args)

Log-probability function: MCMC

Calculates the complete log-probability function combining prior and likelihood.

Parameters:

• p_step (dict) – contains the values of the variable parameters at current MCMC step

• fixed_args (dict) – contains parameters useful to the calculation of the function, in particular the values of parameters that are fixed.

Returns:

ln_prob (float) – log-probability

ln_prob_func_lmfit(p_step, x_val, fixed_args=None)

Log-probability function: lmfit

Calculates the complete log-probability function combining prior and likelihood. The function minimizer() requires the objective function to return an array of residuals ‘chi’ of which it minimizes the sum of squares, ie

\[\begin{split}x &= \arg \min(\sum_{k} \chi_{k}^2) \\ &= \arg \min(\chi^2) \\ &= \arg \min(-2 \ln{P})\end{split}\]

The lmfit minimizer expects chi as an array, but defining \(\chi = [\sqrt{-2 \ln{P}/n_{k}}]\) so that \(x = \arg \min(-2 \mathrm{\ln{P}})\) seems to raise issues with error determination.

Parameters:

• p_step (dict) – contains the values of the variable parameters at current MCMC step

• x_val (array) – mock grid, required to call ln_prob_func_lmfit() with minimizer()

• fixed_args (dict) – contains parameters useful to the calculation of the function, in particular the values of parameters that are fixed.

Returns:

chi (array, float) – \(\chi\) values

gen_hrand_chain(par_med, epar_low, epar_high, n_throws)

PDF generator

Generates normal or half-normal distributions of a parameter.

Parameters:

TBD

Returns:

TBD

lmfit_fitting_method_check(method)

Method function

Returns string for the chi2 minimization method used.

Parameters:

method (str) – method string input by user.

Returns:

method_str (str) – method string which can be output.

init_fit(fit_dic, fixed_args, p_start, model_par_names, model_par_units)

Fit initialization

Initializes lmfit, MCMC, and nested sampling.

Parameters:

TBD

Returns:

TBD

call_lmfit(p_use, xtofit, ytofit, covtofit, f_use, method='leastsq', maxfev=None, xtol=1e-07, ftol=1e-07, verbose=False, fixed_args=None, show_correl=False, fit_dic=None)

Wrapper to lmfit

Runs lmfit minimizer and outputs results and merit values.

Parameters:

TBD

Returns:

TBD

call_MCMC(run_mode, nthreads, fixed_args, fit_dic, run_name='', verbose=True, save_raw=True)

Wrapper to MCMC

Runs emcee and outputs results and merit values.

Parameters:

TBD

Returns:

TBD

call_NS(run_mode, nthreads, fixed_args, fit_dic, run_name='', verbose=True, save_raw=True)

Wrapper to Nested Sampling

Runs dynesty and outputs results and merit values.

Parameters:

TBD

Returns:

TBD

fit_merit(mode, p_final_in, fixed_args, fit_dic, verbose, verb_shift='')

Post-proc: model merit and parameters

Calculates, prints, and saves merit indicators of the best-fit model, as well as best-fit values and confidence intervals for the original and derived parameters.

Parameters:

TBD

Returns:

TBD

compute_Hessian(params, func, args, kwargs, epsilon=1e-05)

Compute the Hessian matrix of a function using finite differences

Parameters:

• func – The function whose Hessian is to be computed. It should accept a Parameters object.

• params – The lmfit.Parameters object.

• epsilon – The small perturbation for finite differences (default: 1e-5).

• args – additional arguments required by the function used to compute the Hessian.

• kwargs – additional keyword parameters required by the function used to compute the Hessian.

Returns:

hessian_matrix – The Hessian matrix.

MCMC_corr_length(fit_dic, max_corr_length, nthreads, var_par_list, merged_chain, istart, iend, verbose=False)

MCMC post-proc: correlation length

Calculates correlation length of each fitted parameter using MCMC chains.

Parameters:

TBD

Returns:

TBD

sub_MCMC_corr_length(pix_shift, d_par_di, d_par, idx_di)

Chain correlation length

Calculates correlation length over a given parameter chain.

Parameters:

TBD

Returns:

TBD

parallel_sub_MCMC_corr_length(func_input, nthreads, n_elem, y_inputs, common_args)

Multithreading routine for sub_MCMC_corr_length().

Parameters:

• func_input (function) – multi-threaded function

• nthreads (int) – number of threads

• n_elem (int) – number of elements to thread

• y_inputs (list) – threadable function inputs

• common_args (tuple) – common function inputs

Returns:

y_output (None or specific to func_input) – function outputs

MCMC_thin_chains(corr_length, merged_chain)

MCMC post-proc: thinning

Thins chains based on their correlation length.

Parameters:

TBD

Returns:

TBD

MCMC_GR_stat(chains)

MCMC post-proc: Gelman-Rubin statistic

Calculates the Gelman-Rubin statistic for an ensemble of chains, following the implementation of Vats & Knudson 2020. In particular, we follow their approach of using batch means estimators and distinguishing two cases: univariate and multivariate MCMC runs. In practice, GR < 1.1 is used to declare convergence of chains.

Parameters:

chains (array) – three-dimensional array of the chains from an MCMC run.

Returns:

GR (float) – Gelman-Rubin statistic.

MCMC_retrieve_sample(fixed_args, fix_par_list, exp_par_list, iexp_par_list, ifix_par_list, par_names, fixed_par_val, calc_envMCMC, merged_chain, n_free, nsteps_final_merged, p_best_in, var_par_list, ivar_par_list, calc_sampMCMC, linked_par_expr, fit_dic, st_samp, end_samp, n_samp)

MCMC post-proc: sampling

Retrieve MCMC samples randomy or within 1 sigma from the best fit.

Parameters:

TBD

Returns:

TBD

MCMC_HDI(chain_par, nbins_par, dbins_par, bw_fact, frac_search, HDI_interv_par, HDI_interv_txt_par, HDI_sig_txt_par, med_par, use_arviz=False)

MCMC post-proc: HDI intervals

Calculates Highest Density Intervals of fitted MCMC parameters.

Parameters:

TBD

Returns:

TBD

prep_MCMC_HDI(dbin_par, dens_par, frac_search)

MCMC post-proc: HDI intervals initialization

Preliminary analysis of sample to prepare HDI calculations.

Parameters:

TBD

Returns:

TBD

PDF_hist(chain_par, nbins_par, dbins_par)

Histogram-based PDF

Calculates sample distribution as an histogram with manual settings.

Parameters:

TBD

Returns:

TBD

PDF_smooth(chain_par, bw_fact)

Smoothed PDF

Calculates sample distribution as a smoothed density profile using Gaussian kernels.

Parameters:

TBD

Returns:

TBD

quantile(x, q, weights=None)

MCMC post-proc: quantiles

Compute sample quantiles with support for weighted samples.

Note

When weights is None, this method simply calls numpy’s percentile function with the values of q multiplied by 100.

Parameters:

• x (array, float) – the samples.

• q (array, float) – the list of quantiles to compute. These should all be in the range [0, 1].

• weights (array, float) – an optional weight corresponding to each sample.

Returns:

quantiles (array, float) – the sample quantiles computed at q.

Raises:

ValueError – For invalid quantiles; q not in [0, 1] or dimension mismatch between x and weights.

MCMC_estimates(merged_chain, fixed_args, fit_dic, verbose=True, calc_quant=True, verb_shift='')

MCMC post-proc: best fit

Calculates best estimates and confidence intervals for fitted MCMC parameters.

Parameters:

TBD

Returns:

TBD

postMCMCwrapper_1(fit_dic, fixed_args, walker_chains, step_outputs, nthreads, par_names, verbose=True, verb_shift='')

MCMC post-proc: raw chains

Processes and analyzes MCMC chains of original parameters. Returns :

• best-fit parameters for model calculation

• 1-sigma and envelope samples for plot

• plot of model parameter chains

• save file

Parameters:

TBD

Returns:

TBD

postMCMCwrapper_2(fit_dic, fixed_args, merged_chain, sim_points=None)

MCMC post-proc: modified chains

Analyze MCMC chains of modified parameters.

Parameters:

TBD

Returns:

TBD

MCMC_plot_chains(save_mode, save_dir_MCMC, var_par_list, var_par_names, chain, burnt_chains, nsteps, nsteps_pb_walk, nwalkers, nburn, keep_chain, low_thresh_par_val, high_thresh_par_val, exclu_walk_autom, verbose=True, verb_shift='')

MCMC post-proc: walker chains plot

Plots the chains for each fitted parameter over all walkers.

Parameters:

TBD

Returns:

TBD

MCMC_plot_chains_chi2(fit_dic, chain, keep_chain, fixed_args, verbose=True, verb_shift='')

MCMC post-proc: walker chains’ chi2 plot

Plots the chi2 values for the chain of each walker.

Parameters:

TBD

Returns:

TBD

MCMC_plot_merged_chains(save_mode, save_dir_MCMC, var_par_list, var_par_names, merged_chain, nsteps_final_merged, verbose=True, verb_shift='')

MCMC post-proc: merged chains plot

Plots the cleaned, merged chains from all workers for each fitted parameter.

Parameters:

TBD

Returns:

TBD

MCMC_corner_plot(mode, save_mode, save_name, save_dir_MCMC, xs, HDI_interv, sim_points=None, labels_raw=None, labels=None, truths=None, truth_color='#4682b4', bins_1D_par=20, bins_2D_par=20, quantiles=[0.15865525393145702, 0.841344746068543], plot1s_1D=True, plot_HDI=False, color_1D_quant='darkorange', color_1D_HDI='green', levels=(0.39346934028, 0.86466471, 0.988891003), plot_contours=True, color_levels='black', use_math_text=True, range_par=None, smooth1d=None, smooth2D=None, weights=None, color='k', label_kwargs=None, tick_kwargs=None, show_titles=False, title_fmt='.2f', title_kwargs=None, scale_hist=False, verbose=False, fig=None, major_int=None, minor_int=None, max_n_ticks=5, top_ticks=False, hist_kwargs=None, **hist2d_kwargs)

MCMC post-proc: corner plot

Plots correlation diagram, showing the projections of a data set in a multi-dimensional space. kwargs are passed to MCMC_corner_plot_hist2d() or used for matplotlib styling. If mode = ‘sims’ the plot is used to display density histograms of simulated points, rather than corner plot of MCMC samples

Parameters:

• mode (str) – use of plot

• save_mode (str) – extension of the figure (png, pdf, jpg)

• save_dir_MCMC (str) – path of the directory in which the figure is saved

• xs (array, float) – Samples. This should be a 1- or 2-dimensional array with dimensions [nsamples, ndim]. For a 1-D array this results in a simple histogram. For a 2-D array, the zeroth axis is the list of samples and the next axis are the dimensions of the space.

• HDI_interv (array, object) – HDI intervals for each parameter

• sim_points (array, float) – model points. This should be a 1- or 2-dimensional array with dimensions [npoints, ndim].

• labels_raw (list, str) – names of variable parameters, as used in the model

• labels (list, str) – names of variable fitted parameters, as used in the plots. If xs is a pandas.DataFrame, labels will default to column names.

• truths (array, float) – a list of reference values to indicate on the plots. Individual values can be omitted by using None. Typically the best-fit values

• truth_color (str) – a matplotlib style color for the truths makers

• bins_1D_par (int or dict) – number of bins in the 1D histogram ranges (default 20) if int, defines bins for all parameters if dict, defines bins for parameters set as keys

• bins_2D_par (int or dict) – same as bins_1D_par for the 2D histograms

• quantiles (list, float) – x-sigma confidence intervals around the median for the 1D histogram default 1 and 2-sigma

• plot1s_1D (bool) – condition to plot 1D confidence intervals

• plot_HDI (bool) – condition to plot HDI (if HDI_interv) is defined

• color_1D_HDI (str) – matplotlib style color for quantiles.

• color_1D_quant (str) – matplotlib style color for HDIs.

• levels (tuple) – sigma contours for the 2D histograms, defined as (1-np.exp(-0.5*(x sigma)**2.),) default 1, 2, and 3 sigma

• plot_contours (bool) – draw contours for dense regions of the 2D histograms

• color_levels (str) – matplotlib style color for plot_contours

• use_math_text (bool) – if true, then axis tick labels for very large or small exponents will be displayed as powers of 10 rather than using e

• range_par (list or dict) – each element is either a length 2 tuple containing lower and upper bounds, or a float in (0., 1.) giving the fraction of samples to include in bounds, e.g., [(0.,10.), (1.,5), 0.999, etc.]. If a fraction, the bounds are chosen to be equal-tailed.

• smooth1d (float or list of float) – standard deviation for Gaussian kernel passed to scipy.ndimage.gaussian_filter to smooth the 2-D and 1-D histograms respectively. If None (default), no smoothing is applied. If list, each element is associated with a parameter

• smooth2D (float or list of float) – standard deviation for Gaussian kernel passed to scipy.ndimage.gaussian_filter to smooth the 2-D and 1-D histograms respectively. If None (default), no smoothing is applied. If list, each element is associated with a parameter

• weights (array, float) – weight of each sample. If None (default), samples are given equal weight.

• color (str) – A matplotlib style color for all histograms.

• label_kwargs (dict) – any extra keyword arguments to send to the set_xlabel and set_ylabel methods.

• tick_kwargs (dict) – any extra keyword arguments to send to the tick_params methods.

• show_titles (bool) – displays a title above each 1-D histogram showing the 0.5 quantile with the upper and lower errors supplied by the quantiles argument.

• title_fmt (str) – the format string for the quantiles given in titles. If you explicitly set show_titles=True and title_fmt=None, the labels will be shown as the titles. (default: .2f)

• title_kwargs (dict) – any extra keyword arguments to send to the set_title command

• scale_hist (bool) – scale the 1-D histograms in such a way that the zero line is visible

• verbose (bool) – if true, print quantile and HDI values

• fig (matplotlib.Figure) – overplot onto the provided figure object

• major_int (list) – list of major/minor tick intervals for each parameter. Some elements can be set to None, in which case max_n_ticks is used

• minor_int (list) – list of major/minor tick intervals for each parameter. Some elements can be set to None, in which case max_n_ticks is used

• max_n_ticks (int) – maximum number of ticks to try to use

• top_ticks (bool) – if true, label the top ticks of each axis

• hist_kwargs (dict) – any extra keyword arguments to send to the 1-D histogram plots.

• **hist2d_kwargs – any remaining keyword arguments are sent to corner.hist2d to generate the 2-D histogram plots

Returns:

None

MCMC_corner_plot_hist2d(mode, x, y, i, j, bins_2D=[20, 20], range_par=None, weights=None, levels=None, smooth=None, ax=None, color=None, plot_datapoints=True, plot_density=True, plot_contours=True, no_fill_contours=False, fill_contours=False, contour_kwargs=None, contourf_kwargs=None, data_kwargs=None, color_levels='black', sim_points=None, **kwargs)

MCMC post-proc: 2-D histograms

Plots 2-D histograms of samples for correlation diagram

Parameters:

• x (array, float) – The samples.

• y (array, float) – The samples.

• levels (array, float) – The contour levels to draw.

• ax (matplotlib.Axes) – A axes instance on which to add the 2-D histogram.

• plot_datapoints (bool) – Draw the individual data points.

• plot_density (bool) – Draw the density colormap.

• plot_contours (bool) – Draw the contours.

• no_fill_contours (bool) – Add no filling at all to the contours (unlike setting fill_contours=False, which still adds a white fill at the densest points).

• fill_contours (bool) – Fill the contours.

• contour_kwargs (dict) – Any additional keyword arguments to pass to the contour method.

• contourf_kwargs (dict) – Any additional keyword arguments to pass to the contourf method.

• data_kwargs (dict) – Any additional keyword arguments to pass to the plot method when adding the individual data points.

Returns:

None