$Id$

NeSDaC

dlc, create a detector lightcurve

NAME

dlc - create event-time histograms (lightcurves) from one or several eventfile(s)

SYNOPSIS

dlc
dlc -p [options] evl lc
dlc -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 (dlc -q) creates the parameterfile in $PFILES.

The current dlc revision, 1.08, differs substantially from the previous releases, the information in this document is quite useless for the pre 1.08 dlc versions.

The table lists all the parameters used by dlc, the second column lists the paramater key names used in the parameterfile, the first column gives the corresponding switch letter,

dlc parameters
switch key value IO description
lcfile string o lc, created detectorlightcurve file (FITS).
evtfile list i evl, simple eventfile or list of eventfiles.
b tbin real i The resolution (time-bin length) in seconds.
g gtifile string i the state of this gtifile, on or off, is marked for every timebin.
t t_filtr range i select the start and end time for the lighrcurve. 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.
p p_filtr area i Several area's can be specified in the form of a comma separated list, dlc produces a column for each detector section listed.
(dlc attaches no meaning to exclusion of detector sections, the x range modifier is ignored)
e e_filtr range i Several energy ranges (channels) can be specified in the form of a comma separated list, every rate (event-count) columns generated will have a third dimension, to store the rates in the energy bands.

1 cl_time string i name and format of the time column in the table, defaults to "time,s", the column name is "time" and it gives the center bin time in seconds since the start of the first bin. an alternative might be "TIME,d", time column, named "TIME" in days (MJD). The column name is yours to choose, the format character can be 'd' (or 'D') for days, anything else is interpreted as 's' for seconds.
2 cl_cnts string i name (template) of the rate column(s) in the table, defaults to "rate". if more than 1 rate column is generated, an serial number (1,2 ..) is appended to this name, if the last character of the name is alphanumeric (letter or number) the underscore is used as a separator.
3 cl_cmdsc string i name of the column for the compound (both Fe and Cd) calibration source, defaults to "rateCs", the Fe and Cd events may be resolved by setting appropriate energy windows.
4 cl_phfe string i name of the column for all 8 pinhole calibration sources, defaults to "ratePh".
5 cl_gti string i name of the column for the gti column, defaults to "gti".
6 cl_tod string i name of the column for the tod (time of day) column, defaults to "tod". this column, provided attitude data was available, tracks the whether the earth obscures the center of the field of view or not, column is "1" in the latter case.
- cl_utw string i name of the column for the utw (user time window) column. do not use, not functional, no switch character linked.
I insfile string i overrides the IDF name as inferred from the (first) input eventfile.

@ tapearch string i SRON tape archive escape. Inputfiles may be retrieved from the tape archive. Parameter is ignored, unless a compile time variable (SRON) in the software build was set.
p, L, i StageII global switches

dlc parameters
switch	key	value	IO	description
	lcfile	string	o	lc, created detectorlightcurve file (FITS).
	evtfile	list	i	evl, simple eventfile or list of eventfiles.
b	tbin	real	i	The resolution (time-bin length) in seconds.
g	gtifile	string	i	the state of this gtifile, on or off, is marked for every timebin.
t	t_filtr	range	i	select the start and end time for the lighrcurve. 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.
p	p_filtr	area	i	Several area's can be specified in the form of a comma separated list, dlc produces a column for each detector section listed. (dlc attaches no meaning to exclusion of detector sections, the x range modifier is ignored)
e	e_filtr	range	i	Several energy ranges (channels) can be specified in the form of a comma separated list, every rate (event-count) columns generated will have a third dimension, to store the rates in the energy bands.

1	cl_time	string	i	name and format of the time column in the table, defaults to "time,s", the column name is "time" and it gives the center bin time in seconds since the start of the first bin. an alternative might be "TIME,d", time column, named "TIME" in days (MJD). The column name is yours to choose, the format character can be 'd' (or 'D') for days, anything else is interpreted as 's' for seconds.
2	cl_cnts	string	i	name (template) of the rate column(s) in the table, defaults to "rate". if more than 1 rate column is generated, an serial number (1,2 ..) is appended to this name, if the last character of the name is alphanumeric (letter or number) the underscore is used as a separator.
3	cl_cmdsc	string	i	name of the column for the compound (both Fe and Cd) calibration source, defaults to "rateCs", the Fe and Cd events may be resolved by setting appropriate energy windows.
4	cl_phfe	string	i	name of the column for all 8 pinhole calibration sources, defaults to "ratePh".
5	cl_gti	string	i	name of the column for the gti column, defaults to "gti".
6	cl_tod	string	i	name of the column for the tod (time of day) column, defaults to "tod". this column, provided attitude data was available, tracks the whether the earth obscures the center of the field of view or not, column is "1" in the latter case.
-	cl_utw	string	i	name of the column for the utw (user time window) column. do not use, not functional, no switch character linked.
I	insfile	string	i	overrides the IDF name as inferred from the (first) input eventfile.

@	tapearch	string	i	SRON tape archive escape. Inputfiles may be retrieved from the tape archive. Parameter is ignored, unless a compile time variable (SRON) in the software build was set.
p, L, i	StageII global switches

DESCRIPTION

Read one or more eventfiles, creating lightcurves (time-count histograms) for the events, separating the in-flight calibrationsource events from the 'sky' events. By default, events from all channels are summed. This is different from the previous versions, where a separate column for each energy channel was generated. More emphasis is now on the option to create lightcurves for different detector sections, doing that for each energy channel produces, at high time resolution very, large files. You can still do it by specifying the 31 energy bands for the e_filtr parameter (e_filtr="1,2,3 .... ,30,31").

if the parameter p_filtr is undefined (empty), all non-calibration source, detector events are summed in the "rate" column.
If defined, each detector section, listed in the parameter p_filtr (-p), defines a column in the outputfile, giving the events in that section only. The column names are extended with a serial number, 1, 2 etc.
Besides the normal range values, the parameter can have one of the special values a, b or c, selecting a predefined list of detector sections:

a the 4 major detector quadrants.
b as a, each quadrant itself divided in 4 equal parts, 16 in total.
c the 100 secondary support-structure windows.

The cl_time, cl_cnts etc. parameters can be used to rename a column.
One column name, namely '-', is special, that column is suppressed, it is removed from the table produced.

The gti column, provided a gti-file was available, is '1' if the corresponding bin fully lies in a good' part of the time interval file, '0' otherwise.
The tod column is '1' if the center of the field of view at the center of the corresponding time bin is directed at open space, '0' if at that time the earth obscures the FOV center, again provided an attitude-file was available.

EXAMPLE

The command (assuming valid environment variables are set)

dlc -p2 -a su_1389.att -g su_13749.gti -p a -e1-12,13-22,23-31 \
		 -1 TIME,d -2 RATE -b 10 su_9497.rn,su_9498.rn yop719w2.dlc

produces the follwing output

===============================================================================
 dlc[1.08]                                Wed Feb  4 09:39:37 1998  page    1
   ------------------------------------------------------------
[1]evt_open: "su_9497.rn"[SCI_NM],  1 of  2.
[2]evt_open: Sat Aug  3 03:55:58 1996(UT)  [  4822.70 sec.]
[1]evt_open: "su_1389.att"[ATTITUDE],  1 of  1.
[2]evt_open: Sat Aug  3 03:38:01 1996(UT)  [  8173.00 sec.]
[2]dlc: good time interval file: "su_13749.gti"
 +           time 50298.16387 - 50298.24598
[1]dlc_assemble: tstart=50298.16387, tend=50298.24603,  710 bins
[1]evt_open: "su_9498.rn"[SCI_NM],  2 of  2.
[2]evt_open: Sat Aug  3 05:39:24 1996(UT)  [   892.66 sec.]
   dlc_assemble: scanned 2 files, accepted 940464 events
                   5715.32 sec. exposure time, starting Sat Aug  3 03:55:58 1996(UT)
                              event time filter starting Sat Aug  3 03:55:58 1996(UT)

and produces a file yop719w2.dlc. The ftool fstruct run on yop719w2.dlc produces

  No. Type     EXTNAME      BITPIX Dimensions(columns)      PCOUNT  GCOUNT
 
   0  PRIMARY                 32     0                           0    1
   1  BINTABLE dlc             8     88(9) 710                   0    1

and the latter part of the fverify output on yop719w2:

------------------------------------------------------------------------------
    Extension #  1: BINTABLE extension:
    Header contains    44 keywords.
 
    All keywords were read successfully and conform to required FITS syntax.
    No duplicate keywords were found.
    Header space following END keyword is correctly filled with ASCII blanks.
 
    Table dlc                     contains   9 columns and      710 rows.
  Col  TTYPE         TFORM     TUNIT         Nulls  Data Min.      Data Max.
    1 TIME             1D       mjd             0   50298.16       50298.25
    2 RATE_1           3E       counts          0   .0000000E+00   182.0000
    3 RATE_2           3E       counts          0   .0000000E+00   212.0000
    4 RATE_3           3E       counts          0   .0000000E+00   168.0000
    5 RATE_4           3E       counts          0   .0000000E+00   195.0000
    6 rateCs           3E       counts          0   .0000000E+00   64.00000
    7 ratePh           3E       counts          0   .0000000E+00   15.00000
    8 gti              1E       on/off          0   .0000000E+00   1.000000
    9 tod              1E       on/off          0   .0000000E+00   1.000000
 
    Empty space (if any) following last data record is correctly filled.
 
------------------------------------------------------------------------------

The following command allmost mimics the pre-1.08 dlc behaviour:

dlc -p -e1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,\
          20,21,22,23,24,25,26,27,18,19,30,31 w817w1.in w817w1

The "dlc" binary table harbours the following columns:
(n is given by the number of energy bands selected by the e_filtr (e) parameter, if this parameetr is undefined a value of 1-31 (all channels) is used.)

dlc columns
name type description
time 1E timetag, seconds.
rate nE detector events, excluding in flight calibration sources (ifc).
rateCs nE ifc, compound source, both Fe and Cd.
ratePh nE ifc, sum of all 8 pinhole sources, Fe.
gti 1E gti file state, on= 1, off= 0.
tod 1E earth occultation for the center of the field of view, clear sky= 1, eatrh= 0.