NAME

hxdwampipeline - Suzaku HXD-WAM reprocessing and product generation tool

SYNOPSIS

hxdwampipeline indir=<input dir> outdir=<output dir> steminputs=<input filename stem> entrystage=<entry stage> exitstage=<exit stage> eventmode=ALL

DESCRIPTION

This task re-calibrates, filters and extracts products from HXD-WAM TRN and BST mode event data.

Pipeline Stages

The pipeline is divided into 3 stages:

  1. Calibration
  2. Data screening
  3. Products generation

Stage 1 for TRN data consists of event TIME assignment with hxdwamtime. For BST data it consists of event TIME assignment with hxdbsttime.

Stage 2 consists of data screening. There is no screening performed for BST mode data, since this mode is only activated by a burst trigger, and is only active for 128s at any given time. It is assumed that all BST mode data is good data. TRN mode screening is (if trn_mkfexpr=DEFAULT) identical to the default GSO screening in the production Suzaku pipeline:

SAA_HXD==0 && T_SAA_HXD>500 && TN_SAA_HXD>180 && COR>6 && HXD_HV_T0_CAL>700 && HXD_HV_T1_CAL>700 && HXD_HV_T2_CAL>700 && HXD_HV_T3_CAL>700 && HXD_HV_W0_CAL>700 && HXD_HV_W1_CAL>700 && HXD_HV_W2_CAL>700 && HXD_HV_W3_CAL>700

If the trn_exclude_scan parameter is set, then the WAM "scan" times will also be excluded in the screened event files. See the trn_exclude_scan parameter for details.

Stage 3 consists of light curve extraction using hxdmkwamlc for TRN and hxdmkbstlc for BST mode. Burst and/or occultation step detection is also run on each light curve. A FITS table of detections is output in the file "<stemoutputs>hxd_0_wam_bst.det". Step detection is only available for TRN mode data.

INPUT

The input to hxdwampipeline is specified using (at minimum) the indir parameter. This should be specified as the top level sequence directory, e.g.:

hxdwampipeline indir=/path/to/100039010 ...

Paths to specific housekeeping and satellite data files can be specified using the hxdhk_fname, tim_fname and mkf_fname parameters. But this should NOT be necessary if indir is specified correctly.

NOTE: Errors can occur if a subdirectory of a sequence directory is used for the indir parameter or if the output is stored within the sequence directory.

OUTPUT

The number of output files depends on both pipeline processing stage(s) and the instrument(s) selected. All output files are written to the directory specified by the outdir parameter. The archive directory structure is NOT reproduced (i.e. all output files will be in a single directory).

The names of files produced are similar to those found in the HEASARC archive. However the usual "aeXXXXXXXXX" prefix, where "XXXXXXXXX" is the sequence number, can be replaced by a character string set by the stemoutputs parameter. This defaults to the value set by the steminputs parameter.

A typical output file set (if entrystage=1 and exitstage=3) will look like: 

    ae100039010.mkf
    ae100039010.tim
    ae100039010hxd_0.hk

    ae100039010hxd_1_wam_uf.evt
    ae100039010hxd_1_bstidt.fits
    ae100039010hxd_1_bst01_uf.evt
    ae100039010hxd_2_wam_uf.evt
    ae100039010hxd_2_bstidt.fits
    ae100039010hxd_2_bst01_uf.evt
    ae100039010hxd_3_wam_uf.evt
    ae100039010hxd_3_bstidt.fits
    ae100039010hxd_4_wam_uf.evt
    ae100039010hxd_4_bstidt.fits


    ae100039010hxd_0_wam_cl.evt
    ae100039010hxd_0_wam_cl.gti

    ae100039010hxd_0_wam.lc
    ae100039010hxd_1_bst01.lc
    ae100039010hxd_2_bst01.lc

    ae100039010hxd_0_wam_bst.det

A light curve file will be created for the TRN screened event file and each BST un-screened event file. Each light curve file will contain light curves and GTIs for each energy band and WAM unit requested. The "bst.det" table will contain detections from all light curves (and all modes).

PARAMETERS

indir [string]
Input directory. This should be the top level archive directory, e.g. /path/to/100039010.

outdir [string]
Output directory. This should NOT be a sub-directory of the input directory.

steminputs [string]
Stem for finding input files

(stemoutputs = DEFAULT) [string]
Root filename for output files. If set to DEFAULT, steminputs will be used.

entrystage = 1 [int]
Pipeline entry stage:
1 - Re-calibrate un-filtered event files
2 - Start with calibrated event files
3 - Start with screened event files (TRN only)

exitstage = 3 [int]
Pipeline exit stage:
1 - Calibrated, un-filtered event files
2 - Screened event files (TRN only)
3 - TRN/BST light curves and burst/step detection table

eventmode = ALL [ALL|BST|TRN]
Event modes to process. ALL will process BST and TRN events.

(hxdhk_fname = DEFAULT) [file]
HXD HK fits file name (DEFAULT=determine from input files)

(leapfile = CALDB;$ENV{LHEA_DATA}/leapsec.fits) [file]
Leap second file name

(tim_fname = DEFAULT) [file]
Input .tim FITS file name (DEFAULT=determine from input files)

(trn_bintbl_name = CALDB) [file]
HXD TRN re-bin table file name (CALDB=query calibration database)

(create_bstidt = no) [bool]
Create new Burst ID files? Re-runs hxdwambstid for each 'wam_uf.evt' file.

(time_convert_mode = 4) [int]
HxdTime2aetime convert mode

(rand_seed = 7) [int]
Seed for random number generator (for hxdwampi)

(mkf_fname = DEFAULT) [file]
Makefilter file

(trn_mkfexpr = DEFAULT) [string]
HXD TRN makefilter time screening expression (DEFAULT=use pipeline default expression). If set to DEFAULT, the screening criteria will be set to:
SAA_HXD==0 && T_SAA_HXD>500 && TN_SAA_HXD>180 && COR>6 && HXD_HV_T0_CAL>700 && HXD_HV_T1_CAL>700 && HXD_HV_T2_CAL>700 && HXD_HV_T3_CAL>700 && HXD_HV_W0_CAL>700 && HXD_HV_W1_CAL>700 && HXD_HV_W2_CAL>700 && HXD_HV_W3_CAL>700

(trn_gti_fname = NONE) [file]
HXD TRN additional GTI file to AND with GTI created with trn_mkfexpr. Use NONE to indicate no additional GTI should be used.

(trn_exclude_scan = yes) [bool]
HXD TRN exclude WAM scans in screening expression? The WAM scans are daily calibration operations that generally occur approximately 5 minutes after an SAA passage has completed. Each scan lasts for approximately 10 minutes. The data taken during this period are not generally useful for end-users.

The scan times are calculated as the time between "OG_NAME==hxd_t?" and "OG_NAME==hxd_tpu_normal" in the "OPERATION_COM" extension of the input ".tim" file. The "?" can be any of 0, 1, 2 or 3. The "hxd_t?" command initiates the "scan" operation, and the "hxd_tpu_normal" command ends the scan operation.

(trn_gtitrim = 0.0) [real]
HXD TRN seconds to trim from GTI START and STOP?

(trn_tpu_board = -1) [string]
HXD WAM detector(s) to include when creating TRN light curves (comma separated list, or -1 for all)

(bst_tpu_board = -1) [string]
HXD WAM detector(s) to include when creating BST light curves (comma separated list, or -1 for all)

(trn_lc_mode = TH) [TH|PH]
Data mode for TRN light curves (TH = 4-channel, PH = channel range)

(th_mode = 1) [int]
Data mode for BST light curves (1=TH data; 0=PH data)

(trn_min_channel = 0) [int]
HXD TRN Minimum channel number for PH light curves (only used if trn_lc_mode==PH)

(trn_max_channel = 54) [int]
HXD TRN Maximum channel number for PH light curves (only used if trn_lc_mode==PH)

(trn_dt_cor = yes) [bool]
HXD TRN Perform deadtime correction for TRN light curves?

(trn_dt_clk = 12.8e-6) [real]
HXD TRN Deadtime clock frequency

(bst_dt_cor = no) [bool]
HXD BST Perform a deadtime correction?: yes or no?

(bst_dt_clk = 12.8e-6) [real]
HXD BST Deadtime clock frequency

(bst_dt_ph = 13.0e-6) [real]
HXD BST Deadtime for PH data

(bst_energy_mode = -1) [int]
HXD BST Light curve production mode for energy channels(-1:All,0:One,1:Accumulated)

(bst_energy_channel = 2) [int]
HXD BST Energy channel for the one-channel production mode

(bst_min_channel = 0) [int]
HXD BST Minimum energy channel for the accumulated production mode

(bst_max_channel = 1) [int]
HXD BST Maxinum energy channel for the accumulated production mode

(trn_use_trigger_set = no) [bool]
Use HETE-2 trigger sets instead of input trigger specification for TRN?

(trn_trigger_set = MEDIUM) [0|SHORT|1|MEDIUM|2|LONG]
HETE-2 trigger set to use for TRN

(trn_bgd_integ_time = 8) [int]
Background integration time for detecting bursts in TRN light curves

(trn_delta_t = 1.0) [real]
Burst integration time for detecting bursts in TRN light curves

(trn_sigma = 5.5) [real]
Burst detection threshold for TRN light curves

(trn_det_alg = HETE2) [0|GINGA|1|HETE2|2|STEP]
Burst detection algorithm for TRN mode

(trn_bgd_early_gap = 0) [int]
Gap (seconds) between 'early' background interval and foreground interval for TRN

(trn_bgd_late_gap = 0) [int]
Gap (seconds) between foreground interval and 'late' background interval for TRN

(trn_step_window = 240) [int]
Window size in seconds for step fitting for TRN

(trn_step_delchi = 2.71) [real]
Change in delta chi-squared to be considered a '1-sigma' change in fit parameter error estimates for TRN

(trn_gaptol = 2.0) [real]
Gap tolerance (s) for TRN

(trn_overlaptol = 10.0) [real]
Burst detection overlap tolerance (s) for TRN

(trn_maxdur = 200.0) [real]
Maximum allowed burst duration for TRN

(trn_durest = yes) [bool]
Try to refine burst duration estimate (T50/T90 are always calculated) for TRN?

(bst_use_trigger_set = no) [bool]
Use HETE-2 trigger sets instead of input trigger specification for BST?

(bst_trigger_set = MEDIUM) [0|SHORT|1|MEDIUM|2|LONG]
HETE-2 trigger set to use for BST

(bst_bgd_integ_time = 6) [int]
Background integration time for detecting bursts in BST light curves

(bst_delta_t = 1.0) [real]
Burst integration time for detecting bursts in BST light curves

(bst_sigma = 5.5) [real]
Burst detection threshold for BST light curves

(bst_det_alg = HETE2) [0|GINGA|1|HETE2]
Burst detection algorithm for BST mode

(bst_bgd_early_gap = 0) [int]
Gap (seconds) between 'early' background interval and foreground interval for BST

(bst_bgd_late_gap = 0) [int]
Gap (seconds) between foreground interval and 'late' background interval for BST

(bst_gaptol = 2.0) [real]
Gap tolerance (s) for BST

(bst_overlaptol = 10.0) [real]
Burst detection overlap tolerance (s) for BST

(bst_maxdur = 200.0) [real]
Maximum allowed burst duration for BST

(bst_durest = yes) [bool]
Try to refine burst duration estimate (T50/T90 are always calculated) for BST?

(event_freq = 10000) [int]
Event printout frequency

(anl_verbose = -1) [int]
ANL verbose level (-1:full, 0:minimum)

(anl_profile = yes) [bool]
Enable ANL module profiling?

(chatter = 2) [int]
Terminal chattiness level (0=no output; 5=debugging output)

(clobber = no) [bool]
Overwrite existing output files?

(history = yes) [bool]
Write task HISTORY keywords to output files?

(cleanup = yes) [bool]
Cleanup temporary files?

(mode = ql) [string]
Parameter mode

NOTES

None Currently

LAST MODIFIED

March 2011