group_bins

Context: data

Synopsis

Group into a fixed number of bins.

Syntax

group_bins(id, num=None, bkg_id=None, tabStops=None)

id - int or str, optional
num - int
bkg_id - int or str, optional
tabStops - array of int or bool, optional

Description

Combine the data so that there `num` equal-width bins (or groups). 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.

Examples

Example 1

Group the default data set so that there are 50 bins.

>>> group_bins(50)

Example 2

Group the 'jet' data set to 50 bins and plot the result, then re-bin to 100 bins and overplot the data:

>>> group_bins('jet', 50)
>>> plot_data('jet')
>>> group_bins('jet', 100)
>>> plot_data('jet', overplot=True)

Example 3

The grouping is applied to the full data set, and then the filter - in this case defined over the range 0.5 to 8 keV - will be applied. This means that the noticed data range will likely contain less than 50 bins.

>>> set_analysis('energy')
>>> notice(0.5, 8)
>>> group_bins(50)
>>> plot_data()

Example 4

Do not group any channels numbered less than 20 or 800 or more. Since there are 780 channels to be grouped, the width of each bin will be 20 channels and there are no "left over" channels:

>>> notice()
>>> channels = get_data().channel
>>> ign = (channels <= 20) | (channels >= 800)
>>> group_bins(39, tabStops=ign)
>>> plot_data()

PARAMETERS

The parameters for this function are:

Parameter	Definition
id	The identifier for the data set to use. If not given then the default identifier is used, as returned by `get_default_id` .
num	The number of bins in the grouped data set. Each bin will contain the same number of channels.
bkg_id	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.
tabStops	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).

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_bins` multiple times on the same data set without needing to call `ungroup` .

Since the bin width is an integer number of channels, it is likely that some channels will be "left over". This is even more likely when the tabstops parameter is set. If this happens, 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.

Bugs

See the bugs pages on the Sherpa website for an up-to-date listing of known bugs.