Binning or Histogramming Specification

One of the powerful features of CFITSIO's virtual file syntax is the ability to create a 2-dimensional image (or 'histogram') on the fly by binning the values in a pair of columns in a FITS table. This is frequently used with 'event list' tables to bin the columns that contain the X and Y coordinate of each event to create a FITS primary array image of all the events. Each pixel in the 2-dimensional histogram records the number of events that occur within the spatial coordinates defined by of that pixel. The virtual FITS file that is opened by the application program consists only of the primary array image and not the FITS table from which it was constructed.

This technique is not limited to just creating 2 dimensional images. It can also be used to create a 1-dimensional array (e.g., a spectrum or light curve) by binning a single table column, or a 3 or 4 dimensional data cube by binning over 3 or 4 columns.

Binning Syntax

The binning filter begins with the string 'bin' enclosed in square brackets, and is appended to the root file name and optional extension specifier. There are several forms of binning filter, and the general syntax is:

  [bin{bijrd} Xcol=min:max:binsize, Ycol= ..., Zcol=...; weight]

  or

  [bin{bijrd} (Xcol, Ycol, ...) = min:max:binsize; weight]

  or

  [bin{bijrd} @file.txt]

By default the created primary array image will have a 32-bit signed integer datatype except if the weighting option is also specified in which case the image will have a 32-bit floating point data type. The default datatype may be overridden by appending a code letter to the 'bin' keyword as follows:
   binb -  8-bit unsigned byte
   bini - 16-bit signed integers
   binj - 32-bit signed integers
   binr - 32-bit floating points
   bind - 64-bit double precision
For example,
   file.fits[events][bini detx = 1:500:10, dety = 1:500:10]
means "bin the DETX and DETY columns in the EVENTS extension over the range from 1 to 500 using a bin size of 10 in both dimensions. This will create a 50 by 50 pixel 16-bit integer image. Since these are integer data type columns, the min and max range limits are both inclusive. If the columns have a floating point data type then the binning range includes the lower limit value but excludes the upper limit value.

In the general case, as shown in the above example, the column name is followed by an equals sign and then the lower and upper range of the histogram, and the size of the histogram bins, separated by colons. Spaces are allowed before and after the equals sign but not within the 'min:max:binsize' string. The min, max and binsize values may be integer or floating point numbers, or they may be the names of keywords in the header of the table. If the latter, then the value of that keyword is substituted into the expression.

If the binning ranges or size are not specified, CFITSIO will use default values as given by the TLMINn, TLMAXn, and TDBINn keywords (where 'n' represents the column number) if they exist in table header. If the keywords do not exist then the actual minimum and maximum values in the column will be used for the histogram min and max values and the default binsize will be set to 1, or (max - min) / 20., whichever is smaller.

The column names are case insensitive, and the column number may be given instead of the name, preceded by a pound sign (e.g., [bin #4=1:512]). If the column name is not specified, then CFITSIO will first try to use the 'preferred columns' as specified by the CPREF keyword (e.g., 'CPREF = 'DETX,DETY') if it exists, otherwise column names 'X', 'Y', 'Z', and 'T' will be assumed for each of the 4 axes, respectively.

The following example illustrated the possible variations in syntax:

       [bin x = :512:2]  - use default minimum value
       [bin x = 1::2]    - use default maximum value
       [bin x = 1:512]   - use default bin size
       [bin x = 1:]      - use default maximum value and bin size
       [bin x = :512]    - use default minimum value and bin size
       [bin x = 2]       - use default minimum and maximum values
       [bin x]           - use default minimum, maximum and bin size

       [bin 4]           - default 2-D image, bin size = 4 in both axes
       [bin]             - default 2-D image

A shortcut notation is allowed if all the columns/axes have the same binning specification. In this case all the column names may be listed within parentheses, followed by the (single) binning specification, as in:

   [bin (X,Y)=1:512:2]
   [bin (X,Y) = 5]      - use bin size = 5

The optional weighting factor is the last item in the binning specifier and, if present, is separated from the list of columns by a semi-colon. As the histogram is accumulated, this weight is used to incremented the value of the appropriated bin in the histogram. If the weighting factor is not specified, then the default weight = 1 is assumed. The weighting factor may be a constant integer or floating point number, or the name of a keyword containing the weighting value. Or the weighting factor may be the name of a table column in which case the value in that column, on a row by row basis, will be used.

In some cases, the column or keyword may give the reciprocal of the actual weight value that is needed. In this case, precede the weight keyword or column name by a slash '/' to tell CFITSIO to use the reciprocal of the value when constructing the histogram.

For complex or commonly used histograms, one can also place its description into a text file and import it into the binning specification using the syntax '[bin{bijrd} @filename.txt]'. The file's contents can extend over multiple lines, although it must still conform to the no-spaces rule for the min:max:binsize syntax and each axis specification must still be comma-separated. Any lines in the external text file that begin with 2 slash characters ('//') will be ignored and may be used to add comments into the file.

Combined Filtering

The binning specifier can be combined with other filters to make an image of only selected rows in the table. For example:
  file.fits[events][pi < 100][bin (X,Y) = 1:500:10]
will first create a virtual table containing only the rows that have a PI column value less than 100, which will be used to create a virtual image by binning the X and Y columns. Similarly,
  file.fits[events][regfilter("stars.reg")][bin (X,Y) = 1:500:10]
will first filter the table to keep only those rows with X and Y column values that are within the spatial region defined by the 'stars.reg' region file. All the pixels in the binned image that lie outside the defined region will be equal to zero.

EXAMPLES


    [bini detx, dety]                - 2-D, 16-bit integer histogram
                                       of DETX and DETY columns, using
                                       default values for the histogram
                                       range and binsize.

    [bin (detx, dety)=16; /exposure] - 2-D, 32-bit real histogram of DETX
                                       and DETY columns with a bin size=16
                                       in both axes. The histogram values
                                       are divided by the EXPOSURE keyword
                                       value.

    [bin time=TSTART:TSTOP:0.1]      - 1-D lightcurve, range determined by
                                       the TSTART and TSTOP keywords, 
                                       with 0.1 unit size bins.  
 
    [bin pha, time=8000.:8100.:0.1]  - 2-D image using default binning
                                       of the PHA column for the X axis,
                                       and 1000 bins in the range 
                                       8000. to 8100. for the Y axis.
    
    [bin @binFilter.txt]             - Use the contents of the text file
                                       binFilter.txt for the binning
                                       specifications.

SEE ALSO

filenames, colfilter, rowfilter, imfilter. pixfilter. calc_express.