Last modified: December 2023

URL: https://cxc.cfa.harvard.edu/sherpa/ahelp/group_adapt_snr.html
AHELP for CIAO 4.16 Sherpa

group_adapt_snr

Context: data

Synopsis

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

Syntax

group_adapt_snr(id, min=None, bkg_id=None, maxLength=None,
tabStops=None, errorCol=None)

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

Description

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, by default, applied to only the noticed data range. It is suggested that filtering is done before calling group_adapt_snr.


Examples

Example 1

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

>>> group_adapt_snr(5)

Example 2

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)

Example 3

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_adapt_snr(4)
>>> plot_data()

Example 4

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_adapt_snr(3, tabStops="nofilter")

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 minimum signal-to-noise ratio that must be reached to form a group 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.
maxLength The maximum number of channels that can be combined into a single group.
tabStops 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).
errorCol 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.

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.

Changes in CIAO

Changed in CIAO 4.16

Grouping now defaults to only using the noticed channel range. The tabStops argument can be set to "nofilter" to use the previous behaviour.

The filter is now reported, noting any changes the new grouping scheme has made.


Bugs

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

See Also

data
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_bins, group_counts, group_snr, group_width, load_ascii, load_data, load_grouping, load_quality, set_data, set_grouping, set_quality, ungroup, unpack_ascii, unpack_data
filtering
get_filter, ignore, ignore2d, ignore2d_id, ignore_bad, ignore_id, load_filter, notice, notice2d, notice2d_id, notice_id, set_filter, show_filter
info
get_default_id, list_data_ids, list_response_ids
modeling
clean
plotting
plot_data, set_xlinear, set_xlog, set_ylinear, set_ylog
saving
save_error, save_filter, save_grouping, save_quality, save_staterror, save_syserror
utilities
calc_data_sum, calc_data_sum2d, calc_ftest, calc_kcorr, calc_mlr, calc_model_sum2d, calc_source_sum2d, get_rate
visualization
contour, contour_data, contour_ratio, histogram1d, histogram2d, image_data, rebin