Last modified: December 2022

URL: https://cxc.cfa.harvard.edu/ciao/ahelp/splitobs.html
AHELP for CIAO 4.16

splitobs

Context: Tools::Utilities

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
download_chandra_obsid, download_obsid_caldb, find_chandra_obsid, obsid_search_csc, search_csc