Document: input
Purpose: Explanation of input syntax for GIPSY tasks
Category: DOCUMENTATION, SYNTAX
File: input.doc
Author: M. Vogelaar
Description: Explanation of the IO syntax for numbers, characters,
sets, subsets and positions.
Updates: Nov 11, 1992: VOG, document created.
Jul 03, 2000: VOG, adapted for use in help browser
#begin section main
1. SUPPLYING A TASK WITH PARAMETERS
Giving a task parameters is done through keywords. Keywords are asked
by a task when the task needs information. If a Graphical User Interface
(GUI) is available, then the keywords get a value in input fields or with
buttons etc.
A keyword is a case-insensitive character string followed by an equal sign
(e.g. INSET=). Following the equal sign, values can be given.
Depending on the function of the keyword these values can be floating point
numbers, integers, character strings and even expressions. Context-sensitive
help about keywords is provided at a single keystroke (TAB key) or the so
called bubble help if a GUI is available.
Parameters for a task can be specified on the Hermes command line
e.g.
MNMX INSET=aurora freq BOX=-10 -10 10 10
2. INPUT OF STRUCTURES AND SUBSTRUCTURES
A set is an n-dimensional data structure with n different axis names.
The contents of the set are floating point numbers stored in a file with
the extension "image". The description of the structure is stored in a
file with extension "descr". Substructures (subsets) have dimensions in
the range 0..n. A subset of dimension 0 is a pixel and a subset of
dimension n is the whole data set. If the dimension is less than n, there
are more subsets in a set. This number depends on the number of axes
(and their sizes in pixels) that are not part of the subset.
The structure is specified by a character string i.e. the name of the set
(less than 80 characters including a path) and the subsets by the name of
one or more axes outside the subset and numbers indicating pixel positions
along those axes. In short, the following format applies:
: : ...
The substructure axes can be found under the header item CTYPEi where i=1..n.
CTYPE's can be displayed with program FIXHED (run: FIXHED ITEM=HEAD) or
program HEADER. The applications with a GUI show the axes of a set after
you entered the name of this set.
Known GIPSY axis types:
Name Meaning
RA Equatorial, right ascension
DEC Equatorial, declination
GLON Galactic longitude
GLAT Galactic latitude
ELON Ecliptic longitude
ELAT Ecliptic latitude
SLON Supergalactic longitude
SLAT Supergalactic latitude
FREQ Frequency
VELO Velocity axis
LAMBDA Wavelength
INVLAM Inverse Wavelength
LOGLAM log(wavelength)
TIME Time
POLN polarisation
PARAM Parameter axis
SAMPL IRDS sample axis
TICK IRDS tick axis
SDET IRDS detector axis
SNIP IRDS snip axis
All other axis names are automatically of type PARAM.
Axis name can be abbreviated because there is a minimal match for these
names. If you omit the axis name, then the last axis of the set is set
to the default. The variables 'lo' and 'hi' indicate grid positions on an axis.
These numbers follow the input rules for integers (See under 2.). If an axis
name is given but not a number, all subsets along that axis will be included
Usually sets are asked by the keyword INSET= (or variants).
Examples:
The structure (GIPSY set) AURORA is a data cube and has axes
RA,DEC and FREQ with sizes:
RA from -63 to 64
DEC from -63 to 64
FREQ from 1 to 32
Consider the following examples:
INSET=AURORA FREQ 10:18 24 or
INSET=AURORA F 10:18 24 or
INSET=AURORA 10:18 24
gives 2-d planes (RA,DEC) for values of FREQ 10 to 18 and 24
INSET=AURORA F or
INSET=AURORA 1:32
gives 2-d planes (RA,DEC) for values of FREQ 1 to 32
INSET=AURORA DEC 5:10 FREQ 10
gives 1-d lines (RA) for values of DEC 5 to 10 at FREQ 10
INSET=AURORA
gives the whole 3-d cube
INSET=AURORA DEC 1
gives 2-d plane (RA,FREQ) for a value of DEC 1
INSET=AURORA RA 0 DEC 0 FREQ 1
gives a pixel at (RA, DEC, FREQ) = (0, 0, 1)
Most applications repeat their operations for the specified axes (so called
class 1 programs). Therefore you could call these axes 'repeat' axes. However,
some applications (class 2 programs like MOMENTS, GAUFIT, MEAN, SUM)
need the specification of a so called 'operation' axis. For example MOMENTS
knows one operation axis, this is the integration direction. The operation
performed along, 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 F BOX=-63 -63 64 64
gives for all pixels in the RA-DEC plane the average over all
frequencies.
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 should state whether class 1 input or class 2
input is necessary. Also the structure of your output is
explained in the application documentation.
2. INPUT OF FLOATING POINT OR INTEGER NUMBERS
Number input can be given as numbers and/or expressions.
In expressions the following elements can be used:
operators, numbers, constants, variables and functions.
A list of numbers can be specified as a sequence separated by
spaces and/or using the `start:end:increment' notation, where
the `:increment' part is optional and defaults to one.
A list of n identical values can be specified as `value::n'.
A list can also be used as an operand in an expression. In this
case the list must be enclosed by square brackets [] or
parentheses ( ). The expression is then evaluated for each
element of the list.
The operator ? can be used to select one or more items from a list.
Examples: 1 2 3/3 sin(pi) yields 1.0 2.0 1.0 0.0
log(10)::4 yields 1.0 1.0 1.0 1.0
log(10):log(100):2/4 yields 1.0 1.5 2.0
10**[0 1 5] yields 1 10 100000
10**[0:3] yields 1 10 100 1000
[1:3]+[90:70:-10] yields 91 82 73
[20:30]?[3 4 5] yields 22 23 24
Suppose an inclination at keyword INCL= must be given in
degrees, but you want the input in axis ratio.
INCL=DEG(ACOS([0.3 0.5]))
Between square brackets (the list facility) are the
arguments 0.3 and 0.5. The expression evaluates twice
the value for the ACOS en converts these values to
degrees. The result is that the values 0.3 and 0.5
are converted to the angles 72.5424 and 60.0 deg.
The following expressions are known to the system:
numbers: Numbers can be specified as integers, using fixed point
notation or using E or D format. Internally all numbers are
represented as double precision floating point numbers.
e.g. 123 123.45 1234.5E-2 .12345D3
operators: The following operators are known:
+ addition - subtraction
* multiplication / division
** power
constants: The following constants are implemented:
pi 3.14159.... c speed of light (SI)
h Planck (SI) k Boltzmann (SI)
g gravitation (SI) s Stefan-Boltzman (SI)
m mass of sun (SI) p parsec (SI)
BLANK Universal undefined value
Note: the Hubble constant is not included.
functions: The following mathematical functions are implemented:
abs(x) absolute value of x
sqrt(x) square root of x
sin(x) sine of x
asin(x) inverse sine of x
cos(x) cosine of x
acos(x) inverse cosine of x
tan(x) tangent of x
atan(x) inverse tan of x
exp(x) exponential of x
sinh(x) hyperbolic sine of x
cosh(x) hyperbolic cosine of x
tanh(x) hyperbolic tangent of x
ln(x) natural log of x
log(x) log (base 10) of x
rad(x) convert x to radians
deg(x) convert x to degrees
erf(x) error function of x
erfc(x) 1-error function
max(x,y) maximum of x and y
min(x,y) minimum of x and y
sinc(x) sin(x)/x
atan2(x,y) inverse tan (mod 2pi) x = sin, y = cos
sign(x) sign of x (-1,0,1)
mod(x,y) gives remainder of x/y
int(x) truncates to integer
nint(x) nearest integer
ranu(x,y) generates uniform noise between x and y
rang(x,y) generates Gaussian noise with mean x and dispersion y
ranp(x) generates Poisson noise with mean x
ifeq(x,y,a,b) returns a if x equal y, else b
ifne(x,y,a,b) returns a if x not equal y, else b
ifgt(x,y,a,b) returns a if x greater y, else b
ifge(x,y,a,b) returns a if x greater or equal y, else b
iflt(x,y,a,b) returns a if x less y, else b
ifle(x,y,a,b) returns a if x less or equal y, else b
There are also a number of Database- and file functions to access
data in image or header:
descr(set, name)
descriptor item 'name' from (sub)set(s) 'set'.
table(set, tab, col, rows)
cell(s) from column 'col' of table 'tab' in (sub)set 'set'.
image(set, box)
pixel(s) from (sub)set 'set'.
file(name, col, rows)
number(s) from a column in a text file 'name' in range 'rows'
The argument `rows' has the following syntax:
: use the whole file;
n:m use line numbers n to m;
:n use line numbers 1 to n;
n: use line numbers n to the end of the file;
n use only line number n.
3. INPUT OF LOGICALS
Logicals are decoded in the following way: YES, JA and TRUE result
in a logical which is true, NO, NEE and FALSE give a logical which
is false. It is sufficient to give the first letter of the possible
affirmative and negative replies. Any other answer will result in
a syntax error.
Examples: PLOTGRIDS=N
OK=YES
4. INPUT OF CHARACTER STRINGS
Normally character strings are case-sensitive, but individual tasks can
deviate from this or convert to either uppercase or lowercase. Some programs
can pass an array of characters. The characters are then separated by blanks
and/or comma's. Sometimes spaces however can be part of the string. The input
is called text then and carriage return closes the text.
Examples: INSTRUME=WSRT (character string)
COMMENT=Set smoothed on 2-2-92 (text)
5. INPUT OF COORDINATES
You can specify the sizes of the substructures, i.e. the sizes of the subset
axes. Usually you are asked to do so with the keyword BOX=. Positions can be
entered either as pixel positions or as physical coordinates (provided that
the relevant header items are correct).
To define a box, there are two general input possibilities:
a).
and indicate the lower- and upper
corner of the substructure and have the same dimension as the subset.
b). D
with indicating the rectangular size of a box centered
on . The D stands for Delta.
If only the size is given, the box input routine will prompt
you to specify the central position in CPOS=
The general format for a position in an n-dimensional subset is
(prompted with POS= or POSITION=):
There are two symbols that denote one position. The first one is PC.
This stands for Projection Centre and is effectively grid (0,0,...).
The second is AC which means Axis Centre. If the length of axis i is NAXISi
and the reference pixel is pixel number CRPIXi then the i-th coordinate of
AC is given by the expression NAXISi/2 - CRPIXi. In most cases this will be
[(hi+lo+1)/2, ...].
Examples:
STAT INSET=AURORA DEC 0 BOX=-30 1 20 32
gives a RA-FREQ plane with RA from -30 to 20 and FREQ from 1 to 32
STAT INSET=AURORA F 1 BOX=0 0 D 7 6
is a RA-DEC plane with RA from -3 to 3 and dec from -2 to 3
(Central position is 0,0, size of the box is 7x6).
STAT INSET=AURORA F 1 BOX=PC D 10 10
results in a RA-DEC plane with sizes 10x10 centered around the
projection centre.
COORDS INSET=AURORA F 1 POS=PC
determines the physical coordinates of the projection centre in
set AURORA.
If the correct header items and the correct axes names are entered,
you can replace the grid coordinates with physical coordinates. If a
coordinate is not followed by a unit, it is assumed to be a grid else it
will be converted. A position on a FREQ axis might be given then as:
POS=32 ; just a grid
POS=1418.6 MHZ ; a frequency
POS=300000 M/S ; a velocity
If you want to enter physical coordinates in the units corresponding to
the axis units, it is possible to prefix the values with 'U'. If the axis
has secondary units, these units are used instead of the primary units.
For example if CTYPE3 is 'FREQ' (primary units MHZ) and DTYPE3 is 'VEL'
(secondary units M/S),
POS=U 300000 is equivalent to POS=300000 M/S
GIPSY recognizes the units:
DEGREE ARCSEC ARCMIN RADIAN
CIRCLE DMSSEC DMSMIN DMSDEG
HMSSEC HMSMIN HMSHOUR
METER ANGSTROM NM MICRON
MM CM INCH FOOT
YARD M KM MILE
PC KPC MPC
TICK SECOND MINUTE HOUR
DAY YEAR
HZ KHZ MHZ GHZ
M/S MM/S CM/S KM/S
K MK
JY MJY
TAU
For spatial axes there are a number of prefixes:
* ; for RA or DEC in resp. HMS and DMS.
*1950 ; for RA or DEC in resp. HMS and DMS in EPOCH 1950.0
*xxxx.x ; for RA or DEC in resp. HMS and DMS in EPOCH xxxx.x
G ; Galactic longitude or latitude in degrees
E ; Ecliptic longitude or latitude in degrees
S ; Supergalactic longitude or latitude in degrees
Examples:
POS=* 10 12 8 * -67 8 9.6
RA = 10 hour, 12 min, 8 sec, DEC = -67 deg, 8 min, 9.6 sec.,
in a 2-d area and in the epoch as found in the header of the set.
POS=*2000.0 3 14 38.02 *2000.0 41 13 54.84
Input of RA 3 h 14 m 38.02 s, DEC 41 d 13 m 54.84 s in
epoch 2000.0
BOX=G 56.7 G 9.89 D 12 ARCSEC 10 ARCSEC
An area centered on galactic coord. 56.7 longitude, 9.89 latitude
with a size of 12 by 10 seconds of arc.
Some applications use conversion routines independent of the set header,
for example to convert angles given in HMS or DMS to a real value. The
documentation (for example: userangle.dc2) will explain the input syntax.
Also some applications use a special input routine based on the input
routines for reals. This routine allows input of the values -INF and INF
as minimum and maximum of the image. You can expect to be able to use these
values if you encounter the RANGE= keyword. Again, the application will contain
documentation about this.
#end section main
#begin section set
INPUT OF SET AND SUBSETS
Examples: The structure (GIPSY set) AURORA is a data cube and has axes
RA,DEC and FREQ with sizes:
RA from -63 to 64
DEC from -63 to 64
FREQ from 1 to 32
INSET=AURORA FREQ 10:18 24 or
INSET=AURORA F 10:18 24 or
INSET=AURORA 10:18 24
gives 2-d planes (RA,DEC) for values of FREQ 10 to 18 and 24
INSET=AURORA F or
INSET=AURORA 1:32
gives 2-d planes (RA,DEC) for values of FREQ 1 to 32
INSET=AURORA DEC 5:10 FREQ 10
gives 1-d lines (RA) for values of DEC 5 to 10 at FREQ 10
INSET=AURORA
gives the whole 3-d cube
INSET=AURORA DEC 1
gives 2-d plane (RA,FREQ) for a value of DEC 1
INSET=AURORA RA 0 DEC 0 FREQ 1
gives a pixel at (RA, DEC, FREQ) = (0, 0, 1)
syntax: The syntax for the input of set and subsets is:
...
The "substructure axis" is the axis name of an axis along which a
subset (e.g. a 2-dim image) is repeated. Subset axis are followed by
numbers corresponding to grids along that axis for which you want a
subset. If these numbers are omitted, the entire range of available
subsets is used.
Web: http://www.astro.rug.nl/~gipsy/gds/input.html
#end section set
#begin section box
BOX INPUT
You can specify the sizes of the subsets, i.e. the sizes of the subset
axes. Usually you are asked to do so with the keyword BOX= or a
corresponding input field.
Examples: The structure (GIPSY set) AURORA is a data cube and has axes
RA,DEC and FREQ with sizes:
RA from -63 to 64
DEC from -63 to 64
FREQ from 1 to 32
STAT INSET=AURORA DEC 0 BOX=-30 1 20 32
gives a RA-FREQ plane with RA from -30 to 20 and FREQ from 1 to 32
STAT INSET=AURORA F 1 BOX=0 0 D 7 6
is a RA-DEC plane with RA from -3 to 3 and dec from -2 to 3
(Central position is 0,0, size of the box is 7x6).
STAT INSET=AURORA F 1 BOX=PC D 10 10
results in a RA-DEC plane with sizes 10x10 centered around the
projection centre.
For spatial axes there are a number of prefixes:
* ; for RA or DEC in resp. HMS and DMS.
*1950 ; for RA or DEC in resp. HMS and DMS in EPOCH 1950.0
*xxxx.x ; for RA or DEC in resp. HMS and DMS in EPOCH xxxx.x
G ; Galactic longitude or latitude in degrees
E ; Ecliptic longitude or latitude in degrees
S ; Supergalactic longitude or latitude in degrees
U ; in physical units without postfix
POS=* 10 12 8 * -67 8 9.6
RA = 10 hour, 12 min, 8 sec, DEC = -67 deg, 8 min, 9.6 sec.,
in a 2-d area and in the epoch as found in the header of the set.
POS=U 150.0333 U -67.0026666
Same position as above, but in degrees and
in the coordinate system of the current set
POS=*2000.0 3 14 38.02 *2000.0 41 13 54.84
Input of RA 3 h 14 m 38.02 s, DEC 41 d 13 m 54.84 s in
epoch 2000.0
BOX=G 56.7 G 9.89 D 12 ARCSEC 10 ARCSEC
An area centered on galactic coord. 56.7 longitude, 9.89 latitude
with a size of 12 by 10 seconds of arc.
Syntax: To define a box, there are two general input possibilities:
a)
and indicate the lower- and upper
corner and have the same dimension as the subset.
b) D
with indicating the rectangular size of a box centered
on . The D stands for Delta.
If only the size is given, the box input routine will prompt
you to specify the central position in CPOS=
In gui's an incomplete specification is rejected.
The general format for a position in an n-dimensional subset is
There are two symbols that denote one position. The first one is PC.
This stands for Projection Centre and is effectively grid (0,0,...).
The second is AC which means Axis Centre. If the length of axis i is NAXISi
and the reference pixel is pixel number CRPIXi then the i-th coordinate of
AC is given by the expression NAXISi/2 - CRPIXi. In most cases this will be
[(hi+lo+1)/2, ...].
Web: http://www.astro.rug.nl/~gipsy/gds/input.html
#end section box
#begin section list
NUMBER INPUT
To facilitate the input of a row of numbers (e.g. subsets), you can use
expressions. Here are some examples:
Examples: 1 2 3/3 sin(pi) yields 1.0 2.0 1.0 0.0
log(10)::4 yields 1.0 1.0 1.0 1.0
log(10):log(100):2/4 yields 1.0 1.5 2.0
10**[0 1 5] yields 1 10 100000
10**[0:3] yields 1 10 100 1000
[1:4 10:11] yields 1 2 3 4 10 11
[1:3]+[90:70:-10] yields 91 82 73
[20:30]?[3 4 5] yields 22 23 24
Syntax: Number input can be given as numbers and/or expressions.
In expressions the following elements can be used:
operators, numbers, constants, variables and functions.
A list of numbers can be specified as a sequence separated by
spaces and/or using the `start:end:increment' notation, where
the `:increment' part is optional and defaults to one.
A list of n identical values can be specified as `value::n'.
A list can also be used as an operand in an expression. In this
case the list must be enclosed by square brackets [] or
parentheses ( ). The expression is then evaluated for each
element of the list.
The operator ? can be used to select one or more items from a list.
Web: http://www.astro.rug.nl/~gipsy/hermes/numbers.html
#end section list