Ahelp: psextract - CIAO 3.4

Jump to: Description Examples Parameters CHANGES IN PSEXTRACT 4.0 CHANGES IN CIAO 3.4/PSEXTRACT 3.4 CHANGES IN CIAO 3.3 NOTES Bugs See Also

AHELP for CIAO 3.4

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]

`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.

FITTING THE OUTPUT SPECTRA IN SHERPA:

Both source and linearly grouped background (if any) spectra are updated in their header keywords BACKFILE (source spectrum only), RESPFILE and ANCRFILE. The spectra can then be read into sherpa and fitted. If only the source spectrum is read in, Sherpa would read in the (ungrouped) background spectrum defined in the keyword BACKFILE of the source spectrum, and the source response matrices (RMF and ARF). The user can then subtract the background from the source spectrum and fit the background-subtracted source spectrum. Alternatively, the user may choose to fit simultaneously source and (linearly grouped) background spectra, each with its own RMF and ARF. In this case, of course, no background subtraction should be performed. Please see the Sherpa threads for more information on using Sherpa to fit spectral data.

Example 1

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

Extract a point source from evt.fits using the region ds9.reg. Don't make a background spectrum and don't group the output. Creates mysource.pi, mysource.rmf and mysource.arf. The keywords BACKFILE, RESPFILE and ANCRFILE in the header of mysource.pi are updated to none, mysource.rmf and mysource.arf, respectively.

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" clobber=yes

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). Group source spectrum using the dmgroup parameters BIN 1:1024:20. (See dmgroup for details of BIN, SNR and NUM_CTS options). Creates mysource.pi, mysource_bg.pi (or mysource_bg.pi and mysource_bg_grp.pi), mysource.rmf and mysource.arf (or mysource.arf and mysource_bg.arf). The keywords BACKFILE, RESPFILE and ANCRFILE in the headers of mysource.pi and mysource_bg_grp.pi (if any) are updated to "mysource_bg.pi", "mysource.rmf", "mysource.arf", and "none", "mysource.rmf" and "mysource.arf" (or "mysource_bg.arf"), respectively.

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 clobber=yes

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 (see "ahelp dmgroup" for details). Creates mysource.pi, mysource_bg.pi, mysource_bg_grp.pi, mysource.rmf mysource_bg.rmf and mysource.arf (or mysource.arf and mysource_bg.arf). The keywords BACKFILE, RESPFILE and ANCRFILE in the headers of mysource.pi and mysource_bg_grp.pi are updated to "mysource_bg.pi", "mysource.rmf", "mysource.arf", and "none", "mysource_bg.rmf" and "mysource.arf" (or "mysource_bg.arf"), respectively.

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	NONE
dafile	string	input	NONE
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 filetype=input default=NONE)`

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. The correction is off by default in CIAO 3.4.

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.

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=NONE)`

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 correction is off by default in CIAO 3.4.

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

New Parameters: pbkfile and dafile

New parameters added to the psextract.par file: pbkfile and dafile; see the parameter descriptions for details. These values are used to apply the ACIS dead area correction in the mkarf step. The correction is off by default in CIAO 3.4.

Using mkacisrmf

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.

Error and warning messages

The script name has been added to error and warning messages.

Verbosity

The script is quiet at verbose=0.

CHANGES IN CIAO 3.4/PSEXTRACT 3.4

There were several parameter changes to mkarf - a tool called by psextract - in the CIAO 3.4 release.

The mkarf "obsfile" parameter should be set to the event file instead of the asphist file. This parameter change was made in v3.4 of psextract.

Two new hidden parameters have also been added to mkarf to allow the ACIS dead area correction to be taken into account: "pbkfile" and "dafile". By default, the correction is "off", i.e. both parameters are set to "NONE". See the parameter descriptions in "ahelp mkarf" for more information.

To apply this correction when running psextract, set the mkarf parameters BEFORE executing the script:

unix% pset mkarf pbkfile=acisf063875928N002_pbk0.fits dafile=CALDB
unix% psextract

Parameter=events (string required filetype=input)

Parameter=bgevents (string required filetype=input)

Parameter=root (string required)

Parameter=asol (string required filetype=input)

Parameter=bgasol (string required filetype=input)

Parameter=pbkfile (string filetype=input default=NONE)

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

Parameter=ptype (string not required default=pi)

Parameter=gtype (string not required default=NONE)

Parameter=gspec (string not required default=NONE)

Parameter=clobber (boolean default=no)

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