group_adapt_snr

sherpa.astro.ui.group_adapt_snr(id, min=None, bkg_id=None, maxLength=None, tabStops=None, errorCol=None)

Adaptively group to a minimum signal-to-noise ratio.

Combine the data so that each bin has a signal-to-noise ratio of at least num. The difference to group_snr is that this algorithm starts with the bins with the largest signal, in order to avoid over-grouping bright features, rather than at the first channel of the data. The adaptive nature means that low-count regions between bright features may not end up in groups with the minimum number of counts. The binning scheme is applied to all the channels, but any existing filter - created by the ignore or notice set of functions - is re-applied after the data has been grouped.

Changed in version 4.15.1: The filter is now reported, noting any changes the new grouping scheme has made.

Parameters:

  • id (int or str, optional) – The identifier for the data set to use. If not given then the default identifier is used, as returned by get_default_id.

  • num (number) – The minimum signal-to-noise ratio that must be reached to form a group of channels.

  • bkg_id (int or str, optional) – Set to group the background associated with the data set. When bkg_id is None (which is the default), the grouping is applied to all the associated background data sets as well as the source data set.

  • maxLength (int, optional) – The maximum number of channels that can be combined into a single group.

  • tabStops (array of int or bool, optional) – If set, indicate one or more ranges of channels that should not be included in the grouped output. The array should match the number of channels in the data set and non-zero or True means that the channel should be ignored from the grouping (use 0 or False otherwise).

  • errorCol (array of num, optional) – If set, the error to use for each channel when calculating the signal-to-noise ratio. If not given then Poisson statistics is assumed. A warning is displayed for each zero-valued error estimate.

Raises:

sherpa.utils.err.ArgumentErr – If the data set does not contain a PHA data set.

See also

group_adapt

Adaptively group to a minimum number of counts.

group_bins

Group into a fixed number of bins.

group_counts

Group into a minimum number of counts per bin.

group_snr

Group into a minimum signal-to-noise ratio.

group_width

Group into a fixed bin width.

set_grouping

Apply a set of grouping flags to a PHA data set.

set_quality

Apply a set of quality flags to a PHA data set.

Notes

The function does not follow the normal Python standards for parameter use, since it is designed for easy interactive use. When called with a single un-named argument, it is taken to be the num parameter. If given two un-named arguments, then they are interpreted as the id and num parameters, respectively. The remaining parameters are expected to be given as named arguments.

Unlike group, it is possible to call group_adapt_snr multiple times on the same data set without needing to call ungroup.

If channels can not be placed into a “valid” group, then a warning message will be displayed to the screen and the quality value for these channels will be set to 2. This information can be found with the get_quality command.

Examples

Group the default data set so that each bin contains a signal-to-noise ratio of at least 5:

>>> group_adapt_snr(5)

Plot two versions of the ‘jet’ data set: the first uses an adaptive scheme and the second the non-adaptive version:

>>> group_adapt_snr('jet', 4)
>>> plot_data('jet')
>>> group_snr('jet', 4)
>>> plot_data('jet', overplot=True)