.ec _
.ll 76
.ad b
.in 4
.ti -4
1 Language
.nf
  DISPLAY_\ Language summary

The DISPLAY_\ Language contains commands to display data cubes and results
in a flexible, interactively controlled or scripted way. Available commands:

CATALOG       : Define the spectral line catalog to identify transitions
COLOR         : Control the color LUT to highlight the Zero level
FIND          ! Search for spectral lines in the specified range
LOAD          : Read a file in the DATA area for further display
EXPLORE       : Explore a data cube: make a plot of spectra around a 2-D map
EXTRACT       : Extract a subset from a data cube
INSPECT__3D    : Visualize any data cube by cuts along 3 main directions
POPUP         : Enlarge one panel of a display
SET 	      : Set some IMAGER or GreG parameter
SHOW          : Display (in a plane by plane plot) any data cube or
                other results from the IMAGER program.
SLICE         : Extract a Slice of the specified data cube
SPECTRUM      : Compute integrated spectrum from data cube
STATISTIC     : Compute Statistics on specified data
VIEW          : Show (in a comprehensive plot) any data cube
.fi

Commands EXPLORE, INSPECT__3D, SHOW and VIEW remember and share the same 
input data for their display (e.g. SHOW CLEAN, followed by EXPLORE will
work as EXPLORE CLEAN).

.!======================================================================  
.ti -4
1 CATALOG
.ti +4 
[DISPLAY_\]CATALOG [FileName [.. [FileNameN]]

Define or list the current catalog(s) for spectral line identification. 
A catalog is a file in the "Astro" GILDAS format, as used in programs
ASTRO or CLASS in the GILDAS suite, or in  the LINEDB data format. 
Without argument, or with argument ?, the command
will just list the names of the current catalog(s).

There can be only ONE Astro catalog connected at a time, and it is exclusive
of any LINEDB data bases. On the opposite, there may be several
LINDEB data bases specified by the CATALOG command.

At initialization, IMAGER search for $HOME/imager.linedb as default
catalog, then gag__data:imager.linedb if not found. If the specified
catalog does not exist, no spectral line identification will be done.

Direct use of the LINEDB\USE command is also possible to define the
LINEDB catalog(s), though this is not recommended (possible conflicts
with an Astro catalog).


.ti -4
2 Default
.ti +4

A default catalog can be created (in the local directory) by executing once
.br
  @ gag__data:imager-linedb.sic 
.br
This may take a while, and even get stuck occasionally because it
performs network access to remote databases. You can later copy 
this catalog to your $HOME. See HELP LINEDB_\ to add or remove
species from such catalogs. 

.ti -4
2 Astro
.ti +4

The ASTRO catalog format is one of the two following ones:

A comma separated value file, including the frequency in MHz,
the species name, and the transition name, e.g.:
.ti +4
  150E3; MOLE; TRANSITION;

A list-directed file, with the same information, e.g.:
.ti +4
  150E3 'MOLE' 'TRANSITION'

Lines beginning with an exclamation mark are considered as comments.
The first line **MUST** be a comment line.

A default catalog (with no implied warranty) is given in gag__data:molecules.dat.

.ti -4
2 Linedb
.ti +4

The LINEDB catalog format is a more flexible facility, which can also
holds additional information.  On-line spectral databases (JPL and
CDMS) are directly useable as LINEDB catalogs, although access can
be long in this case. 

Scripts named gag__data:*-linedb.sic are availables as examples
to construct local data bases from the on-line ones. Beware that
the on-line databases sometimes change their naming conventions, so
that identifying a given species by name can be tricky.

In 2020, access to CDMS was unreliable. It has improved since.
Access to JPL is operational, but frequencies are not as up-to-date as in CDMS.

Local files in the JPL ".cat" format can be used, but as of Jan-2020,
the Einstein coefficients are wrong. They also require a "partfunc.cat"
in the following format (given here for HN-15-C as an example)
.nf
species HN-15-C 28006
temperatures 300. 225. 150. 75. 37.5 18.75 9.375
qpart 141.06 105.9 70.797 35.514 17.23 9.135 4.746
.fi
The tag number (28006 here) must match that of the ".cat" file.

.ti -4
2 LINEDB%ENERGY

Maximum energy of the upper state of the selected transitions, in K.
This applies only to LINEDB data bases.


.!========================================================================
.ti -4
1 COLOR
.ti +4

  [DISPLAY_\]COLOR HueRange [HueZero HueExtent]
  
Select a color Look-up-Table so that the color at value Zero is given
by HueZero (in range [0,360[), and the overall HUE extent is HueExtent 
(which can be larger than 360).
HueRange (in the same units) indicate a part of the LUT
which  becomes progressively whiter (less saturation, HueRange < 0) or 
darker (less intensity, HueRange > 0) around the colour HueZero.

Such LUTs allow to outline the Signal-containing regions compared
to the noise level, either in bright (HueRange < 0) or dark (HueRange > 0)
modes.

.!========================================================================
.ti -4
1 EXPLORE
.ti +4
[DISPLAY_\]EXPLORE  [DataCube] [/ADD Cx Cy [Box]] [/NOPAUSE]

Create a plot with a 2-D map in the middle, and up to 8 spectra
around it. 

DataCube is the name of an internal 3-D buffer, SIC variable or
data file. The 2-D map will be either a channel of this 3-D data set,
or a velocity integrated map obtained from it. It will displayed
at the center of the plot. If not present, argument DataCube keeps its
previous value.

Spectra can be displayed around, with arrows showing their position
in the map, either interactively (when the /NOPAUSE option is not
present), or manually through the /ADD option. In interactive mode,
the user can press S to extract and display the spectrum from
any place in the 2-D map.

EXPLORE ?  will list the control variables for this command. The
usual SIZE and CENTER control the 2-D map size, RANGE controls the
velocity range, and SCALE the spectral flux range.

.ti -4
2 /ADD
.ti +4
[DISPLAY_\]EXPLORE  /ADD Cx Cy [Box]

Add the spectrum coming from positin Cx Cy (in arcsec) in the specified
Box number. The Box number indicates the placement as in a numeric
keypad layout. Box 5 (the center) is reserved for the 2-D map.

If Box is not present, the spectrum is placed in the most plausible
position according to the coordinates (Cx,Cy).

.ti -4
2 /NOPAUSE
.ti +4
[DISPLAY_\]EXPLORE  [DataCube] /NOPAUSE

Just display the 2-D map and any already existing spectra, but do
not call the cursor.

.ti -4
2 Variables:
.ti +4

Like SHOW, VIEW and INSPECT__3D, EXPLORE is controlled by variables.  Most of them  are among  
those controlling SHOW:
.ti +8
SPAN, RANGE, SIZE, CENTER, SCALE, SPACING, DO__BIT DO__GREY, DO__CONTOUR, DO__MASK.

In addition, the SFLUX variables controls the displayed flux scale in the map.

.ti -4
2 CENTER
.ti +4
  REAL CENTER[2]

Specify the relative coordinates of the center of the displayed
region, in ANGLE__UNIT defined by SET ANGLE__UNIT command.


.ti -4
2 DO__BIT
.ti +4
  LOGICAL DO__BIT
  
Show a bitmap color plot (YES) or do not (NO) for each panel.
The bitmap range is controlled by variable SCALE.

.ti -4
2 DO__CONTOUR
.ti +4
  LOGICAL DO__CONTOUR

Draw (YES) or do not (NO) draw the contour level, which are controlled
by SPACING and SPACE__TYPE. This is provided for compatibility
with Mapping and Greg.

.ti -4
2 DO__GREY
.ti +4
  LOGICAL DO__GREY 

Do (YES) or do not (NO) use grey-scale contouring. Note that this
is independent of DO__CONTOUR.

.ti -4
2 DO__MASK
.ti +4
  LOGICAL DO__MASK
  
Hide part of the plot (contour or bitmaps, and even axis ticks) that lie
in the upper left corner of each panel to have a clean display of the
value specified by MARK.

.ti -4
2 RANGE
.ti +4
  REAL RANGE[2]
  
Specify the range to be displayed for the 3rd axis, as well as the displayed
range of the integrated spectrum. 

RANGE should not be confused with SPAN, which specifies the displayed
velocity range in the two PV diagram panels.

.ti +4 
2 SFLUX
.ti -4
  Character*32 SFLUX
  
Specify the flux (intensity) range for the spectra. SFLUX can be * or 0 to indicate
a fully automatic scale, or indicate a Min Max, each of which possible * to indicate a
automatic limit.

.ti -4
2 SIZE
.ti +4
  REAL SIZE[2]

Specify the displayed are size, in ANGLE__UNIT (see SET ANGLE__UNIT command).

.ti -4
2 SCALE
.ti +4
  REAL SCALE[2]
  
SCALE indicates the Colour Scale Range, range of image units which are 
displayed in the color bitmap. SCALE = 0 implies an automatic evaluation 
of this range, based on the Min and Max of the data cube.

.ti -4
2 SPACE__TYPE
.ti +4
  CHARACTER_*8 SPACE__TYPE

 Define the type of spacing for the contour levels
.nf
   LIN       Linear spacings. The Zero contour is always omitted.
   LOG       Exponential spacing
   NONE      No contour levels at all (same as DO__CONTOUR = NO)
   USER      Keep the contour levels specified by command LEVELS 
.fi
For LOG case, see HELP LEVELS EXPO in the GreG internal help.
 
As a backward compatibility, a negative spacing is a convention to use 
the current contour levels, although using SPACE__TYPE = USER
should be preferred.

.ti -4
2 SPACING
.ti +4
  CHARACTER*_16 SPACING[2]
  
SPACING indicates the step (and implicitely the contour levels) for
contouring and/or greyscale. SPACING[1] control the values, and
SPACING[2] the Unit of these values. It can be UNITS (default data
cube units), NOISE or SIGMA (noise level), Jy (which also stands
for Jy/Beam) and its sub-units mJy (or milliJy) and microJy, or K and its
sub-units mK (or milliK) or microK.  

Jy (and its sub-units) is taken as equivalent to Jy/Beam,
and automatic conversion between brightness unit (K) and flux unit (Jy/Beam)
is made when the data cube has a specified angular resolution and frequency.

SPACING[1] = 0 means an automatic guess 
of the contours from the Min and Max of the data cube.

The type of spacing is controlled by  variable SPACE__TYPE.   

.ti -4
2 SPAN
.ti +4
  REAL SPAN[2]
  
For EXPLORE, SPAN indicates the limits of plot for the spectra. 

.!======================================================================
.ti -4
1 EXTRACT
.ti +4
[DISPLAY_\]EXTRACT VarName [blc1 blc2 blc3 trc1 trc2 trc3]

  Extract a subset of the image variable VarName and put it 
in the EXTRACTED image variable.
  
  Without argument, the region covered by the subset is 
defined by the SIZE, CENTER and RANGE values. In this case, 
the EXTRACTED variable dimensions are automatically derived
from this values, and EXTRACTED can be bigger than
the actual cube defined by VarName. Areas not covered by the
initial VarName are filled out with the Blanking value of
the VarName, or by zeros if VarName has no blanking. 

  If the arguments blc1 to trc3  are  specified, the subset
corresponds to  VarName[blc1:trc1,blc2:trc2,blc3:trc3]
of the image variable VarName. The BLCi and TRCi values must 
correspond to a valid subset.


.!======================================================================
.ti -4
1 FIND
.ti +4
[DISPLAY_\]FIND Fmin Fmax [/SPECIES Name]
  
Select spectral lines in the range Fmin to Fmax (in MHz) and return
them in the LINES% structure. 

LINES%SPECIES contains the name of the species for each line.
LINES%FREQUENCY holds its frequency in MHz. 
LINES%LINES contains the full line names, including the transition.
LINES%PLOT contains the string to be used in graphic display, with
codes for superscripts and subscrips when needed.

The sign of LINES%N encodes the number of selected lines
and type of catalog which was used.

The rest of the structure depends on the catalog type.

If the catalog is in the ASTRO format, LINES%N is negative and
contains the opposite of the number of lines. 

If the catalog is in the LINEDB format (see HELP LINEDB_\ for details), 
LINE%N is positive and contains the number of selected lines. Quantum
numbers, energy levels and line strengths are also available in this 
case, allowing a more precise selection.

.ti -4 
2 /SPECIES
.ti +4
[DISPLAY_\]FIND Fmin Fmax /SPECIES Name

Only select lines from species that match the specified Name.
Only one Name can be specified, and the match is case sensitive.
There is (limited) support for wildcard so far.

.!========================================================================
.ti -4
1 INSPECT__3D
.ti +4
[DISPLAY_\]INSPECT__3D [Argument [FirstPlane [LastPlane]]]

where
.br 
Argument
.ti +4 
is the the name of a 3-D internal buffer to be plotted (BEAM, CCT, CLEAN, DIRTY,
FIELDS, MASK, etc.. ), or any Sic Image variable, or a file name.
If not present, Argument falls back to the last argument used in EXPLORE,
INSPECT__3D, SHOW, or VIEW commands.

Simultaneously display cuts along each of main cube directions, as
well as the current spectrum. Coordinates are controlled by the cursor
position in the plots.

.ti -4
2 History

INSPECT__3D is a command similar to GO 3VIEW in Mapping, but with a simpler
syntax and the ability to display program buffers as well as files.

.ti -4
2 Variables:
.ti +4

Like SHOW, VIEW and EXPLORE, INSPECT__3D is controlled by variables, selected among 
those controlling SHOW:
.ti +8 
SPAN, RANGE, SIZE, CENTER and CROSS.


.ti -4
2 SPAN
.ti +4
  REAL SPAN[2]
  
SPAN indicates the limits of 2-D plot along the velocity axis, while
RANGE indicates the 3rd axis range that is displayed in the integrated
spectrum.  The spatial dimension (if any is displayed) is controlled by SIZE and CENTER. 

If SPAN is 0, it defaults to RANGE. If RANGE is zero, all planes/channels are displayed.

.!==========================================================================

.ti -4
1 LOAD
.ti +4 
[DISPLAY_\]LOAD File [/FREQUENCY NewFreq] [/PLANES Start End] [/RANGE Start End Type] 

Read the specified File (GILDAS or FITS data cube) into the DATA
buffer, for further display.

.ti -4
2 /FREQUENCY
.ti +4
[DISPLAY_\]LOAD File /FREQUENCY RestFreq [/RANGE Min Max Type]

Read the file into the DATA area  and reset the velocity scale to 
the corresponding rest frequencies. Velocities specified
in the /RANGE Min Max VELOCITY option would then refer to this
new frequency.

.ti -4
2 /PLANES
.ti +4
[DISPLAY_\]LOAD File /PLANES Min Max 

Read only the last axis "planes" between the  First and Last implied
by Min and Max. For an LMV-ordered cube, this would be equivalent to 
.ti +4
  LOAD File /RANGE Min Max CHANNEL
.br
However, for transposed data cubes, VML or LVM-ordered for example, this is
not true at all when a Frequency/Velocity axis is present: /RANGE would
specify a subset of that axis, while /PLANES always indicate
a subset of the 3rd axis of the cube.

Min and Max indicate offsets from Plane 1 and the number of planes Nplane.
Thus Max can be negative: it then indicates Last = Nplane-Max. 
Also Min=0 and Max=0 implies loading all the channels.

.ti -4
2 /RANGE
.ti +4
[DISPLAY_\]LOAD  File /RANGE Min Max Type

Load only the channels between the First and Last
defined by Min Max and Type.  Type can be
CHANNEL, VELOCITY or FREQUENCY. If the Data cube has
no Frequency/Velocity axis, only CHANNEL is allowed.

For type CHANNEL, Min and Max indicate offsets from
Channel 1 and Channel Nchan (the number of channels
in the data set). Thus Max can be negative: it then
indicates Last = Nchan-Max. Also Min=0 and Max=0 implies
loading all the channels.

The /RANGE option is not (yet) allowed for FITS files.

.!=======================================================================
.ti -4
1 POPUP
.ti +4
    DISPLAY_\POPUP [Number] 
  
  POPUP allows to "pop up" a single plane display out of a multi-box plot.  
he action driven by POPUP depends on the content of the whole plot.
  
  After a SHOW command, POPUP will call the cursor, and any key stroke (except E to
EXIT the loop) will display the corresponding sub-plot in a separate window.
The sub-plot may contain an single plane display, a spectrum, a cumulative
flux, the phase or amplitude correction from a SELFCAL, etc...
  
  POPUP Number will popup the specified panel number (counted from Top Left 
Corner down to Bottom Right corner).
  
  POPUP will have no action if the display was not created by SHOW.
 
.!=======================================================================
.ti -4
1 SET
.ti +4 
[DISPLAY_\]SET KeyWord [Value [...]] [/DEFAULT]

Set an IMAGER or GREG internal value. The only current possible keyword
for IMAGER is ANGLE__UNIT. Use HELP GREG_\SET for help on the Greg
keywords. This command has no impact on axes that are in Angles.

.ti -4
2 ANGLE__UNIT
.ti +4
[DISPLAY_\]SET ANGLE__UNIT [Degree|Minute|Second|Radian|ABSOLUTE|RELATIVE] 

List or Specify the angular unit and mode used for box labelling. 
The mode can be ABSOLUTE to use sexagesimal notation in Hour - Degree 
for  Right Ascension and Declination, or RELATIVE to label with
offsets in the current angle unit.

SET ANGLE__UNIT
.br
will list the current and fallback units (if any)

SET ANGLE__UNIT ABSOLUTE|RELATIVE
.br 
will toggle between ABSOLUTE labels and relative ones in the current 
angular unit. ABSOLUTE labeling is not possible if there is a
rotation angle in the images: only relative labels are used in this case,
whatever the mode specified by SET ANGLE__UNIT.

SET ANGLE__UNIT Degree|Minute|Second|Radian
.br
will set the current angle unit to the specified value, and enforce
use of offset labels in the specified unit.

.ti -4
2 OtherKeyword
.ti +4
[DISPLAY_\]SET OtherKeyword [Value ...]

If the SET argument is not recognized, the command falls back
to the GREG_\SET command. See HELP GREG_\SET for possibilities.

.!=======================================================================
.ti -4
1 SHOW
.ti +4
[DISPLAY_\]SHOW Argument [Arg1 [Arg2]] [/SIDE]

where
.br 
Argument
.ti +4 
is a Keyword (e.g. COVERAGE, NOISE, UV__FIT or MOMENTS), the
name of an internal buffer to be plotted (BEAM, CCT, CLEAN, 
DIRTY, etc.. ), a 2-D or 3-D SIC image variable or datacube
filename (in Gildas or simple FITS image format).

.ti +4
[DISPLAY_\]SHOW ?
.br
will list the names of recognized keywords and buffers. 

.ti +4
Except for UV data where they have a different meaning,
.br 
Arg1 and Arg2
.ti +4
are optional arguments to restrict the range of
channels to be plotted. They default to  FIRST and LAST variable values
respectively, and Arg2 defaults to Arg1 if only Arg1 is specified.

The UV data in the internal buffer is the one loaded by command
READ UV File and optionally resampled by UV__RESAMPLE, UV__COMPRESS, etc..., or
transformed by UV__CONTINUUM. Flagged UV data  will appear in a different color.

Command VIEW offers a different style of display for cubes, NOISE and CCT.
Command INSPECT__3D offers another style for cubes.

.ti -4
2 /SIDE
.ti +4
[DISPLAY_\]SHOW Argument [FirstPlane [LastPlane]] /SIDE

  Add the _<VSIDE display of coordinates and values like in the VIEW
command, and loop on the Graphic cursor to explore the data.

  This will be the default mode if variable SHOW__SIDE is set to YES.

.ti -4
2 History
.ti +4 
SHOW derives from the GO PLOT script available in GreG and Mapping.
GO PLOT (or its variants GO BIT, GO NICE and GO MAP) and GO UVSHOW 
offered similar features to those of SHOW, but take data from files 
or SIC image variables, depending on variables NAME and TYPE.

.ti -4 
2 Keywords:

SHOW recognizes the following keywords
.nf
  BEAM        Synthesized beam(s)
  CCT         Clean Cumulative Flux
  COMPOSITE   Moments + Flux
  COVERAGE    UV Coverage
  FLUX        Integrated spectra over defined regions
  KEPLER      Radial profile and PV diagram of a Keplerian disk
  MOMENTS     0th,1st,2nd moments + peak value
  NOISE       per channel noise
  PRIMARY     Primary beam(s) 
  PV          Position-Velocity plot
  SED         Spectral Energy Distribution 
  SELFCAL     Self-Calibration corrections
  SPECTRA     Spectra on a 2-D map-like grid
  SOURCES     Clean component positions
  UV          UV data
  UV__FIT      Results of the UV__FIT command
.fi

SHOW calls the appropriate procedures for each action
.nf
  p__show__map       for data cubes
  p__show__beam      for BEAM and PRIMARY cubes
  p__show__cct       for CCT (Clean Component Tables)
  p__show__composite for Composite display (Moments + Flux)
  p__show__flux      for FLUX
  p__show__moments   for MOMENTS 
  p__show__noise     for NOISE
  p__lmv__map        for PV 
  p__show__sed       for SED
  p__show__selfcal   for SELFCAL
  p__show__tcc       for SOURCES (Clean Component Positions)
  p__spectra        for SPECTRA
  p__uvshow__sub     for UV__DATA data
  p__plotfit        for UV__FIT data (UV__FIT results)
.fi

.ti -4
2 BEAM
.ti +4
  SHOW BEAM [PLANE|FIELD Kn] [First Last]

Show some sub-cube of the (up to 4-D) dirty Beam.

The 2nd argument indicates whether SHOW shows all Fields for a
given frequency plane (PLANE keyword), or all Frequency-dependent
beams for a given Field. The 2nd and 3rd arguments are optional if 
the beam is only 3-D, which occurs for a single field or a
frequency-indepedent beam in Mosaics (narrow band approximation).


.ti -4
2 CCT
.ti +4
SHOW CCT 

Display the Cumulative Clean Flux as function of component
number. Pretty useful to see if CLEAN has reasonably converged.

.ti -4
2 COMPOSITE
.ti +4
SHOW COMPOSITE
  
Display the 3 "moments" images derived from a datacube by command MOMENTS,
and the integrated line flux computed by command FLUX.
The contour spacing for each image is controlled by its own variable:
.nf
AREA__SPACING   for the integrated area  M__AREA
VELO__SPACING   for the Velocity field M__VELO (in km/s)
WIDTH__SPACING  for the Width field M__WIDTH (in km/s)
.fi

As for other image displays, CENTER and SIZE control the center
and size of the image (in arcsec). Limits for the Flux spectrum
are computed automatically.

.ti -4
2 CONTINUUM
.ti +4
SHOW CONTINUUM

Display the "continuum" map, i.e. the map obtained by UV__MAP /CONTINUUM
and CLEAN.

.ti -4
2 COVERAGE
.ti +4
SHOW COVERAGE [Ant [Date]]

Displays the UV coverage.
Ant and Date are optional arguments indicating which Antenna
is to be highlighted, and for which date. Date is a sequential
number from 1 to the number of observing dates.

For spectral line UV data, SHOW COVERAGE will only show one
UV coverage if FIRST and LAST are set to zero. It will show one
per channel otherwise.

.ti -4
2 FIELDS
.ti +4
SHOW FIELDS

Display the positions of the fields in a Mosaic, by a
circle at the half-power primary beam size.

.ti -4
2 FLUX
.ti +4
SHOW FLUX

Displays the integrated spectra in all regions used by  
command FLUX. 

.ti -4
2 KEPLER
.ti +4
SHOW KEPLER [ALl|BOth|PV|PRofile|SPectrum]

Displays the results of the KEPLER command, which can be
.nf
  PV              Position (radius) Velocity plot
  PRofile         Peak intensity radial profile
  SPectrum        Integrated spectrum
  BOth            Radial Profile and Integrated spectrum
  ALl             All of the above
.fi
Other combinations are allowed using the KEPLER__SHOW%PROF,
KEPLER__SHOW%PV and KEPLER__SHOW%SPEC variables.

Display ranges are controlled by variables KEPLER__SHOW%X, where
X = V for the velocity range, X = T for the temperature profile
range, X = R for the radius range, and X = F for the integrated
flux range.

.ti -4
2 MOMENTS
.ti +4
SHOW MOMENTS
  
Display the 4 "moments" images derived from a datacube by command MOMENTS.
The contour spacing for each image is controlled by its own variable:
.nf
AREA__SPACING   for the integrated area  M__AREA
PEAK__SPACING   for the peak brightness value M__PEAK (in K)
VELO__SPACING   for the Velocity field M__VELO (in km/s)
WIDTH__SPACING  for the Width field M__WIDTH (in km/s)
.fi

As for other image displays, CENTER and SIZE control the center
and size of the image (in arcsec). 
  
.ti -4
2 NOISE
.ti +4
SHOW NOISE [CLEAN|DIRTY]

Compute and display the noise statistic of the specified data
cube, using a Gaussian fit to the histogram of pixel intensities
for each channel.

.ti -4
2 PRIMARY
.ti +4
  SHOW PRIMARY [PLANE|FIELD Kn] [First Last]

Show some sub-cube of the (4-D) Primary Beams.

The 2nd argument indicates whether SHOW shows all Fields for a
given frequency plane (PLANE keyword), or all Frequency-dependent
beams for a given Field (FIELD keyword). The 2nd and 3rd arguments are optional if 
the beam is only 3-D, which occurs for a single field or a
frequency-indepedent beam in Mosaics (narrow band approximation).

.ti -4
2 PV
.ti +4
SHOW PV [[CLEAN|DIRTY|SKY] Axis Offset]

Extract from the indicated data cube a Position-Velocity image at the specified Offset
(in arcsec) along the specified Axis (X or Y), and display it.

The data cube name is optional: the last specified one is used by default.

.ti +4 SHOW PV  

will simply redisplay (with different controls, see SHOW PV ? to have a list)
the last extracted Position-Velocity image.


.ti -4
2 SED
.ti +4
  SHOW SED [Frequency [FileName]] 

Display the SED, computed by the "SED" widget from images (using the FLUX command) 
or from UV Tables (by fitting a simple model using UV__FIT), and fit a simple
power law model through it.

Frequency is the reference frequency in GHz at which the flux is computed.

FileName is the data file produced by the "SED" widget.

If Frequency or Filename are not specified, their last values are re-used. 


.ti -4
2 SELFCAL
.ti +4

  See HELP SELFCAL SHOW, and/or use SHOW SELFCAL ?
  
.ti -4
2 SNR
.ti +4
SHOW SNR 

Display the Signal to Noise ratio map of a Mosaic.

.ti -4
2 SOURCES
.ti +4
SHOW SOURCES [First [Last]]

Display the "point sources" found by CLEAN at their positions,
using a marker with area proportional to their flux. Positive
sources are in black, negative ones are in red.

The displayed zone is controlled by variables SIZE and CENTER, as
for in SHOW CLEAN  or SHOW DIRTY. However, when SIZE is 0, the
displayed zone is set to  the minimum required to display all point 
sources detected by CLEAN. It may thus differ from the CLEAN map size.

.ti -4
2 SPECTRA
.ti +4
SHOW SPECTRA Clean|Dirty|Sky|ImageVar

Display individual spectra in a Map-like display (one per box, placed
at their respective positions) from a 3-D SIC variable, assumed
to be in the LMV order.

Note: the second argument may be omitted to re-display the same
dataset with different control parameters. SHOW SPECTRA is however not
fully protected against changes in the data set between two invocations,
so this should only be used for consecutive commands.

.ti -4
2 UV__DATA
.ti +4
SHOW UV__DATA [Ant [Date]]
.ti +4
SHOW UV [Ant [Date]]

Displays the UV data.  Items to be displayed are controlled
by XTYPE and YTYPE variables.
Ant and Date are optional arguments indicating which Antenna
is to be highlighted, and for which date. Date is a sequential
number from 1 to the number of observing dates.

Structure uvshow% controls some additional options, such
as coloring of various dates, of data flagging, etc...

.ti -4
2 UV__FIT
.ti +4
SHOW UV__FIT [? | RESET]

Display the UV__FIT results. The display is controlled by the
UVF% structure. 

SHOW UV__FIT ? will list the current values
of these control parameters. 

SHOW UV__FIT RESET  
will reset all control variables (UVF% structure) to their
default values.

The number and order of the fitted functions to be plotted are
controlled by UVFIT%NF and UVFIT%ORDER

The number of parameters to be plotted along X and Y axes are controlled
by UVFIT%NX, UVFIT%NY. The kinds and ranges of those parameters are 
coded in the UVFIT%XTYPE and UVFIT%YTYPE strings (e.g. kind min max).
Possible kinds are: CHANNEL VELO FREQ RMS RA DEC FLUX  WIDTH MAJOR MINOR
ANGLE and RATIO. A * instead of min and/or max implies the use of the default
minimum and maximum values of the plotted parameter.


.ti -4
2 Variables:
.ti +4
    SHOW Image  control variables

The following variables control the SHOW display. 
.nf 
  Display the header     DO__HEADER   [ YES ]   
  Display a color wedge  DO__WEDGE    [ YES ]     
  Plot bitmaps           DO__BIT      [ YES ]         
  Add the clean beam     DO__NICE     [ NO ]     
  Add the UV coverage    DO__COVERAGE [ NO ]  
  Add the dirty beam     DO__DIRTY    [ NO ]     
  Display the labels     DO__LABEL    [ YES ]     
  Display contour levels DO__CONTOUR  [ YES ] 
  grey-scale contours    DO__GREY     [ NO ] 
  Better marks           DO__MASK     [ NO ]           (Hide image behind channel marks)
 
  Channel range          RANGE       [ 0 0 ]         in 3rd axis unit, (0,0) ==> all
  Channel label          MARK        [ velocity ]    [VELOCITY, FREQUENCY or CHANNEL]
  Displayed field size   SIZE        [ 0 0 ]         in ANGLE__UNIT
  Field center           CENTER      [ 0 0 ]         offset in ANGLE__UNIT
  Cross size at center   CROSS       [ 2 ]           in arcsec, 0 ==> none 
  Fields layout          DO__FIELDS   [ NO ]          (for Mosaics)
 
  Colour Scale range     SCALE       [ 0 0 ]         (0,0) ==> all dynamic
  Contour levels         SPACING     [ 0 Units]      (0) =+> Guess
  Spacing type           SPACE__TYPE  [ AUTO]  [LIN, LOG or USER]
  Side Display           SHOW__SIDE  [ NO ]
.fi

.ti -4
2 BOX__LIMITS
.ti +4
  CHARACTER*60 BOX__LIMITS
  
If not void, this character string must indicate the 4 limits of each panel display,
for example 
.ti +8  
  LET BOX__LIMITS "* * -5 10"

If void, variables SIZE and CENTER are used instead.

.ti -4
2 DO__BIT
.ti +4
  LOGICAL DO__BIT
  
Show a bitmap color plot (YES) or do not (NO) for each panel.
The bitmap range is controlled by variable SCALE.

.ti -4
2 DO__CONTOUR
.ti +4
  LOGICAL DO__CONTOUR

Draw (YES) or do not (NO) draw the contour level, which are controlled
by SPACING and SPACE__TYPE. This is provided for compatibility
with Mapping and Greg.

.ti -4
2 DO__COVERAGE
.ti +4
  LOGICAL DO__COVERAGE
  
For SHOW DIRTY or SHOW CLEAN, DO__COVERAGE indicates if in addition
to the channel maps, the UV coverage should be displayed in another
panel.

.ti -4
2 DO__DIRTY
.ti +4
  LOGICAL DO__DIRTY
  
For SHOW DIRTY or SHOW CLEAN, DO__DIRTY indicates if in addition
to the channel maps, the dirty beam should be displayed in another
panel.

.ti -4
2 DO__FIELDS
.ti +4
  LOGICAL DO__FIELDS

  Plot the 50 % contour levels of the individual pointings in a Mosaic
on top of the maps.

.ti -4
2 DO__GREY
.ti +4
  LOGICAL DO__GREY 

Do (YES) or do not (NO) use grey-scale contouring. Note that this
is independent of DO__CONTOUR.

.ti -4
2 DO__HEADER
.ti +4
  LOGICAL DO__HEADER
  
DO__HEADER indicates whether a panel displaying a summary information
about the displayed data is drawn or not.

.ti -4
2 DO__LABEL
.ti +4
  LOGICAL DO__LABEL
  
DO__LABEL indicates if the axes should be labelled.

.ti -4
2 DO__MASK
.ti +4
  LOGICAL DO__MASK
  
Hide part of the plot (contour or bitmaps, and even axis ticks) that lie
in the upper left corner of each panel to have a clean display of the
value specified by MARK.

.ti -4
2 DO__NICE
.ti +4
  LOGICAL DO__NICE
  
DO__NICE indicates if the angular resolution of the data ("beam") should
be displayed in the lower left corner of each panel.

.ti -4
2 DO__WEDGE
.ti +4
  LOGICAL DO__WEDGE
  
DO__WEDGE indicates whether a color wedge of the bitmaps is drawn or not. 
It appears in the Header panel, so DO__WEDGE is active only if DO__HEADER
and DO__BIT are set.

.ti -4
2 CENTER
.ti +4
  REAL CENTER[2]

Specify the relative coordinates of the center of the displayed
region, in ANGLE__UNIT (as specified by SET ANGLE__UNIT). 

.ti -4
2 CROSS
.ti +4
  REAL CROSS

Indicate the size (in arcsec) of a cross to be drawn at the map projection
center, as a reference marker for relative positions.

.ti -4
2 MARK
.ti +4
  CHARACTER*12 MARK
  
Specify the type of labelling for each panel. It can be 
VELOCITY, FREQUENCY or CHANNEL. Case is not significant.

.ti -4
2 RANGE
.ti +4
  REAL RANGE[2]
  
Specify the range (in 3rd axis unit) of displayed channels. This
provides a facility similar to FIRST and LAST variables, but in a
more user-oriented unit.

RANGE should not be confused with SPAN, which specifies the displayed
velocity range when one of the 2 first axis is of type Velocity, e.g.
for SHOW PV

.ti -4
2 SCALE
.ti +4
  REAL SCALE[2]
  
SCALE indicates the Colour Scale Range, range of image units which are 
displayed in the color bitmap. SCALE = 0 implies an automatic evaluation 
of this range, based on the Min and Max of the data cube.

.ti -4
2 SIZE
.ti +4
  REAL SIZE[2]

Specify the displayed are size, in ANGLE__UNIT. 

.ti -4
2 SPACE__TYPE
.ti +4
  CHARACTER_*8 SPACE__TYPE

 Define the type of spacing for the contour levels
.nf
   LIN       Linear spacings. The Zero contour is always omitted.
   LOG       Exponential spacing
   NONE      No contour levels at all (same as DO__CONTOUR = NO)
   USER      Keep the contour levels specified by command LEVELS 
.fi
For LOG case, see HELP LEVELS EXPO in the GreG internal help.
 
As a backward compatibility, a negative spacing is a convention to use 
the current contour levels, although using SPACE__TYPE = USER
should be preferred.

.ti -4
2 SPACING
.ti +4
  CHARACTER*_16 SPACING[2]
  
SPACING indicates the step (and implicitely the contour levels) for
contouring and/or greyscale. SPACING[1] control the values, and
SPACING[2] the Unit of these values. It can be UNITS (default data
cube units), NOISE or SIGMA (noise level), Jy (which also stands
for Jy/Beam) and its sub-units mJy (or milliJy) and microJy, or K and its
sub-units mK (or milliK) or microK.  

Jy (and its sub-units) is taken as equivalent to Jy/Beam,
and automatic conversion between brightness unit (K) and flux unit (Jy/Beam)
is made when the data cube has a specified angular resolution and frequency.

SPACING[1] = 0 means an automatic guess 
of the contours from the Min and Max of the data cube.

The type of spacing is controlled by  variable SPACE__TYPE.   
 
.ti -4
2 SPAN
.ti +4
  REAL SPAN[2]
  
SPAN indicates the limits of plot along the velocity axis, when one of the
plotted dimensions is Velocity. In particular, SPAN is used for SHOW PV.
The spatial dimension (if any is displayed) is controlled by SIZE and CENTER. 

Note that SPAN differs from RANGE: RANGE controls the range of 
planes displayed for a 3-D cube. 

.ti -4
2 SHOW__SIDE
.ti +4
  LOGICAL SHOW__SIDE
  
  Controls whether the Side Display is active by default or not.
  Option /SIDE can be used to overcome this default value.

.!===========================================================================


.ti -4
1 SLICE
.ti +4
[DISPLAY_\]SLICE VarName Start1 Start2 End1 End2 UNIT

  Cut a slice through the 3-D image variable VarName with the specified 
edges and put it in the SLICED image variable. UNIT is a keyword 
indicating in which units the edges are specified. It can be PIXELS, 
DEGREE, MINUTE, SECOND, RADIAN, of ABSOLUTE.  For ABSOLUTE, Start1 and 
End1 are assumed to be in hours and Start2 End2 in degrees, with 
sexagesimal notation allowed. 


.ti +4
[DISPLAY_\]SLICE VarName StartX StartY Unit ANGLE AngleValue

  This alternate syntax allows to specify a point and an orientarion
of the slice. The coordinates StartX StartY are in the angular unit
specified by Unit (which can be ABSOLUTE) AngleValue is in Degree.
The Slice length will be automatically computed to intersect the whole cube.
This syntax can be more convenient to compare parallel slices, or slice
intersecting at a common point that can be specified by StartX StartY.

.!===========================================================================
.ti -4
1 SPECTRUM
.ti +4
[DISPLAY_\]SPECTRUM OutSpec InCube [Mask] 
      [/CORNER Imin Imax Jmin Jmax] [/PLANE First Last]  /MEAN  or  /SUM

Compute a Spectrum, stored in variable OutSpec from an input data cube 
stored in variable InCube, by summing (if /SUM is present) or averaging 
(if /MEAN is present) over the region specified by the current GreG 
polygon, or the 2-D or 3-D mask specified by Mask, truncated to the 
specified corner if any.

OutSpec[1] contains the "velocities" (values along the 3rd axis of the
InCube data cube).  OutSpec[2] contains the spectrum values.

.ti -4
2 /CORNER
.ti +4
[DISPLAY_\]SPECTRUM OutSpec InCube [Mask] /CORNER Imin Imax Jmin Jmax
  [/PLANE First Last]  /MEAN or /SUM

  Restricts the computation to the specified 2-D region of the data cube.
One of the mutually exclusive options /MEAN or /SUM must be present.

.ti -4
2 /MEAN
.ti +4
[DISPLAY_\]SPECTRUM OutSpec InCube [Mask] /MEAN
  [/CORNER Imin Imax Jmin Jmax] [/PLANE First Last]

  Indicates that we are computing a Mean spectrum.
  The spectrum is the average spectrum accounting for all valid pixels
  defined by the selection.
  
  /MEAN is exclusive of /SUM.
  
.ti -4
2 /PLANE
.ti +4
[DISPLAY_\]SPECTRUM OutSpec InCube [Mask]  /PLANE First Last
  [/CORNER Imin Imax Jmin Jmax] /MEAN  or  /SUM

  Restricts the spectrum to the specified channels of the data cube.
One of the mutually exclusive options /MEAN or /SUM must be present.

.ti -4
2 /SUM
.ti +4
[DISPLAY_\]SPECTRUM OutSpec InCube [Mask] /SUM
  [/CORNER Imin Imax Jmin Jmax] [/PLANE First Last]

  Indicates that we are computing an integrated spectrum. The result 
  corresponds to the integral of the signal over the valid area (sum of 
  values times the pixel size in user units).

  /SUM is typically used to compute integrated flux from Jy/Beam
  units. /SUM is exclusive of /MEAN.

.\"====================================================================

.ti -4
1 STATISTIC
.ti +4
[DISPLAY_\]STATISTIC [DataCube [FirstPlane [LastPlane]] 
  [/EDGE Margin] [/NOISE VarNoise] 

Compute some basic statistics (min, max, mean, rms,...) on the specified
DataCube buffer (default: CLEAN) and planes (default: variables FIRST and LAST). 
The current polygon or mask (see commands SUPPORT and MASK) is used 
to define the area on which the pixels are to be taken into account, 
except when /EDGE 0 is mentionned.

In addition to Min and Max, the command prints 3 noise numbers: 
.nf
- the rms inside the current support (whose value depends on the source 
strength and structure)
- the rms outside of the support (a good estimate of the effective 
noise), returned in variable STAT__NOISE. 
- the theoretical thermal noise (that would be the expected noise unless
the data is dynamic range limited, or unless the weights were
not set properly)
.fi

Caution: Statistics on primary-beam corrected images (SKY) cannot be 
properly computed in this way, because the noise is non uniform.

.ti -4
2 /NOISE
.ti +4
[DISPLAY_\]STATISTIC [DataCube [FirstPlane [LastPlane]] 
  [/EDGE Margin] /NOISE VarNoise 
  
Return the rms noise in the specified VarNoise SIC real scalar variable.
The rms noise is also available in variable STAT__NOISE, and if the
image is the CLEAN image, in CLEAN%NOISE as well for further convenience
and use in scripts.

.ti -4
2 /EDGE
.ti +4
[DISPLAY_\]STATISTIC [DataCube [FirstPlane [LastPlane]] 
  /EDGE Margin [/NOISE VarNoise] 

Define the size of the "edges" that are avoided in the statistic 
estimate. Margin is a number in range [0,0.5[ . Default is 1/16.

Margin 0 means considering the whole image, ignoring mask and supports.

.!===========================================================================
.ti -4
1 VIEW
.ti +4
[DISPLAY_\]VIEW Argument [FirstPlane [LastPlane]] [/NOPAUSE] [/OVERLAY]

where (in the most general case, see details for specific Keywords)
.br Argument
.ti +4 
is the the name of an internal buffer to be plotted (BEAM, CCT, CLEAN, DIRTY,
FIELDS, MASK, etc.. ), or any Sic Image variable, or a file name.

.ti +4
[DISPLAY_\]VIEW ?

will list the names of recognized keywords. If Variable
is not one of the recognized keywords, but an existing
Image variable, this image will be displayed.

.br 
FirstPlane and LastPlane
.ti +4
are optional arguments to restrict the range of
channels to be plotted (default: planes between variables FIRST
and LAST). If only FirstPlane is specified, SHOW only that plane.

VIEW is also controlled by a set of variables, available in the View% 
global structure. VIEW shows 4 (or 6) panels, representing the
Integrated area, the current channel, and the Integrated spectrum and
the current spectrul (in possibly 2 different scales). An interactive
control of the View is possible using the cursor, unless the /NOPAUSE
option is given.

The spectral panels can display line identifications based
on the current CATALOG. If a variable REDSHIFT exists, the frequency 
scale is corrected for the source Redshift, so that line identification
remains possible.

.ti -4
2 /NOPAUSE
.ti +4
[DISPLAY_\]VIEW Argument [FirstPlane [LastPlane]] /NOPAUSE

  Just display the panels as currently defined, without looping 
with the Graphic cursor for interactive view.

  This will be the default mode if variable DO__LOOP is set to NO.

.ti -4
2 /OVERLAY
.ti +4
[DISPLAY_\]VIEW Argument [FirstPlane [LastPlane]] [/NOPAUSE] 
  /OVERLAY [Variable [Channel]]
  
Overlay (in contours) the specified Channel of the specified SIC 
2 or 3-D Variable.  The default Variable is CONTINUUM, the continuum
image. If Variable is a 3-D SIC Variable, Channel indicates which plane
is overlaid (default: last one).

.ti -4
2 Keys

Position-independent actions:
.nf
  Press E key: EXIT loop
  Press H key: HELP display
  Press P key: PRINT plot in "ha" subdirectory
  Press Q key: QUIT loop
  Press X key: EXTRACT on disk current zoomed region
  Press N key: Toggle  Narrow - Wide mode 
.fi

Cursor on images:
.nf
  Left  clic: Display spectrum at pointed position
  Right clic: Define a polygon
  Press B key: BACK to full field of view
  Press C key: COORDINATES toggled from absolute to relative and back
  Press M key: Display MASK if any
  Press S key: SLICE definition (velocity-position)
  Press U key: UNKILL pointed pixel
  Press Z key: ZOOM defined spatial region
  Press V key: Display map coordinates at current position 
  Press W key: WRITE Integrated Area image
.fi
Cursor on spectra:
.nf
  Left clic in Selected   Spectrum: Display selected velocity channel
  Left clic in Integrated Spectrum: Define velocity range
  Press B key: BACK to full velocity range
  Press C key: COORDINATES toggled from freq/velo to channels and back
  Press L key: LABEL spectral Lines
  Press M key: MOVIE  
  Press Z key: ZOOM defined velocity region
  Press W key: WRITE Integrated (and current) Spectrum
.fi
Cursor outside plots:
.nf
  Press B key: BACK to full velocity range AND full field of view
.fi

Returned values are found in view%current structure. The
ZOOM action produces a sub-cube named EXTRACTED.  The SLICE action produces
a 2-D data set named SLICED. As any other SIC Image variable, EXTRACTED
and SLICED can be written on disk using command WRITE.

.ti -4
2 Scripts

The VIEW plot is done by procedure p__view__cct for Clean Components CCT
and p__view__map for data cubes. 

.ti -4
2 Variables

VIEW uses the SHOW control variables SIZE, CENTER, RANGE and CROSS. 
In addition, it has its own control variables
.nf
view%expand       0.8 Character and Tick expansion factor
view%contour      NO  Contour the current channel map
view%movie        0   Elapsed time in seconds for a movie (0 means guess)
view%side         YES Display values in side Window
view%status%rima  NO  Relative coordinates in Images
view%status%rspe  NO  Relative coordinates in Spectra
.fi

.ti -4
2 Keywords:
.ti +4

VIEW recognizes the following keywords
.nf
  BEAM        Synthesized beam(s)
  CCT         Clean Cumulative Flux
  CLEAN, DIRTY, SKY   Usual sky maps
  NOISE       per channel noise
  PRIMARY     Primary beams
.fi
or any other 3-D SIC variable.

VIEW falls back to SHOW for un-recognized keywords, such as MOMENTS
COMPOSITE, UV, etc...

.ti -4
2 BEAM
.ti +4
  VIEW BEAM [PLANE|FIELD Kn] 

View some sub-cube of the (up to 4-D) dirty Beam.

The 2nd argument indicates whether VIEW shows dirty beams
of all Fields for a given frequency plane (PLANE keyword), or all 
Frequency-dependent beams for a given Field. 

The 2nd and 3rd arguments are optional if 
the beam is only 2-D or 3-D, which occurs for a single field or a
frequency-independent beam in Mosaics (narrow band approximation).

.ti -4
2 PRIMARY
.ti +4
  VIEW PRIMARY [PLANE|FIELD Kn] 

View some sub-cube of the (up to 4-D) primary Beams.

The 2nd argument indicates whether VIEW shows all Fields for a
given frequency plane (PLANE keyword), or all Frequency-dependent
beams for a given Field. 

The 2nd and 3rd arguments are optional if 
the beam is only 2-D or 3-D, which occurs for a single field or a
frequency-independent beam in Mosaics (narrow band approximation).






.ti -4
1 ENDOFHELP
