group_bins
- sherpa.astro.ui.group_bins(id, num=None, bkg_id: IdType | None = None, tabStops=None) None
Group into a fixed number of bins.
Combine the data so that there
num
equal-width bins (or groups). The binning scheme is, by default, applied to only the noticed data range. It is suggested that filtering is done before calling group_bins.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 bins in the grouped data set. Each bin will contain the same number of channels.
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.tabStops (str or 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_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 theid
andnum
parameters, respectively. The remaining parameters are expected to be given as named arguments.Unlike
group
, it is possible to callgroup_bins
multiple times on the same data set without needing to callungroup
.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 theget_quality
command.Examples
Group the default data set so that there are 50 bins.
>>> group_bins(50)
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)
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_bins(50) >>> 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_bins(50, tabStops="nofilter")
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()