threeML.plugins package

Subpackages

• threeML.plugins.experimental package
  • Submodules
  • threeML.plugins.experimental.SherpaLike module
  • threeML.plugins.experimental.VERITASLike module
  • Module contents

Submodules

threeML.plugins.DispersionSpectrumLike module

class threeML.plugins.DispersionSpectrumLike.DispersionSpectrumLike(name: str, observation, background=None, background_exposure=None, verbose=True, tstart=None, tstop=None)

Bases: threeML.plugins.SpectrumLike.SpectrumLike

display_rsp()

Display the currently loaded full response matrix, i.e., RMF and ARF convolved :return:

classmethod from_function(name: str, source_function, response, source_errors=None, source_sys_errors=None, background_function=None, background_errors=None, background_sys_errors=None) → threeML.plugins.DispersionSpectrumLike.DispersionSpectrumLike

Construct a simulated spectrum from a given source function and (optional) background function. If source and/or background errors are not supplied, the likelihood is assumed to be Poisson.

Parameters

• name – simulated data set name

• source_function – astromodels function

• response – 3ML Instrument response

• source_errors – (optional) gaussian source errors

• source_sys_errors – (optional) systematic source errors

• background_function – (optional) astromodels background function

• background_errors – (optional) gaussian background errors

• background_sys_errors – (optional) background systematic errors

Returns

simulated DispersionSpectrumLike plugin

get_pha_files()

get_simulated_dataset(new_name=None, **kwargs)

Returns another DispersionSpectrumLike instance where data have been obtained by randomizing the current expectation from the model, as well as from the background (depending on the respective noise models)

Returns

a DispersionSpectrumLike simulated instance

property response

set_model(likelihoodModel)

Set the model to be used in the joint minimization.

set_model_integrate_method(method: str)

Change the integrate method for the model integration :param method: (str) which method should be used (simpson or trapz)

write_pha(filename: str, overwrite: bool = False, force_rsp_write: bool = False) → None

Writes the observation, background and (optional) rsp to PHAII fits files

Parameters

• filename – base file name to write out

• overwrite – if you would like to force overwriting of the files

• force_rsp_write – force the writing of an rsp even if not required

threeML.plugins.FermiLATLike module

threeML.plugins.FermipyLike module

class threeML.plugins.FermipyLike.FermipyLike(*args, **kwargs)

Bases: threeML.plugin_prototype.PluginPrototype

Plugin for the data of the Fermi Large Area Telescope, based on fermipy (http://fermipy.readthedocs.io/)

property configuration

Returns the loaded configuration

Returns

a dictionary containing the active configuration

static get_basic_config(evfile, scfile, ra, dec, emin=100.0, emax=100000.0, zmax=100.0, evclass=128, evtype=3, filter='DATA_QUAL>0 && LAT_CONFIG==1')

get_log_like()

Return the value of the log-likelihood with the current values for the parameters stored in the ModelManager instance

property gta

inner_fit()

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.

set_model(likelihood_model_instance)

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

threeML.plugins.HAWCLike module

threeML.plugins.OGIPLike module

class threeML.plugins.OGIPLike.OGIPLike(name: str, observation, background=None, response=None, arf_file=None, spectrum_number=None, verbose=True)

Bases: threeML.plugins.DispersionSpectrumLike.DispersionSpectrumLike

classmethod from_general_dispersion_spectrum(dispersion_like: threeML.plugins.DispersionSpectrumLike.DispersionSpectrumLike) → threeML.plugins.OGIPLike.OGIPLike

Build on OGIPLike from a dispersion like. This makes it easy to write a dispersion like to a pha file

Parameters

dispersion_like –

Returns

get_simulated_dataset(new_name: Optional[str] = None, **kwargs: dict) → threeML.plugins.OGIPLike.OGIPLike

Returns another OGIPLike instance where data have been obtained by randomizing the current expectation from the model, as well as from the background (depending on the respective noise models)

Parameters

• new_name – name of the simulated plugin

• kwargs – keywords to pass back up to parents

Returns

a DispersionSpectrumLike simulated instance

property grouping

write_pha(file_name: str, overwrite: bool = False, force_rsp_write: bool = False) → None

Create a pha file of the current pha selections

Parameters

• file_name – output file name (excluding extension)

• overwrite – overwrite the files

• force_rsp_write – for an rsp to be saved

Returns

None

threeML.plugins.PhotometryLike module

class threeML.plugins.PhotometryLike.BandNode(name, index, value, mask)

Bases: object

property off

Turn on or off the band. Use booleans, like: ‘p.off = True’ or ‘p.off = False’.

property on

Turn on or off the band. Use booleans, like: ‘p.on = True’ or ‘p.on = False’.

class threeML.plugins.PhotometryLike.PhotometryLike(name: str, filters: Union[speclite.filters.FilterSequence, speclite.filters.FilterResponse], observation: threeML.utils.photometry.photometric_observation.PhotometericObservation)

Bases: threeML.plugins.XYLike.XYLike

display_filters()

display the filter transmission curves

Returns

classmethod from_file(name: str, filters: Union[speclite.filters.FilterResponse, speclite.filters.FilterSequence], file_name: str)

Create the a PhotometryLike plugin from a saved HDF5 data file

Parameters

• name – plugin name

• filters – speclite filters

• file_name – name of the observation file

classmethod from_kwargs(name, filters, **kwargs)

Example:

grond = PhotometryLike.from_kwargs(‘GROND’,

filters=threeML_filter_library.ESO.GROND, g=(20.93,.23), r=(20.6,0.12), i=(20.4,.07), z=(20.3,.04), J=(20.0,.03), H=(19.8,.03), K=(19.7,.04))

Magnitudes and errors are entered as keyword arguments where the key is the filter name and the argument is a tuple containing the data. You can exclude data for individual filters and they will be ignored during the fit.

NOTE: PhotometryLike expects apparent AB magnitudes. Please calibrate your data to this system

Parameters

• name – plugin name

• filters – speclite filters

• kwargs – keyword args of band name and tuple(mag, mag error)

property magnitude_errors

property magnitudes

set_model(likelihood_model)

set the likelihood model :param likelihood_model: :return:

threeML.plugins.SpectrumLike module

class threeML.plugins.SpectrumLike.SpectrumLike

Bases: threeML.plugin_prototype.PluginPrototype

property area_ratio

Returns

ratio between source and background area

assign_to_source(source_name: str) → None

Assign these data to the given source (instead of to the sum of all sources, which is the default)

Parameters

source_name – name of the source (must be contained in the likelihood model)

Returns

none

property background_count_errors

Returns

the observed background count errors

property background_counts

Returns

the observed background counts

property background_exposure

Exposure of the background spectrum, if present

property background_noise_model

Sets/gets the noise model for the background spectrum

property background_plugin

property background_scale_factor

The background scale factor

Returns

property background_spectrum

property current_background_count_errors

property current_background_counts

property current_observed_count_errors

property current_observed_counts

property current_scaled_background_counts

display()

display_model(data_color: str = 'k', model_color: str = 'r', background_color: str = 'b', step: bool = True, show_data: bool = True, show_residuals: bool = True, ratio_residuals: bool = False, show_legend: bool = True, min_rate: Union[int, float] = 1e-99, model_label: Optional[str] = None, model_kwargs: Optional[dict] = None, data_kwargs: Optional[dict] = None, background_label: Optional[str] = None, background_kwargs: Optional[dict] = None, source_only: bool = True, show_background: bool = False, **kwargs) → threeML.io.plotting.data_residual_plot.ResidualPlot

Plot the current model with or without the data and the residuals. Multiple models can be plotted by supplying a previous axis to ‘model_subplot’.

Example usage:

fig = data.display_model()

fig2 = data2.display_model(model_subplot=fig.axes)

Parameters

• data_color – the color of the data

• model_color – the color of the model

• step – (bool) create a step count histogram or interpolate the model

• show_data – (bool) show_the data with the model

• show_residuals – (bool) shoe the residuals

• ratio_residuals – (bool) use model ratio instead of residuals

• show_legend – (bool) show legend

• min_rate – the minimum rate per bin

• model_label – (optional) the label to use for the model default is plugin name

• model_subplot – (optional) axis or list of axes to plot to

• model_kwargs – plotting kwargs affecting the plotting of the model

• data_kwargs – plotting kwargs affecting the plotting of the data and residuls

Returns

property energy_boundaries

Energy boundaries of channels currently in use (rebinned, if a rebinner is active)

Returns

(energy_min, energy_max)

property expected_model_rate

property exposure

Exposure of the source spectrum

property exposure_ratio

Returns

ratio between source and background exposure

fix_effective_area_correction(value: Union[int, float] = 1)

Fix the multiplicative factor (see use_effective_area_correction) to the provided value (default: 1)

Parameters

value – new value (default: 1, i.e., no correction)

Returns

classmethod from_background(name: str, spectrum_like, verbose: bool = True)

Extract a SpectrumLike plugin from the background of another SpectrumLike (or subclass) instance

Parameters

• name – name of the extracted_plugin

• spectrum_like – plugin with background to extract

• verbose – if the plugin should be verbose

Returns

SpectrumLike instance from the background

classmethod from_function(name: str, source_function, energy_min, energy_max, source_errors=None, source_sys_errors=None, background_function=None, background_errors=None, background_sys_errors=None, **kwargs)

Construct a simulated spectrum from a given source function and (optional) background function. If source and/or background errors are not supplied, the likelihood is assumed to be Poisson.

Parameters

• name – simulkated data set name

• source_function – astromodels function

• energy_min – array of low energy bin edges

• energy_max – array of high energy bin edges

• source_errors – (optional) gaussian source errors

• source_sys_errors – (optional) systematic source errors

• background_function – (optional) astromodels background function

• background_errors – (optional) gaussian background errors

• background_sys_errors – (optional) background systematic errors

Returns

simulated SpectrumLike plugin

get_background_model(without_mask: bool = False)

The background model integrated over the energy bins. Note that it only returns the model for the currently active channels/measurements

Returns

array of folded model

get_log_like(precalc_fluxes: Optional[numpy.array] = None)

Calls the likelihood from the pre-setup likelihood evaluator that “knows” of the currently set noise models

Returns

get_model(precalc_fluxes: Optional[numpy.array] = None)

The model integrated over the energy bins. Note that it only returns the model for the currently active channels/measurements

Returns

array of folded model

get_number_of_data_points()

returns the number of active data bins :return:

get_pha_files() → dict

get_simulated_dataset(new_name=None, **kwargs)

Returns another Binned instance where data have been obtained by randomizing the current expectation from the model, as well as from the background (depending on the respective noise models)

Returns

an BinnedSpectrum or child instance

inner_fit()

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 likelihood_model

property mask

The channel mask :return:

property n_data_points

property observation_noise_model

Sets/gets the noise model for the background spectrum

property observed_count_errors

Returns

the observed counts errors

property observed_counts

Returns

the observed counts

property observed_spectrum

property quality

rebin_on_background(min_number_of_counts)

Rebin the spectrum guaranteeing the provided minimum number of counts in each background bin. This is usually required for spectra with very few background counts to make the Poisson profile likelihood meaningful. Of course this is not relevant if you treat the background as ideal, nor if the background spectrum has Gaussian errors.

The observed spectrum will be rebinned in the same fashion as the background spectrum.

To neutralize this completely, use “remove_rebinning”

Parameters

min_number_of_counts – the minimum number of counts in each bin

Returns

none

rebin_on_source(min_number_of_counts)

Rebin the spectrum guaranteeing the provided minimum number of counts in each source bin.

To neutralize this completely, use “remove_rebinning”

Parameters

min_number_of_counts – the minimum number of counts in each bin

Returns

none

remove_rebinning()

Remove the rebinning scheme set with rebin_on_background.

Returns

property scale_factor

Ratio between the source and the background exposure and area

Returns

set_active_measurements(*args, **kwargs) → None

Set the measurements to be used during the analysis. Use as many ranges as you need, and you can specify either energies or channels to be used.

NOTE to Xspec users: while XSpec uses integers and floats to distinguish between energies and channels specifications, 3ML does not, as it would be error-prone when writing scripts. Read the following documentation to know how to achieve the same functionality.

• Energy selections:

They are specified as ‘emin-emax’. Energies are in keV. Example:

set_active_measurements(‘10-12.5’,’56.0-100.0’)

which will set the energy range 10-12.5 keV and 56-100 keV to be used in the analysis. Note that there is no difference in saying 10 or 10.0.

• Channel selections:

They are specified as ‘c[channel min]-c[channel max]’. Example:

set_active_measurements(‘c10-c12’,’c56-c100’)

This will set channels 10-12 and 56-100 as active channels to be used in the analysis

• Mixed channel and energy selections:

You can also specify mixed energy/channel selections, for example to go from 0.2 keV to channel 20 and from channel 50 to 10 keV:

set_active_measurements(‘0.2-c10’,’c50-10’)

• Use all measurements (i.e., reset to initial state):

Use ‘all’ to select all measurements, as in:

set_active_measurements(‘all’)

Use ‘reset’ to return to native PHA quality from file, as in:

set_active_measurements(‘reset’)

• Exclude measurements:

Excluding measurements work as selecting measurements, but with the “exclude” keyword set to the energies and/or channels to be excluded. To exclude between channel 10 and 20 keV and 50 keV to channel 120 do:

set_active_measurements(exclude=[“c10-20”, “50-c120”])

• Select and exclude:

Call this method more than once if you need to select and exclude. For example, to select between 0.2 keV and channel 10, but exclude channel 30-50 and energy , do:

set_active_measurements(“0.2-c10”,exclude=[“c30-c50”])

• Using native PHA quality:

To simply add or exclude channels from the native PHA, one can use the use_quailty option:

set_active_measurements(

“0.2-c10”,exclude=[“c30-c50”], use_quality=True)

This translates to including the channels from 0.2 keV - channel 10, exluding channels 30-50 and any channels flagged BAD in the PHA file will also be excluded.

Parameters

• args –

• exclude – (list) exclude the provided channel/energy ranges

• use_quality – (bool) use the native quality on the PHA file (default=False)

Returns

set_background_integrate_method(method: str)

Change the integrate method for the background integration :param method: (str) which method should be used (simpson or trapz)

set_model(likelihoodModel)

Set the model to be used in the joint minimization.

set_model_integrate_method(method: str)

Change the integrate method for the model integration :param method: (str) which method should be used (simpson or trapz)

property significance

Returns

the significance of the data over background

property significance_per_channel

Returns

the significance of the data over background per channel

property simulated_parameters

Return the simulated dataset parameters :return: a likelihood model copy

property source_rate

The source rate of the model. If there is background or a background background plugin present, the source is background subtracted, but only for visual purposes. If no background is present, then, this is just the observed rate.

Returns

the source rate

property source_rate_error

The source rate error of the model. If there is background or a background background plugin present, the source is background subtracted, but only for visual purposes. If no background is present, then, this is just the observed rate.

Returns

the source rate error

property tstart

property tstop

use_effective_area_correction(min_value: Union[int, float] = 0.8, max_value: Union[int, float] = 1.2)

Activate the use of the effective area correction, which is a multiplicative factor in front of the model which might be used to mitigate the effect of intercalibration mismatch between different instruments.

NOTE: do not use this is you are using only one detector, as the multiplicative constant will be completely degenerate with the normalization of the model.

NOTE2: always keep at least one multiplicative constant fixed to one (its default value), when using this with other OGIPLike-type detectors

Parameters

• min_value – minimum allowed value (default: 0.8, corresponding to a 20% - effect)

• max_value – maximum allowed value (default: 1.2, corresponding to a 20% + effect

Returns

view_count_spectrum(plot_errors: bool = True, show_bad_channels: bool = True, show_warn_channels: bool = False, significance_level: Optional[bool] = None, scale_background: bool = True) → matplotlib.figure.Figure

View the count and background spectrum. Useful to check energy selections. :param plot_errors: plot errors on the counts :param show_bad_channels: (bool) show which channels are bad in the native PHA quality :return:

write_pha()

threeML.plugins.SwiftXRTLike module

class threeML.plugins.SwiftXRTLike.SwiftXRTLike(name: str, observation, background=None, response=None, arf_file=None, spectrum_number=None, verbose=True)

Bases: threeML.plugins.OGIPLike.OGIPLike

threeML.plugins.XYLike module

class threeML.plugins.XYLike.XYLike(name, x, y, yerr=None, poisson_data=False, exposure=None, quiet=False, source_name=None)

Bases: threeML.plugin_prototype.PluginPrototype

assign_to_source(source_name)

Assign these data to the given source (instead of to the sum of all sources, which is the default)

Parameters

source_name – name of the source (must be contained in the likelihood model)

Returns

none

fit(function, minimizer='minuit', verbose=False)

Fit the data with the provided function (an astromodels function)

Parameters

• function – astromodels function

• minimizer – the minimizer to use

• verbose – print every step of the fit procedure

Returns

best fit results

classmethod from_dataframe(name, dataframe, x_column='x', y_column='y', err_column='yerr', poisson=False)

Generate a XYLike instance from a Pandas.DataFrame instance

Parameters

• name – the name for the XYLike instance

• dataframe – the input data frame

• x_column – name of the column to be used as x (default: ‘x’)

• y_column – name of the column to be used as y (default: ‘y’)

• err_column – name of the column to be used as error on y (default: ‘yerr’)

• poisson – if True, then the err_column is ignored and data are treated as Poisson distributed

Returns

a XYLike instance

classmethod from_function(name, function, x, yerr=None, exposure=None, **kwargs)

Generate an XYLike plugin from an astromodels function instance

Parameters

• name – name of plugin

• function – astromodels function instance

• x – where to simulate

• yerr – y errors or None for Poisson data

• kwargs – kwargs from xylike constructor

Returns

XYLike plugin

classmethod from_text_file(name, filename)

Instance the plugin starting from a text file generated with the .to_txt() method. Note that a more general way of creating a XYLike instance from a text file is to read the file using pandas.DataFrame.from_csv, and then use the .from_dataframe method of the XYLike plugin:

> df = pd.DataFrame.from_csv(filename, …) > xyl = XYLike.from_dataframe(“my instance”, df)

Parameters

• name – the name for the new instance

• filename – path to the file

Returns

get_log_like()

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

get_model()

get_number_of_data_points()

returns the number of active data points :return:

get_simulated_dataset(new_name=None)

goodness_of_fit(n_iterations=1000, continue_of_failure=False)

Returns the goodness of fit of the performed fit

Parameters

• n_iterations – number of Monte Carlo simulations to generate

• continue_of_failure – whether to continue or not if a fit fails (default: False)

Returns

tuple (goodness of fit, frame with all results, frame with all likelihood values)

property has_errors

inner_fit()

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 is_poisson

plot(x_label='x', y_label='y', x_scale='linear', y_scale='linear')

set_model(likelihood_model_instance)

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

Parameters

likelihood_model_instance (astromodels.Model) – instance of Model

to_csv(*args, **kwargs)

Save the data in a comma-separated-values file (CSV) file. All keywords arguments are passed to the pandas.DataFrame.to_csv method (see the documentation from pandas for all possibilities). This gives a very high control on the format of the output

All arguments are forwarded to pandas.DataFrame.to_csv

Returns

none

to_dataframe()

Returns a pandas.DataFrame instance with the data in the ‘x’, ‘y’, and ‘yerr’ column. If the data are Poisson, the yerr column will be -99 for every entry

Returns

a pandas.DataFrame instance

to_txt(filename)

Save the dataset in a text file. You can read the content back in a dataframe using:

> df = pandas.DataFrame.from_csv(filename, sep=’ ‘)

and recreate the XYLike instance as:

> xyl = XYLike.from_dataframe(df)

Parameters

filename – Name of the output file

Returns

none

property x

property y

property yerr

threeML.plugins.gammaln module

Module contents