NAME

rslsamcnt - Calculate the local time at fine resolution in XRISM Resolve files for later synchronization with the GPS-related time in final time assignment

USAGE

rslsamcnt infile outfile

DESCRIPTION

The rslsamcnt task calculates the XRISM Resolve local time and fills the sample count column(s) that represent the fine time resolution assigned internally by the instrument electronics. This is used to assign time using the xatime task. After rslsamcnt is executed, xatime synchronizes the fine local time to the TT time (obtained via the GPS). It may be applied to Resolve (pixel and antico) event, diagnostic mode, lost GTI, and HK files. The diagnostic mode files that this task is applied to are the pixel and antico WaveForm Ring-Buffer (WRFB), antico and pixel Noise Record, and pixel Pulse Record data files.

The input file columns required to calculate sample count depend on file type, and may be specified using the appropriate subset of 'col1', 'col2', 'col3', col4', and 'col5' parameters. There are four general file types: PIXEL, ANTICO, HK, and GTILOST. Each file type supports various input file types. The PIXEL file type supports: pixel event (e.g., p0px), pixel noise record (e.g., pxnr), and pixel pulse record (e.g., pxpr) input file types. The ANTICO file type supports: antico event (e.g., a0ac), antico noise record (e.g., acnr), antico WFRB (e.g., acwf), and pixel WFRB (e.g., pxwf) input file types. The HK and GTILOST file types only support Resolve HK (e.g., *rsl.hk1) and lost GTI (e.g., *rsl_el.gti) input file types, respectively.

For the PIXEL file type, by default the input file columns are ('col1') TRIG_LP, a rough event trigger time, ('col2') TIME_VERNIER, a fine time correction, ('col3') WFRB_WRITE_LP, a reference for TRIG_LP, and ('col4') WFRB_SAMPLE_CNT, a reference for SAMPLECNT. For the ANTICO file type, by default, the input file columns are ('col1') TRIG_LP, ('col3') WFRB_WRITE_LP, ('col4') WFRB_SAMPLE_CNT, and ('col5') FLG_EVENT_LOST. For the HK file type, by default, the input file columns are ('col1') LATCH_SAMPLE_CNT1, a reference for SAMPLECNT, and ('col2') LATCH_BASE_CNT1, a fine clock value. For the GTILOST file type, by default, the input file columns are ('col1') EL_#_LP, which is the TRIG_LP for the beginning and end of the interval, ('col3') WFRB_WRITE_LP, and ('col4') WFRB_SAMPLE_CNT. The hash (#) symbol for the GTILOST file type directs the task to calculate two sample count values using values in the columns EL_START_LP and EL_STOP_LP. For ANTICO and GTILOST file types, the value(s) specified by the parameter(s) 'timever1' and 'timever2' (GTILOST only) set the TIME_VERNIER (fine time correction used in the sample count calculation(s). Since antico event times and lost GTI are used in event screening, this allows for some margin and/or offset relative to pixel events.

The result of the sample count calculation is written in the column(s) set by the parameter 'outcol'. The file type also determines the default number of columns and column names: SAMPLECNT for the ANTICO and HK file types, SAMPLECNT1 and SAMPLECNT2 for the GTILOST file type (corresponding to EL_START_LP and EL_STOP_LP, respectively), and SAMPLECNT and SAMPLECNTTRIG for the PIXEL file type. SAMPLECNTTRIG, is derived in a similar manner to the other local time values, and enables the calculation of the event trigger time by xatime. SAMPLECNT for the PIXEL file type, which enables the calculation of the event arrival time by xatime, is derived from a polynomial function of SAMPLECNTTRIG, whose coefficients are stored in CalDB. The table below also shows the file types and their corresponding columns, as well as the output column ('outcol') and the time vernier values ('timever1' and 'timever2') where applicable.

Default values for parameters for each file type:
============================================================================================================================================
File     col1               col2             col3           col4             col5            timever1  timever2  outcol      | corresponding
Type                                                                                                                         | # columns
============================================================================================================================================
PIXEL	 TRIG_LP            TIME_VERNIER     WFRB_WRITE_LP  WFRB_SAMPLE_CNT  --              --         --       SAMPLECNT#  | SAMPLECNT,
                                                                                                                             | SAMPLECNTTRIG
--------------------------------------------------------------------------------------------------------------------------------------------
ANTICO	 TRIG_LP            --               WFRB_WRITE_LP  WFRB_SAMPLE_CNT  FLG_EVENT_LOST  0          --       SAMPLECNT   |
--------------------------------------------------------------------------------------------------------------------------------------------
HK       LATCH_SAMPLE_CNT1  LATCH_BASE_CNT1  --             --	             --              --         --       SAMPLECNT   |
--------------------------------------------------------------------------------------------------------------------------------------------
GTILOST  EL_#_LP            --               WFRB_WRITE_LP  WFRB_SAMPLE_CNT  --              23         -8       SAMPLECNT#  | SAMPLECNT1,
                                                                                                                             | SAMPLECNT2
============================================================================================================================================

PARAMETERS

infile [filename]
Input Resolve file name. This file may be one of several types, containing either pixel events, antico events, specific types of diagnostic modes, HK data, or lost GTI data.

outfile [filename]
Output Resolve file name with the sample count column(s) relevant for the type of file specified by 'infile'.

(coeftime = CALDB) [string]
Input file with arrival time coefficients. If CALDB is specified, the file will be obtained from the calibration database.

(col1 = DEFAULT) [string]
Column name for the rough local time. If 'col1=DEFAULT', this is set to TRIG_LP for pixel, antico, pulserec, and noiserec event files; to LATCH_SAMPLE_CNT1 for Resolve HK extensions; and to EL_#_LP for lost GTI, where # indicates that both START and STOP times are processed.

(col2 = DEFAULT) [string]
Column name for the fine local time correction. If 'col2=DEFAULT', this is set to TIME_VERNIER for pixel and pulserec event files and to LATCH_BASE_CNT1 for a Resolve HK extension. For other file types this parameter is ignored.

(col3 = DEFAULT) [string]
Column name for the reference for rough local time. If 'col3=DEFAULT', this is set to WFRB_WRITE_LP for pixel, antico, pulserec, noiserec, and lost GTI files. For HK files this parameter is ignored.

(col4 = DEFAULT) [string]
Column name for the reference sample count. If 'col4=DEFAULT', this is set to WFRB_SAMPLE_CNT for pixel, antico, pulserec, noiserec, and lost GTI files. For HK files this parameter is ignored.

(col5 = DEFAULT) [string]
Column name that specifies whether an antico event is a lost antico event. If 'col5=DEFAULT', this is set to FLG_EVENT_LOST, and the SAMPLECNT column is set to its null value if FLG_EVENT_LOST=1. If the input file is not an antico file this parameter is ignored.

(timever1 = DEFAULT) [string]
Time (in units of 5 microsecond ticks) to be added to the local time calculation. For lost GTI files, this value is added to the sample count corresponding to the START time. For antico events this value is added to the SAMPLECNT column. Default values are 23 for lost GTI, and 0 for antico events.

(timever2 = DEFAULT) [string]
Time (in units of 5 microsecond ticks) to be added to the local time calculation. For lost GTI files, this value is added to the sample count corresponding to the STOP time. The default value is -8 for lost GTI.

(outcol = DEFAULT) [string]
Output column name for the calculated local time. If set to DEFAULT, the name is SAMPLECNT for antico, pulserec, and noiserec files, and Resolve HK extensions. For lost GTI files, by default the columns are SAMPLECNT1 and SAMPLECNT2, otherwise the names of the two columns are generated by appending '1' and '2' to the string specified by 'outcol'. For pixel events, by default, the columns are SAMPLECNT and SAMPLECNTTRIG; otherwise use the 'outcol' string for one file name and generate the second by appending the string 'TRIG' to 'outcol'.

(buffer = -1) [integer -1|0|N]
Rows to buffer (-1=auto, 0=none, N>0=numrows).

(clobber = no) [boolean yes|no]
Overwrites the existing output file if set to yes.

(chatter = 1) [integer 0|1|2|3]
Chatter level for output. Set to 0 to suppress output, or to 1, 2, or 3 for increasing the chatter of the output.

(logfile = !DEFAULT) [string DEFAULT|NONE|file name]
Log file name. If set to DEFAULT, uses the name of the task and, if preceded by "!", overwrites the file if it exists. If set to NONE, no log file is created.

(debug = no) [boolean yes|no]
Diagnostic output is printed to the screen if set to yes.

(history = yes) [boolean yes|no]
Records tool parameters in HISTORY.

EXAMPLES

  1. Calculate SAMPLECNT for the Resolve HK file hk_in.fits, creating an output HK file (hk_out.fits) with the SAMPLECNT column populated according to the values in the LATCH_SAMPLE_CNT1 ('col1') and LATCH_BASE_CNT1 ('col2') columns.
  2.    rslsamcnt hk_in.fits hk_out.fits
    
  3. Calculate SAMPLECNT for the Resolve pixel event file event_in.fits, creating an output event file (event_out.fits) with the SAMPLECNT and SAMPLECNTTRIG columns populated according to the values in the WFRB_SAMPLE_CNT ('col4'), WFRB_WRITE_LP ('col3'), TRIG_LP ('col1'), and TIME_VERNIER ('col2') columns.
  4.    rslsamcnt event_in.fits event_out.fits
    
  5. Calculate SAMPLECNT for an Resolve antico event file antico_in.fits, creating an output event file (antico_out.fits) with the SAMPLECNT column populated according to the values in the WFRB_SAMPLE_CNT ('col4'), WFRB_WRITE_LP ('col3'), TRIG_LP ('col1'), and FLG_EVENT_LOST ('col5') columns.
  6.    rslsamcnt antico_in.fits antico_out.fits
    
  7. Calculate the start and stop SAMPLECNT values for the lost GTI file lost_in.gti, creating an output event file (lost_out.gti) with the SAMPLECNT1 and SAMPLECNT2 columns populated according to the values in the WFRB_SAMPLE_CNT ('col4'), WFRB_WRITE_LP ('col3'), and TRIG_LP ('col1') columns. Shrink each interval by extending the GTI START times by 30 ticks and curtailing the STOP times by 15 ticks.
  8.    rslsamcnt lost_in.gti lost_out.gti timever1=30 timever2=-15
    

SEE ALSO

xatime

LAST MODIFIED

November 1, 2023