|
|
|
|
|
SynopsisCreate an observation-specific bad-pixel file Syntaxacis_build_badpix pbkfile berrfile calibfile biasfile evt0file outfile [pbkext] [berrext] [maxerr] [usrfile] [bitflag] [procbias] [biasthresh] [evtsext] [writebias] [outbias] [obsfile] [clobber] [verbose] DescriptionThe tool acis_build_badpix has two related uses. First, it is used to create an observation-specific bad-pixel file. The input for this file includes a list of known bad pixels and columns from the calibration database, observation-specific bias-parity error files (if any), and bias maps. The bias maps may be searched for pixels that have unusually high or low bias values. When appropriate, pixels adjacent to bad pixels are also identified as bad. Second, acis_build_badpix is one of the tools in the hot-pixel tool suite. The bad-pixel output file of the tool acis_classify_hotpix is reprocessed using acis_build_badpix to insure that pixels adjacent to hot pixels are identified as bad, if necessary. To make it easier to customize observation-specific bad-pixel files, the tool acis_build_badpx includes two enhancements. Once enhancement permits users to ignore selected bad-pixel criteria. For example, a user can choose not to include cosmic-ray afterglows, hot pixels, and/or node boundaries in the output bad-pixel file. This functionality is embodied in the parameter bitflag. The same parameter can be used to prevent the code from identifying the neighbors of bad pixels as bad, but still flag pixels next to other bad pixels as bad. A second enhancement enables users to include or exclude specific regions from the output file by preparing a supplemental file that includes a list of regions of interest. The name of the supplemental input file is specified via the parameter usrfile. The output bad-pixel file includes the columns SHAPE ("point" or "rectangle"), COMPONENT (a sequential ID number), CHIPX, CHIPY, TIME (the beginning of the observation or cosmic-ray afterglow), TIME_STOP (the end of the observation or afterglow) and STATUS (a bit-encoded description of the reason a pixel is identified as bad (see table below). Reasons a pixel is identified as "bad"
Example 1acis_build_badpix pbkfile="acisf079650447N002_pbk0.fits" berrfile="none" calibfile="CALDB" biasfile=@bias_list.txt evt0file="none" outfile="tmp1_bpix1.fits" obsfile="axaff00732_000N002_obs0a.par" In this example, the output bad-pixel file tmp1_bpix1.fits includes pixels and columns identified as bad in the CALDB file and pixels that have unusually large or small bias values. The file bias_list.txt includes the names of the bias map(s) for the observation, with one file name per line. There are no bias-parity error files for this observation. No Level 0 event files are used as input, because the observation was not performed using faint-with-bias mode. The output file is used as input for the tool acis_find_hotpix. While the bias and bias-error files can be excluded, users are encouraged to include them as part of the input. Otherwise, some bad pixels may be overlooked. Example 2acis_build_badpix pbkfile="acisf079650447N002_pbk0.fits" berrfile="none" calibfile="tmp2_bpix1.fits" biasfile=@bias_list.txt evt0file="none" outfile="acisf00732_999N002_bpix1.fits" obsfile="axaff00732_000N002_obs0a.par" In this example, the input file tmp2_bpix1.fits is not a bad-pixel file in the calibration database, but the output of the tool acis_classify_hotpix. The output file created by acis_build_badpix includes pixels and columns identified as bad in the input file and, in some cases, pixels adjacent to the pixels in the input file. The output bad-pixel file should be used as input when making an imaging or grating ARF (see mkarf, mkgarf, mkwarf and acisspec) or when making an instrument map (see mkinstmap) by editing the ardlibpar file. Example 3This example demonstrates the use of the usrfile parameter. The tool uses the Data Model to handle the input of the file. The format of the file should be similar to the following. The top row of the usrfile should have the nine column headings tab delimited preceded by the '#' symbol. The second row of the usrfile should have the '#' symbol followed by the appropriate number of '-'s which are also tab delimited (appropriate number of '-'s comes from the length of the column heading, for example 'chipx_lo' will have eight '-'s). The following rows will contain the data for the desired pixels, columns or regions.
The first two rows of this sample usrfile contain duplicate information for some individual pixels. The first row declares an action of exclude where the second row declares an action of include. In this situation, the last row supersedes the data of all previous rows. Thus, the inclusion of those individual pixels will occur. Note that if the time and time_stop fields are both set to 0, the values of the start and stop times associated with the observation will replace the 0 value. Parameters
Detailed Parameter DescriptionsParameter=pbkfile (file required filetype=input)The name of the input parameter-block file (e.g. acisf079650447N002_pbk0.fits). The parameter-block file is used to determine which CCDs are active, the READMODE and DATAMODE and the values of CCD_ID, FEP_ID, ROWCNT, STARTROW, TSTART, TSTOP etc. Parameter=berrfile (file required filetype=input stacks=yes)The name(s) of the optional input bias-parity error file(s), if there are any. Pixels that have bias-parity errors are written to the output bad-pixel file. Occasionally, the pixels (CHIPX,CHIPY) = (1023,1) and (1024,1) are reported to have bias-parity errors for TIMED VFAINT mode observations even if the pixels are fine. This problem is due to the manner in which TIMED VFAINT mode data is handled onboard. The problem does not occur for other observing modes. The bias-parity data also provides a diagnostic for the rare "FEP0" problem (see maxerr). Parameter=calibfile (file required filetype=input default=CALDB)The name of the input bad-pixel file. This file may be a CALDB file, an observation-specific bad-pixel file (e.g. "acisf00732_000N002_bpix1.fits") or a file created by the tool acis_classify_hotpix. If a bias map is searched for pixels with unusually high or low bias values, then the pixels known to be bad are excluded from the search. Parameter=biasfile (file required filetype=input stacks=yes)The name(s) of the optional input bias map(s) for the observation (e.g. acisf079649146N002_0_bias0.fits). Pixels that have bias values of 4094 or 4095 adu are written to the output bad-pixel file. If procbias=yes, then the bias map(s) is searched for pixels whose bias values are either too low or too high (see biasthresh). If the bias value of a pixel is found to be too low or too high, the pixel is identified as bad in the output file. Parameter=evt0file (file required filetype=input default=none stacks=yes)If the observation was performed in faint-with-bias mode and an output bias map(s) is desired (i.e. writebias=yes), then the name(s) of the input Level 0 event data file(s) (e.g. acisf079650447N002_0_evt0.fits) must be specified using the parameter evt0file. The prefix of the name(s) of the output bias map(s) is specified using the parameter outbias. Parameter=outfile (file required filetype=output)The name of the output bad-pixel file. This file includes a list of the bad pixels and columns in the input bad-pixel file. The output file may also include the pixels adjacent to bad pixels and columns and pixels associated with bias errors or bad bias values. Parameter=pbkext (string not required default=PBK)The name (EXTNAME) of the extension in the parameter-block file that includes information about the active CCDs. Parameter=berrext (string not required default=BERR)The name (EXTNAME) of the extension in the bias-error file(s) that includes information about bias-parity errors. Parameter=maxerr (integer not required default=10)If a CCD has more than maxerr bias-parity errors, then the CCD is most likely suffering from the "FEP0" problem and the entire top half of the CCD is marked as bad. This problem is rare. The default value of this parameter should be adequate in most cases. Be cautious about using some other value. Parameter=usrfile (string not required filetype=input default=none)The user has the option of specifying a supplemental input file which includes one row for each pixel, column, or region. Each row has exactly nine columns that are tab delimited. The columns are, from left to right along a row,
If the usrfile is not "none" or "NONE" and specifies an existing file, then each row of the file will be read. An error in any row of the file will result in an error message and the file will be ignored. The possible error conditions include a row that
If more than one row of the usrfile describes the same pixel, then the information on the last row supersedes the information on previous rows. Parameter=bitflag (string not required default=00000000000000022221100120022222)This parameter is a thirty-two character string, where the characters correspond to STATUS bits 0-31 from right to left. The acceptable and default values for each character are listed below.
The action associated with each character are:0: Ignore a bad pixel or column. Do not write such regions to the output file unless they satisfy another condition. If they do satisfy another condition, then the STATUS bit(s) for which bitflag = "0" are set to zero. For example, if the characters in the bitflag associated with STATUS bits 14 (hot pixels) and 15 (afterglows) are "0", then exclude hot pixels and afterglows from the output bad-pixel file and do not set STATUS bits 14 and 15 to one for any pixel. 1: Include a bad pixel or column, but not the pixels or columns adjacent to it. For example, if the character in the bitflag associated with STATUS bit 1 (bad columns) is "1," the the bad columns at CHIPX = 66, 496-8 and 738 for CCD_ID = 7 are marked as bad in the output file, but not the columns at CHIPX = 65, 67, 495, 499, 737 and 739. STATUS bit 8 is set to zero for the columns CHIPX = 66, 496-8 and 738. 2: Include a bad pixel or column and the pixels or columns adjacent to it. For example, if the character in the bitflag associated with STATUS bit 1 (bad columns) is "2," then the bad columns at CHIPX = 66, 496-8 and 738 for CCD_ID = 7 are marked as bad in the output file. In addition, the columns at CHIPX = 65-67, 495-499 and 737-739 have STATUS bit 8 set to one. Parameter=procbias (boolean not required default=yes)If procbias=yes, then the bias map(s) is searched for pixels that have suspiciously high or low bias values. Pixels with suspicious bias values are written to the output file. Parameter=biasthresh (integer not required default=6 min=3 max=4000)This parameter is used to determine which pixels in a bias map have suspiciously high or low values. Before performing the test, the median bias value of a column of a CCD is subtracted from the bias values of all the pixels in the column to obtain the adjusted biases. Pixels identified as bad in the calibration, bias-err and bias-map files are excluded from the computation of the median. If the adjusted-bias value of a pixel > biasthresh adu or < -biasthresh adu, then the pixel is identified as bad and written to the output file. The default value of this parameter should be adequate in most cases. Be cautious about using some other value. Parameter=evtsext (string not required default=EVENTS)The name (EXTNAME) of the extension in the Level 0 event-data file(s) that includes the list of event information. Parameter=writebias (boolean not required default=no)If writebias=yes and the input includes Level 0 faint-with-bias mode event-data file(s), then a bias map will be created for each CCD used from the bias information in the event file(s). The file name prefix for each bias is specified by the parameter outbias. Parameter=outbias (string not required)The file name prefix of the output bias map(s) created if writebias=yes and the input includes faint-with-bias mode Level 0 event-data file(s). Parameter=obsfile (string not required filetype=input)The name of the input observation-parameter file (e.g. axaff00732_000N002_obs0a.par). This file is used to populate some of the header keywords of the output file. If you do not have the file, it can be created from the header of a Level 1 or Level 2 event file by using the tool dmmakepar. Parameter=clobber (boolean not required default=no)If clobber=yes and a file exists that has the same name as the name of the output file, then the existing file is overwritten. If clobber=no, then the existing file remains unchanged. Parameter=verbose (integer not required default=0 min=0 max=5)This parameter determines the amount of messages that is generated by acis_build_badpix. If verbose=0, very few messages are reported. If verbose=5, the largest amount of messages is produced. BugsSee the bugs page for this tool on the CIAO website for an up-to-date listing of known bugs. |
 |
The Chandra X-Ray
Center (CXC) is operated for NASA by the Smithsonian Astrophysical Observatory. 60 Garden Street, Cambridge, MA 02138 USA. Email: cxcweb@head.cfa.harvard.edu Smithsonian Institution, Copyright © 1998-2004. All rights reserved. |
![[CIAO Logo]](../imgs/ciao_logo_navbar.gif){kind=logo}