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. Contextsensitive
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:
<structure> <substructure axis1> <lo>:<hi> <sub.axis2> <lo>:<hi> ...
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
RA
DEC
GLON
GLAT
ELON
ELAT
SLON
SLAT
FREQ
VELO
LAMBDA
INVLAM
LOGLAM
TIME
POLN
PARAM
SAMPL
TICK
SDET
SNIP
Meaning
Equatorial, right ascension
Equatorial, declination
Galactic longitude
Galactic latitude
Ecliptic longitude
Ecliptic latitude
Supergalactic longitude
Supergalactic latitude
Frequency
Velocity axis
Wavelength
Inverse Wavelength
log(wavelength)
Time
polarisation
Parameter axis
IRDS sample axis
IRDS tick axis
IRDS detector axis
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
FREQ
from
from
-63 to
1 to
64
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)
log(10)::4
log(10):log(100):2/4
10**[0 1 5]
10**[0:3]
[1:3]+[90:70:-10]
[20:30]?[3 4 5]
yields
yields
yields
yields
yields
yields
yields
1.0 2.0 1.0 0.0
1.0 1.0 1.0 1.0
1.0 1.5 2.0
1 10 100000
1 10 100 1000
91 82 73
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:
abs(x)
sqrt(x)
sin(x)
asin(x)
cos(x)
acos(x)
tan(x)
atan(x)
exp(x)
sinh(x)
cosh(x)
tanh(x)
ln(x)
log(x)
rad(x)
deg(x)
erf(x)
erfc(x)
max(x,y)
min(x,y)
sinc(x)
atan2(x,y)
sign(x)
mod(x,y)
int(x)
nint(x)
ranu(x,y)
rang(x,y)
ranp(x)
The following mathematical functions are implemented:
absolute value of x
square root of x
sine of x
inverse sine of x
cosine of x
inverse cosine of x
tangent of x
inverse tan of x
exponential of x
hyperbolic sine of x
hyperbolic cosine of x
hyperbolic tangent of x
natural log of x
log (base 10) of x
convert x to radians
convert x to degrees
error function of x
1-error function
maximum of x and y
minimum of x and y
sin(x)/x
inverse tan (mod 2pi) x = sin, y = cos
sign of x (-1,0,1)
gives remainder of x/y
truncates to integer
nearest integer
generates uniform noise between x and y
generates Gaussian noise with mean x and dispersion y
generates Poisson noise with mean x
ifeq(x,y,a,b)
ifne(x,y,a,b)
ifgt(x,y,a,b)
ifge(x,y,a,b)
iflt(x,y,a,b)
ifle(x,y,a,b)
returns
returns
returns
returns
returns
returns
a
a
a
a
a
a
if
if
if
if
if
if
x
x
x
x
x
x
equal y, else b
not equal y, else b
greater y, else b
greater or equal y, else b
less y, else b
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
COMMENT=Set smoothed on 2-2-92
(character string)
(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).
<lower position> <upper position>
<lower position> and <upper position> indicate the lower- and upper
corner of the substructure and have the same dimension as the subset.
b).
<centre position> D <size>
with <size> indicating the rectangular size of a box centered
on <centre position>. 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=):
<n-tupel value>
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
POS=1418.6 MHZ
POS=300000 M/S
; just a grid
; a frequency
; 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
CIRCLE
HMSSEC
METER
MM
YARD
PC
TICK
DAY
HZ
M/S
K
JY
TAU
ARCSEC
DMSSEC
HMSMIN
ANGSTROM
CM
M
KPC
SECOND
YEAR
KHZ
MM/S
MK
MJY
ARCMIN
DMSMIN
HMSHOUR
NM
INCH
KM
MPC
MINUTE
RADIAN
DMSDEG
MHZ
CM/S
GHZ
KM/S
MICRON
FOOT
MILE
HOUR
For spatial axes there are a number of prefixes:
*
*1950
*xxxx.x
G
E
S
;
;
;
;
;
;
for RA or DEC in resp. HMS and DMS.
for RA or DEC in resp. HMS and DMS in EPOCH 1950.0
for RA or DEC in resp. HMS and DMS in EPOCH xxxx.x
Galactic longitude or latitude in degrees
Ecliptic longitude or latitude in degrees
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
DEC
FREQ
from
from
from
-63 to
-63 to
1 to
64
64
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:
<set name> <substructure axis1> <numbers(s)> <sub.axis2>
<numbers> ...
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
DEC
FREQ
from
from
from
-63 to
-63 to
1 to
64
64
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:
*
*1950
*xxxx.x
G
E
S
;
;
;
;
;
;
for RA or DEC in resp. HMS and DMS.
for RA or DEC in resp. HMS and DMS in EPOCH 1950.0
for RA or DEC in resp. HMS and DMS in EPOCH xxxx.x
Galactic longitude or latitude in degrees
Ecliptic longitude or latitude in degrees
Supergalactic longitude or latitude in degrees
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.
Syntax:
To define a box, there are two general input possibilities:
a)
<lower position> <upper position>
<lower position> and <upper position> indicate the lower- and
upper
corner and have the same dimension as the subset.
b)
<centre position> D <size>
with <size> indicating the rectangular size of a box centered
on <centre position>. 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
<n-tupel value>
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
log(10):log(100):2/4
10**[0 1 5]
10**[0:3]
[1:4 10:11]
[1:3]+[90:70:-10]
[20:30]?[3 4 5]
Syntax:
yields
yields
yields
yields
yields
yields
yields
1.0 1.0 1.0 1.0
1.0 1.5 2.0
1 10 100000
1 10 100 1000
1 2 3 4 10 11
91 82 73
22 23 24
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