Skip to the navigation links
Last modified: December 2009

URL: http://cxc-newtest.cfa.harvard.edu/ciao4.2/psextract.html
AHELP for CIAO 4.2

psextract

Context: tools

Synopsis

Extract source and background ACIS spectra for point-like sources and build associated ARFs and RMFs.

Syntax

psextract events bgevents root asol bgasol pbkfile [dafile] [ptype]
[gtype] [gspec] [clobber] [verbose]

Description

`psextract' is a script which lets the user create source and background PHA or PI spectra and their associated ARFs and RMFs files for a point source. The script combines the dmextract, asphist, mkarf, mkrmf, dmgroup and dmhedit programs, plus the script acis_fef_lookup.

The user supplies events lists, extraction regions and aspect solution files for source and background. Extraction regions have to be specified as part of the input events files, following the usual Data Model syntax for filtering (see "ahelp dmsyntax" or "ahelp dmfiltering").

The number of files created depends on whether or not common RMFs and ARFs are built for the source and background spectra. If the gain maps associated with the input source and background events files, or the centroids (in detector coordinates) of the source and background extraction regions are different, then distinct source and background RMFs and ARFs will be created. In this case the output files will be:

  • a grouped source spectrum
  • an ungrouped background spectrum plus a linearly grouped background spectrum
  • source RMF and ARF
  • background RMF and ARF

INPUT EVENT LISTS AND OUTPUT RMFs:

The input events files can be different for source and background (if the bgevents parameter is left blank, or is given the value "none", only source spectrum, RMF and ARF will be computed). The tool will check if the two input events files correspond to different observations with different associated gain-maps. If yes, the program will compute different RMFs for source and background. Otherwise, a common RMF will be computed. If two RMFs are created then the RESPFILE keyword in the header of both the source spectrum and the linearly grouped background spectrum is properly updated. Otherwise only the RESPFILE keyword in the header of the source spectrum is updated.

Users who are working with CTI-corrected, -120 C data should run mkacisrmf standalone to generate new RMFs after using the script to create the spectrum and ARF files. The Creating ACIS RMFs with mkacisrmf thread has more details and shows how to run the tool.

Psextract checks for CTI keywords in the input file headers and prints a warning if users should remake the RMF response with the mkacisrmf tool. The warnings are printed at verbosity > 0.

THE OUTPUT ENERGY GRID:

The ARF and RMF files created by psextract are generated on a "standard" energy grid suitable for analysing most ACIS data. This grid is


  energy=0.1:11.0:0.01

(which says that the energy grid goes from 0.1 to 11.0 keV with a bin size of 10 eV).

INPUT EXTRACTION REGIONS AND OUTPUT ARFs:

Either a single ARF for source and background spectra, or 2 different ARFs will be computed depending on whether or not the mean detector coordinates of source and background extraction regions correspond to the same (32 x 256) square pixels (FI) or (32 x 32) square pixels (BI) chip region. Again, the ANCRFILE keyword in the header of the source and, eventually, the linearly grouped background spectra is updated consequently.

NOTE: the script runs the tool 'dmstat' on the list of events contained in the source and background extraction regions, to compute the average chipx and chipy detector cordinates for those regions. If the background extraction region is symmetric, compared to the center of the source region, then the averaged (chipx,chipy) for the background region will be similar to the averaged (chipx,chipy) for the source region. The script might then be instructed to build common RMFs (if the gain-maps associated to the two events files are the same) and ARFs for source and background. To force the script to build different (and possibly more precise) RMFs and ARFs for source and background, the user should select background extraction regions that are non-symmetric compared to the source extraction region.

ASPECT SOLUTION:

Aspect solution files are used to allows mkarf to determine off-axis angles. The aspect solution file corresponding to the source events list must be input. If the parameter "bgaoff" is left blank (the default) the background aspect solution file is assumed to be the same as the source one. However, in this case the script will check whether the two input events files for source and background are the same or not, and will exit with a WARNING in the latter case. Similarly, if "asol" and "bgasol" have different values, but the two input events files are the same, then the program will exit with an ERROR.

GROUPED OUTPUT SPECTRA:

The user can choose to group the output source spectrum. All the group-type options available with dmgroup (see "ahelp dmgroup" for details) are allowed. However, the dmgroup parameters "xcolumn" and "ycolumn" are here hard-coded and fixed to "channel" and "counts" respectively, as appropriate for standard PHA files. Grouping of the output background spectrum (if any) depends on whether or not common RMFs and ARFs are created for source and background. In the latter case two output background spectra will be created: one ungrouped, and the other one linearly grouped by a factor of 20. Only the RESPFILE and ANCRFILE keywords in the header of the linearly grouped background spectrum will be updated. This is to give the user the possibility to choose whether fitting the background-subtracted source spectrum with source RMF and ARF, or fitting source and background spectra simultaneously using their own RMF and ARF.

Example 1

psextract events="evt.fits[sky=region(ds9.reg)]" bgevents=none
root=mysource asol=asol.fits bgasol="" pbkfile=pbk0.fits dafile=CALDB

Extract a point source from evt.fits using the region ds9.reg. Don't make a background spectrum and don't group the output. The ACIS dead area correction will be applied to the ARF.

Example 2

psextract "evt.fits[time=1000:2000][sky=region(ds9.reg)]"
bgevents="evt.fits[time=1000:2000][sky=region(bg.reg)]" root=mysource
asol=asol.fits bgasol="" gtype="BIN" gspec="1:1024:20"
pbkfile=pbk0.fits dafile=CALDB

Extract source and background spectrum from the same events file, and from different extraction regions, and make a common source and background RMF and one or two ARFs depending on the "distance" between the centroids of the source and background extraction regions (in detector cordinates). The ACIS dead area correction will be applied to the ARFs. Group source spectrum using the dmgroup parameters BIN 1:1024:20.

Example 3

psextract "evt.fits[sky=region(ds9.reg)]"
bgevents="evt_bg.fits[sky=region(bg.reg)]" root=mysource asol=asol.fits
bgasol=bgasol.fits gtype="NUM_CTS" gspec=20 pbkfile="" dafile=NONE

Extract source and background spectrum from different events files (with different associated gain-maps), and from different extraction regions (in detector coordinates), and make two RMFs and one or two ARFs depending on the "distance" between the centroids of the source and background extraction regions (in detector cordinates). Group source spectrum using the dmgroup parameters grouptype=NUM_CTS with grouptypeval=20. The ACIS dead area correction is not applied because the source and background event files are different; see the "pbkfile" parameter description for details.

Parameters

name type ftype def min max reqd
events string input       yes
bgevents string input       yes
root string         yes
asol string input       yes
bgasol string input       yes
pbkfile string input       yes
dafile string input CALDB      
ptype string   pi     no
gtype string   NONE     no
gspec string   NONE     no
clobber boolean   no      
verbose integer   0 0 5  

Detailed Parameter Descriptions

Parameter=events (string required filetype=input)

The input (source photons) virtual file specification.

Parameter=bgevents (string required filetype=input)

The background photons.

Parameter=root (string required)

Root name for the output files root.pi, root_bg.pi (root_bg_grp.pi), root.arf, (root_bg.arf), root.rmf (root_bg.rmf).

Parameter=asol (string required filetype=input)

Aspect solution file for the source events list.

Parameter=bgasol (string required filetype=input)

Aspect solution file for the background events list. If left blank, it is assumed equal to asol.

Parameter=pbkfile (string required filetype=input)

The parameter block file, which defines ACIS pixel clocking parameters, is used in conjunction with the "dafile" parameter to apply the ACIS dead area correction.

Note that psextract applies the same pbkfile to the source and background datasets. If this is not appropriate for your analysis, you will have to run mkarf independently to create an ARF with the dead area correction. (In this case, make sure to "turn off" the correction during the psextract run, i.e. pbkfile=NONE and dafile=NONE.)

This is a standard product of pipeline processing and is available for every observation. Parameter block files have names of the form, "acisf146860615N001_pbk0.fits". The long string of digits refers to the time of observation (seconds since reference date).

See "ahelp mkarf" for more information on this parameter.

Parameter=dafile (string filetype=input default=CALDB)

ACIS "dead area" coefficients file, which may have the values "NONE" (no dead area computation), CALDB (for automatic lookup), or an explicit file reference to an ACIS "dead area" coefficients FITS table.

The parameter block file is required to scale the coefficients in the dafile. If dafile=NONE, then pbkfile=NONE is assumed.

See "ahelp mkarf" for more information on this parameter.

Parameter=ptype (string not required default=pi)

The spectrum channel type (PHA or PI). This applies to both the source and the background spectra. Response matrices are generated consequently. The default is for spectra and responses to be generated in PI space.

Parameter=gtype (string not required default=NONE)

The grouping type (NONE, BIN, SNR, NUM_BINS, NUM_CTS, ADAPTIVE, ADAPTIVE_SNR, BIN_WIDTH, MIN_SLOPE, MAX_SLOPE, BIN_FILE). See "ahelp dmgroup" for details. This applies to the source spectrum only.

Parameter=gspec (string not required default=NONE)

The grouping specification; form depends on GTYPE. See "ahelp dmgroup" for details. This applies to the source spectrum only.

Parameter=clobber (boolean default=no)

Specifies if an existing output file should be overwritten.

Parameter=verbose (integer default=0 min=0 max=5)

Controls amount of information to print (0-5).

The verbose parameter provides debugging information; verbose = 0 is usually fine.

CHANGES IN PSEXTRACT 4.0.3

The head and tail commands were replaced by the CIAO tool "pget". The file output is not affected. A user reported the script failing on Mac OS X 10.4 Intel due to outdated syntax.

CHANGES IN PSEXTRACT 4.0.2

The head and tail command syntax was updated to include the "-n" flag.

CHANGES IN CIAO 4.0/PSEXTRACT 4.0.1

Parameter defaults: pbkfile and dafile

The ACIS dead area correction is on by default in CIAO 4.0. The pbkfile and dafile parameter defaults have been updated to reflect this. The pbkfile parameter is now automatic (i.e. not hidden) and there is no default value. The default value of the dafile parameter has been changed to "CALDB".

Note that psextract applies the same pbkfile to the source and background datasets. If this is not appropriate for your analysis, you will have to run mkarf independently to create an ARF with the dead area correction. (In this case, make sure to "turn off" the correction during the psextract run, i.e. pbkfile=NONE and dafile=NONE.)

NOTES

This script is not an official part of the CIAO release but is made available as "contributed" software via the CIAO scripts page. Please see the installation instructions page for help on installing the package.

Bugs

See the bugs page for this script on the CIAO website for an up-to-date listing of known bugs.

See Also

calibration
ardlib
tools
acis_bkgrnd_lookup, acis_fef_lookup, acis_set_ardlib, acisspec, add_grating_orders, add_grating_spectra, asphist, dither_region, dmarfadd, dmextract, eff2evt, fullgarf, hrc_bkgrnd_lookup, make_instmap_weights, merge_all, mkacisrmf, mkarf, mkexpmap, mkgarf, mkgrmf, mkinstmap, mkpsf, mkpsfmap, mkrmf, mkwarf, psf_project_ray, rmfimg, specextract

Last modified: December 2009