Chandra X-Ray Observatory
	(CXC)
Skip to the navigation links
Last modified: October 2014

URL: http://cxc.harvard.edu/ciao/ahelp/fullgarf.html
AHELP for CIAO 4.9

fullgarf

Context: tools

Synopsis

Create a grating ARF for a particular order and grating for a given observation.

Syntax

fullgarf  phafile pharow evtfile asol engrid dtffile badpix rootname
maskfile [dafile] [osipfile] [clobber]

Description

fullgarf is a script that creates a grating ARF for a particular order and grating for a given observation. While the mkgarf tool will create a grating ARF for an individual chip given an aspect histogram, this script will create ARFS for each chip, creating aspect histograms as necessary. The script will then combine the individual ARFS into the full array's ARF via the dmarfadd tool (see mkgarf for further details). The order and grating can be specified either by giving the corresponding row in a Type II PHA file, or by specifying a Type I PHA file which contains a spectrum for the desired order/grating combination.

This tool carries out all of the steps involved in creating a grating ARF and runs asphist, mkgarf and dmarfadd. See help on those tools for additional information. In successive invocations, the rootname parameter is used to check for the existence of asphist files in order to avoid re-creating them for the same chip (since they depend only on chip, and not grating or order).

HRC-S/LETG Data

For HRC-S/LETG data, fullgarf creates +/- 1 gARFs correctly. However, the functionality does not exist to create higher order responses. Users who wish to model more than the first order of the observation should follow the Compute LETG/HRC-S Grating ARFs thread to creater gARFs for higher orders.

HRC-I/LETG Data

This script does not operate on HRC-I/LETG data. Users doing analysis with this configuration should follow the Compute LETG/HRC-I Grating ARFs thread.

Example 1

fullgarf phafile=acisf00007_005N001_pha2.fits pharow=1
evtfile=acisf00007N001_evt2.fits.gz asol=pcadf085492801N001_asol1.fits
engrid="grid(acis_heg_1.rmf[cols ENERG_LO,ENERG_HI])"
maskfile=acisf00007_002N001_msk1.fits dafile=CALDB

For the first 2 examples, consider an HETG+ACIS-S observation with a pha file named "acisf00007_005N001_pha2.fits". Examining the file via dmlist (dmlist "acisf00007_005N001_pha2.fits[SPECTRUM][cols tg_m,tg_part]" opt=data) gives:


----------------------------------------------------------------------
Data for Table Block SPECTRUM
----------------------------------------------------------------------
 
ROW    TG_M TG_PART
 
     1   -3    1
     2   -2    1
     3   -1    1
     4    1    1
     5    2    1
     6    3    1
     7   -3    2
     8   -2    2
     9   -1    2
    10    1    2
    11    2    2
    12    3    2
      

In other words, e.g., row one corresponds to an HEG (TG_PART=1) minus-third order spectrum while row ten corresponds to an MEG (TG_PART=2) first-order spectrum.

In this case, fullgarf will create an ACIS-S, HEG ARF for the minus third order.

Example 2

fullgarf phafile=acisf00007_005N001_pha2.fits pharow=11
evtfile=acisf00007N001_evt2.fits.gz asol=pcadf085492801N001_asol1.fits
engrid="grid(acis_meg_1.rmf[cols ENERG_LO,ENERG_HI])"
maskfile=acisf00007_002N001_msk1.fits dafile=NONE

This will create an ACIS-S, MEG ARF for the second order. The ACIS dead area correction is not applied.

Example 3

fullgarf hrcf01715_002N001_pha2.fits 1 hrcf01715_002N001_evt2.fits.gz
hrcf01715_002N001_asoff.fits engrid="grid(hrc_leg_1.rmf[cols
ENERG_LO,ENERG_HI])" dtffile=hrcf01715_000N001_dtf1.fits
rootname=mrk421_ maskfile=""

This will create an HRCS-S, LEG ARF for the minus first order.

Parameters

name type ftype def units reqd stacks
phafile file       yes no
pharow integer   1   yes  
evtfile file       yes  
asol file       yes  
engrid string     keV yes  
dtffile file       yes  
badpix file       yes  
rootname string       yes  
maskfile string input     yes  
dafile string input CALDB      
osipfile string input CALDB   no  
clobber boolean   no      

Detailed Parameter Descriptions

Parameter=phafile (file required stacks=no)

The name of the PHA file containing the order, grating and source position information. This file may be either a Type I or a Type II PHA file. (See tgextract for information on Type I/Type II PHA files.) In the case of a Type I file, this information is contained in header keywords. For a Type II file this information is contained in the data table of the SPECTRUM extension. In this case the data are specified by row number via the pharow parameter.

Note that the user does not need to specify which type of PHA file the above file is. The script will determine this via looking at the TFORMx header keywords.

Parameter=pharow (integer required default=1)

Type II PHA files contain multiple spectra in the SPECTRUM binary-table extension. (Type I files contain only one spectrum.) Each row of the table contains one spectrum for a given order, grating and source. The pharow parameter specifies the appropriate row for the desired order and grating combination. (The order and grating data are contained in the TG_M and TG_PART columns). The dmlist tool can be used to determine row corresponds to which grating grating and order.

Note that if a Type I pha is specified for the phafile parameter, the pharow parameter is ignored.

Parameter=evtfile (file required)

This parameter is passed on to the asphist tool.

The event file provides observational configuration information via FITS keywords. It also provides good-time interval (GTI) data.

Parameter=asol (file required)

This parameter is passed on to the asphist tool.

This parameter give the aspect solution or sim-corrected aspect offset file(s). It is required as input to the asphist tool. (For additional information on this, try ahelp asphist.)

Parameter=engrid (string required units=keV)

This parameter is passed on to the mkgarf tool.

This parameter gives the specification for the energy grid. The string may specify either a file (FITS or ASCII) which contains the energy grid or an explicit energy grid. CIAO users should, in general, use a gRMF file (created with mkgrmf) for the energy grid specification.

For example, to specify the grid contained in the MATRIX block of an RMF file name "grating_rmf.fits", specify: "engrid=grid(grating_rmf.fits[MATRIX][cols ENERG_LO,ENERG_HI])" You should NOT specify a block that contains a wavelength grid! For example, often a file will contain columns named BIN_LO and BIN_HI which may contain wavelengths. Such grids may not be specified, since the values will be interpreted as energies.

To explicitly specify a grid which runs from 0.3 keV to 10.0 keV in 0.01 keV increment steps, specify: "engrid=0.3:10.0:0.01"

To use an ASCII file which contains two columns, the energ_lo and energ_hi, specify: "engrid=grid(myfile.tbl)"

Note that the preferred grid is linear in wavelength, since this reflects the natural dispersion of photons onto the detector. For back-compatibility, we write the grid in energy units in ascending order. Grating rmfs (see mkgrmf) have energy grids in descending linear wavelength. (Also see mk_tggrid, a script which converts the wavelength grid of a pha file into an FITS-format energy grid file.)

Parameter=dtffile (file required)

This parameter is passed on to the asphist tool.

This parameter gives the name of the file containing the dead-time correction factor. In the case of the HRC, these data are contained as a table in a FITS file. For the ACIS, a single value given by the DTCOR header keyword is used. This value is stored in the event file, so that usually (for the case of ACIS only!) one specifies the same value for this parameter as for the evtfile parameter.

Parameter=badpix (file required)

This parameter is passed on to the ardlib.par file.

This parameter will replace the value given in ardlib.par. It is not implemented for observations involving the HRC.

Parameter=rootname (string required)

The rootname for all of the output files. The script will prepend this parameter to all output filenames. The script will first check for the existence of an output file (which includes this rootname). If the file already exists, the script will not create a new version.

Parameter=maskfile (string required filetype=input)

This parameter is passed on to the mkgarf tool.

The mask file (msk1.fits) for the observation; used by mkgarf. The mask file is needed in particular when a window or subarray was used. A value of "NONE" indicates that no mask file will be applied.

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

This parameter is passed on to the mkgarf tool.

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.

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

Parameter=osipfile (string not required filetype=input default=CALDB)

This parameter is passed on to the mkgarf tool.

The Order Sorting and Integrated Probability file; used by mkgarf. The default value, "CALDB", indicates that the highest version for the most recent date before the observation date will be retrieved from the calibration database.

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

Parameter=clobber (boolean default=no)

If set to yes, existing output files will be removed. Note that this value is passed on to each tool in the script. That is, the value chosen for this parameter will set the value for the clobber parameter of all tools called by the script.

Changes in CIAO 4.6 contributed software release

The ACIS parameter block file parameter, pbkfikle, was removed.

About Contributed Software

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

Caveats

*** ERROR: aspect histogram acisf00459_ah4.fits[ASPHIST] contains no rows

This error is from mkgarf and occurs when a chip wasn't on for the observation. The fullgarf script attempts to calculate gARFs for ACIS chips S0-S3 if the order is less than zero or chips S3-S5 if the order is greater than zero, regardless of whether or not the chip was actually used in the observation. This error can be ignored, as it does not adversely affect the script output.

WARNING: OSIP file contains invalid data for the region
512<=CHIPX<=768 608<=CHIPY<=640 at 0.1 keV.
WARNING: OSIP file contains invalid data for the region
512<=CHIPX<=768 608<=CHIPY<=640 at 0.277 keV.

This warning is innocuous. Events at energies < 0.3 keV are outside the supported range of wavelength by HETG/ACIS-S (the events would fall off the chips). The gARFs should be fine for use in the analysis.

See Also

calibration
ardlib
psf
psf
tools
acis_bkgrnd_lookup, acis_fef_lookup, acis_set_ardlib, addresp, aprates, asphist, combine_grating_spectra, combine_spectra, dither_region, dmarfadd, dmextract, eff2evt, hrc_bkgrnd_lookup, make_instmap_weights, mean_energy_map, mkacisrmf, mkarf, mkexpmap, mkgarf, mkgrmf, mkinstmap, mkpsfmap, mkrmf, mkwarf, psextract, psf_project_ray, readout_bkg, rmfimg, sky2tdet, specextract

Last modified: October 2014
Smithsonian Institute Smithsonian Institute

The Chandra X-Ray Center (CXC) is operated for NASA by the Smithsonian Astrophysical Observatory. 60 Garden Street, Cambridge, MA 02138 USA.   Email:   cxchelp@head.cfa.harvard.edu Smithsonian Institution, Copyright © 1998-2017. All rights reserved.