threeML.plugins package¶
Subpackages¶
Submodules¶
threeML.plugins.DispersionSpectrumLike module¶
-
class
threeML.plugins.DispersionSpectrumLike.
DispersionSpectrumLike
(name: str, observation, background=None, background_exposure=None, verbose=True, tstart=None, tstop=None)[source]¶ Bases:
threeML.plugins.SpectrumLike.SpectrumLike
-
display_rsp
()[source]¶ 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[source]¶ 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_simulated_dataset
(new_name=None, **kwargs)[source]¶ 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_integrate_method
(method: str)[source]¶ 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[source]¶ 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)[source]¶ 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')[source]¶
-
get_log_like
()[source]¶ Return the value of the log-likelihood with the current values for the parameters stored in the ModelManager instance
-
property
gta
¶
-
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
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)[source]¶ Bases:
threeML.plugins.DispersionSpectrumLike.DispersionSpectrumLike
-
classmethod
from_general_dispersion_spectrum
(dispersion_like: threeML.plugins.DispersionSpectrumLike.DispersionSpectrumLike) → threeML.plugins.OGIPLike.OGIPLike[source]¶ 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[source]¶ 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
¶
-
classmethod
threeML.plugins.PhotometryLike module¶
-
class
threeML.plugins.PhotometryLike.
BandNode
(name, index, value, mask)[source]¶ 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’.
-
property
-
class
threeML.plugins.PhotometryLike.
PhotometryLike
(name: str, filters: Union[speclite.filters.FilterSequence, speclite.filters.FilterResponse], observation: threeML.utils.photometry.photometric_observation.PhotometericObservation)[source]¶ Bases:
threeML.plugins.XYLike.XYLike
-
classmethod
from_file
(name: str, filters: Union[speclite.filters.FilterResponse, speclite.filters.FilterSequence], file_name: str)[source]¶ 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)[source]¶ 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
¶
-
classmethod
threeML.plugins.SpectrumLike module¶
-
class
threeML.plugins.SpectrumLike.
SpectrumLike
[source]¶ Bases:
threeML.plugin_prototype.PluginPrototype
-
property
area_ratio
¶ - Returns
ratio between source and background area
-
assign_to_source
(source_name: str) → None[source]¶ 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_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[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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_simulated_dataset
(new_name=None, **kwargs)[source]¶ 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
()[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
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)[source]¶ 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)[source]¶ 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
-
property
scale_factor
¶ Ratio between the source and the background exposure and area
- Returns
-
set_active_measurements
(*args, **kwargs) → None[source]¶ 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)[source]¶ Change the integrate method for the background integration :param method: (str) which method should be used (simpson or trapz)
-
set_model_integrate_method
(method: str)[source]¶ 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)[source]¶ 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[source]¶ 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:
-
property
threeML.plugins.SwiftXRTLike module¶
threeML.plugins.XYLike module¶
-
class
threeML.plugins.XYLike.
XYLike
(name, x, y, yerr=None, poisson_data=False, exposure=None, quiet=False, source_name=None)[source]¶ Bases:
threeML.plugin_prototype.PluginPrototype
-
assign_to_source
(source_name)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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
()[source]¶ Return the value of the log-likelihood with the current values for the parameters
-
goodness_of_fit
(n_iterations=1000, continue_of_failure=False)[source]¶ 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
()[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
is_poisson
¶
-
set_model
(likelihood_model_instance)[source]¶ 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)[source]¶ 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
()[source]¶ 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)[source]¶ 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
¶
-