Last modified: December 2021

Jump to: Description · Examples · PARAMETERS · Notes · Bugs · See Also

AHELP for CIAO 4.14 Sherpa


Context: data


Group into a fixed bin width.


group_width(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


Combine the data so that each bin contains `num` channels. 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.


Example 1

Group the default data set so that each bin contains 20 channels:

>>> group_width(20)

Example 2

Plot two versions of the 'jet' data set: the first uses 20 channels per group and the second is 50 channels per group:

>>> group_width('jet', 20)
>>> plot_data('jet')
>>> group_width('jet', 50)
>>> 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.

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

Example 4

The grouping is not applied to channels 101 to 149, inclusive:

>>> notice()
>>> channels = get_data().channel
>>> ign = (channels > 100) & (channels < 150)
>>> group_width(40, tabStops=ign)
>>> plot_data()


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 channels to combine into a group.
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).


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

Unless the requested bin width is a factor of the number of channels (and no tabstops parameter is given), then some channels will be "left over". 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.


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

See Also

copy_data, dataspace1d, dataspace2d, datastack, delete_data, fake, get_axes, get_bkg_chisqr_plot, get_bkg_delchi_plot, get_bkg_fit_plot, get_bkg_model_plot, get_bkg_plot, get_bkg_ratio_plot, get_bkg_resid_plot, get_bkg_source_plot, get_counts, get_data, get_data_contour, get_data_contour_prefs, get_data_image, get_data_plot, get_data_plot_prefs, get_dep, get_dims, get_error, get_grouping, get_quality, get_specresp, get_staterror, get_syserror, group, group_adapt, group_adapt_snr, group_bins, group_counts, group_snr, load_ascii, load_data, load_grouping, load_quality, set_data, set_grouping, set_quality, ungroup, unpack_ascii, unpack_data
get_filter, ignore, ignore2d, ignore2d_id, ignore_bad, ignore_id, load_filter, notice, notice2d, notice2d_id, notice_id, set_filter, show_filter
get_default_id, list_data_ids, list_response_ids
plot_data, set_xlinear, set_xlog, set_ylinear, set_ylog
save_error, save_filter, save_grouping, save_quality, save_staterror, save_syserror
calc_data_sum, calc_data_sum2d, calc_ftest, calc_kcorr, calc_mlr, calc_model_sum2d, calc_source_sum2d, get_rate
contour, contour_data, contour_ratio, histogram1d, histogram2d, image_data, rebin