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