$Id: cdi.html,v 1.1 2019/09/05 09:27:11 wwwadmin Exp $

NeSDaC

cdi, create a detector image

NAME

cdi - create a detector-image from one or several eventfile(s)

SYNOPSIS

cdi
cdi -p [options] evl di
cdi -q

The program can be started with no arguments at all, in which case the parameter values are taken from the parameterfile.
Alternatively, values can be passed via the commandline, the required items as command arguments, the optional ones as valued switches.

The last form (cdi -q) creates the parameterfile in $PFILES.

The table lists all the parameters used by cdi, the second column lists the paramater key names used in the parameterfile, the first column gives the corresponding switch letter,
cdi parameters
switch key value IO description
expfile string o di, detector image file (FITS).
evtfile list i evl, simple eventfile or list of eventfiles.
g gtifile string i the event selection time intervals are read from the g(ood)t(ime)i(nterval) file gti. Default action is to apply the HK data based gti-file created during WFC-StageI.
Explicit selection of a time interval (-t,-T) cancels the automatic use of the gtifile, an explicit -g filename will be used.
t t_filtr range i select events within one of the time intervals, events from the intervals are gathered into one image. The time interval must be specified in modified julian days (MJD). By default, all events are used. The time unit is not particularly easy to use, the numbers are large and do not readily relate to a date, however it allows you to select any event detected over the WFC's life time. Several interval can be specified in the form of a comma separated list.
T t_ftrsec range i as -t, however the interval time(s) is in seconds from the start time of the first input(event) file.
(if both -t and -T are present, the -T switch is ignored.
e e_filtr range i for a value e0-e1 assemble a detector image, selecting events with an energy in the WFC-channel range from e0 to e1 (incl). You can specify more ranges (up to 32), each range defines a detector image. The images are stored as a 3 dimensional FITS image. The default value of this parameter is 1-31, ie. generate 1 image with no energy resolution, all events are accumulated in one detector image.
z z_filtr range i Select events detected in the lower (-z0 (equiv. -z0-0)) or the upper ((-z1) detector compartment. default value is (-z0-1), do not discriminate.
p p_filtr area i area= x0-x1:y0-y1. Select events with a detector coordinate in a rectangle with lower left corner (x0,y0) and upper right corner (x1,y1). Several area's can be specified in the form of a comma separated list.
px p_filtr area i As above, but reject events in the specified area (-list).
w wsbar int i select events detected under a support structure bar (i= 1) or only those events NOT under such a bar (i= -1). (i= -1 is not equivalent to a run with no -w parameter at all, explain).
b tbin real i append to the outputfile a count vs. time histogram (lightcurve) of the events in the form of a FITS Binary table. The parameter value specifies the resolution (time-bin length) in seconds. The table will contain a column for every detector plane created, only the events selected for the image are used in the lightcurve
f b_filtr int i In cases of non-nominal satellite stability, the StageI processing software has the option to partition the observation period in a number of intervals. For each interval a nominal instrument pointing is computed, event detector(!) coordinates are corrected for drift within this interval and the event is labeled with the interval's index. The -b switch selects the events with a particular range of pointing indeces. (b0 is equivalent to b0-b0). Currently, the StageI software deos not provide this functionality.
(Alternative - we may delete this procedure, as the pointing clusters define a event partition in time also, providing the user with the time intervals for a selected pointing makes this event labeling superfluous.)
I insfile string i overrides the IDF name as inferred from the (first) input eventfile.

p, L, i StageII global switches

cdi parameters
switch	key	value	IO	description
	expfile	string	o	di, detector image file (FITS).
	evtfile	list	i	evl, simple eventfile or list of eventfiles.
g	gtifile	string	i	the event selection time intervals are read from the g(ood)t(ime)i(nterval) file gti. Default action is to apply the HK data based gti-file created during WFC-StageI. Explicit selection of a time interval (-t,-T) cancels the automatic use of the gtifile, an explicit -g filename will be used.
t	t_filtr	range	i	select events within one of the time intervals, events from the intervals are gathered into one image. The time interval must be specified in modified julian days (MJD). By default, all events are used. The time unit is not particularly easy to use, the numbers are large and do not readily relate to a date, however it allows you to select any event detected over the WFC's life time. Several interval can be specified in the form of a comma separated list.
T	t_ftrsec	range	i	as -t, however the interval time(s) is in seconds from the start time of the first input(event) file. (if both -t and -T are present, the -T switch is ignored.
e	e_filtr	range	i	for a value e0-e1 assemble a detector image, selecting events with an energy in the WFC-channel range from e0 to e1 (incl). You can specify more ranges (up to 32), each range defines a detector image. The images are stored as a 3 dimensional FITS image. The default value of this parameter is 1-31, ie. generate 1 image with no energy resolution, all events are accumulated in one detector image.
z	z_filtr	range	i	Select events detected in the lower (-z0 (equiv. -z0-0)) or the upper ((-z1) detector compartment. default value is (-z0-1), do not discriminate.
p	p_filtr	area	i	area= x0-x1:y0-y1. Select events with a detector coordinate in a rectangle with lower left corner (x0,y0) and upper right corner (x1,y1). Several area's can be specified in the form of a comma separated list.
px	p_filtr	area	i	As above, but reject events in the specified area (-list).
w	wsbar	int	i	select events detected under a support structure bar (i= 1) or only those events NOT under such a bar (i= -1). (i= -1 is not equivalent to a run with no -w parameter at all, explain).
b	tbin	real	i	append to the outputfile a count vs. time histogram (lightcurve) of the events in the form of a FITS Binary table. The parameter value specifies the resolution (time-bin length) in seconds. The table will contain a column for every detector plane created, only the events selected for the image are used in the lightcurve
f	b_filtr	int	i	In cases of non-nominal satellite stability, the StageI processing software has the option to partition the observation period in a number of intervals. For each interval a nominal instrument pointing is computed, event detector(!) coordinates are corrected for drift within this interval and the event is labeled with the interval's index. The -b switch selects the events with a particular range of pointing indeces. (b0 is equivalent to b0-b0). Currently, the StageI software deos not provide this functionality. (Alternative - we may delete this procedure, as the pointing clusters define a event partition in time also, providing the user with the time intervals for a selected pointing makes this event labeling superfluous.)
I	insfile	string	i	overrides the IDF name as inferred from the (first) input eventfile.


p, L, i	StageII global switches

DESCRIPTION

Read one or more eventfiles, creating a 2 (or 3) dimensional image.

event selection

Selection of events is done at a low level in the software, the eventread routine will return events having in range (time-tag, energy channel+Z, position coordinates) values only, specially filtering on time (events are consequetive, assured by StageI) can be speeded up in this way. The consequence is however that events with some out of range value, are NEVER SEEN by the functions that assemble the detector image, the spectrum and the (optional) lightcurve. As for the detector image, this is certainly right. For the spectral data however, though all (31) channels are written, only the energy channels within the selected range are filled, the others are 0. Equally, only those timebins in a lightcurve that are (partially) within the selected time range have non-zero data (bins are NOT deleted from the lightcurve extension).

Nearly all cdi's parameters relate to the selection of events from the input eventlists. The use and meaning of most of these are clear, one, -w(wsbar), may need some further explanation. By default, ie. not steared by any (position) selection parameter values, cdi reads ALL events from the eventlist(s). After all eventfiles are processed, the detector image pixels in the detector calibration source regions as well as the pixels obscured by the detector-window support structure, will be cleared (assigned 0). Judging from the image, these, usually unwanted, events were filtered out. This IS NOT true for the spectrum and the lightcurve, these still contain the events, that cannot be removed as the position information is lost. If the input eventlists were cleaned (datalevel 1 files), the impact is small, calibration source events were removed from the eventfile, but the events detected under the support structure are in the temporal and spectral data items.

A special parameter wsbar can be used to reject, wsbar= -1 events under the support structure or exclusively select, wsbar= +1 these events. In this case, rejected events are not processed and NOT included in any data product. Cdi run time does increase, the position selection procedure is applied to each event read.
(wsbar is equivalent to a p_filtr parameter, listing the support structure and calibration source areas, either to be excluded wsbar= +1 or included, wsbar= -1.
To be perfectly clear, inclusion of some region implies the exclusion of all events NOT in that region).

-binning- detector pixel size as defined in the instrument data file used.

-linearisation-

EXAMPLE

We have 2 eventfiles

WOP817_0001w1prn1.fits
WOP817_0003w1prn1.fits

and a file w817w1.in, containing the full paths's of above files.

/ruurq2/817/WOP817_0001w1prn1.fits, /ruurq2/817/WOP817_0003w1prn1.fits

the command (assuming valid environment variables are set)

cdi -p2 -e2-18 -b10 w817w1.in w817w1

cdi -p2 -e2-18 -b10 /ruurq2/817/WOP817_0001w1prn1.fits,/ruurq2/817/WOP817_0003w1prn1.fits w817w1

produces the following list output

===============================================================================
 cdi[99.99]                                Mon Jul  7 10:00:06 1997  page    1
   ------------------------------------------------------------
[2] ---------------------------------------------------------------------
 +  good time interval file: "/ruurq2/817/WOP817_0000w1.gti"
 +                final time filter
 +       start(mjd)     end(mjd)   length(sec)
 +      50318.487510-50318.519975    2805.000 sec
 +      50318.519998-50318.534445    1248.200 sec
 +      50318.545297-50318.549732     383.183 sec
 +      50318.549778-50318.557266     647.000 sec
 +      50318.557324-50318.560463     271.200 sec
 +  ---------------------------------------------------------------------
[1]evt_assemble: tstart=50318.48751, tend=50318.56046,  631 bins
[1]evt_open: "/ruurq2/817/WOP817_0001w1prn1.fits"[SCI_NM], 1 of 2.
 +          time  50318.48730 - 50318.53446 (MJD)  [  4074.54 sec.]
[1]evt_open: "/ruurq2/817/WOP817_0003w1prn1.fits"[SCI_NM], 2 of 2.
 +          time  50318.54530 - 50318.56055 (MJD)  [  1318.09 sec.]
   evt_assemble: scanned 2 files, accepted 517190 events in detector image
                 5353.933 sec. exposure time, starting (UT) Fri Aug 23 11:42:00 1996
                        event time filter starting (UT) Fri Aug 23 11:42:00 1996
[1]evt_open: "/ruurq2/817/WOP817_0000w1att1.fits"[ATTITUDE], 1 of 1.
 +          time  50318.48730 - 50318.56047 (MJD)  [  6322.00 sec.]
[2]cdi_stability:  x                  y                   na
 +   mean:        0.16 (mm.)         0.77 (mm.)        178.75 (deg)
 + st.dev:        0.02 (mm.)         0.02 (mm.)          0.16 (min)
 +    min:        0.23 (mm.)         0.02 (mm.)        178.91 (deg)
 +    max:        0.34 (mm.)         0.34 (mm.)        178.93 (deg)
[1]evt_open: "/ruurq2/817/WOP817_0001w1pdt1.fits"[LIFETIME], 1 of 2.
 +          time  50318.48751 - 50318.53458 (MJD)  [  4067.00 sec.]
[1]evt_open: "/ruurq2/817/WOP817_0003w1pdt1.fits"[LIFETIME], 2 of 2.
 +          time  50318.54529 - 50318.56062 (MJD)  [  1325.00 sec.]
[2]cdi_lftmfrctn: accumulated effective exposure time 4734.936 sec.
 +                accumulated   nominal exposure time 5378.000 sec.
 +                              mean lifetimefraction 0.880

and produces a file w817w1.exp. The ftool fstruct run on w817w1.exp produces

  No. Type     EXTNAME      BITPIX Dimensions(columns)      PCOUNT  GCOUNT
 
   0  PRIMARY                -32     680 680                     0    1
   1  BINTABLE WFC_Eventspec   8     16(4) 32                    0    1
   2  BINTABLE WFC_DetLcv      8     4(1) 631                    0    1
   3  IMAGE    WFC_Pointing  -32     123 123                     0    1

The created file contains a

PRIMARY FITS IMAGE, containing a 2-dimensional detector image, events with an energy in the range 2-18 (channels).
BINARY TABLE extension WFC_Eventspec list the number of events found in each channel. though there are 32 columns, only channels 2-18 as selected, are filled.
BINARY TABLE extension WFC_DetLcv list the number of events found in 10 second wide timebins, the table has 1 colummn, the lightcurve for the energy range. This table is present only if the parameter TBIN (option -b) has a value greater than 0.
BINARY TABLE extension WFC_Pointing, an 2D image. The linear pixel size is 1/3 that of an detectorpixel, corresponding to approx. 0.6 arcmin. in the center field of view. Each pixel contains that time fraction of the observing period, the wfc-ponting, as derived from the AOCS attitude, was in that pixel.