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

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


AHELP for CIAO 4.3 Sherpa v1

group_sherpa

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 dataset to group; if not given, uses the default dataset id (id=1 by default, see "ahelp get_default_id")
  • bkg_id - background data set ID, if the grouping is to be applied to the background data
  • 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 dataset ID. Specifically, it sets the "grouped" boolean in a Sherpa PHA dataset 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.

In all cases, resetting the grouping clears any filters already in place.

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 bins of data until the number of counts in each group exceeds the minimum number of counts specified in the 'min' argument, keeping bright features ungrouped while grouping low signal-to-noise regions.

group_adapt_snr()

This function allows the user to adaptively group PHA spectral data by signal-to-noise ratio, i.e., group bins of data 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 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 activate grouping of a background associated with a source data set, both the data ID and 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, 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(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, data set 1 is grouped so that the minimum snr per group is 3, and each group of bins in data set 2 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 dataset into 23 bins. The second examples groups dataset 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 dataset. The second example divides the channels in dataset 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, 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 2010
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-2019. All rights reserved.