NAME pcadeadcalc1 - Calculate deadtime for PCA Standard1 file USAGE Standard1: pcadeadcalc1 std1file std1file_DT hkfiles=@hkfiles.lis DESCRIPTION pcadeadcalc1 calculates PCA deadtime quantities for data in the Standard1 mode. This tool calculates the dead time due to various terms, including GoodXenon counts, Very Large Event (VLE) counts, Propane layer counts, and other counts in the detector. Also, by default, the tool filters out bad data during times which are known to be "bad" for typical scientific analysis. As output, the tool produces a "new" Standard1 file which contain dead-time related quantities appended as new columns to the table. The user can use these quantities to adjust their light curves or spectra to remove the effects of dead-time. pcadeadcalc1 does not apply any deadtime correction by itself, but merely calculates dead-time related quantities, and (optionally) filters out PCU data during known bad states This task does not work for Standard2 background files. See the task 'pcadeadcalc2' instead. The most useful columns in the FITS table are: LiveTimePcu0 LiveTimePcu1 LiveTimePcu2 LiveTimePcu3 LiveTimePcu4 which represent the detector live-time for each PCU in the PCA array, I.e. the number of effective seconds each PCU was sensitive to X-rays during each 16-second counting interval. When a PCU's high voltage is disabled, the detector is considered "dead". Other useful quantities in the output file are: PCUN_ON - is PCU N enabled? DeadTimePcuN - [sec] effective dead-time for PCU N LiveFracPcuN - fractional live-time for PCU N BadPcuN - PCU N is OFF or in a known bad state IMPORTANT CAVEATS There are some important caveats related to the results of this tool. **THE DEAD-TIME RESULTS ARE ESTIMATES, NOT 100% ACCURATE**. Standard1 files contain VLE and Propane counts that are summed across all five PCUs. It is not possible to determine which individual PCU a VLE or Propane count is attributable to. (In contrast, Standard2 does maintain separate counts for each PCU). Therefore, a heuristic must be applied to estimate the individual PCU VLE and Propane rates. We estimate that for faint sources, the dead-time will be accurate to approximately 15% or better; this is dominated by PCU-to-PCU imbalances in VLE rates. Thus, if the dead-time is estimated to be 3%, this really means 3% +/- 0.45%. For bright sources, the error in the estimate maybe be dominated by PCU-to-PCU variations in propane layer counts. Based on collimator misalignments, this may contribute a 5-10% error. **THE RESULTING OUTPUT FILE IS MUCH LARGER THAN THE ORIGINAL STANDARD1 FILE** Because many dead-time related quantities must be calculated every 0.125 sec, there is a significant expansion of the total file size compared to the original Standard1 size. Users can expect a 10-12x size increase compared to the original (ungzipped) file size. Users should plan accordingly for needed disk space and file I/O. BAD SCIENCE TIMES By default, zero_bad=YES, which instructs pcadeadcalc1 to filter out data from PCUs which are in a known "bad" state for scientific analysis. It does this by setting the Xenon counts to zero during these times, as well as OnTime = LiveTime = 0. This setting is recorded on a PCU-by-PCU basis. However, because the individual VLE and Propane rates are computed based on a heuristic the total rate, some "bad" times will blank out the rates for all five PCUs. (The heuristic does not function during transition periods.) pcadeadcalc1 has a list of known conditions which would flag a PCU as "bad" for scientific analysis. The tool's categorization does not mean that such data cannot be analyzed, but it does mean that typically a scientist would not analyze these data, but even if they did, it would require special care. The conditions also represent the RXTE PCA team's best recommendations for data filtering for generic observations and typical scientific analysis. The conditions for declaring a "bad time" are: 1. A PCU's high voltage is disabled. 2. A PCU's high voltage transition occurred within 24 seconds of the current time. Note that when *any* PCU transition occurs, *all* PCU counts during the transition time will be zeroed. (disable with transition_bad=NO)' 3. A PCU breakdown event occurred between TIME-600 and TIME+150. (only if breakfile is set) 4. PCU0 is missing its propane layer (i.e., after 2000-05-20). (disable with propane_bad=NO) 5. PCU1 is missing its propane layer (i.e., after 2006-12-25). (disable with propane_bad=NO) Most of these conditions can be disabled, as indicated in the list. BREAKDOWNS PCA breakdown events can create subtle effects even before the high voltage is turned off. The user is strongly recommended to download a up-to-date version of the RXTE calibration database (CALDB) and set breakfile=CALDB, which is the default. This will automatically flag breakdown events as "bad" times on an individual PCU-by-PCU basis. HOW TO RUN Standard1 files (files beginning with "FS46"), contain various counting rates and spectra that are used for science. The user must provide as input the name of the Standard1 file and the names of the PCA housekeeping files via the 'hkfiles' parameter (i.e., files beginning with "FH5a,b,c,d,e"). Let us assume that following files are present: FS46 - Standard1 data and we wish to calculate deadtime quantities FS46_DT - Standard1 *PLUS* deadtime quantities First, change directories to the OBSID/pca directory, and then obtain a list-file with the housekeeping files with this command, ls FH5* > hkfiles.lis This should list all 5 PCU housekeeping files. Next, run pcadeadcalc1 on the Standard1 file, pcadeadcalc1 infile=FS46 outfile=FS46_DT hkfiles=@hkfiles.lis This should create a new file, FS46_DT, with deadtime correction quantities. HOW TO USE OUTPUTS This section briefly describes how these outputs can be used. The user can simply plot the various quantities to get a sense of the deadtime variations during an observation. The most relevant quantities are TIME vs. LiveFracPcuN. The resulting Standard1 files with deadtime quantities can be used to extract light curves with the 'pcaextlc1' task. PARAMETERS infile [filename] Name of the Standard1 or background file. outfile [filename] Name of the output file which will have dead-time quantities appended. (hkfiles) [string] Specify a list of PCA housekeeping files. This can either be a comma-separated list, or a @filename.txt where filename.txt contains a list of files. There must be exactly five files specified because there are five PCUs. (breakfile = 'CALDB') [string] Set to a file name which contains PCU breakdown GTI information. If set to 'CALDB', then the task will query CALDB for the appropriate file. If set to 'NONE', then no PCU breakdown processing will be done. (zero_bad = YES) [boolean] If set, then the task will set the Xenon counts to zero any PCU which is considered to be in a "bad" science state at the given time, as described above. If not set, then Xenon counts are not changed. (transition_bad = YES) [boolean] If set, then PCU high voltage transitions are considered "bad" science times (+/- 16 sec). If not set, then only PCU high voltage "off" is considered bad. (propane_bad = YES) [boolean] If set, then PCUs are considered "bad" if their propane layers are gone. If not set, then the propane layer status is not considered. (cleanup = yes) [boolean] Clean up scratch files? (chatter = 2) [int] range 0-5 Verbosity level of output (clobber = no) [boolean] Overwrite output file? (history = yes) [boolean] Write standard HEADAS parameter history into output file? EXAMPLES See main text. CAVEATS See main text above. BUGS Please report problems to xtehelp@athena.gsfc.nasa.gov. SEE ALSO pcadeadcalc2, saextrct