threeML.plugins.SpectrumLike module

class threeML.plugins.SpectrumLike.SpectrumLike(name: str, observation: threeML.utils.spectrum.binned_spectrum.BinnedSpectrum, background: Optional[Union[threeML.utils.spectrum.binned_spectrum.BinnedSpectrum, threeML.plugins.SpectrumLike.SpectrumLike, threeML.plugins.XYLike.XYLike]] = None, verbose: bool = True, background_exposure=None, tstart: Optional[Union[float, int]] = None, tstop: Optional[Union[float, int]] = None)

Bases: threeML.plugin_prototype.PluginPrototype

property area_ratio: float

ratio between source and background area

Type

return

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: Optional[numpy.ndarray]

the observed background count errors

Type

return

property background_counts: Optional[numpy.ndarray]

the observed background counts

Type

return

property background_exposure: float

Exposure of the background spectrum, if present

property background_noise_model: str

Sets/gets the noise model for the background spectrum

property background_plugin

property background_scale_factor: float

The background scale factor

Returns

property background_spectrum: threeML.utils.spectrum.binned_spectrum.BinnedSpectrum

property current_background_count_errors: numpy.ndarray

property current_background_counts: numpy.ndarray

property current_observed_count_errors: numpy.ndarray

property current_observed_counts: numpy.ndarray

property current_scaled_background_counts: numpy.ndarray

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[str, Any]] = None, data_kwargs: Optional[Dict[str, Any]] = None, background_label: Optional[str] = None, background_kwargs: Optional[Dict[str, Any]] = 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: Tuple[float]

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

Returns

(energy_min, energy_max)

property expected_model_rate: numpy.ndarray

property exposure: float

Exposure of the source spectrum

property exposure_ratio: float

ratio between source and background exposure

Type

return

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

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, exposure=1.0, scale_factor=1.0, **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

• exposure – the exposure to assume

• scale_factor – the scale factor between source exposure / bkg exposure

Returns

simulated SpectrumLike plugin

get_background_model(without_mask: bool = False) → numpy.ndarray

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.ndarray] = None) → float

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) → numpy.ndarray

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() → int

returns the number of active data bins :return:

get_pha_files() → Dict[str, threeML.utils.spectrum.binned_spectrum.BinnedSpectrum]

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

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() → float

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: astromodels.core.model.Model

property mask: numpy.ndarray

The channel mask :return:

property n_data_points: int

property observation_noise_model: str

Sets/gets the noise model for the background spectrum

property observed_count_errors: Optional[numpy.ndarray]

the observed counts errors

Type

return

property observed_counts: numpy.ndarray

the observed counts

Type

return

property observed_spectrum: threeML.utils.spectrum.binned_spectrum.BinnedSpectrum

property quality: threeML.utils.spectrum.binned_spectrum.Quality

rebin_on_background(min_number_of_counts: float) → None

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: int) → None

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() → None

Remove the rebinning scheme set with rebin_on_background.

Returns

property scale_factor: float

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) → None

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

set_model(likelihoodModel: astromodels.core.model.Model) → None

Set the model to be used in the joint minimization.

set_model_integrate_method(method: str) → None

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

property significance: float

the significance of the data over background

Type

return

property significance_per_channel: numpy.ndarray

the significance of the data over background per channel

Type

return

property simulated_parameters: astromodels.core.model.Model

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

property source_rate: numpy.ndarray

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: numpy.ndarray

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

property tstop: float

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

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()