threeML package

Subpackages

Submodules

threeML.analysis_results module

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

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)[source]: Bases: object

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

Bases: FITSFile

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

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

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

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)[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: Dict | None = None, components: List | None = 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
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)[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_median_fit_model()[source]: Sets the model parameters to the mean of the marginal distributions

get_statistic_frame()[source]

property log_probability

The log probability values

Returns:

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: _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: 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) → _AnalysisResults[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) → _AnalysisResults[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: str, nuisance_parameters: Dict[str, Parameter])[source]

Bases: object

exclude_from_fit(flag=False)[source]: This can be used to explude a plug in from the fit :param flag: True or Fase (default) :return:

abstract get_log_like() → float[source]: Return the value of the log-likelihood with the current values for the parameters

get_name() → str[source]

get_number_of_data_points() → int[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: str

Returns the name of this instance

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

property nuisance_parameters: Dict[str, Parameter]

Returns a dictionary containing the nuisance parameters for this dataset

Returns:: a dictionary

abstract set_model(likelihood_model_instance: Model)[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: Dict[str, Parameter]) → None[source]

threeML.random_variates module

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

Bases: 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

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