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)[source]#

Bases: object

Observation data.

Parameters:

namestr: Name of the observation data.
erangearray_like: Energy range of interest in keV, e.g., erange=[(0.5, 2), (5, 200)].
spec_dataSpectrumData: Spectrum data of the observation.
resp_dataResponseData: Response matrix data of the observation.
back_dataSpectrumData: Background data of the observation.
ignore_badbool, optional: Whether to ignore bad channels whose quality flags are 2 or 5. The default is True.
keep_channel_infobool, optional: Whether to keep channel information when grouping the data. The default is False.

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.

set_erange(erange: list | tuple)[source]#

Set energy range of interest.

Parameters:

erangearray_like: Energy range of interest in keV, e.g., erange=[(0.5, 2), (5, 200)].

set_grouping(grouping: ndarray | None)[source]#

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:

groupingndarray: 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)[source]#

Group the spectrum.

Parameters:

methodstr

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) [1]
'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

scalefloat, int or None

Grouping scale.

preserve_data_groupbool, optional

Whether to preserve the grouping flags stored in spec_data. If true, will first group the data based on the grouping flags stored in spec_data, 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 spec_data. The default is False.

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[source]#

Plot the spectrum.

Warning

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

Parameters:

xlogbool, optional: Whether to use log scale on x-axis. The default is True.
data_ylogbool, optional: Whether to use log scale on y-axis in spectral plot. The default is True.
sig_ylogbool, optional: Whether to use log scale on y-axis in significance plot. The default is False.

Returns:

plt.Figure: The figure object.

plot_effective_area(hatch: bool = True, ylog: bool = True) → Figure[source]#

Plot the effective area.

Parameters:

hatchbool, optional: Whether to add hatches in the ignored region. The default is True.
ylogbool, optional: Whether to use log scale on y-axis. The default is True.

Returns:

plt.Figure: The figure object.

plot_matrix(hatch: bool = True, norm: str = 'log') → Figure[source]#

Plot the response matrix.

Parameters:

hatchbool, optional: Whether to add hatches in the ignored region. The default is True.
normstr, optional: Colorbar normalization method. The default is 'log'.

Returns:

plt.Figure: The figure object.

get_fixed_data() → FixedData[source]#: 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: float#: Area scaling factor.

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, sys_errors: float | ndarray = 0.0, zero_errors_warning: bool = True, non_int_warning: bool = True, sys_errors_warning: bool = True)[source]#

Bases: object

Spectrum data.

Parameters:

countsarray_like

Spectrum counts in each measuring channel.

errorsarray_like

Uncertainty of spectrum counts.

poissonbool

Whether spectrum data follows counting statistics.

exposurefloat

Spectrum exposure.

qualityarray_like, optional

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

0: good

1: defined bad by software

2: defined dubious by software

5: defined bad by user

-1: reason for bad flag unknown

groupingarray_like, optional

The grouping flag. When grouping the spectrum, channel with a grouping flag of 1 with all successive channels with grouping flags of -1 will be combined. The default is 1 for all channels.

area_scalefloat or array_like, optional

Area scaling factor. The default is 1.0.

back_scalefloat or array_like, optional

Background scaling factor. The default is 1.0.

sys_errorsfloat or array_like, optional

Systematic errors. If scalar, it will be applied to all channels. The default is 0.0.

zero_errors_warningbool, optional

Whether to warn about zero errors when poisson is False. The default is True.

non_int_warningbool, optional

Whether to warn about non-integer counts when poisson is True. The default is True.

sys_errors_warningbool, optional

Whether to warn about non-zero systematic errors when poisson is True. The default is True.

Attributes

`area_scale`	Area scaling factor.
`back_scale`	Background scaling factor.
`counts`	Spectrum counts in each measuring channel.
`errors`	Uncertainty of spectrum counts.
`exposure`	Spectrum exposure.
`grouping`	Grouping flags of the spectrum.
`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][source]#

Group the spectrum.

Parameters:

groupingndarray: Channel with a grouping flag of 1 with all successive channels with grouping flags of -1 are combined.
qualityndarray, optional: Flag indicating which channel to be used in grouping.

Returns:

countsndarray: Grouped spectrum counts.
errorsndarray: 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: float#: Area scaling factor.

property back_scale: float#: Background scaling factor.

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

Bases: object

Response matrix data.

Parameters:

photon_egridarray_like: Photon energy array of response matrix, must be increasing.
channel_eminarray_like: Left edge of the measurement channel energy array, must be increasing.
channel_emaxarray_like: Right edge of the measurement channel energy array, must be increasing.
response_matrixarray_like or sparse matrix: Response matrix, the shape is (len(photon_egrid), len(channel)). This can be a sparse matrix.
channelarray_like: Measurement channel information.
channel_typestr, optional: Measurement channel type, e.g. ‘PI’. The default is ‘Ch’.
sparsebool, optional: 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][source]#

Group the response matrix.

Parameters:

groupingndarray: Channel with a grouping flag of 1 with all successive channels with grouping flags of -1 are combined.
qualityndarray, optional: Flag indicating which channel to be used in grouping.
keep_channel_infobool, optional: Whether to keep channel information when grouping the response. The default is False.

Returns:

group_eminndarray: Left edge of the grouped channel energy array.
group_emaxndarray: Right edge of the grouped channel energy array.
matrixcoo_array: Grouped response matrix.
channelndarray: Grouped channel information.

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

Get grouped channels’ energy grid information.

Parameters:

groupingndarray: Channel with a grouping flag of 1 with all successive channels with grouping flags of -1 are combined.
qualityndarray, optional: Flag indicating which channel to be used in grouping.
keep_channel_infobool, optional: Whether to keep channel information when grouping the response. The default is False.

Returns:

group_eminndarray: Left edge of the grouped channel energy array.
group_emaxndarray: Right edge of the grouped channel energy array.
channelndarray: Grouped channel information.

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

Plot the response matrix.

Parameters:

noticed_rangendarray, optional: Energy range to show. Other energy ranges will be hatched.
good_qualityndarray, optional: Flags indicating which measurement channel to be used in plotting. It must be the same length as the number of channels.
ylogbool, optional: Whether to use log scale on y-axis. The default is True.

Returns:

figplt.Figure: The figure object.

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

Plot the response matrix.

Parameters:

noticed_rangendarray, optional: Energy range to show. Other energy ranges will be hatched.
good_qualityndarray, optional: Flags indicating which measurement channel to be used in plotting. It must be the same length as the number of channels.
normstr, optional: Colorbar normalization method. The default is 'log'.

Returns:

figplt.Figure: 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)[source]#

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[source]#

Bases: Warning

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