threeML package

Subpackages

Submodules

threeML.analysis_results module

class threeML.analysis_results.ANALYSIS_RESULTS(analysis_results)[source]

Bases: threeML.io.fits_file.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)[source]

Bases: object

class threeML.analysis_results.AnalysisResultsFITS(*analysis_results, **kwargs)[source]

Bases: threeML.io.fits_file.FITSFile

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

class threeML.analysis_results.AnalysisResultsSet(results)[source]

Bases: collections.abc.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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

Bases: threeML.analysis_results._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)[source]

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)[source]

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=None, **kwargs)[source]

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

  • kwargs – arguments to be passed to the corner function

Returns

a matplotlib.figure instance

corner_plot_cc(parameters=None, renamed_parameters=None, **cc_kwargs)[source]

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)[source]
static freedman_diaconis_rule(data)[source]

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()[source]

Estimate the covariance matrix from the samples

Returns

the correlation matrix

get_highest_density_posterior_interval(parameter, cl=0.68)[source]

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_statistic_frame()[source]
plot_chains(thin=None)[source]

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)[source]

Bases: threeML.analysis_results._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)[source]
get_correlation_matrix()[source]

Compute correlation matrix

Returns

the correlation matrix

get_statistic_frame()[source]
class threeML.analysis_results.SEQUENCE(name, data_tuple)[source]

Bases: threeML.io.fits_file.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)[source]
threeML.analysis_results.load_analysis_results(fits_file: str)[source]

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)[source]

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.data_list module

class threeML.data_list.DataList(*data_sets)[source]

Bases: object

A container for data sets. Can be accessed as a dictionary, with the [key] operator.

insert(dataset)[source]
keys()[source]
values()[source]

threeML.plugin_prototype module

Define the interface for a plugin class.

class threeML.plugin_prototype.PluginPrototype(name, nuisance_parameters)[source]

Bases: object

abstract get_log_like()[source]

Return the value of the log-likelihood with the current values for the parameters

get_name()[source]
get_number_of_data_points()[source]

This returns the number of data points that are used to evaluate the likelihood. For binned measurements, this is the number of active bins used in the fit. For unbinned measurements, this would be the number of photons/particles that are evaluated on the likelihood

abstract inner_fit()[source]

This is used for the profile likelihood. Keeping fixed all parameters in the LikelihoodModel, this method minimize the logLike over the remaining nuisance parameters, i.e., the parameters belonging only to the model for this particular detector. If there are no nuisance parameters, simply return the logLike value.

property name

Returns the name of this instance

Returns

a string (this is enforced to be a valid python identifier)

property nuisance_parameters

Returns a dictionary containing the nuisance parameters for this dataset

Returns

a dictionary

abstract set_model(likelihood_model_instance)[source]

Set the model to be used in the joint minimization. Must be a LikelihoodModel instance.

property tag

Gets/sets the tag for this instance, as (independent variable, start, [end])

update_nuisance_parameters(new_nuisance_parameters)[source]

threeML.random_variates module

class threeML.random_variates.RandomVariates(input_array, value=None)[source]

Bases: numpy.ndarray

A subclass of np.array which is meant to contain samples for one parameter. This class contains methods to easily compute properties for the parameter (errors and so on)

property average

Returns average value

equal_tail_interval(cl=0.68)[source]

Returns the equal tail interval, i.e., an interval centered on the median of the distribution with the same probability on the right and on the left of the mean.

If the distribution of the parameter is Gaussian and cl=0.68, this is equivalent to the 1 sigma confidence interval.

Parameters

cl – confidence level (0 < cl < 1)

Returns

(low_bound, hi_bound)

highest_posterior_density_interval(cl=0.68)[source]

Returns the Highest Posterior Density interval (HPD) for the parameter, for the given credibility level.

NOTE: the returned interval is the HPD only if the posterior is not multimodal. If it is multimodal, you should probably report the full posterior, not only an interval.

Parameters

cl – credibility level (0 < cl < 1)

Returns

(low_bound, hi_bound)

property median

Returns median value

property samples
property std

Returns sample std value

property value
property var

Returns sample variance value

threeML.version module

Module contents

threeML.get_available_plugins()[source]

Print a list of available plugins

Returns

threeML.is_module_importable(module_full_path)[source]
threeML.is_plugin_available(plugin)[source]

Test whether the plugin for the provided instrument is available

Parameters

plugin – the name of the plugin class

Returns

True or False