Synopsis
`splitobs' separates the data products for Multi-Obi and ACIS interleaved observations
Syntax
splitobs indir outroot [verbose] [clobber]
Description
Most Chandra datasets contain a single level 1 event file produced from a single observation interval ("obi"). There are two classes of observation configurations where this is not the case.
1) Mutli-Obi observations.
See the Why topic on Multi-OBI observations.
2) ACIS Interleaved, or Alternating Exposure mode observations.
See the Alternating Exposure mode dictionary entry.
This script automates the per-obi file selection to seprate the datasets into different directories for both interleaved and mutli-obi observations. The separated directories can then be processed as if they were separate observations (e.g. with chandra_repro).
Both of these classes of observations are exceptionally uncommon. They have two (or in one case three) level 1 event files that need to be processed separately. The tricky part is separating the auxiliary files (aspect solution, mask, bad pixel, biases) that belong with each Level 1 event file, and in the case of Multi-OBI observations performed with the Gratings, to separate the correct REGION extension for each OBI.
Examples
Example 1
% splitobs indir=1612 outroot=1612
OBS_ID 1612 is an interleaved mode observation. Here the _e1_ and _e2_ files are split into separate directories and copies are made of the auxiliary files.
% /bin/ls 1612 1612_e1 1612_e2 % /bin/ls -1 1612*/secondary/*evt* 1612/secondary/acisf01612_000N004_e1_evt1.fits.gz 1612/secondary/acisf01612_000N004_e2_evt1.fits.gz 1612_e1/secondary/acisf01612_000N004_e1_evt1.fits.gz 1612_e2/secondary/acisf01612_000N004_e2_evt1.fits.gz
For interleaved mode observations, "_e1" and "_e2" are appended to the outroot parameter.
Example 2
% splitobs 3764 mode=h
The multi-obi observation OBS_ID=3764 is split into its two OBIs. The zero-padded 3 digit OBI_NUM value is appended to the outroot and the files associated with each OBI are copied into the correctly directory:
% /bin/ls -d 3764* 3764 3764_001 3764_003
Note: as with this observation, OBI_NUM values do no always start at 0 and they are not continuous. The OBI_NUM values do not have to have been observed in numeric order.
The _001 and _003 event files are copied to the appropriate directories and the correct aspect solution, and other auxiliary files are also split.
% /bin/ls 3764*/secondary/*evt1.fits* 3764/secondary/hrcf03764_001N003_evt1.fits.gz 3764/secondary/hrcf03764_003N003_evt1.fits.gz 3764_001/secondary/hrcf03764_001N003_evt1.fits.gz 3764_003/secondary/hrcf03764_003N003_evt1.fits.gz % /bin/ls 3764*/primary/*asol1.fits* 3764/primary/pcadf186708443N003_asol1.fits.gz 3764/primary/pcadf190260958N003_asol1.fits.gz 3764_001/primary/pcadf186708443N003_asol1.fits.gz 3764_003/primary/pcadf190260958N003_asol1.fits.gz
Gratings Datasets
This observation was also performed with the LETG. The level 2 event file from the Chandra archive contains separate REGION blocks for each OBI:
% dmlist 3764/primary/hrcf03764N004_evt2.fits.gz blocks
--------------------------------------------------------------------------------
Dataset: 3764/primary/hrcf03764N004_evt2.fits.gz
--------------------------------------------------------------------------------
Block Name Type Dimensions
--------------------------------------------------------------------------------
Block 1: PRIMARY Null
Block 2: EVENTS Table 16 cols x 4328706 rows
Block 3: GTI Table 2 cols x 3 rows
Block 4: REGION Table 8 cols x 2 rows
Block 5: REGION2 Table 8 cols x 2 rows
These region blocks are needed for example by chandra_repro when recalibrating and processing the data. The correct REGION extension has also been extracted and a per-obi level 2 event file, evt2, has been provided in each OBI's primary/ directory
% /bin/ls 3764*/primary/*evt2* 3764/primary/hrcf03764N004_evt2.fits.gz 3764_001/primary/hrcf03764_001N004_evt2.fits 3764_003/primary/hrcf03764_003N004_evt2.fits
Note: the Level 2 file name now contains the _001 or _003 OBI_NUM in the file name whereas from the archive it does not.
Parameters
| name | type | def | min | max | reqd |
|---|---|---|---|---|---|
| indir | file | yes | |||
| outroot | file | )indir | yes | ||
| verbose | integer | 1 | 0 | 5 | |
| clobber | boolean | no |
Detailed Parameter Descriptions
Parameter=indir (file required)
Input directory name
This should be the top level input directory name, usually this will be the OBS_ID. It should contain the standard 'primary' and 'secondary' subdirectories.
Parameter=outroot (file required default=)indir)
Output root directory name
For interleaved mode observations the script will create and populate ${outroot}_e1 and ${outroot}_e2 subdirectories. For multi-obi observations, the script will create ${outroot}_00n subdirectories where 'n' is the OBI_NUM value.
The default value of root is ")indir" which sets the outroot equal to the indir value. Thus if for example the multi-obi OBS_ID 3764 will has indir=3764 outdir=")indir" it will create two directories: 3764_001 and 3764_003.
Parameter=verbose (integer default=1 min=0 max=5)
Amount of information printed to the terminal
Parameter=clobber (boolean default=no)
Overwrite files if output directories exist?
If the output directory exists and clobber=no the tool will error out even if files do not exist. If the output directory exists and is populated with files and clobber=yes, the tool will overwrite files.
Other files
This script only copies the files in the data directory that are needed for data analysis. Things such as the V&V report, JPEG images, on-orbit aspect solution (osol) and any supporting files (README, oif.fits, level 0 event files) are not copied.
Changes in the scripts 4.14.2 (April 2022) release
Updated to split up the ARF and RMF files in the the interleaved mode gratings primary/responses directories. Responses are not created in SDP for multi-obi grating observations.
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 this page for installation instructions - such as how to ensure that the parameter file is available.
Bugs
There are no known bugs for this tool.
See Also
- contrib
- cda_data, cda_search
- tools
- download_chandra_obsid, download_obsid_caldb, find_chandra_obsid, obsid_search_csc, search_csc, splitobs