elisa.data.ogip#

class Data(erange: list | tuple, specfile: str, backfile: str | None = None, respfile: str | None = None, ancrfile: str | None = None, name: str | None = None, group: str | None = None, scale: float | None = None, preserve_data_group: bool = False, spec_poisson: bool | None = None, back_poisson: bool | None = None, ignore_bad: bool = True, keep_channel_info: bool = False, sparse_response: bool = False)[source]#

Bases: ObservationData

Handle observation data in OGIP standards [1] [2].

Load the observation spectrum, the telescope response and the possible background, and handle the grouping of spectrum and response.

Parameters:

erange (list | tuple) – Energy range of interest in keV, e.g., erange=[(0.5, 2), (5, 200)].
specfile (str) – Spectrum file path. For type II pha file, the row specifier must be given in the end of path, e.g., specfile='spec.pha2{1}'.
backfile (str | None) – Background file path. Read from the specfile header if None. For type II pha file, the row specifier must be given in the end of path, e.g., backfile='back.pha2{1}'.
respfile (str | None) – Response file path. Read from the specfile header if None. The path must be given if RESPFILE is undefined in the header.
ancrfile (str | None) – Ancillary response path. Read from the specfile header if None.

Attributes

`area_scale`	Area scaling factor of grouped spectrum bins.
`back_counts`	Background counts of grouped measuring channels.
`back_data`	The background data of the observation.
`back_errors`	Uncertainty of background counts of grouped measuring channels.
`back_exposure`	Background exposure.
`back_poisson`	Whether background data follows Poisson counting statistics.
`back_ratio`	Ratio of spectrum to background effective exposure.
`ce`	Grouped net counts per second per keV.
`ce_errors`	Uncertainty of grouped net counts per second per keV.
`channel`	Grouped channel information.
`channel_emax`	Right edge of the grouped measurement channel energy grid.
`channel_emean`	Geometric mean of the grouped measurement channel energy grid.
`channel_emid`	Midpoint of the grouped measurement channel energy grid.
`channel_emin`	Left edge of the grouped measurement channel energy grid.
`channel_errors`	Width between left/right edge and geometric mean of channel grid.
`channel_width`	Width of the grouped measurement channel energy grid.
`erange`	Energy range of interest.
`good_quality`	Flags indicating which measurement channel to be used.
`grouping`	Current grouping flags of the observation data.
`has_back`	Whether the observation has background.
`keep_channel_info`	Whether to keep channel information when grouping the data.
`name`	Name of the observation data.
`net_counts`	Net counts of grouped measuring channels.
`net_errors`	Uncertainty of net counts of grouped measuring channels.
`resp_data`	The response matrix data of the observation.
`response_matrix`	Grouped response matrix.
`sparse_matrix`	Grouped response matrix in sparse representation.
`spec_counts`	Spectrum counts of grouped measuring channels.
`spec_data`	The spectrum data of the observation.
`spec_errors`	Uncertainty of grouped spectrum counts.
`spec_exposure`	Spectrum exposure.
`spec_poisson`	Whether spectrum data follows Poisson counting statistics.

Methods

`get_fixed_data`()	Return a fixed data object.
`group`(method[, scale, preserve_data_group])	Group the spectrum.
`plot_effective_area`([hatch, ylog])	Plot the effective area.
`plot_matrix`([hatch, norm])	Plot the response matrix.
`plot_spec`([xlog, data_ylog, sig_ylog])	Plot the spectrum.
`set_erange`(erange)	Set energy range of interest.
`set_grouping`(grouping)	Set grouping flags.

Parameters:

name (str | None) – Data name. Read from the specfile header if None. The name must be given if DETNAM, INSTRUME and TELESCOP are all undefined in the header.
group – Method to group spectrum and background adaptively, these options are available so that each channel group has:

Notes

Reading and applying correction to data is not yet supported.

References

[1]

The OGIP Spectral File Format and Addendum: Changes log

[2]

The Calibration Requirements for Spectral Analysis (Definition of RMF and ARF file formats) and Addendum: Changes log

[3]

Kaastra & Bleeker 2016, A&A, 587, A151

class Spectrum(specfile: str, poisson: bool | None = None)[source]#

Bases: SpectrumData

Load spectrum data in OGIP standards [1].

Parameters:

specfile (str) – Spectrum file path. For type II pha file, the row specifier must be given at the end of path, e.g., specfile='spec.pha2{1}'.
poisson (bool | None) – Whether the spectrum data follows counting statistics, reading from the specfile header. This value must be set if POISSERR is undefined in the header.

Attributes

`ancrfile`	The ancillary response file path.
`area_scale`	Per-channel area scaling factors.
`back_scale`	Per-channel background scaling factors.
`backfile`	The background file path.
`counts`	Spectrum counts in each measuring channel.
`errors`	Uncertainty of spectrum counts.
`exposure`	Spectrum exposure.
`grouping`	Grouping flags of the spectrum.
`header`	The spectrum header.
`name`	The name of the observation instrument.
`net`	Whether grouped source scales should follow NET averaging.
`poisson`	Whether spectrum data follows counting statistics.
`quality`	Data quality of each spectrum channel.
`respfile`	The response file path.
`specfile`	The spectrum file path.

Methods

group(grouping[, quality])

Group the spectrum.

References

[1]

The OGIP Spectral File Format and Addendum: Changes log

property name: str#: The name of the observation instrument.

property header: Header#: The spectrum header.

property specfile: str#: The spectrum file path.

property backfile: str#: The background file path.

property respfile: str#: The response file path.

property ancrfile: str#: The ancillary response file path.

class Response(respfile: str, ancrfile: str | None = None, sparse: bool = False)[source]#

Bases: ResponseData

Load telescope response data in OGIP standards [1].

Parameters:

respfile (str) – Response file path.
ancrfile (str | None) – Ancillary response path. The default is None.
sparse (bool) – Whether the response matrix is sparse. The default is False.

Attributes

`ancrfile`	The ancillary response file path.
`channel`	Measurement channel information.
`channel_emax`	Right edge of measurement energy grid.
`channel_emin`	Left edge of measurement energy grid.
`channel_fwhm`	Estimated Full Width at Half Maximum (FWHM) in channel energy space.
`channel_number`	Number of channels.
`channel_type`	Measurement channel type.
`fwhm`	Estimated Full Width at Half Maximum (FWHM) in photon energy space.
`matrix`	Response matrix.
`photon_egrid`	Photon energy grid of response matrix.
`respfile`	The response file path.
`sparse`	Whether the response matrix is sparse.
`sparse_matrix`	Sparse response matrix.

Methods

`group`(grouping[, quality, keep_channel_info])	Group the response matrix.
`group_energy`(grouping[, quality, ...])	Get grouped channels' energy grid information.
`plot_effective_area`([noticed_range, ...])	Plot the response matrix.
`plot_matrix`([noticed_range, good_quality, norm])	Plot the response matrix.

References

[1]

The Calibration Requirements for Spectral Analysis (Definition of RMF and ARF file formats) and Addendum: Changes log

property respfile: str#: The response file path.

property ancrfile: str#: The ancillary response file path.

exception PoissonFlagNotFoundError[source]#

Bases: RuntimeError

Issued by POISSERR not found in spectrum header.