fullgarf

Synopsis

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

fullgarf  phafile pharow evtfile asol engrid dtffile badpix rootname
maskfile [dafile] [osipfile] [ardlibqual] [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.

Examples

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.

Example 4

fullgarf phafile=acisf00007_005N001_pha2.fits pharow=10
evtfile=acisf00007N001_evt2.fits.gz asol=pcadf085492801N001_asol1.fits
engrid="grid(acis_meg_1.rmf[cols ENERG_LO,ENERG_HI])" maskfile=""
dafile=NONE ardlibqual=";UNIFORM;bpmask=0"

This will create an ACIS-S, MEG ARF for the first order with no dead area correction, no dead pixel mask and assuming a uniform quantum efficiency of the detector. This setting would be appropriate to process spectra simulated with MARX.

Parameters

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=ardlibqual (string default=)

This script processes several ACIS chips or HRC plates in a loop. This parameters can specify additional ardlib qualifiers that will be used for each chip; it will be attached to the detector specification when passed to the mkgarf tool. Thus, this parameter has to be empty or start with a semicolon (;).

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 the scripts 4.11 (December 2018) release

A parameters was added to specify ARDLIB qualifiers to be used for all chips that are processed by this script.

Changes in the scripts 4.10.1 (April 2018) release

Extend the chips used to create the ARF to support offset pointings when zero order is not on ACIS-7.

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

PHAFRAC column values

The grating ARF files created by mkgarf contain a PHAFRAC column. It is not used by any analysis tools nor is it used when modeling and fitting. It is contains diagnostic information used by the developers.

When the grating ARFs for individual CCDs are combined the dmarfadd tool simply copies the PHAFRAC column from one of the input files to the output. It does not try to combine the values in any way. This is also the case when combining positive and negative orders, and when combining responses from multiple observations.

Therefore, the PHAFRAC values may be different based on the order the files are input tool. Again, since the values are not used, this has user-visable effect.

*** 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, fullgarf, 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