acisevents - Find ACIS events from a FITS file. The program requires the following runtime options: ethreshold, sthreshold. The program outputs a fits eventlist containning the x, y location of the events, the flight grade, the frame exposure number, and the total energy of each event and the value of each pixel in the 3x3 island.
The input FITS image file must have the following keywords: NCCD, EXPOSURE, CCDOCLKS, CCDNCOLS, DATETIME, IRIGTIME. Where DATETIME is of the form: 'Thu Mar 15 12:25:08 2001' and IRIGTIME is an integer denoting the number of seconds from the start of the year.
acisevents [ --biasfile | -b biasfilename ]
[ --coloffset | -c numcoloffset ]
[ --debug | -d debuglevel ]
[ --ethreshold | -e theeventthreshold ]
[ --fct fct2modifyevents ]
[ --biasalgo | -a { quadrant | row-by-row } ]
[ --mpar | -m key=value ]
[ --output | -o outputfilename ]
[ --pthreshold | -p theprecursorthreshold ]
[ --range | -r [start]:[end] or [start]/count ]
[ --sthreshold | -s thesplitthreshold ]
[ --Stats | -S { avg | median } ] [ --usage ]
[ --version | -v ]
[ cxccti --ardfname | -f --ccd_id | -c --convergence --iteration ]
-- file | @filename
This program can either be used as an ACIS event list generator (if the option fct is missing from the command line argument) or as a program to generate the ACIS events and to modify them (if the option fct is present at the command line argument).
The user must supply a function to modify the events, the modification is done through an embedded language interface (CINT, see http://root.cern.ch/root/Cint.html). CINT is a C/C++ interpreter which covers about 95% of ANSI C and 85% of C++. By using the CINT C++ interpreter, the program enables the user to quickly prototype the model functions without going through the lengthy compile/link cycle. The resulting model functions can be compiled if faster performance is needed since they are written in C/C++.
The program outputs a level 1 ACIS FITS file.
Options may be abbreviated. Options which take values may be separated from their values either by white space. If some arguments begin with a dash, then a double dash must preceed the file list.
The options are :
For example, to use the biasfile mybiasfile.fits, with the input files /pool1/*.fits. Type:
acisevents --biasfile mybiasfile.fits --biasalgo quadrant --Stats avg --ethreshold 38 --sthreshold 13 -- /pool1/*.fits
or
acisevents -b mybiasfile.fits -a quadrant -S avg -e 38 -s 13 -- /pool1/*.fits
For example,
acisevents -b ../../data/obs61705_bias.fits -o foo.fits -e 38 -s 13 -c 15 -a classic cxccti --ardfname /pool1/foo.fits --ccd_id 1 --convergence 0.5 --iteration 15 -- ../../data/cuckoo.1111.fits | more
For example, to set the
acisevents --biasfile mybiasfile.fits --biasalgo quadrant --Stats avg --ethreshold 38 --sthreshold 13 --coloffset 35 -- /pool1/*.fits
or
acisevents -b mybiasfile.fits -a quadrant -S avg -e 38 -s13 -w -c 35 -- /pool1/*.fits
For example, to verify that -1, 3 and 1 are being added to the 1st, 2nd and 3rd column (see, the file mymodify.cc below). Type:
acisevents --debug 2 -b ../../data/obs61705_bias.fits -o foo.fits -e 38 -s 13 -c 15 -a classic --fct mymodify.cc -- ../../data/cuckoo.1111.fits | more
or
acisevents -d 2 -b ../../data/obs61705_bias.fits -o foo.fits -e 38 -s 13 -c 15 -a classic --fct mymodify.cc -- ../../data/cuckoo.1111.fits | more ../../data/cuckoo.1111.fits
expno = 1111, row = 58, col = 6, xpos = 20, ypos = 57
________________________ ________________________
| | | | | | | |
| 44 | 45 | 55 | | 43 | 48 | 56 |
| | | | | | | |
------------------------ ------------------------
| | | | | | | |
| 30 | 58 | 50 | | 29 | 61 | 51 |
| | | | | | | |
------------------------ ------------------------
| | | | | | | |
| 27 | 17 | 44 | | 26 | 20 | 45 |
| | | | | | | |
------------------------ ------------------------
adu = 370, fltgrade = 255 adu = 373, fltgrade = 255
....
acisevents --help
or
acisevents -h
For example, to use the biasfile mybiasfile.fits, with the input file /pool1/*.fits with the event threshold hold set at 38. Type:
acisevents --biasfile mybiasfile.fits --biasalgo quadrant --Stats avg --ethreshold 38 --sthreshold 13 -- /pool1/*.fits
or
acisevents --b mybiasfile.fits -a quadrant -S avg -e 38 -s 13 -- /pool1/*.fits
//
// The initialization function, this function will
// be called before any event is processed.
//
int foo_init( );
//
// The function to modify:
//
int foo( short island_column, short island_row[], double island_pha[],
short num_precursor, short precursor_row[],
short precursor_pha[] )
//
// The clean up function. This function will
// be called after the events are processed.
//
int foo_final( );
For example, to use the function simplemodify in the file simplemodify.cc in the current directory where the program is run at type:
acisevents -b obs61705_bias.fits -a quadrant -S avg -o foo.fits -e 38 -s 13 -c 953 --mpar cti=1.4e-4 --fct simplemodify.cc --pthreshold 24 -- /pool1/*.fits
or
acisevents -b obs61705_bias.fits -a quadrant -S avg -o foo.fits -e 38 -s 13 -c 953 -m cti=1.4e-4 -f simplemodify.cc -p 24 -- /pool1/*.fits
See Event modification interface for more details.
For example, to use a quadrant option:
acisevents --b mybiasfile.fits --biasalgo quadrant -S avg -e 38 -s 13 -- /pool1/*.fits
or
acisevents --b mybiasfile.fits -a quadrant -S avg -e 38 -s 13 -- /pool1/*.fits
acisevents -b obs61705_bias.fits -a quadrant -S avg -o foo.fits -e 38 -s 13 -c 953 --mpar foo=3 --mpar bar=5 --fct simplemodify --pthreshold 24 -- /pool1/*.fits
or
acisevents -b obs61705_bias.fits -a quadrant -S avg -o foo.fits -e 38 -s 13 -c 953 -m foo=3 -m bar=5 --fct simplemodify --pthreshold 24 -- /pool1/*.fits
acisevents --biasfile mybiasfile.fits --ethreshold 38 --sthreshold 13 --output foo -- /pool1/*.fits
or
acisevents --b mybiasfile.fits -e 38 -s 13 -o foo -- /pool1/*.fits
r1,r2,r3
The file index must be delimited by a period
(.), dash (-) or underscore (_). For example the files must be of
the form: /pool1/foo.1234.fits, /pool1/foo-1234.fits, or
/pool1/foo_1234.fits respectively.
For example, to select file /pool1/cuckoo.1107.fits to the end, type:
acisevents --range 1107: --biasfile mybiasfile.fits --ethreshold 38 --sthreshold 13 --output foo -- /pool1/*.fits
or
acisevents -r 1107: --biasfile mybiasfile.fits --ethreshold 38 --sthreshold 13 --output foo -- /pool1/*.fits
To select file /pool1/cuckoo.1101.fits through /pool1/cuckoo.1107.fits and /pool1/cuckoo.1115.fits through /pool1/cuckoo.1119.fits, type:
acisevents --range 1101:1107,1115:1119 --biasfile mybiasfile.fits --ethreshold 38 --sthreshold 13 --output foo -- /pool1/*.fits
or
acisevents -r 1101:1107,1115:1119 --biasfile mybiasfile.fits --ethreshold 38 --sthreshold 13 --output foo -- /pool1/*.fits
To select 17 files after file /pool1/cuckoo.1100.fits, type:
acisevents --range 1100/17 --biasfile mybiasfile.fits --ethreshold 38 --sthreshold 13 --output foo -- /pool1/*.fits
or
acisevents -r 1100/17 --biasfile mybiasfile.fits --ethreshold 38 --sthreshold 13 --output foo -- /pool1/*.fits
For example, to use the median:
acisevents --b mybiasfile.fits -a quadrant -Stats median -e 38 -s 13 -- /pool1/*.fits
or
acisevents --b mybiasfile.fits -a quadrant -S median -e 38 -s 13 -- /pool1/*.fits
acisevents --biasfile mybiasfile.fits --ethreshold 38 --sthreshold 13 -- /pool1/*.fits
or
acisevents --b mybiasfile.fits -e 38 -s 13 --/pool1/*.fits
acisevents --usage
For example:
acisevents --version
or
acisevents -v
An event is defined by the following criteria: The value of the center pixel of a 3x3 island must be the local maximum within the 3x3 island and the value must strictly greater then ( > ) the event threshold after the bias substraction has been made. If the neighboring pixels have the same value as the center value, then the island where the row and column center with the smallest value shall be chosen as the event. The event threshold is a run time option of the program.
The output of the program is a FITS bintable containing the following columns: The x and y location of the 3x3 center pixel of the event, respectively. The value of the pixels in the 3x3 island, the flight grade and the total energy of the event. The flight grade and total energy are calculated using the following criteria: The flight grade is the cummulative sum of the 2^label (where the label for each pixel within the 3x3 island is given in the figures below depending on which quadrant the 3x3 island lies in) if the value of the pixel is greater or equal ( <= ) to the split threshold and the value of the pixel is less then or equal
The total energy is the cummulative sum of all the pixels within the 3x3 island which is greater ( < ) or greater or equal ( <= ) to the split threshold according to the rules given in the figures below, the value of the center island is always added.
______ _____ _____
| | | |
| 5 | 6 | 7 |
| < | < | < |
|______|_____|_____|
| | | |
| 3 | | 4 |
| <= | | < |
|______|_____|_____|
| | | |
| 0 | 1 | 2 |
| <= | <= | <= |
|______|_____|_____|
Where the integers [0..7] indicate the label of the pixel within the 3x3 island and the less then and less then or equal to signs (< and <= ) indicate the comparison used to compare the value of the pixel with the split threshold to calculate the flight grade and the total energy.
The acisevents program makes the following assumptions:
CCDOCLKS
->| |<-
___ __________...__________ _.._
| | || |
| | || |
| | || |
| | || |
| | || |
| | || |
NAXIS2 . .. .
or . .. .
CCNROWS . .. .
|
| | || |
| | || |
_|_ ___________..._________ _.._
|------- CCDNCOLS ------|
|---------- NAXIS1 ----------|
Where the NAXIS1, NAXIS2, CCNCOLS and CCDOCLKS are written
in the header of the input FITS file.
The data (image plus overclock) is stored as a two dimensional array of size NAXIS2 (CCDNROWS) by NAXIS1. The sub-arrays of size CCDNROWS by CCDNCOLS and CCDNROWS by CCOCLKS contain the image and the overclock, respectively. The program assumes that NAXIS1 = CCDNCOLS + CCDOCLKS. There overclock correction can be done either as a quadrant or row-by-row, the details are given below:
Quadrant:
image( i, j ) -= biasimage( i, j ) + biasstat - imagestat
Where a -= b means a = a - b, image( i, j ) is the ith, jth pixel in the data frame, biasimage( i , j ) is the ith, jth pixel in the bias map, biasstat is the average or the median of the overclock sub-array in the bias map, imagestat is the average or the median of the overclock sub-array in the data frame.
Row-by-Row:
image( i, j ) -= biasimage( i, j ) + biasstat( i ) - imagestat( i )
Where a -= b means a = a - b, image( i, j ) is the ith, jth pixel in the data frame, biasimage( i , j ) is the ith, jth pixel in the bias map, biasstat( i ) is the average or the median of the ith row of the overclock in the bias map, imagestat( i ) is the average or the median of the ith row of the overclock in the data frame.
The function which will be used to modify the events. The filename where the function is stored at must have the same name (with a .cc extension) as the function name. For example the function foo must be written in the file called foo.cc. The file must contain three functions:
//
// The initialization function, this function will
// be called before any event is processed.
//
int foo_init( );
//
// The function to modify:
//
int foo( short island_column, short island_row[], double island_pha[],
short num_precursor, short precursor_row[],
short precursor_pha[] )
Note: All arrays start with the index at 0.
1) short island_column, a short which ranges from 0, 1 or 2 to
denote the column of the island.
2) short island_row[ 3 ], is a short array of dimension 3.
It contains the row number of the island's column.
3) double island_pha[ 3 ], is a double array of dimension 3. It
contains the value of the pha of the island's column.
A double array is passed but the returned value will be
truncated to a short once the user has finished modifying
its contents.
4) short num_precursor, a short to denote the number of
precursors.
5) short precursor_row[ num_precursor ], a short array of
dimension num_precursor containing the row of the precusor
which exceeds the precursor threshold.
6) short precursor_pha[ num_precursor ], a short array of
dimension num_precursor containing the value of the pha of
the precusor which exceeds the precursor threshold.
A pixel is considered to be part of the precursor if its pha
value is greater or equal to the precursor threshold.
Note that for column 0 and 2, the precursor may end at the
last row of the island if its pixel value is greater then ( > )
the precursor threshold. For the middle column, the precursor
must end after the island.
island_column==0 island_column==1 island_column==2
__________________ __________________ __________________ 3
| | | |
| island_row[ 0 ] | island_row[ 0 ] | island_row[ 0 ] | b
| island_pha[ 0 ] | island_pha[ 0 ] | island_pha[ 0 ] | y
|__________________|__________________|__________________|
| | | | 3
| island_row[ 1 ] | island_row[ 1 ] | island_row[ 1 ] |
| island_pha[ 1 ] | island_pha[ 1 ] | island_pha[ 1 ] | i
|__________________|__________________|__________________| s
| | | | l
| island_row[ 2 ] | island_row[ 2 ] | island_row[ 2 ] | a
| island_pha[ 2 ] | island_pha[ 2 ] | island_pha[ 2 ] | n
|__________________|__________________|__________________| d
. . .
. . __________________
. . | |
. . |precursor_row[n-1]|
. . |precursor_pha[n-1]|
. . |__________________|
. __________________ .
. | | .
. |precursor_row[ n ]| .
. |precursor_pha[ n ]| .
. |__________________| .
__________________ . .
| | . .
|precursor_row[n-1]| . .
|precursor_pha[n-1]| . .
|__________________| . .
. . .
. __________________ .
. | | .
. |precursor_row[ 0 ]| .
. |precursor_pha[ 0 ]| .
. |__________________| .
. . .
. . __________________
. . | |
. . |precursor_row[ 0 ]|
__________________ . |precursor_pha[ 0 ]|
| | . |__________________|
|precursor_row[ 0 ]| .
|precursor_pha[ 0 ]| .
|__________________| .
//
// The clean up function. This function will
// be called after the events are processed.
//
int foo_final( );
It is not necessary to compile the file where the user's modification of the acis events in order to run it; However, it is recommended that the user uses the C++ compiler to find any syntax error, this is done by typing the following command:
CC -I/proj/axaf/simul/include -c simplemodify.cc
Where myprogram.cc is the name of the file where the user's definitions are defined.
// Uncomment the following line if the functions in this file are to be compiled //#pragma compile
#include <iostream> #include <stdlib.h>
#include "aciseventsAccessibleFcts.h"
// // Define cti as a global variable. The value will be set at // the command line. See the simplemodify_init( ) for details. // double cti = 0.0;
int simplemodify_init( ) {
//
// Get the 'cti' parameter as entered from the command line
//
if ( EXIT_FAILURE == get_model_parameters( "cti", cti ) )
return EXIT_FAILURE;
return EXIT_SUCCESS;
}
/*
*
* ADU [corrected] = ADU [detected] / {1- CTI * row number of event}
*
* at the moment let's take CTI=1.4 * 10-4 (i3 avg.)
*
*/
int simplemodify( short island_column, short island_row[], double island_pha[],
short num_precursor, short precursor_row[],
short precursor_pha[] ) {
// double cti = 1.4e-4;
for ( short ii = 0; ii < 3; ii++ ) {
island_pha[ ii ] /= ( 1.0 - cti * island_row[ ii ] );
}
/*
// loop through the precursor to do with whatever suits one's fancy.
for ( short ii = 0; ii < num_precursor; ii++ ) {
// purposely do nothing
}
*/
return EXIT_SUCCESS;
}
int simplemodify_final( ) {
cout << "good bye cruel world\n";
return EXIT_SUCCESS;
}
// Uncomment the following line if the functions in this file are to be compiled // #pragma endcompile
Several functions have been written for the users to use:
/** * * The prototype for all the compiled functions * which are accessible by the users using CINT. * */
// // To get the model parameters which are set at the command line. // The arguments, key and value, denote the parameters which were // entered at the command line respectively. // The function returns EXIT_SUCCESS if the parameter is entered // at the command line. The function returns EXIT_FAILURE if the // parameter is entered a the command line. // int get_model_parameters( const char* key, double& value );
/** * max */
// // Get the maximum value of the short array of dimension [ 0 .. num-1 ] // short get_max_value( short num, short* array );
// // Get the maximum value of the double array of dimension [ 0 .. num-1 ] // double get_max_value( short num, double* array );
// // Get the bing where the maximum value of the // short array of dimension [ 0 .. num-1 ] // short get_max_bin( short num, short* array );
// // Get the bing where the maximum bin of // the double array of dimension [ 0 .. num-1 ] // double get_max_bin( short num, double* array );
/** * min */
// // Get the minimum value of the short array of dimension [ 0 .. num-1 ] // short get_min_value( short num, short* array );
// // Get the minimum value of the double array of dimension [ 0 .. num-1 ] // double get_min_value( short num, double* array );
// // Get the bing where the minimum value of the // short array of dimension [ 0 .. num-1 ] // short get_min_bin( short num, short* array );
// // Get the bing where the minimum bin of // the double array of dimension [ 0 .. num-1 ] // double get_min_bin( short num, double* array );
To use the aforementioned function, the user must include the following line (to declare the prototype):
#include "aciseventsAccessibleFcts.h"
See the file mymodify.cc in the option flag debug for an example.
The user's functions can be compiled for faster execution by including the line
#pragma compile
and
#pragma endcompile
as the first and last line of the user's function. See the files mymodify.cc or simplemodify.cc for an example.