BASTA auxiliary functions

Plotting functions

Production of corner plots.

Modified from a fork of https://github.com/dfm/corner.py . Original code: Copyright (c) 2013-2020 Daniel Foreman-Mackey Full license: https://github.com/dfm/corner.py/blob/main/LICENSE

This modified version:

• Add the observed quantities to the corner plots

• Colours for the plots

• Add KDE to non-contour panels

• Cleaned

plot_corner.corner(xs, smooth=None, smooth1d='kde', labels=None, label_kwargs={'size': 12}, show_titles=False, title_fmt='.3f', title_kwargs={'size': 12}, truth_color='#4682b4', scale_hist=False, quantiles=None, max_n_ticks=5, use_math_text=False, reverse=False, plotin=None, plotout=None, autobins=True, binrule_fallback='scott', uncert='quantiles', kde_points=250, kde_method='silverman', nameinplot=False, **hist2d_kwargs)

Make a corner plot showing the projections of a data set in a multi-dimensional space. kwargs are passed to hist2d() or used for matplotlib styling.

Parameters:

• xs (array_like[nsamples, ndim]) – The samples. This should be a 1- or 2-dimensional array. 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.

• smooth (float, optional) – The standard deviation for Gaussian kernel passed to scipy.ndimage.gaussian_filter to smooth the 2-D histograms. If None (default), no smoothing is applied.

• smooth1d (str or float, optional) – If “kde”, a Kernel Density Estimate (KDE) is used in the 1D histograms. Otherwise, as smooth above, but for the 1D histograms.

• labels (None or iterable (ndim,), optional) – A list of names for the dimensions.

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

• show_titles (bool, optional) – 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 (string, optional) – 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, optional) – Any extra keyword arguments to send to the set_title command.

• truth_color (str or dict, optional) – A matplotlib style color for the truths makers or a dict with the colors with keys being the labels.

• scale_hist (bool, optional) – Should the 1-D histograms be scaled in such a way that the zero line is visible?

• quantiles (iterable, optional) – A list of fractional quantiles to show on the 1-D histograms as vertical dashed lines.

• max_n_ticks (int, optional) – Maximum number of ticks to try to use

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

• reverse (bool, optional) – If true, plot the corner plot starting in the upper-right corner instead of the usual bottom-left corner

• plotin (iterable (ndim,), optional) – A list of reference input values to indicate on the plots.

• plotout (iterable (ndim,), optional) – A list of reference output values to indicate on the plots.

• autobins (bool or int or array_like[ndim,] optional) – If True, automatically determine bin edges. Otherwise, the number of bins to use in histograms, either as a fixed value for all dimensions, or as a list of integers for each dimension.

• binrule_fallback (str, optional) – In case auto-binning fails for the posterior distribution (usually due to too many zeros, which causes a memory leak), use this rule for posterior binning instead.

• uncert (str, optional) – If uncertainties are given in terms of ‘quantiles’ or ‘std’ (standard deviation), included here to change formatting when reporting inferred quantities in titles.

• kde_points (float, optional) – Number of points to sample the KDE on. The higher number of points, the smoother the KDE, but the longer computation time.

• kde_method (str, optional) – Method used to select the bandwidth in the gaussian KDE. Passed directly to the routine in SciPy. Default is Scott’s rule.

• nameinplot (str, bool) – Star identifier if it is to be included in the figure.

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

plot_corner.hist2d(x, y, bins=20, prange=None, weights=None, levels=None, smooth=None, ax=None, color=None, plot_datapoints=True, plot_density=True, plot_contours=True, no_fill_contours=True, fill_contours=True, contour_kwargs=None, contourf_kwargs=None, data_kwargs=None, **kwargs)

Plot a 2-D histogram of samples.

Parameters:

• x (array_like[nsamples,]) – The samples.

• y (array_like[nsamples,]) – The samples.

• levels (array_like) – 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.

Production of interpolation plots

plot_interp.across_debug(grid, outfile, basepath, basevar, inttrack, envtracks, selmods, outname)

If run with the –debug option, this produces a plot for each interpolated track, comparing the interpolated track to the enveloping tracks.

Parameters:

• grid (h5py file) – Handle of original grid

• outfile (h5py file) – Handle of output grid

• basepath (str) – Base path to access tracks/isochrones in grid

• basevar (str) – Base parameter used for interpolation to map tracks/isochrones along

• inttrack (str) – Name (with path) of interpolated track/isochrone in outfile

• envtracks (str) – Name of enveloping tracks in grid used for interpolated track/isochrone

• selmods (dict) – Selectedmodels of enveloping tracks, to show what models were used for interpolation

• outname (str) – Name and path of outputted plots

plot_interp.base_corner(baseparams, base, newbase, tri, sobol=1.0, outbasename='')

Plots the new vs. old base of across interpolation, as long as dim(base) > 1, and produces a corner plot for dim(base) > 2.

Parameters:

• baseparams (dict) – Parameters forming the base of the grid, and their required resolution.

• base (array) – Old base, in list form with each column corresponding to a different base parameter, and each row corresponding to a given point (track/isochrone).

• newbase (array) – Same as base, but with the newly determined values for across interpolation.

• tri (object) – Triangulation of the old base.

• sobol (float) – Number of points increase factor.

• outbasename (str, optional) – If set, it is the name and location of where to put the figure. If not given, it won’t produce the figure.

Returns:

success (bool) – True of False of whether the figure has been produced

Production of Kiel diagrams

plot_kiel.kiel(Grid, selectedmodels, fitparams, inputparams, lp_interval, feh_interval, Teffout, loggout, gridtype, nameinplot=False, debug=False, experimental=False, validationmode=False, color_by_likelihood=False)

Make a Kiel diagram of the relevant tracks/isochrones, where fitted parameters within their given uncertainties are marked on the tracks.

The plotted tracks/isochrones are chosen as the tracks/isochrones with non-zero likelihood with mass/age within the 16th and 84th percenttile, and if [Fe/H] or [M/H] is fitted, within the given uncertainty. If they are not fitted, they are instead also chosen as the ones within the 16th and 84th percentile.

They are also chosen to be within the fitted evolutionary constants, e.g. alphaMLT and overshooting. See list ‘constants’ for full list of fitting parameters.

Parameters:

• Grid (hdf5 object) – The already loaded grid, containing the tracks/isochrones.

• selectedmodels (dict) – Contains information on all models with a non-zero likelihood.

• fitparams (dict) – A copy of the fitparams with grid-scaled frequency parameters.

• inputparams (dict) – All relevant input information about the fit.

• lp_interval (list) – 16th and 84th percentile of the library parameter, mass for tracks and age for isochrones.

• feh_interval (list) – 16th and 84th quantile of [Fe/H], for determination of plotted tracks/isochrones.

• Teffout (array) – Array with median, min, and max effective temperature.

• loggout (array) – Array with median, min, and max logg.

• gridtype (str) – Type of the grid (as read from the grid in bastamain) containing either ‘tracks’ or ‘isochrones’.

• nameinplot (str or bool) – Star identifier if it is to be included in the figure

• debug (bool, optional) – Debug flag.

• experimental (bool, optional) – If True, experimental features will be used in run.

• validationmode (bool, optional) – If True, style the plots as required for validation runs

Returns:

fig (figure canvas) – Kiel diagram

plot_kiel.plot_param(Grid, ax, track, all_segments, label, color)

Function for plotting the parameter interval in the Kiel diagram

Parameters:

• Grid (hdf5 object) – The already loaded grid, containing the tracks/isochrones

• ax (AxesSubplot object) – Axis in which to plot

• track (str) – Path for the current track/isochrone in the Gridfile

• all_segments (list) – The indeces in the track/isochrone where the parameter is within the limit in fitparams

• label (str) – The label desired for the legend, is ‘_nolegend_’ if it has already been added to the plot

• color (string) – The designated plotting color for the parameter, see ‘constants.py’

Production of asteroseismic plots

plot_seismic.confidence_ellipse(mean_x, std_x, mean_y, std_y, cov, ax, facecolor='none', **kwargs)

Create a plot of the covariance confidence ellipse of x and y.

Parameters:

• mean_x (float) – Mean of input x

• std_x (float) – Standard deviation of input x

• mean_y (float) – Mean of input y

• std_y (float) – Standard deviation of input y

• cov (float) – Covariance of x and y

• ax (matplotlib.axes.Axes) – Axes object to draw the ellipse into.

• **kwargs – Forwarded to ~matplotlib.patches.Ellipse

Returns:

matplotlib.patches.Ellipse

plot_seismic.correlation_map(fittype, obsfreqdata, output, obskey=None)

Routine for plotting a correlation map of the plotted ratios

Parameters:

• fittype (str) – The type of frequency product (individual, ratios, epsilon differences) for which to to the correlation map of.

• obsfreqdata (dict) – All necessary frequency related data from observations.

• output (str) – Name and path to output figure.

• obskey (array, optional) – Contains radial order and degree of frequencies, used if plotting for individual frequencies.

plot_seismic.echelle(selectedmodels, Grid, obs, obskey, mod=None, modkey=None, dnu=None, join=None, joinkeys=False, coeffs=None, scalnu=None, freqcor='BG14', pair=False, duplicate=False, output=None)

Echelle diagram. It is possible to either make a single Echelle diagram or plot it twice making patterns across the moduli-limit easier to see.

Parameters:

• selectedmodels (dict) – Contains information on all models with a non-zero likelihood.

• Grid (hdf5 object) – The already loaded grid, containing the tracks/isochrones.

• obs (array or None) – Array of observed modes.

• obskey (array or None) – Array of mode identification observed modes.

• mod (array or None) – Array of modes in a given model. If None, mod will be found from the most likely model in selectedmodels.

• modkey (array or None) – Array of mode identification of modes from the model. If None, modkey will be found from the most likely model in selectedmodels.

• dnu (float or None) – The large frequency separation. If None, dnufit will be used.

• join (array or None) – Array containing the matched observed and modelled modes. If None, this information is not added to the plot.

• joinkeys (array or None) – Array containing the mode identification of the matched observed and modelled modes. If None, this information is not added to the plot.

• coeffs (array or None) – Coefficients for the near-surface frequency correction specified in freqcor. If None, the frequencies on the plot will not be corrected.

• scalnu (float or None) – Value used to scale frequencies in frequencies correction. numax is often used.

• freqcor (str {‘None’, ‘HK08’, ‘BG14’, ‘cubicBG14’}) – Flag determining the frequency correction.

• pair (bool) – Flag determining whether to link matched observed and modelled frequencies.

• duplicate (bool) – Flag determining whether to plot two echelle diagrams next to one another.

• output (str or None) – Filename for saving the figure.

plot_seismic.epsilon_difference_components_diagram(mod, modkey, moddnu, obs, obskey, dnudata, obsfreqdata, obsfreqmeta, output)

Full comparison figure of observed and best-fit model epsilon differences, with individual epsilons and correlation map.

Parameters:

• mod (array) – Array of frequency modes in best-fit model.

• modkey (array) – Array of mode identification of modes in the best-fit model.

• moddnu (float) – Average large frequency separation (dnufit) of best-fit model.

• obs (array) – Array of observed frequency modes.

• obskey (array) – Array of mode identification of observed frequency modes.

• dnudata (float) – Inputted average large frequency separation (dnu) of observations.

• obsfreqdata (dict) – Requested frequency-dependent data such as glitches, ratios, and epsilon difference. It also contains the covariance matrix and its inverse of the individual frequency modes. The keys correspond to the science case, e.g. r01a, `glitch, or e012. Inside each case, you find the data (data), the covariance matrix (cov), and its inverse (covinv).

• obsfreqmeta (dict) – The requested information about which frequency products to fit or plot, unpacked for easier access later.

• output (str) – Name and path of output plotfile.

plot_seismic.epsilon_difference_diagram(mod, modkey, moddnu, sequence, obsfreqdata, output)

Full comparison figure of observed and best-fit model epsilon differences, with individual epsilons and correlation map.

Parameters:

• mod (array) – Array of frequency modes in best-fit model.

• modkey (array) – Array of mode identification of modes in the best-fit model.

• moddnu (float) – Average large frequency separation (dnufit) of best-fit model.

• sequence (str) – The sequence to be plotted

• obsfreqdata (dict) – Requested frequency-dependent data such as glitches, ratios, and epsilon difference. It also contains the covariance matrix and its inverse of the individual frequency modes. The keys correspond to the science case, e.g. r01a, `glitch, or e012. Inside each case, you find the data (data), the covariance matrix (cov), and its inverse (covinv).

• obsfreqmeta (dict) – The requested information about which frequency products to fit or plot, unpacked for easier access later.

• output (str) – Name and path of output plotfile.

plot_seismic.ratioplot(obsfreqdata, joinkeys, join, modkey, mod, ratiotype, output=None, threepoint=False, interp_ratios=True)

Plot frequency ratios.

Parameters:

• obsfreqdata (dict) – Requested frequency-dependent data such as glitches, ratios, and epsilon difference. It also contains the covariance matrix and its inverse of the individual frequency modes. The keys correspond to the science case, e.g. r01a, `glitch, or e012. Inside each case, you find the data (data), the covariance matrix (cov), and its inverse (covinv).

• joinkeys (array) – Array containing the mode identification of the matched observed and modelled modes.

• join (array) – Array containing the matched observed and modelled modes.

• modkey (array) – Array containing the mode identification of the modelled modes.

• mod (array) – Array containing the modelled modes.

• ratiotype (str) – Key for the ratio sequence to be plotted (e.g. r01, r02, r012)

• output (str or None, optional) – Filename for saving the plot.

• nonewfig (bool, optional) – If True, this creates a new canvas. Otherwise, the plot is added to the existing canvas.

• threepoint (bool) – If True, use three point definition of r01 and r10 ratios instead of default five point definition.

• interp_ratios (bool) – If True (default), plot how the model ratios are linearly interpolated to the frequencies of the observed ratios, in order to compare the sequences at the same frequencies.

Processing tools

Make an input file for BASTA in XML format. Template version.

create_inputfile.define_input(define_io, define_fit, define_output, define_plots, define_intpol)

Define user input for BASTA. Will fill the dictionaries with required information and pass it on to the XML-generation routines.

PLEASE MODIFY THINGS IN THIS FUNCTION TO SUIT YOUR NEEDS

Routines to download assets

downloader.get_basta_dir()

Helper to obtain location of BASTA root directory

downloader.get_dustmaps(dustpath=None, skip=False)

Configure dustmaps and download if necessary

Parameters:

• dustpath (str, optional) – Where to store/find dustmaps

• skip (bool, optional) – Skip the download of the dustmaps

Returns:

None

downloader.get_grid(case, gridpath=None)

Download a grid from the BASTAcode grid repository. Will be stored in the default location: BASTA/grids/ .

Parameters:

case (str) – Which grid to download. Possible value: “16CygA”, “validation”, “iso”.

Returns:

None

downloader.main()

Run the downloader

Preview the change in resolution and final distribution of tracks/isochrones for running BASTA with interpolation.

preview_interpolation.define_preview(define_input, define_along, define_across)

Define information for previewing an interpolation run. Fill the relevant dictionaries and pass it to the automatic routines. Full explanation of options is also given in create_inputfile.py, block 5.

preview_interpolation.determine_l0_spacing(grid, bpath, index, track)

Determine the separation of l=0 modes in the given track, and only for the modes that are continuous throughout the track. It currently differs from the full interpolation scheme, that also accounts for modes appearing and dissapearing within the subgrid, but works as an overview.

Parameters:

• grid (h5py file) – Input grid

• bpath (str) – Base path for accessing the tracks in the grid

• index (list) – Booleans of the indices in the track within the subgrid

• track (str) – Path to the track parameters

Returns:

diffs (list) – Absolute spacings between l=0 modes in the subgrid

preview_interpolation.test_across_interpolation(grid, selectedmodels, acopt, bpath='grid/', outname='across.png')

Runs a test of a set of input parameters for interpolation across in a grid

Parameters:

• gridname (h5py file) – Input grid

• selectedmodels (dict) – Selected models from the original grid, forming the subgrid

• acopt (dict) – The given options for across interpolation

• baseparams (list) – Parameters forming the base in the grid. If none provided, extract them from the grid as all varied parameters.

• bpath (str) – Base path to the tracks in the grid

• outname (str) – Name and destination of the outputted figure

Returns:

None

preview_interpolation.test_along_interpolation(grid, selectedmodels, alopt, bpath='grid/', outname='along.png')

Plot histograms of the distribution of spacing of the resolution parameter(s) along the tracks in the subgrid, in order to get and idea of the increase in resolution it will provide.

Parameters:

• grid (h5py file) – Input grid

• selectedmodels (dict) – Selected models from the original grid, forming the subgrid

• alopt (dict) – The given options for along interpolation

• bpath (str) – Location of tracks/isochrones in gridfile

• outname (str) – Name and destination of the outputted figure

Returns:

None

An example of how to extract information from a BASTA .json file.

IMPORTANT: Please run an example producing a json-file to run this tutorial!!

process_jsonfile.extract_from_json(jsonfile, gridfile, parameter)

Extract information from a BASTA json file.

During a fit, if “optionaloutputs” is True, a dump of the statistics for each star will be stored in a .json file. The grid used to perform the fit is required to obtain any useful information from the json-dump.

Parameters:

• jsonfile (str) – Path to the .json file from the BASTA fit

• gridfile (str) – Path to the grid used to compute the fit

• parameter (str) – The parameter values to extract (must be a valid name!)

Returns:

• parametervals (array_like) – Values of the given parameter for all models (with non-zero likelihood) in the grid

• loglikes (array_like) – The log(likelihood) of all models in the grid, excluding zero-likelihood models

• chi2 (array_like) – The chi**2 values of all models (with non-zero likelihood) in the grid

process_jsonfile.main()

An example of how to extract information from a BASTA .json file. Will be plotted as a simple histogram and as a KDE-representation (as BASTA uses for the corner plots). Uses the auxiliary functions above.

IMPORTANT: Please run the example in examples/xmlinput/{create_inputfile_json.py,

input_json.xml} or the template examples/{create_inputfile.py, input_myfit.xml} produce the input files required by this module!

Parameters:

None

Returns:

None

process_jsonfile.sample_posterior(vals, logys)

Computation of the posterior of a parameter by numerical sampling. Duplication of how it is performed in basta/process_output.py.

Parameters:

• vals (array_like) – Parameter values

• logys (array_like) – Corresponding log(likelihood)’s

Returns:

samples (array_like) – Samples of the posterior. Can be used to make the posterior distribution.