threeML.analysis_results module

class threeML.analysis_results.ANALYSIS_RESULTS(analysis_results)

Bases: FITSExtension

Represents the ANALYSIS_RESULTS extension of a FITS file encoding the results of an analysis

Parameters:

analysis_results (_AnalysisResults)

class threeML.analysis_results.ANALYSIS_RESULTS_HDF(analysis_results, hdf_obj)

Bases: object

class threeML.analysis_results.AnalysisResultsFITS(*analysis_results, **kwargs)

Bases: FITSFile

A FITS file for storing one or more results from 3ML analysis

class threeML.analysis_results.AnalysisResultsSet(results)

Bases: Sequence

A container for results which behaves like a list (but you cannot add/remove elements).

You can index (analysis_set[0]), iterate (for item in analysis_set) and measure with len()

characterize_sequence(name, data_tuple)

Characterize the sequence of these results. The provided data frame will be saved along with the results in the “SEQUENCE” extension to allow the interpretation of the results.

This method is completely general, and allow for a lot of flexibility.

If this is a binned analysis and you only want to save the lower and upper bound of the bins, use set_bins instead.

If you only want to associate one quantity for each entry, use set_x.

set_bins(name, lower_bounds, upper_bounds, unit=None)

Associate the provided bins with these results. These bins will be written in the SEQUENCE extension when saving these results to a FITS file

Parameters:

name – a name for these bins (for example, “time” or “energy”). Please use only letters and numbers

(no special characters) :param lower_bounds: :param upper_bounds: :param unit: unit for the boundaries (like “s” for seconds, or a astropy.units.Unit instance) :return:

set_x(name, x, unit=None)

Associate the provided x with these results. The values in x will be written in the SEQUENCE extension when saving these results to a FITS file.

Parameters:

name – a name for this sequence (for example, “time” or “energy”). Please use only letters and numbers

(no special characters) :param x: :param unit: unit for x (like “s” for seconds, or a astropy.units.Unit instance) :return:

write_to(filename, overwrite=False, as_hdf=False)

Write this set of results to a FITS file.

Parameters:

• filename – name for the output file

• overwrite – True or False

Returns:

None

class threeML.analysis_results.BayesianResults(optimized_model, samples, posterior_values, statistical_measures, log_probabilty)

Bases: _AnalysisResults

Store results of a Bayesian analysis (i.e., the samples) and allow for computation with them and “error propagation”

Parameters:

optimized_model – a Model instance with the MAP values of the parameters. A clone will be stored within

the class, so there is no need to clone it before hand :type optimized_model: astromodels.Model :param samples: the samples for the parameters :type samples: np.ndarray :param posterior_values: a dictionary containing the posterior values for the different datasets at the HPD :type posterior_values: dict

comparison_corner_plot(*other_fits, **kwargs)

Create a corner plot from many different fits which allow for co-plotting of parameters marginals.

Parameters:

• other_fits – other fitted results

• parameters – parameters to plot

• renamed_parameters – a python dictionary of parameters to rename. Useful when e.g. spectral indices in models have different names but you wish to compare them. Format is {‘old label’: ‘new label’}

• names – (optional) name for each chain first name is this chain followed by each added chain

• kwargs – chain consumer kwargs

Returns:

Returns:

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

corner_plot(renamed_parameters: Dict | None = None, components: List | None = None, **kwargs)

Produce the corner plot showing the marginal distributions in one and two directions.

Parameters:

• renamed_parameters – a python dictionary of parameters to rename. Useful when e.g. spectral indices in models have different names but you wish to compare them. Format is {‘old label’: ‘new label’}, where ‘old label’ is the full path of the parameter

• components – a python list of parameter paths to use in the corner plot

• kwargs – arguments to be passed to the corner function

Returns:

a matplotlib.figure instance

corner_plot_cc(parameters=None, renamed_parameters=None, **cc_kwargs)

Corner plots using chainconsumer which allows for nicer plotting of marginals see: https://samreay.github.io/ChainConsumer/chain_api.html#chainconsumer.ChainConsumer.configure for all options :param parameters: list of parameters to plot :param renamed_parameters: a python dictionary of parameters to rename.

Useful when e.g. spectral indices in models have different names but you wish to compare them. Format is {‘old label’: ‘new label’}

Parameters:

**cc_kwargs –

chainconsumer general keyword arguments

Return fig:

display(display_correlation=False, error_type='equal tail', cl=0.68)

static freedman_diaconis_rule(data)

Returns the number of bins from the Freedman-Diaconis rule for a histogram of the given data

Parameters:

data – an array of data

Returns:

the optimal number of bins

get_correlation_matrix()

Estimate the covariance matrix from the samples

Returns:

the correlation matrix

get_highest_density_posterior_interval(parameter, cl=0.68)

returns the highest density posterior interval for that parameter

Parameters:

• parameter_path – path of the parameter or parameter instance

• cl – credible interval to obtain

Returns:

(low bound, high bound)

get_median_fit_model()

Sets the model parameters to the mean of the marginal distributions

get_statistic_frame()

property log_probability

The log probability values

Returns:

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 list of matplotlib.figure instances

class threeML.analysis_results.MLEResults(optimized_model, covariance_matrix, likelihood_values, n_samples=5000, statistical_measures=None)

Bases: _AnalysisResults

Build the _AnalysisResults object starting from a covariance matrix.

Parameters:

optimized_model – best fit model

:type optimized_model:astromodels.Model :param covariance_matrix: :type covariance_matrix: np.ndarray :param likelihood_values: :type likelihood_values: dict :param n_samples: Number of samples to use :type n_samples: int :return: an _AnalysisResults instance

property covariance_matrix

Returns the covariance matrix.

Returns:

covariance matrix or None (if the class was built from samples. Use estimate_covariance_matrix in that case)

display(display_correlation=True, cl=0.68)

get_correlation_matrix()

Compute correlation matrix

Returns:

the correlation matrix

get_statistic_frame()

class threeML.analysis_results.SEQUENCE(name, data_tuple)

Bases: FITSExtension

Represents the SEQUENCE extension of a FITS file containing a set of results from a set of analysis

threeML.analysis_results.convert_fits_analysis_result_to_hdf(fits_result_file: str)

threeML.analysis_results.load_analysis_results(fits_file: str) → _AnalysisResults

Load the results of one or more analysis from a FITS file produced by 3ML

Parameters:

fits_file – path to the FITS file containing the results, as output by MLEResults or BayesianResults

Returns:

a new instance of either MLEResults or Bayesian results dending on the type of the input FITS file

threeML.analysis_results.load_analysis_results_hdf(hdf_file: str) → _AnalysisResults

Load the results of one or more analysis from a FITS file produced by 3ML

Parameters:

fits_file – path to the FITS file containing the results, as output by MLEResults or BayesianResults

Returns:

a new instance of either MLEResults or Bayesian results dending on the type of the input FITS file