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:

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