Extract CXO Data (extract-chandra)

Pipeline module to generate Chandra images, PSF maps, source/background regions, and extracted spectra from a Chandra X-ray Observatory (CXO) evt2 event file.

Automates the standard CIAO workflow:

1. Locate the user’s Conda environment.

2. Locate the appropriate aspect solution (.asol1.fits) and mask (.msk1.fits) files.

3. Convert the requested RA/Dec to SKY coordinates with dmcoords when auto-generating regions.

4. Run dmcopy to make a filtered image.

5. Create a PSF map with mkpsfmap.

6. If source/background regions are not supplied, run wavdetect and auto-create physical/SKY regions.

7. If source/background regions are supplied but are not physical regions, convert simple fk5/icrs circle or annulus regions to physical/SKY coordinates.

8. Run specextract to build source and background spectra.

Auto-region behavior:

If --src-reg and --bkg-reg are not supplied:

• --ra and --dec are required.

• wavdetect is run on the image cutout.

• If one or more wavdetect detections fall within

  --detect-match-radius of the input RA/Dec, the closest detection is used as the source center.

• The selected center is converted to physical/SKY X,Y using

  dmcoords.

• A circular source region is written with radius --src-radius.

• A background annulus is written with inner radius --bkg-inner and

  outer radius --bkg-outer.

• By default, --bkg-inner is set to --src-radius.

• If a wavdetect detection falls inside the background annulus, the

  annulus is replaced by a circular background region with radius --bkg-circle-radius.

Default auto-region values:

• --detect-match-radius 5 arcsec

• --src-radius 2 arcsec

• --bkg-inner defaults to --src-radius

• --bkg-outer 45 arcsec

• --bkg-circle-radius defaults to --bkg-outer

Existing-region behavior

If --src-reg and --bkg-reg are supplied:

• --ra and --dec are not required.

• Existing physical regions are used directly.

• Simple celestial fk5 or icrs circle and annulus regions are

  converted to physical/SKY regions before running specextract.

• If no RA/Dec is supplied, the script makes a full-field image instead of a

  centered cutout.

Supported region shapes for automatic conversion:

• circle(ra,dec,radius)

• annulus(ra,dec,r_in,r_out)

Positional arguments:

• COND_ENV : Name of the Conda environment to check against $CONDA_DEFAULT_ENV.

• EVT_FILE : Path to the Chandra evt2 event file.

Options:

• --src-reg SRC_REG : Existing source region file.

• --bkg-reg BKG_REG : Existing background region file.

• --outdir OUTDIR : Output directory. Defaults to the event file directory.

• --ra RA : Source RA in degrees. Required only when auto-generating regions.

• --dec DEC : Source Dec in degrees. Required only when auto-generating regions.

• --src-radius SRC_RADIUS : Auto source radius in arcsec. Default: 2.

• --bkg-inner BKG_INNER : Auto background annulus inner radius in arcsec. Defaults to --src-radius.

• --bkg-outer BKG_OUTER : Auto background annulus outer radius in arcsec. Default: 45.

• --bkg-circle-radius BKG_CIRCLE_RADIUS : Circular background radius in arcsec, used when a detection falls inside the proposed background annulus. Defaults to - --bkg-outer.

• --detect-match-radius DETECT_MATCH_RADIUS :

Match radius in arcsec for choosing a wavdetect source as the region center. Default: 5.

• --wav-scales WAV_SCALES :

wavdetect wavelet scales in image pixels. Default: "1 2 4 8".

• --wav-sigthresh WAV_SIGTHRESH :

wavdetect significance threshold. Default: 1e-6.

• --cutout-size CUTOUT_SIZE :

Image cutout size in SKY pixels when RA/Dec are supplied. Default: 512.

• --bin-size BIN_SIZE :

Image bin size in SKY pixels. Default: 1.

• --emin EMIN

Minimum ACIS energy in eV. Default: 500.

• --emax EMAX

Maximum ACIS energy in eV. Default: 8000.

• --ccd-id CCD_ID :

CCD ID filter. If omitted for ACIS energy-filtered data, defaults to 7.

• --no-energy-filter :

Disable energy filtering. This should be used for HRC event files.

• --psf-energy PSF_ENERGY :

Energy for mkpsfmap in keV. Default: 1.4967.

• --ecf ECF :

Encircled counts fraction for mkpsfmap. Default: 0.90.

Output files

Inside OUTDIR:

• evt_img.fits

• evt_psfmap.fits

• wavdetect_src.fits when auto-generating regions

• source.reg

• bkg.reg

• spec{obsid}.arf

• spec{obsid}.rmf

• spec{obsid}.pi

• spec{obsid}.corr.arf

• spec{obsid}_bkg.arf

• spec{obsid}_bkg.rmf

• spec{obsid}_bkg.pi

• spec{obsid}_grp.pi

Note

Assuming that the event file is inside obsid/primary/event.fits, the obsid is taken from the parent of the parent directory of the event file.

Usage formula

Auto regions:

extract-chandra <COND_ENV> <EVT_FILE> --ra <RA> --dec <DEC> [OPTIONS]

Existing regions:

extract-chandra <COND_ENV> <EVT_FILE> --src-reg <SRC_REG> --bkg-reg <BKG_REG> [OPTIONS]

Usage examples

HRC, auto regions:

extract-chandra ciao-4.18 hrc_evt2.fits \
    --ra 10.83625 \
    --dec 41.30911 \
    --outdir . \
    --no-energy-filter \
    --cutout-size 512 \
    --bin-size 1

HRC, existing regions:

extract-chandra ciao-4.18 hrc_evt2.fits \
    --src-reg source.reg \
    --bkg-reg bkg.reg \
    --outdir . \
    --no-energy-filter \
    --bin-size 1

ACIS, auto regions:

extract-chandra ciao-4.18 acis_evt2.fits \
    --ra 10.83625 \
    --dec 41.30911 \
    --outdir . \
    --emin 500 \
    --emax 8000 \
    --cutout-size 512 \
    --bin-size 1

ACIS, existing regions:

extract-chandra ciao-4.18 acis_evt2.fits \
    --src-reg source.reg \
    --bkg-reg bkg.reg \
    --outdir . \
    --emin 500 \
    --emax 8000 \
    --bin-size 1

Requirements:

• CIAO (including dmcopy, mkpsfmap, specextract, wavdetect, dmcoords) installed.

• CONDA_DEFAULT_ENV set to the requested environment name.

• XSNAP must also be installed in CONDA_ENV.