A command file is an ASCII file which contains a series of Projection commands, each command beginning at a new row.
Only the SELECT/INTERVAL and the COUNT Projection commands cannot be used in command files (they can be used only at the beginning of pipelines, see section 4.3.3). The commands in a command file must be thought of as executed sequentially. Each Projection command in the command file defines one or more virtual datasets which may be afterwards indicated as input to any of the commands that follow, and possibly output to the appropriate tables or images.
As a default, any virtual dataset is taken as input to the command line which is coming next in the command file. This rule is valid also for several virtual dataset in parallel: as shown in section 4.3.1, a Projection command may produce several datasets; symmetrically, any Projection command is able to input and to process several virtual datasets at the same time.
At the last row of a command file the ``END'' string must close the commands sequence.
A Projection command file is executed via the EXSAS command MAKE/PROJECTION:
Midas 001> MAKE/PROJECTION <command_file_name>
Though the length of a row in the command file is limited to 80 characters, there is practically no limit to the length of a command line. The use of the special character ``&'' makes the interpreter consider the next row in the command file as containing the continuation of the current command line, instead of the beginning of the next one.
In the following example it is shown how in a command file the & continuation line symbol works:
INPUT events
SELECT TIME 10000 to 10500 &
20000 to 20345 &
30000 to 30345 &
34675 to 34788
BIN TIME 10
OUTPUT to count_rate
END
The start of a comment field along the command file is marked by a ``!'' sign. All the characters following the ``!'' sign within the current row are ignored by the Projection interpreter. In the following example it is shown how in a command file the ``!'' comment line symbol works:
SELECT TIME 10000 to 10500 20000 to 20345 &
30000 to 30345 34675 to 34788 ! End of the first command line
!
! Here the filtered photons are binned into a light curve
!
BIN TIME 10
OUTPUT to count_rate ! Output it to the MIDAS table count_rate.tbl
END
The Projection command lines in a command file can be labeled by mean of identifier strings. In this way, the virtual dataset corresponding to that command line can be referenced by any of the command lines which are coming next in the command file. In the next two examples of command files it is shown how the reference mechanism works:
IDENT1 = SELECT TIME 100000 to 200000
IDENT2 = SELECT/RING center = (500,1200) radius = 450
SPECTR = BIN AMPL 1
OUT to result
END
When this command file is run the commands are simply executed sequentially, because no reference to the identifier strings IDENT1, IDENT2 and SPECTR is specified.
The input photons are first selected in time and the resulting list, labeled IDENT1, is taken as input to the next command line.
The next command line is a spatial selection within a ring. The resulting new virtual dataset, labeled IDENT2, is taken as input to the next command line.
The next command line is a binning in calibrated pulse height. The result of the binning is a virtual dataset labeled SPECTR, which is taken as input to the next command line.
The next command line is an output specification to a file named result.tbl (the filename extension does not need to be specified). The result is written into the table column labeled SPECTR, i.e. the column label is equal to the identifier string of the input virtual dataset.
The command file in the example might now be modified in order to skip the spatial selection in the production of the spectrum, and to save the result of the spatial selection separately into a new Photon Event Table. Note the usage of the ``colon'' separator (:) which always marks the end of a reference string:
IDENT1 = SELECT TIME 100000 to 200000
IDENT2 = SELECT/RING center = (500,1200) radius = 450
SPECTR = BIN IDENT1:AMPL 1 ! Bin virtual dataset IDENT1
OUT to result
OUT IDENT2: to ring_photon_list ! A new output command for dataset IDENT2
END
Identifier strings are also necessary in merging different virtual photon lists. In the following example two (overlapping) circles are selected on the sky, and the resulting photon lists are merged before to be binned into an image:
III = INPUT events
AAA = SELECT/RING III: (100,100),500
BBB = SELECT/RING III: (400,400),500
BIN/IMAGE AAA+BBB: 30
OUTPUT to image4
END
The symbol + is used to merge different photon lists. The photons belonging both to the list AAA and the list BBB are not duplicated in the merged list AAA+BBB.
One more point: the virtual dataset produced by the command INPUT can always be referenced by using a simple colon separator. The identifier string III in the last example can be omitted. The following command file works as the previous one:
INPUT events
AAA = SELECT/RING : (100,100),500
BBB = SELECT/RING : (400,400),500
BIN/IMAGE AAA+BBB: 30
OUTPUT to image4
END
It is never necessary to label an INPUT command line with an identifier string. In fact, it is generally suggested not to do so in order to make it easy to remove the INPUT command line from a command file. The same command file without INPUT command can be used in processing different photon event tables in input, their names being externally specified via the utility command MAKE/PROJECTION (see section 4.3.4 for more details).
Now some examples with command lines producing and processing several virtual datasets in parallel. In the first example it is shown how to produce 15 images from photons selected in different time intervals (i.e., this is how to create a movie):
!
! Movie of a Star:
!
INPUT events
!
! Select the photons coming from a circle centered on the source
!
SELECT/RING cen = (-156,6534) rad = 650
!
! Selection of 15 separate time intervals (in parallel)
!
SELECT TIME [10000 to 10500] [10500 to 11000] &
[11000 to 11500] [11500 to 12000] &
[12000 to 12500] [12500 to 13000] &
[13000 to 13500] [13500 to 14000] &
[14000 to 14500] [14500 to 15000] &
[15000 to 15500] [15500 to 16000] &
[16000 to 16500] [16500 to 17000] &
[17000 to 17500]
BIN/IMAGE #64, #64
OUT to foto1,foto2,foto3,foto4,foto5,foto6,foto7,foto8 &
foto9,foto10,foto11,foto12,foto13,foto14,foto15
END
Note that a single BIN/IMAGE command is used to bin 15 separate virtual photon lists. 15 virtual images are created, and are output to the 15 files specified by the OUTPUT command.
And here is a variation, a command file producing from the same sequence of time intervals a sequence of spectra which is written into 15 columns of the same table named spectra.tbl:
!
! Sequence of spectra:
!
INPUT events
!
! Select the photons from a circle centered on the source
!
SELECT/RING cen = (-156,6534) rad = 650
!
! Selection of 15 separate time intervals
!
SELECT TIME [10000 to 10500] [10500 to 11000] &
[11000 to 11500] [11500 to 12000] &
[12000 to 12500] [12500 to 13000] &
[13000 to 13500] [13500 to 14000] &
[14000 to 14500] [14500 to 15000] &
[15000 to 15500] [15500 to 16000] &
[16000 to 16500] [16500 to 17000] &
[17000 to 17500]
BIN AMPL 1
OUT to spectra
END
Up to 255 spectra can be output to the same table. It is easy to convert this table into a time/energy image by simply calling the MIDAS command
Midas 005> COPY/TI spectra timespec
Loading the resulting image timespec.bdf into the MIDAS image-display would give an immediate feel of the spectral variations of the selected source as a function of time.
One more example showing a geometrical growth of virtual datasets:
INPUT events
!
SELECT/RING [(0,0), 100] &
[(0,0), 100 to 200] &
[(0,0), 200 to 300]
!
SELECT/SECTOR [(0,0), 0 to 90] &
[(0,0), 90 to 180] &
[(0,0), 180 to 270] &
[(0,0), 270 to 360]
!
SELECT TIME [1000 to 2000] &
[2000 to 3000] &
[3000 to 4000]
!
SPEC = BIN AMPL 1
OUTPUT to all_spectra
END
This command file produces 36 spectra from a web-like pattern centered on the sky coordinate (0,0) and having a radius of 300 sky pixels, separating the contributions from three different time intervals. The spectra are written into the table all_spectra.tbl at the columns SPEC, SPEC2, SPEC3, SPEC4, ..., SPEC36.
The first command after INPUT selects three
separate photon lists from concentrical circular annuli.
Each one of these virtual datasets is input to the SELECT/SECTOR
command and is split into four parts corresponding to the
four sectors. The resulting 12 datasets
flow into the next command in the same order as they are produced:
first the inner ring, 
to 
sector;
second the inner ring, 
to 
sector; third the inner ring, 
to 
sector;
fourth the inner
ring, 
to 
sector;
fifth the intermediate ring, 
to 
sector; ... and so on. Each one of the 12 dataset is then split into three
time intervals. The resulting 36 virtual photon lists are finally
binned by the BIN AMPL command, and then output to the specified
table.
Check on it: at the table column SPEC25 is written the spectrum coming from the outer ring (radius from 200 to 300 sky pixels), the first sector (from 0 to 90 degrees), and the first time interval (from 1000 to 2000 seconds).
In order to reference one among many virtual datasets produced by the same Projection command line an identifier string must label the command line itself. Each single virtual dataset will be completely identified by the command identifier string followed by an index enclosed in round brackets. In the following example is given an idea on how to use the identifier strings for referencing single datasets in a multiple command line, performing merging of photon lists and selecting output to file.
SPOTS = SELECT/RING [(-1000,0),1000] [(0,0), 1000] [(1000,0),1000]
!
SELECT SPOTS(1): TIME 10000 to 20000
OUTPUT to out_phot
!
BIN/IMAGE SPOTS(1,2,3): 10
OUTPUT to image1, image2, image3
!
BIN SPOTS(1+2,3): AMPL 1
OUTPUT to two_spectra
!
SELECT/BOX SPOTS(1+2+3): (-1000,-1000) to (1000,1000)
BIN/IMAGE 5
OUT to one_image
END
The first command line creates three virtual photon lists labeled SPOTS(1), SPOTS(2) and SPOTS(3).
The next SELECT TIME command takes in input only the photon list SPOTS(1). The result of the selection is written to the photon event table out_phot.tbl.
The next BIN/IMAGE command takes in input all the SPOTS datasets separately. Three MIDAS images, image1, image2 and image3, are created.
The next BIN command takes the photon lists SPOTS(1) and SPOTS(2) and before processing them merges them together using the + operator (the photon which are in common between lists SPOTS(1) and SPOTS(2) are not doubled in the merged list SPOTS(1+2)). The dataset SPOTS(3) is taken instead separately. As a result, two spectra are produced and output to two different columns of table two_spectra.tbl.
Finally, the SELECT/BOX command takes all the SPOTS photon lists, merge them into a single list (photon in common among different lists are written just once into the merged list) and performs a BOX selection. The single dataset in output is binned into an image (binsize 5) and written to one_image.bdf.
A graphic overview on the Projection command syntax is given at this chapter end.