|AHELP for CIAO 4.2||
The S-Lang interface to the CXC grouping library
The group module is the interface between the S-Lang interpreter (see "ahelp slang") and the CXC group library (see "ahelp dmgroup"), which bins histogram data based on various user-selected rules. This document provides an overview of the features of the group module, and shows how to use it in a S-Lang program. Detailed descriptions of each function are provided by individual ahelp pages.
The group module is not available by default; to use it in a S-Lang program, it must be loaded using the S-Lang require() function:
The following functions are provided by the module; use "ahelp <function>" to get a detailed description of a function:
|Function name with arguments|
|(grouping, quality) = grpNumCounts(countsArray, numCounts [,maxLength,tabStops]);|
|(grouping, quality) = grpNumBins(numChans, numBins [, tabStops]);|
|(grouping, quality) = grpBinWidth(numChans, binWidth [, tabStops]);|
|(grouping, quality) = grpSnr(countsArray, snr [,maxLength, tabStops,errorCol]);|
|(grouping, quality) = grpAdaptive(countsArray, minCounts [,maxLength, tabStops]);|
|(grouping, quality) = grpAdaptiveSnr(countsArray, snr [,maxLength, tabStops, errorCol]);|
|(grouping, quality) = grpMinSlope(dataArray, binArray, slope [,maxLength, tabStops]);|
|(grouping, quality) = grpMaxSlope(dataArray, binArray, slope [,maxLength, tabStops]);|
|(grouping, quality) = grpBin(dataArray, binLowArray, binHighArray [,tabStops]);|
|(grouping, quality) = grpBinFile(dataArray, fDataArray, fGroupingCol, fQualCol [,tabStops]);|
|grpdata = grpGetGroupSum(dataArray, groupCol);|
|chanspergrp = grpGetChansPerGroup(groupCol);|
|grpnum = grpGetGrpNum(groupCol);|
The group module is intended to take an array of counts and group it, summing certain adjacent bins to increase the overall signal to noise. The available routines can group bins until each bin has a minimum number of counts (grpNumCounts), or until there are a fixed number of bins (grpNumBins), or simply group a fixed number of bins together (grpBinWidth). More complex grouping algorithms exist to bin data adaptively until a minimum signal to noise ratio is met, as well as other methods. See "ahelp <function>" for more details on the individual functions.
Some parameters are optional; these are shown in the function calls listed above inside s. Any optional parameter can be omitted; if you want to use the default for one optional parameter but set an optional parameter that follows it, simply include an extra comma for each skipped parameter. See the EXAMPLE section below for more details.
Most of the grouping functions output two arrays, a grouping array and a quality array. The grouping array is a vector the same length as the data to be grouped. The grouping vector is 1 at the start of a new "grouped" bin and -1 at a continuation. A grouping array of
[ 1, -1, 1, -1, 1, -1 ]
indicates that a 6 element array will be grouped into 3 groups, each containing 2 elements. The quality array is the same length, with values of 0 to indicate good data, 5 to indicate data omitted by the user in the grouping call (i.e., within a tabStop), or 2 to indicate data without enough channels to make a complete bin (i.e., the 13th channel in a 13-element array binned by 3s). For the complete definition of these two arrays, see the OGIP Memo OGIP/92-007
slsh> require("group"); slsh> ChanArr = [1:1024:1]; slsh> CountArr = 5 + 3*sin(ChanArr/100.); % Group to get at least 5 counts per bin, with a maximum of 10 channels binned together. slsh> (grpArr1, QualArr1) = grpNumCounts(CountArr, 5, 10); % Group input vector into 150 bins slsh> GrpCount1 = grpGetGroupSum(CountArr, grpArr1); % Extract only 1 channel for each binned group slsh> GrpChan1 = ChanArr[where(grpArr1==1)];
See the bugs page for the group library on the CIAO website for an up-to-date listing of known bugs.