Using merge_obs to combine observations and create exposure-corrected images

CIAO 4.10 Science Threads

Overview

Synopsis:

In order to create an exposure-corrected image from a set of
observations, an exposure map
has to be created for each observation (the exposure map is essentially an
image of the
effective area at each sky position, accounting
for the effects of
the telescope dither pattern
which are especially
important near the edges of the detector), and then combined.
The merge_obs, reproject_obs,
and flux_obs scripts wrap up all the CIAO tools
needed to perform this task (they replace the
merge_all tool, removed in CIAO 4.6).

Getting Started

In this thread we assume that the observations have
been reprocessed by chandra_repro
and can be found in obsid/repro/; e.g.

unix% chandra_repro 11823,12224 outdir=

Using merge_obs

Calibration products

The merge_obs script
uses all the necessary information available to
create properly-calibrated exposure maps for the
observations. That is, it includes the
per-observation
aspect-solution,
bad-pixel,
mask,
FOV
and
DTF
files (where relevent).

In the following we supply the minimal information
to merge_obs, namely the location
of the event files (it searches for file names that contain
the string evt in
<dirname>/repro/ then
<dirname>/primary/ then
<dirname>/) and the output root.
For ACIS data the default binning is 8
and choice of bands is broad
(that is 0.5 to 7 keV with the exposure map evaluated
at 2.3 keV).
Note that the observations do not need to be listed in
time order and that the script finds the locations of
the ancillary files - e.g. aspect solution and bad-pixel
files - it needs from the header keywords in the event files.

The exposure-corrected 0.5 to 7 keV image is displayed.
Since the two observations had different roll angles
the image is no longer a square.
It can be compared to the
"raw" counts image shown in Figure 2.

Figure 2: Broad-band image and exposure map of RCW 103 created by merge_obs

Figure 2: Broad-band image and exposure map of RCW 103 created by merge_obs

The image on the left - shown with a logarithmic scale - is the
counts image in the 0.5 to 7 keV band. The image on the right - shown
with a linear scale - is the exposure map for the data, and was evaluated
at 2.3 keV. Both images have been "thresholded" to remove pixels where
the exposure map has dropped to a small value (in this case, 1.5 percent
of the maximum value per observation).

If we look in the directory created by merge_obs we find
a number of files:

File name

Description

11823_reproj_evt.fits12224_reproj_evt.fits

The reprojected event files.

merged_evt.fits

The merged event file (this contains only those columns
that are common to all the reprojected event files).

11823_broad_thresh.img12224_broad_thresh.img

The counts image for each reprojected event file.
If the
expmapthresh
parameter is set then these images have been thresholded
to remove pixels where the corresponding exposure value
is low.

11823_broad_thresh.expmap12224_broad_thresh.expmap

The exposure map for each reprojected event file.
If the
expmapthresh
parameter is set then these images have been thresholded
to remove pixels where the exposure is low.

11823_broad_flux.img12224_broad_flux.img

The exposure-corrected image for each reprojected event file.

broad_flux.imgbroad_thresh.expmapbroad_thresh.img

The exposure-corrected image, exposure map, and counts image
for the combined data.

There are a number of optional parameters to
merge_obs that allow you
control over the process, such as:

the bands parameter lets
you chose the energy range (or ranges) used to create the images
and the energy (or spectral weights file) used to create the
exposure map(s);

the image size, location, or bin size can be varied by setting
one of the
binsize,
maxsize,
or xygrid
parameters;

the location used to reproject the observations can be given
(rather than being calculated by the script) by setting
the refcoord
parameter;

the units of the exposure map(s) - and hence the
exposure-corrected image(s) - can be changed using the
units
parameter;

the ancillary files to use - e.g. aspect solution or
bad-pixel files - can be set, rather than read from
the event file headers, using the
asolfiles,
badpixfiles,
maskfiles,
and dtffiles
parameters;

and the number of processors used by the script
can be changed with the nproc
parameter (by default, all processors are used), or
even forced to use only one (by setting
parallel to
no).

Using reproject_obs and flux_obs

The merge_obs script allows you to create
exposure-corrected images easily, but if you want to
try different parameter settings (e.g. choice of bin size,
location, or bands), then some of the work it does each
time is wasted.
For these occasions it can be useful to split the
process into a reprojection stage - done by
reproject_obs - and
the calculation of the exposure-corrected images -
done by flux_obs.

Figure 3: Three color, exposure-corrected image of RCW 103

The soft (red) channel is for the 0.5 to 1.2 keV band, the medium (green)
channel is for the 1.2 to 2.0 keV band, and the hard (blue) channel
is for the 2.0 to 7.0 keV band. More information can be found at the
merge_obs parameter.

depending on whether or not you want the exposure map and
exposure-corrected image. Note that the files in
evt.lis should not include
any energy filter (the default band for ACIS data is 0.5 to 7.0 keV).
If you wish to over-ride the script, e.g. to specify a tangent
point or output grid, then you can.

The following table lists the merge_all parameters and their
equivalents in merge_obs; it does not describe those parameters
that have no equivalent in merge_all.

As the energy filtering is now specified by the bands parameter,
so no energy filter should be applied to the individual observations. You can
now also include additional filters, so infiles="@evt.lis[ccd_id=0:3]"
or infiles="*/repro/*evt*[ccd_id=7]"
are both valid.
The event files no longer need to be sorted by time.

This parameter is no longer required since, if not given, the
script uses the ASOLFILE keyword
in each event file to find the
aspect solution file (or files).
This parameter only needs to be
given if the aspect solution files have been renamed (e.g. because you
have updated them to match WCS solutions between observations) or
moved, and have not updated the ASOLFILE keyword in the header.
The files no longer need to be sorted by time.

This parameter is no longer required for HRC data since it is
found from the DTFFILE keyword in each event file. It only needs
to be specified if you have moved or renamed these files and have
not updated the DTFFILE keyword in the header.

chip

There is no equivalent parameter in merge_obs. If you wish to
restrict the chips used then apply a filter to the input event
files - e.g. infiles="@evt.lis[ccd_id=0:3]".

This parameter is no longer required. If not given, the extents of
the reprojected event files will be calculated and the union of them
used to chose a grid that covers all the data.
In this case the binning size is chosen by either the
maxsize
or
binsize
parameter.

The choice of energy range is now given by the
bands parameter,
which specifies both the energy range and the energy at which to
evaluate the energy map or the
weighting file
to use.
This means that energy filters should no longer be included on
the event files sent in to the infiles parameter.
It is also possible to specify multiple bands in one run
of merge_obs.

merged

The name of the merged event file is either
<outroot>/merged_evt.fits or
<outroot>_merged_evt.fits,
depending on whether the
outroot
parameter ends in a '/' or not. The merge_obs
script will create this directory if it does not exist.

expmap

The name of the combined exposure map is either
<outroot>/<band>_thresh.expmap or
<outroot>_<band>_thresh.expmap,
depending on whether the
outroot
parameter ends in a '/' or not.
If you do not want to create the combined images and exposure
maps then use the reproject_obs script instead, which just does
the reprojection and merging of the event files.

expcorr

The name of the combined fluxed image is either
<outroot>/<band>_flux.img or
<outroot>_<band>_flux.img,
depending on whether the
outroot
parameter ends in a '/' or not.
If you do not want to create the combined images and exposure
maps then use the reproject_obs script instead, which just does
the reprojection and merging of the event files.

The merge_obs script is more careful about naming temporary files
and cleaning up after itself when an error occurs.

History

09 Jan 2012

reviewed for CIAO 4.4: no changes

15 Oct 2012

The thread has been converted to use the new
merge_obs script,
part of the
15 October 2012 scripts package
release,
rather than
the deprecated merge_all script.
The observations used in the thread have been changed.

03 Dec 2012

Review for CIAO 4.5; mkexpmap chatter removed

03 Dec 2013

Review for CIAO 4.6; the pbkfiles parameter has
been removed from merge_obs; merge_all has
been removed from the contributed package.

22 Dec 2014

Review for CIAO 4.7. Added a link to the fine
astrometric correction thread.