elisa.data.base

class ObservationData(name: str, erange: list | tuple, spec_data: SpectrumData, resp_data: ResponseData, back_data: SpectrumData | None = None, ignore_bad: bool = True, keep_channel_info: bool = False)

Bases: object

Observation data.

Parameters:

• name (str) – Name of the observation data.

• erange (list | tuple) – Energy range of interest in keV, e.g., erange=[(0.5, 2), (5, 200)].

• spec_data (SpectrumData) – Spectrum data of the observation.

• resp_data (ResponseData) – Response matrix data of the observation.

• back_data (SpectrumData | None) – Background data of the observation.

• ignore_bad (bool) – Whether to ignore bad channels whose quality flags are 2 or 5. The default is True.

• keep_channel_info (bool) – Whether to keep channel information when grouping the data. The default is False.

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.

set_erange(erange: list | tuple)

Set energy range of interest.

Parameters:

erange (list | tuple) – Energy range of interest in keV, e.g., erange=[(0.5, 2), (5, 200)].

set_grouping(grouping: ndarray | None)

Set grouping flags.

First group the spectrum and background according to the grouping flags, then ignore the channel groups falling outside the energy range of interest.

Parameters:

grouping (ndarray | None) – The grouping flags. If None, restore the grouping flags stored in the spectrum file.

group(method: str, scale: float | None = None, preserve_data_group: bool = False)

Group the spectrum.

Parameters:

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

Warns:

GroupWarning

Warn if grouping scale is not met for any channel.

Notes

If there are ignored channels in a channel group, this may cause an inconsistency in a spectral plot. That is to say, the error bar of a channel group will cover these bad channels, whilst these bad channels are never used in fitting.

References

[1]

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

plot_spec(xlog: bool = True, data_ylog: bool = True, sig_ylog: bool = False) → Figure

Plot the spectrum.

Warning

The significance plot is accurate only if the spectrum data has enough count statistics.

Parameters:

• xlog (bool) – Whether to use log scale on x-axis. The default is True.

• data_ylog (bool) – Whether to use log scale on y-axis in spectral plot. The default is True.

• sig_ylog (bool) – Whether to use log scale on y-axis in significance plot. The default is False.

Returns:

The figure object.

plot_effective_area(hatch: bool = True, ylog: bool = True) → Figure

Plot the effective area.

Parameters:

• hatch (bool) – Whether to add hatches in the ignored region. The default is True.

• ylog (bool) – Whether to use log scale on y-axis. The default is True.

Returns:

The figure object.

plot_matrix(hatch: bool = True, norm: str = 'log') → Figure

Plot the response matrix.

Parameters:

• hatch (bool) – Whether to add hatches in the ignored region. The default is True.

• norm (str) – Colorbar normalization method. The default is 'log'.

Returns:

The figure object.

get_fixed_data() → FixedData

Return a fixed data object.

property name: str

Name of the observation data.

property erange: list[list[float]]

Energy range of interest.

property spec_data: SpectrumData

The spectrum data of the observation.

property resp_data: ResponseData

The response matrix data of the observation.

property has_back: bool

Whether the observation has background.

property back_data: SpectrumData | None

The background data of the observation.

property spec_exposure: float

Spectrum exposure.

property spec_poisson: bool

Whether spectrum data follows Poisson counting statistics.

property area_scale: ndarray

Area scaling factor of grouped spectrum bins.

property back_ratio: ndarray | None

Ratio of spectrum to background effective exposure.

property back_exposure: float | None

Background exposure.

property back_poisson: bool | None

Whether background data follows Poisson counting statistics.

property good_quality: ndarray

Flags indicating which measurement channel to be used.

property grouping: ndarray

Current grouping flags of the observation data.

property keep_channel_info: bool

Whether to keep channel information when grouping the data.

property spec_counts: ndarray

Spectrum counts of grouped measuring channels.

property spec_errors: ndarray

Uncertainty of grouped spectrum counts.

property net_counts: ndarray

Net counts of grouped measuring channels.

property net_errors: ndarray

Uncertainty of net counts of grouped measuring channels.

property ce: ndarray

Grouped net counts per second per keV.

property ce_errors: ndarray

Uncertainty of grouped net counts per second per keV.

property back_counts: ndarray | None

Background counts of grouped measuring channels.

property back_errors: ndarray | None

Uncertainty of background counts of grouped measuring channels.

property channel_emin: ndarray

Left edge of the grouped measurement channel energy grid.

property channel_emax: ndarray

Right edge of the grouped measurement channel energy grid.

property channel: ndarray

Grouped channel information.

property channel_emid: ndarray

Midpoint of the grouped measurement channel energy grid.

property channel_width: ndarray

Width of the grouped measurement channel energy grid.

property channel_emean: ndarray

Geometric mean of the grouped measurement channel energy grid.

property channel_errors: ndarray

Width between left/right edge and geometric mean of channel grid.

property sparse_matrix: csc_array

Grouped response matrix in sparse representation.

property response_matrix: ndarray

Grouped response matrix.

class SpectrumData(counts: ndarray, errors: ndarray, poisson: bool, exposure: float, quality: ndarray | None = None, grouping: ndarray | None = None, area_scale: float | ndarray = 1.0, back_scale: float | ndarray = 1.0, net: bool | None = None, sys_errors: float | ndarray = 0.0, zero_errors_warning: bool = True, non_int_warning: bool = True, sys_errors_warning: bool = True)

Bases: object

Spectrum data.

Parameters:

• counts (ndarray) – Spectrum counts in each measuring channel.

• errors (ndarray) – Uncertainty of spectrum counts.

• poisson (bool) – Whether spectrum data follows counting statistics.

• exposure (float) – Spectrum exposure.

• quality – Data quality of each spectrum channel. The default is 0 for all channels. The possible values are:

Attributes

area_scale	Per-channel area scaling factors.
back_scale	Per-channel background scaling factors.
counts	Spectrum counts in each measuring channel.
errors	Uncertainty of spectrum counts.
exposure	Spectrum exposure.
grouping	Grouping flags of the spectrum.
net	Whether grouped source scales should follow NET averaging.
poisson	Whether spectrum data follows counting statistics.
quality	Data quality of each spectrum channel.

Methods

group(grouping[, quality])

Group the spectrum.

group(grouping: ndarray, quality: ndarray | None = None) → tuple[ndarray, ndarray]

Group the spectrum.

Parameters:

• grouping (ndarray) – Channel with a grouping flag of 1 with all successive channels with grouping flags of -1 are combined.

• quality (ndarray | None) – Flag indicating which channel to be used in grouping.

Returns:

• counts (ndarray) – Grouped spectrum counts.

• errors (ndarray) – Uncertainty of grouped spectrum counts.

property counts: ndarray

Spectrum counts in each measuring channel.

property errors: ndarray

Uncertainty of spectrum counts.

property quality: ndarray

Data quality of each spectrum channel.

property grouping: ndarray

Grouping flags of the spectrum.

property poisson: bool

Whether spectrum data follows counting statistics.

property exposure: float

Spectrum exposure.

property area_scale: ndarray

Per-channel area scaling factors.

property back_scale: ndarray

Per-channel background scaling factors.

property net: bool

Whether grouped source scales should follow NET averaging.

Returns the explicit user/OGIP setting when present; otherwise falls back to an automatic check for negative channel values.

class ResponseData(photon_egrid: ndarray, channel_emin: ndarray, channel_emax: ndarray, response_matrix: ndarray | sparray, channel: ndarray, channel_type: str = 'Ch', sparse: bool = False)

Bases: object

Response matrix data.

Parameters:

• photon_egrid (ndarray) – Photon energy array of response matrix, must be increasing.

• channel_emin (ndarray) – Left edge of the measurement channel energy array, must be increasing.

• channel_emax (ndarray) – Right edge of the measurement channel energy array, must be increasing.

• response_matrix (ndarray | sparray) – Response matrix, the shape is (len(photon_egrid), len(channel)). This can be a sparse matrix.

• channel (ndarray) – Measurement channel information.

• channel_type (str) – Measurement channel type, e.g. ‘PI’. The default is ‘Ch’.

• sparse (bool) – Whether the response matrix is sparse. The default is False.

Attributes

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.
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.

group(grouping: ndarray, quality: ndarray | None = None, keep_channel_info: bool = False) → tuple[ndarray, ndarray, coo_array, ndarray]

Group the response matrix.

Parameters:

• grouping (ndarray) – Channel with a grouping flag of 1 with all successive channels with grouping flags of -1 are combined.

• quality (ndarray | None) – Flag indicating which channel to be used in grouping.

• keep_channel_info (bool) – Whether to keep channel information when grouping the response. The default is False.

Returns:

• group_emin (ndarray) – Left edge of the grouped channel energy array.

• group_emax (ndarray) – Right edge of the grouped channel energy array.

• matrix (coo_array) – Grouped response matrix.

• channel (ndarray) – Grouped channel information.

group_energy(grouping: ndarray, quality: ndarray | None = None, keep_channel_info: bool = False) → tuple[ndarray, ndarray, ndarray]

Get grouped channels’ energy grid information.

Parameters:

• grouping (ndarray) – Channel with a grouping flag of 1 with all successive channels with grouping flags of -1 are combined.

• quality (ndarray | None) – Flag indicating which channel to be used in grouping.

• keep_channel_info (bool) – Whether to keep channel information when grouping the response. The default is False.

Returns:

• group_emin (ndarray) – Left edge of the grouped channel energy array.

• group_emax (ndarray) – Right edge of the grouped channel energy array.

• channel (ndarray) – Grouped channel information.

plot_effective_area(noticed_range: ndarray | None = None, good_quality: ndarray | None = None, ylog: bool = True) → Figure

Plot the response matrix.

Parameters:

• noticed_range (ndarray | None) – Energy range to show. Other energy ranges will be hatched.

• good_quality (ndarray | None) – Flags indicating which measurement channel to be used in plotting. It must be the same length as the number of channels.

• ylog (bool) – Whether to use log scale on y-axis. The default is True.

Returns:

The figure object.

plot_matrix(noticed_range: ndarray | None = None, good_quality: ndarray | None = None, norm: str = 'log') → Figure

Plot the response matrix.

Parameters:

• noticed_range (ndarray | None) – Energy range to show. Other energy ranges will be hatched.

• good_quality (ndarray | None) – Flags indicating which measurement channel to be used in plotting. It must be the same length as the number of channels.

• norm (str) – Colorbar normalization method. The default is 'log'.

Returns:

The figure object.

property photon_egrid: ndarray

Photon energy grid of response matrix.

property channel_emin: ndarray

Left edge of measurement energy grid.

property channel_emax: ndarray

Right edge of measurement energy grid.

property channel: ndarray

Measurement channel information.

property channel_type: str

Measurement channel type.

property channel_number: int

Number of channels.

property matrix: ndarray

Response matrix.

property sparse: bool

Whether the response matrix is sparse.

property sparse_matrix: coo_array

Sparse response matrix.

property fwhm: ndarray

Estimated Full Width at Half Maximum (FWHM) in photon energy space.

Note

The calculation code is translated from heasp. This does assume that the response has a well-defined main peak and operates by the simple method of stepping out from the peak in both directions till the response falls below half the maximum. A better solution would obviously be to fit a gaussian.

property channel_fwhm: ndarray

Estimated Full Width at Half Maximum (FWHM) in channel energy space.

Note

The calculation code is translated from heasp. The calculation interpolates the estimated_fwhm using the nominal channel energy to give the FWHM for each channel. Assuming that FWHM does not change significantly over the channel, so just find the FWHM at the center energy of the channel.

class FixedData(name: str, spec_counts: NDArray, spec_errors: NDArray, spec_poisson: bool, spec_exposure: float, area_scale: float | NDArray, has_back: bool, back_counts: NDArray | None, back_errors: NDArray | None, back_poisson: bool | None, back_exposure: np.float64 | None, back_ratio: np.float64 | NDArray | None, net_counts: NDArray, net_errors: NDArray, ce: NDArray, ce_errors: NDArray, photon_egrid: NDArray, channel: NDArray, channel_emin: NDArray, channel_emax: NDArray, channel_emid: NDArray, channel_width: NDArray, channel_emean: NDArray, channel_errors: NDArray, response_matrix: NDArray, sparse_matrix: coo_array, response_sparse: bool)

Bases: NamedTuple

Data to fit.

Methods

count(value, /)	Return number of occurrences of value.
index(value[, start, stop])	Return first index of value.

name: str

Name of the observation data.

spec_counts: ndarray

Spectrum counts in each measuring channel.

spec_errors: ndarray

Uncertainty of spectrum counts.

spec_poisson: bool

Whether spectrum data follows counting statistics.

spec_exposure: float

Spectrum exposure.

area_scale: float | ndarray

Area scaling factor.

has_back: bool

Whether spectrum data includes background.

back_counts: ndarray | None

Background counts in each measuring channel.

back_errors: ndarray | None

Uncertainty of background counts.

back_poisson: bool | None

Whether background data follows counting statistics.

back_exposure: float64 | None

Background exposure.

back_ratio: float64 | ndarray | None

Ratio of spectrum to background effective exposure.

net_counts: ndarray

Net counts in each measuring channel.

net_errors: ndarray

Uncertainty of net counts in each measuring channel.

ce: ndarray

Net counts per second per keV.

ce_errors: ndarray

Uncertainty of net counts per second per keV.

photon_egrid: ndarray

Photon energy grid of response matrix.

channel: ndarray

Measurement channel information.

channel_emin: ndarray

Left edge of measurement energy grid.

channel_emax: ndarray

Right edge of measurement energy grid.

channel_emid: ndarray

Middle of measurement energy grid.

channel_width: ndarray

Width of measurement energy grid.

channel_emean: ndarray

Geometric mean of measurement energy grid.

channel_errors: ndarray

Width between left/right and geometric mean of channel grid.

response_matrix: ndarray

Response matrix.

sparse_matrix: coo_array

Sparse response matrix.

response_sparse: bool

Whether the response matrix is sparse.

exception GroupingWarning

Bases: Warning

Issued by grouping scale not being met for all channel groups.