/ ciao4.17 / ahelp / acis_build_badpix.html

Jump to: Description · Examples · Parameters · Bugs · See Also

AHELP for CIAO 4.17

acis_build_badpix

Synopsis

Create an observation-specific bad-pixel file

Syntax

acis_build_badpix  pbkfile [berrfile] calibfile biasfile evt0file
outfile [maxerr] [usrfile] [bitflag] [procbias] [biasthresh]
[writebias] [outbias] obsfile [clobber] [verbose]

Description

The tool acis_build_badpix was designed for the ACIS pipeline, but can be employed by users to update and/or customize an observation-specific bad-pixel file. It is executed twice in the pipeline. The first execution (example 1) creates a bad-pixel file that includes a list of (1) known bad pixels and columns from the calibration database, (2) pixels with bias-parity errors (if any), and (3) pixels with bad bias values. After the second execution (example 2), the same data are included in the output file plus additional data about hot pixels and cosmic-ray afterglows.

The parameters bitflag and usrfile can be used to customize a bad-pixel file. For example, the parameter bitflag can be used to exclude from the output file (1) columns adjacent to bad columns (example 3), (2) columns on node boundaries (example 4), (3) pixels affected by cosmic-ray afterglows (example 5), or (4) pixels that are hot (example 6). The parameter usrfile specifies the name of a supplemental input file that can be used to include or exclude any set of bad pixels from the output file (example 7).

Observation-specific bad-pixel files should be used as input when reprocessing ACIS event data with acis_process_events. They should also be used as input (by editing the ardlibpar file) when making an imaging or grating ARF (see mkarf, mkgarf, and mkwarf) or when making an instrument map (see mkinstmap).

Bad-pixel files include the columns SHAPE ("point" or "rectangle"), COMPONENT (a sequential ID number), CHIPX and CHIPY (the coordinates of a point or the boundaries of a rectangle), TIME (the beginning of the observation, bias-parity error, or cosmic-ray afterglow), TIME_STOP (the end of the observation or afterglow) and STATUS (a bit-encoded description of the reason or reasons a region is bad (see Table 1).

Table 1

Bit	Reason a pixel or column is identified as "bad"
0	Known bad pixel
1	Known bad column
2	Bias-parity error. The start time is specified in the column TIME.
3	Bias = 4095 adu.
4	Bias = 4094 adu.
5	CHIPX = 1 or 1024 (i.e. inactive columns). [obsolete]
6	In timed-exposure mode observations, CHIPY = 1 or 1024 (i.e. inactive rows). [obsolete]
7	User specified
8	The pixel is horizontally, vertically or diagonally adjacent to a bad pixel.
9	For TIMED VFAINT mode observations, CHIPX = 2 or 1023 or CHIPY = 2 or 1023 (i.e. avoid having a 5 x 5 event island overlap the edge of a CCD). [obsolete]
10	For TIMED VFAINT mode observations, the pixel is horizontally, vertically or diagonally adjacent to a pixel for which bit eight is set to one. [obsolete]
11	CHIPX = 512 or 513. Events in these columns are often due to cosmic rays.
12	CHIPX = 256, 257, 768 or 769. Events in these columns are often due to cosmic rays.
13	FEP0 problem
14	Hot pixel
15	Cosmic-ray afterglow. The start and stop times of the afterglow are specified in the columns TIME and TIME_STOP, respectively.
16	Bad bias value
17	Frame-Store Shadow. Events landing in the first several rows of each ccd are now marked as bad due to the effect of shadowing by the framestore cover. The number of rows shadowed for each CCD are provided in the CALDB badpix files.
18-31	Unused

The use of STATUS bits 5, 6, and 9 is obsolete because these conditions are properly addressed in observation-specific mask files.

Examples

Example 1

acis_build_badpix pbkfile="acisf158187762N002_pbk0.fits"
berrfile=@berr_list.txt calibfile="CALDB" biasfile=@bias_list.txt
evt0file="none" outfile="tmp1_bpix1.fits"
obsfile="axaff03846_000N002_obs0a.par"

In this example, the output bad-pixel file includes pixels and columns identified as bad in the CALDB file, pixels with bias-parity errors, and pixels that have unusually large or small bias values. The file berr_list.txt includes a list of the names of the bias-parity error files for the observation, with one file name per line. The file bias_list.txt includes a similar list of the bias files. No Level 0 event-data files are used as input (evt0file="none"), because the observation was not performed using faint-with-bias mode. The output file tmp1_bpix1.fits is used as input for the tool acis_find_afterglow.

While the bias and bias-parity error files are optional input files, users are encouraged to include them. Otherwise, some bad pixels may be overlooked.

Example 2

acis_build_badpix pbkfile="acisf158187762N002_pbk0.fits"
berrfile="none" calibfile="tmp2_bpix1.fits" biasfile="none"
evt0file="none" outfile="acisf03846_000N999_bpix1.fits"
obsfile="axaff03846_000N002_obs0a.par"

In this example, the input file tmp2_bpix1.fits is not a bad-pixel file in the calibration database, but is the output of the tool acis_find_afterglow. It is the product of having run acis_build_badpix (see example 1) and acis_find_afterglow in sequence. Not only does it include pixels and columns identified as bad in the CALDB, pixels with bias-parity errors, and pixels that have unusually large or small bias values (example 1), but also it includes pixels that are hot or that contain cosmic-ray afterglows. Executing acis_build_badpix on the output of acis_find_afterglow ensures that pixels adjacent to the hot pixels and afterglows are marked as bad.

Example 3

acis_build_badpix pbkfile="acisf158187762N002_pbk0.fits"
berrfile="none" calibfile="tmp2_bpix1.fits"
bitflag="00000000000000122221100020022212" biasfile="none"
evt0file="none" outfile="acisf03846_000N998_bpix1.fits"
obsfile="axaff03846_000N002_obs0a.par"

This example is the same as example 2 except that the parameter bitflag is used to exclude columns adjacent to bad columns from the output file. That is, the second character of the bitflag string, from right to left, is a "1", not the default value of "2" (see the description of the parameter bitflag for more details).

Example 4

acis_build_badpix pbkfile="acisf158187762N002_pbk0.fits"
berrfile="none" calibfile="tmp2_bpix1.fits"
bitflag="00000000000000122220100020022222" biasfile="none"
evt0file="none" outfile="acisf03846_000N997_bpix1.fits"
obsfile="axaff03846_000N002_obs0a.par"

This example is the same as example 2 except that the parameter bitflag is used to exclude the columns with CHIPX = 256, 257, 768, and 769 from the output file. That is, the thirteenth character of the bitflag string, from right to left, is a "0", not the default value of "1" (see the description of the parameter bitflag for more details).

Example 5

acis_build_badpix pbkfile="acisf158187762N002_pbk0.fits"
berrfile="none" calibfile="tmp2_bpix1.fits"
bitflag="00000000000000120221100020022222" biasfile="none"
evt0file="none" outfile="acisf03846_000N996_bpix1.fits"
obsfile="axaff03846_000N002_obs0a.par"

This example is the same as example 2 except that the parameter bitflag is used to exclude cosmic-ray afterglows from the output file. That is, the sixteenth character of the bitflag string, from right to left, is a "0", not the default value of "2" (see the description of the parameter bitflag for more details).

Example 6

acis_build_badpix pbkfile="acisf158187762N002_pbk0.fits"
berrfile="none" calibfile="tmp2_bpix1.fits"
bitflag="00000000000000122021100020022222" biasfile="none"
evt0file="none" outfile="acisf03846_000N995_bpix1.fits"
obsfile="axaff03846_000N002_obs0a.par"

This example is the same as example 2 except that the parameter bitflag is used to exclude hot pixels from the output file. That is, the fifteenth character of the bitflag string, from right to left, is a "0", not the default value of "2" (see the description of the parameter bitflag for more details).

Example 7

acis_build_badpix pbkfile="acisf158187762N002_pbk0.fits"
berrfile="none" calibfile="tmp2_bpix1.fits" usrfile="suppl_bpix1.txt"
biasfile="none" evt0file="none" outfile="acisf03846_000N994_bpix1.fits"
obsfile="axaff03846_000N002_obs0a.par"

This example is the same as example 2 except that the parameter usrfile is used to specify the supplemental input file suppl_bpix1.txt. This file includes the following six lines.

#ccd_id chipx_lo chipx_hi chipy_lo chipy_hi time time_stop bit action
#------ -------- -------- -------- -------- ---- --------- --- ------
 5      608      608      282      282      0    0         7   include
 6      682      682      1        1024     0    0         -1  exclude
 6      683      683      1        1024     0    0         -1  exclude
 6      684      684      1        1024     0    0         -1  exclude

The first two lines are required. The third line adds a new bad pixel to the output file for (CCD_ID, CHIPX, CHIPY) = (5, 608, 282). The fourth, fifth, and sixth lines remove the bad column (CCD_ID, CHIPX, CHIPY) = (6, 683, 1-1024) and the two columns adjacent to it from the output file. See the description of the parameter usrfile for more details.

Parameters

name	type	ftype	def	min	max	reqd	stacks
pbkfile	file	input				yes
berrfile	file	input				no	yes
calibfile	file	input				yes
biasfile	file	input				yes	yes
evt0file	file	input	none			yes	yes
outfile	file	output				yes
maxerr	integer		10			no
usrfile	file	input	none			no
bitflag	string		00000000000000122221100020022222			no
procbias	boolean		yes			no
biasthresh	integer		6	3	4000	no
writebias	boolean		no			no
outbias	file	output				no
obsfile	file	input				yes
clobber	boolean		no			no
verbose	integer		0	0	5	no

Detailed Parameter Descriptions

Parameter=pbkfile (file required filetype=input)

The name of the required input parameter-block file (see examples 1-7). This file is used to determine which CCDs are active, their CCD_IDs, the corresponding FEP_IDs, the READMODE and DATAMODE, TSTART and TSTOP, and the values of ROWCNT, STARTROW, etc.

Parameter=berrfile (file not required filetype=input stacks=yes)

The name(s) of the optional input bias-parity error file(s), if any (see example 1). The bias-parity error data is useful for two reasons. First, pixels that have bias-parity errors are written to the output bad-pixel file. Due to the manner in which TIMED VFAINT mode data is handled onboard, occasionally the pixels (CHIPX,CHIPY) = (1,ROWCNT+1), (2,ROWCNT+1), (1023,1), and (1024,1) are incorrectly included in the bias-parity error files. In such cases, the output bad-pixel file does not include bias-parity errors for these pixels. The problem does not occur for other observing modes. A second reason for using bias-parity error files is that they provide a means of identifying observations that suffer from the rare "FEP0" problem (see maxerr).

Parameter=calibfile (file required filetype=input)

The name of the required input bad-pixel file. This file may be a CALDB file (example 1) or an observation-specific bad-pixel file (examples 2-7).

Parameter=biasfile (file required filetype=input stacks=yes)

The name(s) of the optional input bias map(s) (see example 1). Pixels that have bias values of 4094 or 4095 are written to the output bad-pixel file. In addition, if procbias=yes, then other pixels are searched for bad bias values. If a pixel is found to have a value that is either too low or too high (see biasthresh), then the pixel is written to the output bad-pixel file.

Parameter=evt0file (file required filetype=input default=none stacks=yes)

The name(s) of the optional input Level 0 event-data file(s). This parameter should only be used if the observation was performed using the rare faint-with-bias mode (i.e. DATAMODE = FAINT_BIAS) and if an output bias map(s) is desired (i.e. writebias=yes). 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 one extension for each active CCD. Each extension includes the columns SHAPE ("point" or "rectangle"), COMPONENT (a sequential ID number), CHIPX and CHIPY (the coordinates of a point or the boundaries of a rectangle), TIME (the beginning of the observation, bias-parity error, or cosmic-ray afterglow), TIME_STOP (the end of the observation or afterglow) and STATUS (a bit-encoded description of the reason or reasons a region is bad (see Table 1).

Parameter=maxerr (integer not required default=10)

The upper limit on the number of "normal" bias-parity errors for a CCD. If a CCD has more than this number, then the CCD is assumed to be suffering from the rare "FEP0" problem. In such cases, the entire top half of the CCD is marked as bad in the output bad-pixel file. The default value of this parameter was chosen with care. Be cautious about using another value.

Parameter=usrfile (file not required filetype=input default=none)

The name of an optional user-specified input file. Such files provide a means of including one or more additional bad pixels or columns in the output bad-pixel file and of excluding one or more bad pixels from the output file (see example 7).

The first two rows of the file must be

#ccd_id chipx_lo chipx_hi chipy_lo chipy_hi time time_stop bit action
#------ -------- -------- -------- -------- ---- --------- --- ------

Every row thereafter must contain nine space- or tab-delimited columns of data. From left to right, these columns are

Table 2

Column	Name	Description
1	CCD_ID	The CCD_ID of the appropriate CCD. CCD_ID must be one of the CCDs identified as active in the parameter-block file.
2	CHIPX_LO	The CHIPX coordinate of a pixel or the lower CHIPX boundary of a rectangle. CHIPX_LO must satisfy the constraints that 1 <= CHIPX_LO <= CHIPX_HI.
3	CHIPX_HI	The CHIPX coordinate of a pixel or the upper CHIPX boundary of a rectangle. CHIPX_HI must satisfy the constraints that CHIPX_LO <= CHIPX_HI <= 1024.
4	CHIPY_LO	The CHIPY coordinate of a pixel or the lower CHIPY boundary of a rectangle. CHIPY_LO must satisfy the constraints that 1 <= CHIPY_LO <= CHIPY_HI.
5	CHIPY_HI	The CHIPY coordinate of a pixel or the upper CHIPY boundary of a rectangle. CHIPY_HI must satisfy the constraints that CHIPY_LO <= CHIPY_HI <= 1024.
6	TIME	The start time for the time interval of interest. If TIME = TIME_STOP = 0, then TIME is set to the beginning of the observation. TIME must satisfy the constraints that 0 <= TIME < TIME_STOP.
7	TIME_STOP	The stop time for the time interval of interest. If TIME = TIME_STOP = 0, then TIME_STOP is set to the end of the observation. Otherwise, TIME_STOP must satisfy the constraint that TIME < TIME_STOP.
8	BIT	Typically BIT = 7 if a new bad pixel or column is added to the output file and BIT = -1 if a bad pixel or column is removed from the output file. However, any value from the set [0-4, 7, 11-16] (see Table 1) may be used if a region is added. One of these nonnegative values can also be used to remove a region, but only the specified STATUS bit will be disabled. Therefore, if more than one STATUS bit is set for a pixel or column, only the specified bit will be unset. The other bits will remain set. A value of -1 unsets all STATUS bits for the region. If BIT = 11, then the region can only have CHIPX coordinates of 512 or 513. If BIT = 12, then the region can only have CHIPX coordinates of 256, 257, 768, or 769. If BIT = 13, then the region can only have CHIPY coordinates greater than or equal to 513.
9	ACTION	Use either "include" to add a new bad pixel or column or "exclude" to remove a bad pixel or column. If ACTION = include, then the corresponding character in the parameter bitflag cannot be "0".

If there is more than one region specified in the usrfile, then the coordinates of the regions cannot overlap.

Parameter=bitflag (string not required default=00000000000000122221100020022222)

A 32 character string with one character for each of the 32 bad-pixel STATUS bits (see Table 1). The character on the right-hand side is associated with STATUS bit 0. The character on the left-hand side is associated with STATUS bit 31. The default and allowed values for each character are listed in Table 3.

Table 3

Bit	Default Value	Valid Values
0-4	2	0-2
5-6	0	0
7	2	1-2
8-10	0	0
11-12	1	0-2
13-16	2	0-2
17	1	0-2
18-31	0	0

The actions associated with the characters "0", "1", and "2" are described in Table 4.

Table 4

Character	Action
0	If the character associated with a bad-pixel STATUS bit is "0", then bad pixels or columns of the type associated with this bit (see Table 1 and examples 4-6) are not written to the output file. If a pixel or column is bad for some other reason, then it may still be written to the output file.
1	If the character associated with a bad-pixel STATUS bit is "1", then bad pixels or columns of the type associated with this bit (see Table 1 and example 3) are written to the output file, but the pixels immediately adjacent to these bad pixels or columns are not written to the output file. If a pixel or column is bad for some other reason, then the pixels adjacent to it may still be written to the output file.
2	If the character associated with a bad-pixel STATUS bit is "2", then bad pixels or columns of the type associated with this bit (see Table 1) are written to the output file as well as the pixels immediately adjacent to these bad pixels or columns.

Parameter=procbias (boolean not required default=yes)

If procbias=yes, then the bias map(s) specified by the parameter biasfile is(are) searched for pixels that have suspiciously high or low bias values (see biasthresh). Pixels that have one or more of the STATUS bits 0-6, 11, or 13 set are excluded from the search. Pixels with suspicious bias values are written to the output file.

Parameter=biasthresh (integer not required default=6 min=3 max=4000)

The threshold used to determine whether a bias value is suspiciously high or low (see procbias). If the absolute value of the difference between the bias value for a pixel and the median bias value for that column differ by more than the biasthresh, then the bias value is suspicious and the pixel is written to the output file. Pixels identified as bad in the calibration, bias-parity error, and bias map files are excluded from the computation of the median. The default value of this parameter was chosen with care. Be cautious about using some other value.

Parameter=writebias (boolean not required default=no)

If writebias=yes and the parameter evt0file is used to specify the input Level 0 faint-with-bias mode event-data file(s), then a bias map will be created for each CCD from the bias information in the event file(s). The file name prefix for each bias is specified by the parameter outbias.

Parameter=outbias (file not required filetype=output)

The file name prefix of the output bias map(s) created if writebias=yes and the parameter evt0file is used to specify the input Level 0 faint-with-bias mode event-data file(s).

Parameter=obsfile (file required filetype=input)

The name of the input observation parameter file. Data in this file are used to populate some of the header keywords in the output file. A Level 1 or Level 2, but not a Level 0, event-data file can be used in lieu of the observation parameter file.

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 is not changed.

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, then very few messages are reported. If verbose=5, then a significantly larger amount of messages is produced.

Bugs

Start and stop times may encompass frames of good data

If two or more afterglows are horizontally, vertically, or diagonally adjacent to one another on a CCD, then the set of afterglows are marked as adjacent to one another, whether they are associated with a common event or not. As a result, the start times of the afterglows in the set are modified to have the same start time, which is the earliest start time of the set of afterglows. Likewise, the stop times are modified to use a common time, which is the latest stop time of the set.

In most cases where afterglows are adjacent to one another, the afterglows are associated with a common event and have similar start and stop times. However, in rare cases, they are not associated with a common event and the start and stop times can encompass many frames of data instead of just a few or a few dozen frames. In these rare circumstances, some good data may be marked as bad in Level=1 event files and excluded from Level=2 event files.