Synopsis

Combine any number of observations. If desired, create corresponding exposure maps and exposure-corrected images.

merge_all evtfile [asol] [dtffile] chip [refcoord] [xygrid] [energy]
[merged] [expmap] [expcorr] [intdir] [clobber] [mode]

Description

This script takes a list of level=2 event files, reprojects them to a given RA and Dec, and combines them. It can then make a combined exposure map and an exposure-corrected image. If only one event file is input, it is treated as a merged event file. One may first use the script to create a merged file and then run it a second time using this merged file as input, omitting the parameters "refcoord" and "merged".

Note that the script may be used to simply combine a set of two or more level=2 event files. In this case, the only parameters which are needed are "evtfile", "chip", "refcoord", and "merged".

If a combined aspect histogram exists from a previous run, and it is in the "intdir" and retains its original name, the script will use this instead of creating a new one.

Using Data Model filters:

It is possible to provide an energy filter. However, region filters are not supported: this is because the "xygrid" is the region filter for the exposure map, and the image size and shape must match that of the exposure map. Filters (to remove sources, etc.) can be applied to the event file prior to running the script, if desired.

Using HRC data:

The script may be used to combine HRC observations (S- or I-array), but it can only make exposure maps and exposure-corrected images for the HRC-I configuration.

Caveat: using merge file for spectral analysis

Merged files are, in general, not suitable for spectral analysis. The exposure map and exposure corrected image do not contain statistical errors, and therefore cannot be used to obtain meaningful values for source fluxes.

Caveat: lightcurves binned on exposure number

A "[subspace -expno]" filter is used in the dmmerge command as a workaround for a problem merging data with different EXPNO ranges. This means that any user who intends to create lightcurves binned on exposure number from the merged output cannot use merge_all, since that information is eliminated from the subspace. (In general, lightcurves are binned on time.)

Example 1

merge_all evtfile="data1.fits,data2.fits,data3.fits"
asol="pcadf063874624N002_asol1.fits,pcadf063875522N002_asol1.fits,pcadf0
63902942N002_asol1.fits" chip="0,1,2,3,6,7" refcoord=data3.fits
xygrid="3056.5:4056.5:#1000,3024.5:4044.5:#1020" energy=spectrum.dat
merged=data123.fits expmap=expmap123.fits expcorr=expcorr123.fits

Combine three level=2 event files using a time-sorted list of asol files. Reproject the data to match the tangent point in data3.fits. Create a full-resolution exposure map as well as an exposure-corrected image of a portion of the data using a spectral weights file.

Example 2

merge_all evtfile=hrcf00461N003_evt2.fits
asol=pcadf064938693N002_asol1.fits dtffile=hrcf00461_001N003_dtf1.fits
chip=hrc-i xygrid="1:16384:#128,1:16384:#128" energy=1
expmap=hrc_expmp.fits expcorr=hrc_expcorr.fits intdir=.

Make an exposure map and exposure-corrected image for a single HRC-I observation. Write temporary files to the current directory.

Parameters

Detailed Parameter Descriptions

Parameter=evtfile (file required filetype=input stacks=yes)

Input level 2 file(s)

Comma-separated list of input level=2 event files. Region filters should not be used. Can use a merged file made from a previous run of the script.

Parameter=asol (file filetype=input stacks=yes)

Input aspect solution file(s)

Comma-separated list of aspect solution (asol) files. These are only required if you are creating an exposure map.

The script assumes that the aspect files are arranged in chronological order. If you have not altered the original filenames, a simple "ls" will put them in order, as the time is listed in the filename.

Parameter=dtffile (file filetype=input stacks=yes)

Input DTF files

Comma-separated list of DTF file name(s). Only necessary when creating an exposure map for HRC-I observations.

Parameter=chip (string required)

ACIS CCD numbers or "HRC-I" or "HRC-S"

Either ccd_id(s) for the ACIS CCDs you want or "HRC-I" or "HRC-S". If entering ccd_ids, can use either a range (seperated by ":" or "-") or a comma-separated list.

Parameter=refcoord (string filetype=input)

Tangent point to which data is reprojected

Either "RA, Dec" (comma-separated) or a level=2 event file to which the tangent point of observations will be reprojected. This parameter is not used if the "evtfile" file is a single observation or a previously-merged file.

Parameter=xygrid (string)

Input grid specification

Input grid for creating the exposure map and exposure-corrected image; should be of the same form expected by the tool mkexpmap: "xmin:xmax:#(no. of x bins),ymin:ymax:#(no. of y bins)"; for example, "0.5:8192.5:#1024,0.5:8192.5:#1024". Do not need if only using the script to merge data.

Parameter=energy (string filetype=input units=keV)

Energy value or spectral weights file for mkinstmap

Either an energy value (in keV) or a normalized spectral weights file. This will be used to calculate the instrument map, see "ahelp mkinstmap" for details on the format of the spectral weights file.

The script uses a decimal test to see if the value is a number or a file, so spectral weight filenames cannot consist entirely of numbers; "2" is not a valid filename, but "2.wgt" is.

Parameter=merged (file filetype=output)

Output merged event file name

Not required if inputting an already-merged file or single level=2 event file.

Parameter=expmap (file filetype=output)

Output exposure map

Not required if only merging data.

Parameter=expcorr (file filetype=output)

Output exposure corrected image.

Leave blank if output is not desired.

Parameter=intdir (string default=/tmp)

Directory for intermediate products

Directory where intermediate products are placed. The temporary files have a timestamp value as the root. Intermediate products are deleted from /tmp when the script finishes. If the tmpdir is set to anything other than /tmp, the intermediate data products are not deleted.

Parameter=clobber (boolean default=no)

Overwrite output files if they already exist?

CHANGES IN CIAO 4.0/MERGE_ALL 3.8

An "echo" command was replaced with dmkeypar. This does not affect the output files.

CHANGES IN MERGE_ALL 3.7

Two code changes were made in merge_all v3.7:

• An outdated ChIPS workaround was replaced by dmtcalc.
• A few instances of dmlist were replaced by dmkeypar.

Users may see tiny changes in the SIM_Z values printed to the screen due to the dmkeypar update, but the output files are unchanged.

CHANGES IN MERGE_ALL 3.6

A "[subspace -expno]" filter was added to the dmmerge command. This is needed as a workaround for a problem merging data with different EXPNO ranges.

CAVEAT: any user who intends to create lightcurves binned on exposure number from the merged output cannot use merge_all, since that information is eliminated from the subspace. (In general, lightcurves are binned on time.)

NOTES

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

See the bugs page for this script on the CIAO website for an up-to-date listing of known bugs.

See Also

calibration

ardlib

tools

acis_bkgrnd_lookup, acis_fef_lookup, acis_set_ardlib, acisspec, add_grating_orders, add_grating_spectra, asphist, dither_region, dmarfadd, dmextract, eff2evt, fullgarf, hrc_bkgrnd_lookup, make_instmap_weights, mkacisrmf, mkarf, mkexpmap, mkgarf, mkgrmf, mkinstmap, mkpsf, mkpsfmap, mkrmf, mkwarf, psextract, psf_project_ray, rmfimg, specextract