Chandra X-Ray Observatory
	(CXC)
Skip to the navigation links
Last modified: December 2016

URL: http://cxc.harvard.edu/sherpa/ahelp/group_sherpa.html
Jump to: Description · Examples · Bugs · See Also


AHELP for CIAO 4.9 Sherpa v1

group

Context: data

Synopsis

Enable and specify the grouping settings of a spectral data set

Syntax

group([id, bkg_id])
group_bins([id,] num [,bkg_id])
group_counts([id,] num [,bkg_id])
group_snr([id,] snr [,bkg_id])
group_adapt([id,] min [,bkg_id])
group_adapt_snr([id,] min [,bkg_id])
group_width([id,] num [,bkg_id])

Description

  • id - the id of the source data set (including associated background data) to group; if not given, uses the default data set id (id=1 by default, see "ahelp get_default_id")
  • bkg_id - background data set ID, to apply a separate grouping to associated background data (when left blank, the background will be grouped automatically according to the specified source grouping scheme; see 'id' description above)
  • num - number of counts per bin; default=None
  • min - minimum number of counts per group of bins; default=None
  • snr - minimum signal-to-noise ratio per group of bins; default=None

group

It is often necessary to "group" spectral data, i.e., combine energy, wavelength, or channel bins until there are enough counts per group for spectral fitting. The group() function activates the grouping scheme of a PHA data set, by data set ID or background data set ID. Specifically, it sets the "grouped" boolean in a Sherpa PHA data set to True or False, after the 'grouping' setting of the data set has been defined with the set_grouping() function (which can be used to apply a user-defined array of integers as the grouping scheme, e.g. to group data into fewer bins, each with a minimum number of counts). Grouping can be disabled with the function ungroup(). The other Sherpa group functions are group_counts(), group_snr(), group_adapt(), and group_adapt_snr(), defined below.

When a grouping scheme is applied to a source data set, it is also automatically applied to all associated background data sets. A different grouping scheme for a background can still be imposed afterward, using the bkg_id parameter to group just the background.

group_bins

This function divides the channels into the specified number ("num") of bins.

group_counts

This function allows the user to group PHA spectral data so that each bin has at least a minimum number of counts, i.e., data are grouped until the number of counts in each bin exceeds the minimum number of counts specified in the 'num' argument.

group_snr

This function allows the user to group PHA spectral data so that each group of bins has at least a minimum signal-to-noise ratio (bins of data are grouped until the square root of the number of counts in each group exceeds the given signal-to-noise value specified in the 'snr' argument).

group_adapt

This function allows the user to adaptively group PHA spectral data by counts, i.e., group data channels until the number of counts in each group exceeds the minimum number of counts specified in the 'min' argument, keeping bright features ungrouped. Some channels between the bright features may remain ungrouped if the grouping criterium has not been met. These ungrouped channels are given the quality flag=2.

group_adapt_snr

This function allows the user to adaptively group PHA spectral data by signal-to-noise ratio, i.e., group data channels until each group exceeds at least the minimum specified signal-to-noise ratio. This function works similarly to group_adapt(), but instead of using a count threshold to determine group cutoffs, the specified signal-to-noise ratio is used.

group_width

This function divides the channels such that there are "num" bins in each group.

Example 1

sherpa> group()
sherpa> group(2)
sherpa> group("src1")
sherpa> group("src1", bkg_id=1)

When called with no arguments, the group() function activates the grouping scheme for the source and background in the default data set. If a data set ID is specified, such as "2" for the second data set loaded (or a user-specified string ID), then grouping is turned on in the indicated data set. To group a background data set separately from the associated source data set, the background ID must be supplied to group().

sherpa> print(get_data(2).grouped)
False

sherpa> group(2)
sherpa> print(get_data(2).grouped)
True

Example 2

sherpa> group_counts(16)
sherpa> group_counts(3, 20)

The function group_counts() requires a 'num' value to indicate the minimum number of counts to be included in each data bin. In this example, default data set 1 is grouped so that there are at least 16 counts per bin, and data set 3 has a minimum of 20 counts per bin.

Example 3

sherpa> group_snr(3)
sherpa> group_snr(5,bkg_id=1)
sherpa> group_snr(2, 10)

The function group_snr() requires an 'snr' value to indicate the minimum signal-to-noise ratio (snr) for each group of bins. In this example, first the default data set 1 is grouped so that the minimum snr per group is 3, and then the background associated with data set 1 is grouped so that the minimum snr per group is 5. In data set 2, each group of bin has a minimum snr of 10.

Example 4

sherpa> group_adapt(22)
sherpa> group_adapt(4, 13)

The function group_adapt() requires a 'min' value to indicate the minimum number of counts for each group of bins in low signal-to-noise regions (the bright features are adaptively ungrouped). In this example, data set 1 is grouped so that there are least 22 counts per group, and data set 4 has a minimum of 13 counts per group.

Example 5

sherpa> group_adapt_snr(5)
sherpa> group_adapt_snr("src1", 100)

The function group_adapt_snr() requires a 'min' value to indicate the minimum signal-to-noise ratio (snr) for each group of bins in low snr regions (the bright features are adaptively ungrouped). In this example, data set 1 is grouped so that the minimum snr per group is 5, and data set "src1" has a minimum snr per group of 100.

Example 6

sherpa> group_bins(23)
sherpa> group_bins(3, 30)

The function group_bins() requires a 'num' value to indicate the number to divide the number of channels. The first example shows how to group the default data set into 23 bins. The second examples groups data set id=3 into 30 bins.

Example 7

sherpa> group_width(16)
sherpa> group_width(3, 20)

The function group_width() requires a 'num' value to indicate the number of bins to create. The first example creates bins of 16 channels for the default data set. The second example divides the channels in data set id=3 into groups of 20.

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_plot, get_counts, get_data, get_data_plot, get_dep, get_dims, get_error, get_grouping, get_quality, get_specresp, get_staterror, get_syserror, 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, get_ratio, get_resid, histogram1d, histogram2d, image_data, rebin

Last modified: December 2016
Smithsonian Institute Smithsonian Institute

The Chandra X-Ray Center (CXC) is operated for NASA by the Smithsonian Astrophysical Observatory. 60 Garden Street, Cambridge, MA 02138 USA.   Email:   cxchelp@head.cfa.harvard.edu Smithsonian Institution, Copyright © 1998-2017. All rights reserved.