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:

erangearray_like: Energy range of interest in keV, e.g., erange=[(0.5, 2), (5, 200)].
specfilestr: 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}'.
backfilestr or None, optional: 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}'.
respfilestr or None, optional: Response file path. Read from the specfile header if None. The path must be given if RESPFILE is undefined in the header.
ancrfilestr or None, optional: Ancillary response path. Read from the specfile header if None.

Attributes

`area_scale`	Area scaling factor.
`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.

Other Parameters:

namestr or None, optional

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.

groupstr or None, optional

Method to group spectrum and background adaptively, these options are available so that each channel group has:

'const': scale number channels

'min': total (source + background) counts >= scale

'sig': source significance >= scale sigma

'bmin': background counts >= scale, used to avoid bias when using wstat to simultaneously fit the source and background

'bsig': background significance >= scale sigma, used to avoid bias when using pgstat to simultaneously fit the source and background

'opt': optimal binning, see Kaastra & Bleeker (2016) [3]

'optmin': optimal binning with total counts >= scale

'optsig': optimal binning with source significance >= scale sigma

'optbmin': optimal binning with background counts >= scale

'optbsig': optimal binning with background significance >= scale sigma

The default is None.

scalefloat or None, optional

Grouping scale for the method specified in group.

preserve_data_groupbool, optional

Whether to preserve the grouping flags stored in specfile. If true, will first group the data based on the grouping flags stored in specfile, then apply the grouping method specified in group. If false, will directly apply the grouping method specified in group to the data, ignoring the grouping flags stored in specfile. The default is False.

spec_poissonbool or None, optional

Whether the spectrum data follows counting statistics, reading from the specfile header. This value must be set if POISSERR is undefined in the header.

back_poissonbool or None, optional

Whether the background data follows counting statistics, reading from the backfile header. This value must be set if POISSERR is undefined in the header.

ignore_badbool, optional

Whether to ignore channels with QUALITY being 2 or 5. The default is True. The possible values for spectral QUALITY are

0: good

1: defined bad by software

2: defined dubious by software

5: defined bad by user

-1: reason for bad flag unknown

keep_channel_infobool, optional

Whether to keep channel information in the label of grouped channel. Takes effect only if group is not None or spectral data has GROUPING defined. The default is False.

sparse_responsebool, optional

Whether the response matrix is sparse. The default is False.

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:

specfilestr: 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}'.
poissonbool or None, optional: 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`	Area scaling factor.
`back_scale`	Background scaling factor.
`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.
`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:

respfilestr: Response file path.
ancrfilestr or None, optional: Ancillary response path. The default is None.
sparsebool, optional: 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.