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.