BIN

 

This command should be used in order to bin photons from virtual photon lists which have been created by other SELECT or INPUT commands. Its general structure is

BIN/<optional_qualifier> <label_list> <binning_parameters>

where an identifier string may be optionally inserted at the beginning or at the end of the command line, as described above.

In case of 1-dimensional binning the label list must consist of a single label among the ones listed in Table 4.3 (see also Table 4.4).

The label list for a BIN/IMAGE command must contain two labels, either the pair XPIX, YPIX or the pair XDET, YDET (see Tables 4.2 and 4.3). When the label list is omitted, the pair XPIX,YPIX will be considered the default.      

The BIN command parameter list syntax is rather flexible. Commas and blanks are generally used as separators between the numerical values which describe the boundaries of the photon binning. Whenever the legibility of a command line would be improved, some of the commas may be optionally replaced by the string ``to''. The correct utilization of the separators will be apparent after a careful reading of the examples reported later on.

In the parameter list alternatively may be defined the binsize or the number of bins, and optionally the interval to be binned.

Generally in a BIN command only the binsize needs to be specified. As a default the input photons are binned in all of the (previously) selected intervals.   When binning the input photon list according to one of the parameters XPIX, YPIX, XDET, YDET (profiles) at least one SELECT/BOX command must have been performed previously.

In the following some BIN command lines are shown. They should be self explaining. Note that the symbol # is conventionally used in order to indicate the number of output bins.

BIN TIME  10
BIN TIME  0.01, 10000 to 20000
BIN AMPL  1
BIN/IMAGE #512,#512
BIN/IMAGE 30
BIN/IMAGE 30, (0,0) to (900,900)
BIN/IMAGE 30, (0,0), #30,#30

        Note that the last two commands produce the same effect. It is very important to note that in the TIME binning the binsize is a real number, while in all other cases the binsize is an integer. In fact, the photon parameters in a photon list are all integers (amplitude channels, sky and detector pixels), save for the TIME parameter. Therefore     the binning of the quantities RAW_AMPL, AMPL, XDET, YDET, XPIX, YPIX is actually a rebin operation.

In the TIME binning case, once the binsize and the extension [start, end] of the interval to be binned are defined, the n-th time bin goes from start + (n-1)binsize (included) to start + n binsize (excluded). This is valid in the absence of time gaps in the data. When a time bin would not be entirely included in the accepted times intervals listed in the header (descriptor TIM_SEL) it is rejected (this can be avoided by setting Projection in ``survey'' mode -- see section 4.3.6).        

In the binning of all of the other (integer) photon parameters the n-th bin is defined in the same way as the TIME bin, within the limits of integer arithmetic. A photon having for instance an amplitude channel ampl would belong to the bin number

where INT is the integer part function. This definition is extended consistently to sky or detector images created via the BIN command.

The binning in TIME creates binned datasets which differ in another property from those created by the BIN RAW_AMPL and BIN AMPL command strings. The difference is in the handling of possible gaps within such bin lists (the gaps in the input photon lists may be due, for instance, to previously performed selections). The bin lists generated by BIN RAW_AMPL and BIN AMPL command lines display data gaps as sequences of null bins. In the bin lists generated by a BIN TIME command the gaps are physically suppressed. The gap suppression turns out to be necessary in TIME bin lists, because time gaps happen to be in some cases very large.