Last modified: 13 Jan 2020


Customizing an ACIS Bad Pixel File

CIAO 4.16 Science Threads



Advanced Thread

This is an advanced thread. Most users do not need to customize their badpixel files.

Pipeline-produced bad pixel files are fairly complete. They include nearly every bad pixel as well as some pixels adjacent to the bad pixels. Events that occur on these pixels have STATUS bits set to one in the associated Level 1 event file and are excluded from Level 2 event files. Depending on the specific goals of an analysis project, it may be advantageous to keep events on one or more bad pixels.

acis_build_badpix has two parameters, bitflag and usrfile, that make it easy to customize an observation-specific ACIS bad pixel file. This thread provides a few brief examples of how these parameters may be used. For more information about these parameters and the tool, refer to the ahelp file.


To create a customized ACIS bad pixel file to be used in the data analysis.

The bad pixel file created by running the "Reprocessing Data to Create a New Level=2 Event File" thread will be sufficient for most analyses. Few users require the advanced analysis in this thread.

Related Links:

Last Update: 13 Jan 2020 - Reviewed for CIAO 4.14. No changes.


Get Started

Download the sample data: 333 (HETG/ACIS-S, NGC 1275)

unix% download_chandra_obsid 333 evt2,bpix,pbk
Anomalous Dataset

A hardware anomaly occurred during this observation that requires special processing. Users should check the V&V report associated with these data before attempting to analyze them.

The input bad pixel file used in this thread should have been created with acis_build_badpix and acis_find_afterglow tools. Follow the "Reprocessing Data to Create a New Level=2 Event File" thread if you are unsure of how your bad pixel file was created.

In this thread, we assume that all relevant files are in the same working directory.

Create an Observation Parameter File

An observation parameter file is used to populate some of the header keywords in the output file. This file is created from the header of a level=1 or level-2 event file.

unix% dmmakepar acisf00333N003_evt2.fits 333_obs.par

Exclude Existing Bad Pixels: the bitflag Parameter

The bitflag parameter can be used, for example, to exclude the following cases from the bad pixel file:

  1. columns adjacent to bad columns
  2. columns on node boundaries
  3. pixels affected by cosmic-ray afterglows
  4. pixels that are hot

If these pixels are excluded from the bad pixel file, the events on them are included in the final event file.

There are additional examples of these cases in the acis_build_badpix ahelp file, as well as a table of when each status bit would be set.

A. Events on the columns adjacent to bad columns

For example, if a bad column runs through a faint source, then a significant fraction of the events may be lost because not only is the bad column included in the the pipeline-produced bad pixel file, the columns adjacent to the bad column are also included. To retain the events on the columns adjacent to bad columns, run acis_build_badpix with bitflag="00000000000000122221100020022212":

acis_build_badpix \
         pbkfile="acisf055915346N003_pbk0.fits" \
         berrfile="none" \
         calibfile="acisf00333_000N003_bpix1.fits" \
         usrfile="none" \
         bitflag="00000000000000122221100020022212" \
         procbias=no \
         biasfile="none" \
         evt0file="none" \
         obsfile="333_obs.par" \

Here, acisf00333_000N003_bpix1.fits is the observation-specific bad pixel file produced as part of the standard pipeline processing. The parameter-block file acisf055915346N003_pbk0.fits and observation-parameter file 333_obs.par are also required. The output bad pixel file acisf00333_000N003_col_bpix1.fits no longer includes columns adjacent to bad columns (unless they are bad for some other reason).

B. Events on the chip node boundaries

A similar problem can occur if the source lies along a node boundary. To retain the events on the one- (and three-, but not two-) quarter chip node boundary, run acis_build_badpix with bitflag="00000000000000122220100020022222":

acis_build_badpix \
         pbkfile="acisf055915346N003_pbk0.fits" \
         berrfile="none" \
         calibfile="acisf00333_000N003_bpix1.fits" \
         usrfile="none" \
         bitflag="00000000000000122220100020022222" \
         procbias=no \
         biasfile="none" \
         evt0file="none" \
         obsfile="333_obs.par" \

The output bad pixel file acisf00333_000N003_node_bpix1.fits no longer includes the columns at CHIPX = 256, 257, 768, and 769.

C. Events associated with afterglows

If an analysis project involves a search for faint sources, then it is possible, albeit unlikely, that events associated with a real astrophysical source have been misidentified as being associated with a cosmic-ray afterglow. This possibility is more likely if most of the events occur over a short time interval. To retain events associated with afterglows, run acis_build_badpix with bitflag="00000000000000120221100020022222":

acis_build_badpix \
         pbkfile="acisf055915346N003_pbk0.fits" \
         berrfile="none" \
         calibfile="acisf00333_000N003_bpix1.fits" \
         usrfile="none" \
         bitflag="00000000000000120221100020022222" \
         procbias=no \
         biasfile="none" \
         evt0file="none" \
         obsfile="333_obs.par" \

The output bad pixel file acisf00333_000N003_aft_bpix1.fits no longer includes pixels associated with cosmic-ray afterglows.

Including New Bad Pixels: the usrfile Parameter

While bitflag can be used to remove one or more types of previously-identified bad pixels from the output bad pixel file, the usrfile parameter provides a means of adding new, previously-unidentified bad pixels. If these pixels are included in the bad pixel file, the events on the pixels are excluded from the final event file.

usrfile specifies the name of a supplemental input file; 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. Table 2 in the acis_build_badpix ahelp file explains each field.

For example, suppose that there is a bad pixel at the coordinates (647,749) on ACIS-7 and that column 330 on ACIS-4 is bad. Yet, these regions are not in the pipeline-produced bad pixel file. To create a bad pixel file which includes these regions, run acis_build_badpix with usrfile="acisf00333_000N003_usr_bpix1.txt":

acis_build_badpix \
         pbkfile="acisf055915346N003_pbk0.fits" \
         berrfile="none" \
         calibfile="acisf00333_000N003_bpix1.fits" \
         usrfile="acisf00333_000N003_usr_bpix1.txt" \
         bitflag="00000000000000122221100010022222" \
         procbias=no \
         biasfile="none" \
         evt0file="none" \
         obsfile="333_obs.par" \

where the contents of acisf00333_000N003_usr_bpix1.txt are

#ccd_id chipx_lo chipx_hi chipy_lo chipy_hi time time_stop bit action
#------ -------- -------- -------- -------- ---- --------- --- ------
 4      330      330      1        1024     0    0         1   include
 7      647      647      749      749      0    0         0   include
 5      608      608      282      282      0    0         -1  exclude
 6      585      585      1        1024     0    0         -1  exclude

Here, bits 0 and 1 are associated with bad pixels and columns, respectively. Since time = time_stop = 0, the changes apply to the entire time interval of the observation. The output file acisf00333_000N003_usr_bpix1.fits includes the new bad pixel and column. This example also illustrates that it is possible to remove individual bad pixels [(608,282) on ACIS-5] and columns [585 on ACIS-6] via usrfile.

Reprocessing with the New Bad Pixel File

Once a new observation-specific bad pixel file has been created, users should run chandra_repro as shown below which will apply the custom badpixel file when it runs the acis_process_events tool.

chandra_repro requires additional data products so they are retrieved using download_chandra_obsid which will only retrieve the files that are not already present. With all the files in place, the original badpixel file is moved to a different name.

unix% download_chandra_obsid 333
unix% cd 333/primary
unix% mv acisf00333_000N003_bpix1.fits acisf00333_000N003_bpix1.ORIG

Next, the user customized badpixel file is copied into the primary> directory. The badpixel file must be named *bpix1.fits. chandra_repro looks for the files by name and requires there be only 1 file named bpix1.fits in the primary directory.

unix% cp /path_to_file/acisf00333_000N003_usr_bpix1.fits ./

Finally, chandra_repro is run with the parameter badpixel=no

unix% cd ..
unix% chandra_repro . ./repro badpixel=no

This instructs chandra_repro to use the customize badpixel file and not to recreate one. This can be verified by examining the BPIXFILE parameter in the event file header

unix% dmkeypar repro/acisf00333_repro_evt2.fits BPIXFILE echo+

Analysis scripts will pickup the correct badpixel file by using this keyword. If running the individual CIAO tool users may need to set this as the the observation-specific bad pixel file for any subsequent analysis tasks; see the Setting the Observation-specific Bad Pixel Files thread for instructions.


19 Jan 2010 new for CIAO 4.2
13 Jan 2011 reviewed for CIAO 4.3: no changes
31 Aug 2011 added the Create an Observation Parameter File section
15 Dec 2011 reviewed for CIAO 4.4: creating a new ACIS bad pixel file is part of the "Reprocessing Data to Create a New Level=2 Event File" thread.
03 Dec 2012 Review for CIAO 4.5; no changes
25 Nov 2013 Reviewed for CIAO 4.6. No changes.
16 Dec 2014 Reviewed for CIAO 4.7. Increased visibility of this being an advanced thread. Expanded the reprocessing section to show to insert the custom badpixel file into the directories so that chandra_repro will find and use it.
20 Dec 2016 Review for CIAO 4.9.
25 Nov 2019 Review for CIAO 4.12. Updated bitflag settings.
13 Jan 2020 Reviewed for CIAO 4.14. No changes.