Set-related user input

A typical radio dataset might be a 3-dimensional "cube" named AURORA, with axes RA, DEC and FREQ. Pixel, or grid, coordinates in such a set can be seen as triplets; (RA,DEC,FREQ). This set is used as an example to aid the following explanation.

Sets and subsets

A subset is a part of the N-dimensional set for which one or more of the coordinates are fixed. For example an RA-DEC plane at FREQ grid 32 is a 2-dimensional subset of the cube AURORA above. And, in the most extreme case, the pixel at say (RA,DEC,FREQ) = (2,34,11) is a 0-dimensional subset of AURORA.

When a program asks for an input set, it usually also accepts one or more subsets. These can be specified by giving the axis name(s) and grids for each subset. For instance,

     AURORA

specifies the whole 3-dimensional ``cube'';

     AURORA FREQ 3

specifies the subset FREQ=3 (i.e. the RA-DEC plane at FREQ grid 3) of the set AURORA. Similarly,

     AURORA FREQ 1 2 3 4 8
        (or: AURORA FREQ 1:4 8)

specifies 5 subsets: 5 RA-DEC planes in AURORA;

     AURORA DEC 5:10 FREQ 10

specifies 1-dimensional subsets (``lines'') for values of DEC from 5 through 10 at FREQ 10.

Specifying only the axis name, and no grids, selects all subsets along that axis:

     AURORA FREQ

selects all RA-DEC planes in AURORA.
The extreme example ``AURORA RA DEC FREQ'' specifies as many subsets as there are pixels in the set. This is not normally useful.

Specifying only the grids, and no axis name, selects subsets along the ``highest'' axis. E.g. the following inputs are equivalent:

     AURORA 3:7
     AURORA FREQ 3:7

Specifying a position in a (sub)set

Many programs will ask for a position in a (sub)set. This is usually done using the keyword POS=. When this keyword is asked, the programs will indicate what coordinates must be specified and what ranges (in pixels) are allowed.

The most simple position is the grid position:

     POS= 3 5

It is also possible to enter some number corresponding to the physical units along an axis. In this case the number should be followed by the units in which it is given:

     POS= 1418.6 MHz

For spatial coordinates more formats are possible. For example in the AURORA FREQ 10 subset, RA and DEC can be specified as follows:

     POS=* 14 26 9 * -12 3 5.4

For an N-dimensional subsets n-tuple coordinate must be specified. For instance POS=3 5 10 specifies the same grid point as above but now starting from the full set AURORA.

There are two symbols that denote one position:

PC: projection centre, effectively grid position (0,0,...,0).
AC: axis centre. If the length of axis i is NAXISi and the reference pixel is CRPIXi, then the i-th coordinate is given by the expression NAXISi / 2 - CRPIXi.

Specifying a frame (area)

In many programs operations will be performed on specified areas of (sub)sets. More general, operations need to be performed on an n-dimensional section of an m-dimensional set (n <= m). Such a section is called a frame.

Programs will prompt for a frame usually using the keyword BOX=. Similar to the POS= keyword, the programs will inform the user of which ranges in which coordinates can be specified.

A frame is specified as two positions: one for the lower left, and one for the upper right corner of the frame. These positions can be specified in the same formats as can be used for the POS= keyword (see above). For instance,

     BOX= -3 -3 4 4

specifies a 2-dimensional frame containing 64 pixels.

Frames can also be specified using a position-and-size notation:

center D size
e.g. BOX= PC D 8 8

(The D stands for delta.) If only the size is given, the user will be prompted to supply the center position.
You can also enter position and/or sizes in physical coordinates. For example:

BOX= * 3 0 0 * 45 0 0 D 6 arcmin 6 arcmin 6

to get a box centered at 3h0m0s and 45d0m0s with sizes in RA and Dec of 6 minutes of arc. The units of the sizes must be compatible with the axis units in the header of the set.

Class 1 and class 2 programs

Most applications repeat their operations along the specified axes (class 1 programs). Therefore you could call these axes `repeat' axes.

Some applications (class 2) however (e.g. MOMENTS, GAUFIT, MEAN, SUM) need the specification of a so called `operation' axis. For example MOMENTS requests one operation axis, this is the integration direction. The operation is carried out but not repeated in this direction.

Examples:

MOMENTS INSET= AURORA FREQ 2:20 BOX= 63 -63 64 64
gives a velocity field of the set AURORA for all RA and DEC.

MEAN INSET= AURORA RA -10:10 DEC -10:10 BOX= 1 32
gives an average spectrum (averaged over RA from -10 to 10 and DEC from -10 to 10) for frequencies 1 to 32.

MEAN INSET= AURORA RA -10:10 DEC -10:10 BOX=1 32
gives an average spectrum (averaged over RA from -10 to 10 and DEC from -10 to 10) for frequencies 1 to 32.

The documentation of the task states whether class 1 input or class 2 input is expected. Also the structure of the output will be documented there.