Getting Help: the HELP command and the ? token
Keywords: imager

Next: IMAGER versus CASA: controlling Up: IMAGER principles Previous: Imaging/deconvolution: a brief sequence Contents Index

##
Getting Help: the HELP command and the ? token

As with any red SIC based program, simple call to magenta`HELP` will display the various languages (e.g., blue`SIC\`, blue`GREG\`, blue`CALIBRATE\`, blue`CLEAN\`) accessible to the help documentation and list some commands with available documentation. Note that magenta`CLEAN` is a command and blue`CLEAN\` a language (i.e., a family of commands). The language of a given command is recalled in the help of each command.

Example: the command magenta`APPLY` belongs to the language blue`CALIBRATE\`, it has one argument which can be magenta`AMPLI` or magenta`PHASE` exclusively, one optional argument magenta`gain`, and one option magenta`/FLAG`.

    IMAGER> help apply
            [CALIBRATE\]APPLY [AMPLI|PHASE [gain]] [/FLAG]

In the provided description, arguments within `[]` are optional. Upper case arguments are fixed keywords that can (in general) be abbreviated. A character separates the allowed keyword values. Lower-case arguments are expected to be numbers, text, filenames, SIC variables or expressions that can be evaluated.

A brief description of the imager program can be obtained through:

    IMAGER> help imager
    USER\IMAGER = "@ welcome.ima"

          IMAGER is a interferometric imaging package, tailored for usage
      simplicity and efficiency for multi-spectral data sets.

         The basic concept of IMAGER is the use of a simple
             READ data  - ACTION(s) - [SHOW or VIEW] - WRITE
      sequence of commands, minimizing the data I/O as much as possible.
      Automatic guesses of appropriate default values for the ACTIONs
      parameters is implemented whenever possible.

    Additional Help Available:
     Actions      BEAM_Handlin MAP_Handling UV_Handling  WebPage
     HOW_TO       MAPPING

In addition, finding documentation and help for the [rgb]1,0,0IMAGER commands can be done in three different ways:

- a simple call to the magenta`HELP` command provides a description of the command and its arguments and options
- the command name followed by one or more questions marks will display some partial help on the command and its most useful parameters (''magenta`Command ?`''), its second level parameters for advanced users (''magenta`Command ??`''), all its parameters (''magenta`Command ???`'').

Documentation on subtopics of a given command (e.g., Variables, Arguments, or Results) can be obtained though: magenta`HELP command subtopic`. The list of available subtopics is found at the bottom of the documentation of each command:

    IMAGER> help uv_map
    [...]
    Additional Help Available:
     Mosaics      /FIELDS      /RANGE       /TRUNCATE
     Variables:
                  BEAM_STEP    MAP_CELL     MAP_CENTER   MAP_CONVOLUT MAP_FIELD
     MAP_POWER    MAP_PRECIS   MAP_ROBUST   MAP_ROUNDING MAP_SHIFT    MAP_SIZE
     MAP_TAPEREXP MAP_TRUNCATE MAP_UVTAPER  MAP_UVCELL   MAP_VERSION
     Old_Names:
                  convolution  map_angle    map_dec      map_ra       mcol
     uv_cell      uv_shift     uv_taper     taper_expo   wcol         weight_mode

Subtopics that appear in UpperCase in the `Additional Help Available` list are case insensitive. Subtopics that are in LowerCase of mixed case are strictly case sensitive.

Example: the following command will list the control variables of the magenta`UV_MAP` function and describe the associated parameter(s):

    IMAGER> help uv_map Variables
    UV_MAP Variables:
                    [CLEAN\]UV_MAP ?
            Will list all MAP_* variables controlling the UV_MAP parameters.

        The list of control variables is (by alphabetic order, with  the  corre-
        sponding old names used by Mapping on the right)

        New names       [   unit]       -- Description --    % Old Name
        BEAM_STEP       [       ]  Channels per dirty beam  % MAP_BEAM_STEP
        MAP_CELL        [ arcsec]  Image pixel size
        MAP_CENTER      [ string]  RA, Dec of map center, and Position Angle
        MAP_CONVOLUTION [       ]  Convolution function     % CONVOLUTION
        MAP_FIELD       [ arcsec]  Map field of view
        MAP_POWER       [       ]  Maximum exponent of 3 and 5 allowed in MAP_SIZE
        MAP_PRECIS      [       ]  Fraction of pixel tolerance on beam matching
        MAP_ROBUST      [       ]  Robustness factor        % UV_CELL[2]
        MAP_ROUNDING    [       ]  Precision of MAP_SIZE
        MAP_SIZE        [       ]  Number of pixels
        MAP_TAPEREXPO   [       ]  Taper exponent           % TAPER_EXPO
        MAP_TRUNCATE    [      %]  Mosaic truncation level
        MAP_UVCELL      [      m]  UV cell size             % UV_CELL[1]
        MAP_UVTAPER     [m,m,deg]  Gaussian taper           % UV_TAPER
        MAP_VERSION     [       ]  Code version (0 new, -1 old)

        See HELP UV_MAP Old_names:  for deprecated variable names.

A more detailed description (type, size) of a given variable can be obtained through `help command variable`, as in this example:

    IMAGER> help uv_map map_uvtaper
    UV_MAP MAP_UVTAPER

          MAP_UVTAPER[3]  Real

        Parameters of the tapering function (Gaussian if MAP_TAPEREXPO = 2): ma-
        jor axis at 1/e level [m], minor axis at 1/e level [m], and position an-
        gle [deg].

blue`MAP_UVTAPER` is an array that requires 3 values of type Real.

The default values of the useful parameters are checked through magenta`Command ?`1

     UV_MAP makes a dirty image and a dirty beam from the UV data

     Behaviour is controlled by a number of SIC Variables
     - BEAM_STEP and MAP_PRECIS control the dirty beam precision
     - MAP_CENTER controls shifting ang rotation
     - MAP_CELL[2], MAP_SIZE[2], MAP_FIELD[2] control the map sampling
     - MAP_UVTAPER[3], MAP_UVCELL and MAP_ROBUST
         control the beam shape and weighting scheme

    ---- Basic parameters                            Selected       Recommended
      Map Size (pixels)              MAP_SIZE        [ 0 0 ]   [ 0 0 ]
      Field of view (arcsec)         MAP_FIELD       [ 0 0 ]   [ 0 0 ]
      Pixel size (arcsec)            MAP_CELL        [ 0 0 ]   [ 0 0 ]
      Map center                     MAP_CENTER      [  ]
      Robust weighting parameter     MAP_ROBUST      [ 0 ]
      UV cell size (meter)           MAP_UVCELL      [ 0 ]          [ 0 ]
      UV Taper (m,m,°)               MAP_UVTAPER     [ 0 0 0 ]

For commands that support the magenta`?` mechanism, magenta`Command ?` blue`ControlVariable` and, in most cases, magenta`Command` blue`ControlVariable`magenta`?` are shortcuts to magenta`HELP Command` blue`ControlVariable`.

Next: IMAGER versus CASA: controlling Up: IMAGER principles Previous: Imaging/deconvolution: a brief sequence Contents Index