Last modified: December 2013

URL: https://cxc.cfa.harvard.edu/ciao/ahelp/group.html
Jump to: Description · Example · Bugs · See Also


AHELP for CIAO 4.16

group

Context: group

Synopsis

Provides the Python interface to the CXC grouping library

Description

The group module is the interface between the Python interpreter and the CXC group library (see "ahelp dmgroup"), which bins 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 Python 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 Python program, it must be loaded using the Python import function, by saying one of:

from group import *
import group

Functions provided by the module

The following functions are provided by the module; use "ahelp <function>" to get a detailed description of a function:

Function Description
grpNumCounts Group by the number of counts
grpNumBins Group by the number of input bins
grpBinWidth Group by the bin width
grpSnr Group by the signal-to-noise value
grpAdaptive Adaptive binning based on the number of counts
grpAdaptiveSnr Adaptive binning based on the signal-to-noise value
grpMinSlope Ensure the gradient is below a value
grpMaxSlope Ensure the gradient is above a value
grpBin Select the individual bin edges
grpBinFile Read the grouping information from a file
grpGetGroupSum Group an array
grpGetChansPerGroup Calculate the size of each grouped element
grpGetGrpNum Calculate the element numbering in the given grouping scheme

Purpose

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.

Optional Parameters

Some parameters are optional; these are shown in the function calls listed in the individual ahelp pages 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 use a keyword in front of the included optional parameter.

Function output

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


Example

Given the following:

>>> from group import *
>>> import numpy as np
>>> ChanArr = np.arange(1, 1025, 1)
>>> CountArr = 5 + 3 * np.sin(ChanArr/100)

we can group to get at least 5 counts per bin, with a maximum of 10 channels binned together by saying

>>> (grpArr1, QualArr1) = grpNumCounts(CountArr, 5, 10)

or group the input vector into 150 bins

>>> (grpArr2, QualArr2) = grpNumBins(1024, 150)
# (CIAO): WARNING: More groups produced than requested.

where the error message indicates that not all input elements could be fit into the requested scheme (these "excess" elements are indicated with a quality value of 2 in the QualArr2 array).

Once a grouping scheme has been created - in this example the grpArr1 scheme created above - we can apply it to create the grouped data using grpGetGroupSum():

>>> GrpCount1 = grpGetGroupSum(CountArr, grpArr1)

Here we extract the left-edge of each grouped bin as x1 and the corresponding grouped value as y1

>>> f = grpArr1 == 1
>>> x1 = ChanArr[f]
>>> y1 = GrpCount1[f]

Bugs

There are no known bugs for this tool.

See Also

group
grpadaptive, grpadaptivesnr, grpbin, grpbinfile, grpbinwidth, grpgetchanspergroup, grpgetgroupsum, grpgetgrpnum, grpmaxslope, grpminslope, grpnumbins, grpnumcounts, grpsnr