Synopsis
Generate an RMF for Chandra grating data
Syntax
mkgrmf outfile wvgrid_arf wvgrid_chan order obsfile regionfile srcid threshold detsubsys grating_arm verbose [diagonalrmf] [ardlibparfile] [geompar] [mirror] [clobber]
Description
The mkgrmf program generates an OGIP style RMF appropriate for spectral analysis of grating observations. The RMF is a representation of how the incident source photons are redistributed onto the detector, thus the grating RMF contains the HRMA + grating line spread function (LSF) vs energy for a given detector and grating combination.
mkgrmf calculates the RMF on user defined set of grid points, e.g. wavelength channel. The output file contains two FITS extensions, MATRIX and EBOUNDS. The MATRIX is generated by interpolating the parameters of a tabulated LSF in wavelength and then generating the LSF from the interpolated parameters. The EBOUNDS extension contains an array with the energy boundaries of each of the detector channels.
The LSF also depends on the position of the source on the detector and any defocus applied in the observation. Since the PSF becomes wider for off-axis source, the LSF also broadens. mkgrmf can take that into account when the off-axis angles is known (which requires an evt file to be used for the obsfile parameter) and the input data files for this particular combination of grating and detector provide a sufficiently dense grid of off-axis information. The CALDB does not contain that information for all parameters and mkgrmf may raise a warning that it "assumes an on-axis source". Broadening of the LSF becomes significant only for sources more than a few arc minutes from the aim point and the message can be ignored safely for the vast majority of Chandra grating observations.
For a given grating type, order, detector configuration, defocus, and off-axis angle, the input data files for mkgrmf have a set for each of five to ten extraction region sizes. These regions range approximately from the 60 to 99% encircled energy (EE), where the percentage is defined to be at 1.497keV. The user is not required to use any specific extraction region width; the tool will use a series of interpolations to determine the best RMF for the extracted data. For the case where the extraction region is larger (or smaller) than the largest (smallest) EE region, the RMF will be derived via extrapolation. The region is, however, required to be centered on the source. If not (as may be necessary in crowded fields), the LSF shape and EE will not be accurate.
The extraction region is assumed to be appended to the PHA file. For the grating data processed by CIAO, this region is appended to the type II PHA file.
Note that the RMF generated is not normalized. Since the EE is extraction-region dependent, there is a wavelength-dependent component of the effective area contained in the RMF --- both ARF and RMF are needed for accurate flux determinations. Default region widths for HETGS provide 93-98% EE, and for LETGS the EE ranges from 88-97%.
Examples
Example 1
mkgrmf grating_arm="HEG" order=3 outfile="heg3.rmf" srcid=1 detsubsys=ACIS-S3 threshold=1e-06 obsfile="acis_f1235_000N002_evt2.fits" regionfile="acis_f1235_000N002_pha2.fits" wvgrid_arf="compute" wvgrid_chan="compute"
Computes a third order RMF for the HEG, writes the output to heg3.rmf and uses the default grids for the rmf. Note setting the parameter wvgrid_arf to "1.0:21.48:#8192" is equivalent to setting it to compute.
Example 2
mkgrmf grating_arm="LEG" order=1 outfile="leg1.rmf" obsfile="hrcf00058N002_evt2.fits" regionfile="hrcf00058N002_pha2.fits" wvgrid_arf="1.0:205.8:0.01" wvgrid_chan="1.0:205.8:0.01"
Computes a first order RMF for the LEG, writes the output to leg1.rmf and uses non-standard grids for the rmf.
Example 3
mkgrmf grating_arm="MEG" order=-1 outfile="meg1_log.rmf" obsfile="acis_f1235_000N002_evt2.fits" regionfile="acis_f1235_000N002_pha2.fits" wvgrid_arf="1.0:21.48:0.05L" wvgrid_chan="1.0:21.48:0.05L"
Computes a minus first order RMF for the MEG, writes the output to meg1_log.rmf and uses custom grids for the rmf. In this case we have chosen a logarithmic grid.
Parameters
name | type | ftype | def | min | max | units | reqd |
---|---|---|---|---|---|---|---|
outfile | string | output | yes | ||||
wvgrid_arf | string | compute | Angstrom | yes | |||
wvgrid_chan | string | compute | Angstrom | yes | |||
order | integer | 1 | yes | ||||
obsfile | string | input | yes | ||||
regionfile | string | input | yes | ||||
srcid | integer | 1 | yes | ||||
threshold | real | 1.0e-6 | yes | ||||
detsubsys | string | ACIS-S3 | yes | ||||
grating_arm | string | yes | |||||
verbose | integer | 0 | 0 | 5 | yes | ||
diagonalrmf | string | no | |||||
ardlibparfile | string | ardlib.par | |||||
geompar | string | geom | |||||
mirror | string | HRMA | |||||
clobber | boolean | yes |
Detailed Parameter Descriptions
Parameter=outfile (string required filetype=output)
Output File Name
The name of the output RMF file.
Parameter=wvgrid_arf (string required default=compute units=Angstrom)
Enter ARF side wavelength grid [angstroms]
Wavelength grid for the arf specification string. This string may specify compute, a file, or an explicit energy grid. For example, to use a grid for the MEG that ranges from 1 to 41.96 angstroms with 8192 channels set. The units for this parameter is angstroms.
wvgrid_arf="1.0:41.96:#8192"
This is the same grid that you would get with
wvgrid_arf=compute
The default grids for the three grating types are
Grating type | wvgrid_arf |
---|---|
MEG | 1.0:41.96:#8192 |
HEG | 1.0:21.48:#8192 |
LEG | 1.0:205.8:#16384 |
Parameter=wvgrid_chan (string required default=compute units=Angstrom)
Enter channel-side wavelength grid [angstroms]
Specification string for the channel side wavelength grid. This string may specify compute, a file, or an explicit energy grid. In general this is set to be the same as the arf grid. However, there is no compelling reason that the fitting engine needs the ARF and the RMF on the same grid so this has been left as a user adjustable parameter. The units for this parameter is angstroms.
Parameter=order (integer required default=1)
Enter Grating order
The order that the RMF will be computed for.
Parameter=obsfile (string required filetype=input)
Name of FITS file with observation info
The name of a FITS file containing keywords which specify the mission, detector, SIM offsets, etc.
Parameter=regionfile (string required filetype=input)
File containing extraction region
The name of a FITS file containing keywords which specify the extraction region.
Parameter=srcid (integer required default=1)
SrcID
The number of the source in the spectrum list. This will be used to determine source parameters such as the source position.
Parameter=threshold (real required default=1.0e-6)
Enter RMF threshold
The lowest value for the response matrix calculation.
Parameter=detsubsys (string required default=ACIS-S3)
Detector Name (e.g., ACIS-S3)
The ACIS chip or HRC plate on which the 0th order falls. The value of this parameter is passed to ARDLIB to select a particular detector subsystem so that the appropriate grid can be computed for the case where wvgrid_arf and wvgrid_chan are both set to "compute". For Chandra, this is most commonly one of these two detector subsystems:
- ACIS-S3
- HRC-S2
However this parameter can be any one of the following detector subsystems:
- HRC-I
- HRC-S1, HRC-S2, HRC-S3
- ACIS-I0, ACIS-I1, ACIS-I2, ACIS-I3
- ACIS-S0, ACIS-S1, ACIS-S2, ACIS-S3, ACIS-S4, ACIS-S5
Parameter=grating_arm (string required)
Enter Grating Arm
Name of the grating that the rmf will be computed for. Valid values are HEG, MEG and LEG.
Parameter=verbose (integer required default=0 min=0 max=5)
Verbosity
The verbose parameter is used to set the level of output from mkgrmf.
Parameter=diagonalrmf (string default=no)
Compute diagonal RMF
Option to compute a diagonal RMF. This option gives the correct wavelength grid for any order but has no LSF information encoded.
Parameter=ardlibparfile (string default=ardlib.par)
name of ardlib parameter file
The tool-specific parameter file contains no explicit CALDB parameters. Instead, the CALDB parameters are all contained in a separate parameter file selectable using the `ardlibparfile' parameter; "ardlib.par" is the default file name. Calibration files are specified implicitly via the `DetSubsys' and `Mirror' parameters described below.
Parameter=geompar (string default=geom)
The name of the Pixlib Geometry parameter file.
Parameter=mirror (string default=HRMA)
Mirror Name
For Chandra the mirror parameter must be set to "HRMA".
Parameter=clobber (boolean default=yes)
Overwrite existing files?
The default values here is yes which allows you to overwrite existing files. Changing this to "no" will prevent the overwriting of files.
Notes
The command "mkgrmf --version" prints the version of mkarf and the associated libraries. This is useful when reporting problems with the tool.
Changes in CIAO 4.15
-
Updated to support HRC-I+HETG, including diagonal RMFs and for orders greater than 1.
-
The tool has been updated for the eventual release of calibration data that will allow for enclosed counts fractions for off-axis sources.
For this to work, users must use the L2 event file, with the attached REGION extension, for the obsfile rather than using the pha2 file.
Bugs
There are no known bugs for this tool.
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