Fits Binary Table Binning

The rows in a FITS binary table must be binned before being displayed as an image. By default, JS9 used a bin factor of 1 to extract the central 1024 x 1024 section of the data for display.

The Binning plugin allows you to bin FITS binary table data in other ways, by choosing the bin factor, the center and the image dimensions. It also allows you to filter rows of the table by means of arithmetic and boolean operations on the table columns.

When binning, you can set one or more of the following options:

For example, if a table has FITS (tlmin, tlmax) dimensions 4096 x 4096, then:

Table filtering allows you to select rows from an FITS binary table (e.g., an X-ray event list) by checking each row against an expression involving the columns in the table. When a table is filtered, only valid rows satisfying these expressions are used to make the image.

A filter expression consists of an arithmetic or logical operation involving one or more column values from a table. Columns can be compared to other columns or to numeric constants. Standard JavaScript math functions can be applied to columns. JavaScript (or C) semantics are used when constructing expressions, with the usual precedence and associativity rules holding sway:

  Operator                                Associativity
  --------                                -------------
  ()                                      left to right
  !  (bitwise not) - (unary minus)        right to left
  *  /                                    left to right
  +  -                                    left to right
  < <= > >=                               left to right
  == !=                                   left to right
  &  (bitwise and)                        left to right
  ^  (bitwise exclusive or)               left to right
  |  (bitwise inclusive or)               left to right
  && (logical and)                        left to right
  || (logical or)                         left to right
  =                                       right to left
For example, if energy and pha are columns in a table, then the following are valid expressions:
  pha > 1
  energy == pha
  pha > 1 && energy <= 2
  max(pha,energy)>=2.5

NB: when using cfitsio (the default, instead of fitsy.js), table filtering follows cfitsio conventions, which is documented here.

NB: the range list support described below works only when using fitsy.js. It does not work for cfitsio.

In addition to the standard JavaScript/C syntax, fitsy.js filter expressions can make use of IRAF-style range lists which specify a range of values. The syntax requires that the column name be followed by an '=' sign, which is followed by a range expression of the form:

  col = :v            # col <= v in range
  col = v:            # col >= v in range
  col = v1:v2         # v1 <= col <= v2 in range
The v values above must be numeric constants.

[A note for DS9/funtools users: the DS9/funtools syntax supported a comma operator, which I now consider to be one of the bigger design mistakes of my career. The problem is that the operator either meant logical AND or logical OR, depending on context. This led to a lot of confusion. For JS9, the comma operator has been removed, so that you now explicitly and clearly specify the logical operator:

  pi=1:4 || pi=7:9    # equivalent to DS9's pi=1:4,7:9
  pi > 5 || pha > 6   # equivalent to DS9's pi > 5, pha > 6
  pi > 5 && pha > 6   # this had no comma equivalent and caused confusion!
Hmmm ... I might have mixed up the last two examples. QED]

Once the desired parameters have been set, pressing the Rebin button will filter, bin and display the data.