group_counts

sherpa.astro.ui.group_counts(id, num=None, bkg_id: IdType | None = None, maxLength=None, tabStops=None) → None

Group into a minimum number of counts per bin.

Combine the data so that each bin contains num or more counts. The background is not included in this calculation; the calculation is done on the raw data even if subtract has been called on this data set. The binning scheme is, by default, applied to only the noticed data range. It is suggested that filtering is done before calling group_counts.

Changed in version 4.16.0: Grouping now defaults to only using the noticed channel range. The tabStops argument can be set to “nofilter” to use the previous behaviour.

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 (int) – The number of channels to combine into a group.

  • bkg_id (int, str, or None, 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 not set then it will be based on the filtering of the data set, so that the grouping only uses the filtered data. If set it can be the string “nofilter”, which means that no filter is applied (and matches the behavior prior to the 4.16 release), or an array of booleans where True indicates that the channel should not be used in the grouping (this array must match the number of channels in the data set).

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_adapt_snr

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

group_bins

Group into a fixed number of bins.

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_counts 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 at least 20 counts:

>>> group_counts(20)

Plot two versions of the ‘jet’ data set: the first uses 20 counts per group and the second is 50:

>>> group_counts('jet', 20)
>>> plot_data('jet')
>>> group_counts('jet', 50)
>>> plot_data('jet', overplot=True)

The grouping is applied to only the data within the 0.5 to 8 keV range (this behaviour is new in 4.16):

>>> set_analysis('energy')
>>> notice()
>>> notice(0.5, 8)
>>> group_counts(30)
>>> plot_data()

Group the full channel range and then apply the existing filter (0.5 to 8 keV) so that the noticed range may be larger (this was the default behaviour before 4.16):

>>> group_counts(25, tabStops="nofilter")

If a channel has more than 30 counts then do not group, otherwise group channels so that they contain at least 40 counts. The group_adapt and group_adapt_snr functions provide similar functionality to this example. A maximum length of 10 channels is enforced, to avoid bins getting too large when the signal is low.

>>> notice()
>>> counts = get_data().counts
>>> ign = counts > 30
>>> group_counts(40, tabStops=ign, maxLength=10)