.ec _
.ll 76
.ad b
.in 4
.ti -4
1 Language
.nf
CATALOG       : Define the spectral line catalog(s)
EXTRACT       : Extract a subset from a data cube
FEATHER       : Add short spacings (image feathering)
FLUX          : Compute integrated flux from Support or Mask
HOW__TO        : Getting help on hwo to perform some action
MAP__CONTINUUM : Determine the continuum image from a spectral cube
MASK          : Define the MASK 
MFS           : Multi Frequency Synthesis (under development - not functional)
MOMENTS       : Compute Moments of the SKY or CLEAN data cubes
SELFCAL       : Perform a self calibration
SLICE         : Extract a Slice of the specified data cube
STOKES        : Extract one Stokes parameter from multi-polarization UV table
UV__ADD        : Add some extra column to the current UV data
UV__DEPROJECT  : Deproject UV data
UV__FIT        : Fit UV data with simple functions
UV__MERGE      : Merge (possibly many) UV tables
UV__PREVIEW    : Quick look at the spectral aspects of the UV data
UV__RADIAL     : Deproject and compute radial average of UV data
UV__SHORT      : Compute and add short spacings to UV data
XY__SHORT      : Compute the short spacing image from the SINGLE Dish table
.fi


.ti -4
1 CATALOG
.ti +4 
[ADVANCED_\]CATALOG [FileName [.. [FileNameN]]

Define or list the current catalog(s) for spectral line identification. 
A catalog is a file in the LINEDB data format. See HELP LINEDB\
for details. Without argument, or with argument ?, the command
will just list the names of the current catalog(s).

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
catalog(s).

.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
1 EXTRACT
.ti +4
[ADVANCED_\]EXTRACT VarName blc1 blc2 blc3 trc1 trc2 trc3

  Extract the subset VarName[blc1:trc1,blc2:trc2,blc3:trc3]
of the image variable VarName and put it in the EXTRACTED
image variable.
  
.ti -4
1 FEATHER
.ti +4
[ADVANCED_\]FEATHER [?] [/FILE Combined HIGHRes LOWres] [/REPROJECT]

  Combines a data cube containing High resolution data (HIGHres) with
one containing the short spacing data (LOWres). Automatic reprojection
and spatial resampling of the LOWres data may be done if the
option /REPROJECT is specified. 

  The method is to hybridize in the UV plane the data, retaining short
UV spacings from LOWres and long UV spacings from HIGHres. It is controlled
mainly by variable FEATHER__RADIUS, the transition radius. Other variables
allow some fine tuning.

  FEATHER ?  will list the input parameters

.ti -4
2 /REPROJECT
.ti +4
  [ADVANCED_\]FEATHER [/FILE Combined HIGHRes LOWres] /REPROJECT
  
  Allow to automatic reproject and rescale the LOWres images to the
projection and sampling of the HIGHres one. If /REPROJECT is not
present and the HIGHres and LOWres data do not match, FEATHER will
complain and stop. 

.ti -4
2 /FILE
.ti +4  
[ADVANCED_\]FEATHER /FILE Combined HIGHRes LOWres [/REPROJECT]
  
  Takes the data from files named HIGHres and LOWres and put the
combined result in file named Combined. The default extension .lmv-sky.
  
  Without the /FILE option, FEATHER takes HIGHres from the SKY buffer,
LOWres from the Short Spacing buffer (SHORT, equal to SINGLE if it is 
a data cube, or derived by UV__SHORT if not), and put the result 
into an image variable named FEATHERED. The result can be written
as any image by WRITE FEATHERED FileName.

Note: Currently, in all cases, the images reside in memory.
A buffer mode for the /FILE option will be added later.
.ti -4 
2 Algorithm
  
  FEATHER use the following steps
.nf
- Make oversampled Fourier Transform of both HIGHres and LOWres images
- Compute the truncation function f(r)
- Make the Truncated compact Fourier Transform, f(r) x T(LOW)
- Make the complement long baseline Fourier Transform, (1-f(r)) x T(HIGH)
- Sum them T(ALL) = R x f(r) x T(LOW) + (1-f(r)) x T(HIGH)
     where is taken from FEATHER__RATIO
- Make the inverse Fourier Transform
- Truncate the resulting image to original size and Mask of the HIGHres
  images
.fi

If LOWres is a single-dish image, f(r) should normally be the beam
of that telescope to use optimal Signal-to-noise ratio from that data
set. However, because of pointing errors and other calibration issues
such as spectral baseline, using a sharper transition function gives
better results. FEATHER uses a  exp(-(r/Radius)^Expo) function, where
Radius is taken from FEATHER__RADIUS and Expo from FEATHER__EXPO.  

.ti -4
2 Variables:
.ti +4
  FEATHER uses the folling input variables
.nf 
  FEATHER__RADIUS,    the transition radius
  FEATHER__EXPO, an exponent controlling the transition sharpness
  FEATHER__RATIO, a scale factor for the short spacing (LOWres) data.
  FEATHER__RANGE, the limits of the overlapping region (see details)
.fi

.ti -4
2 FEATHER__RADIUS
.ti +4
  Real FEATHER__RADIUS  (default 15.0)
  
  FEATHER__RADIUS is the transition radius (in meters) used to compute
the combination function f(uv) = exp(-(uv/Radius)^Expo).

.ti -4
2 FEATHER__EXPO
.ti +4
  Real FEATHER__EXPO  (default 8.0)

  FEATHER__EXPO is the exponent used to computed the
combination function f(uv) = exp(-(uv/Radius)^Expo).

.ti -4
2 FEATHER__RATIO
.ti +4
  Real FEATHER__RATIO (default 1.0)

  FEATHER__RATIO is the scale factor to be applied to the LOWres data
in the combination.

.ti -4
2 FEATHER__RANGE
.ti +4
  Real FEATHER__RANGE[2]

  FEATHER__RANGE[2] defines a region of "overlapping" UV
spacings over which the ratio of LOWres and HIGHres visibilities
can be checked. If the flux scale is correct, this ratio should be 1. 
FEATHER__RANGE defaults to FEATHER__RADIUS/1.15 and FEATHER__RADIUS*1.15.

  The computed ratio is only a guide, and not used in the algorithm.
A proper definition of FEATHER__RANGE requires knowledge of the
initial UV coverage of the HIGHres and LOWres data sets. If 
FEATHER__RANGE is too large, the computed ratio has no real meaning.

.ti -4
1 FLUX
.ti +4
[ADVANCED_\]FLUX Cursor|Mask|Support

  Compute the integrated flux from the CLEAN image, using zones
defined either by calling the Cursor, or by the current Support,
or by the current Mask.

  If the CLEAN data is a 3-D cube, the integrated flux will be
a spectrum.

  For FLUX MASK, if the Mask defines several separate zones, an
integrated flux will be computed for each zone. Zones are ordered
by decreasing number of pixels. 

  The FLUX results are available in the FLUX SIC structure, and
can be displayed by SHOW FLUX  and also SHOW COMPOSITE.

.ti -4
2 Limitations
.ti +4

FLUX MASK does not yet recognize properly Frequency dependent Masks.

.ti -4
2 Results 
.ti +4

  The FLUX results are available in the FLUX SIC structure
.nf  
FLUX%NC                       Number of channels
FLUX%FREQUENCIES[Flux%Nc]     Frequencies of the Channels
FLUX%VELOCITIES[Flux%Nc]      Velocities of the Channels
FLUX%NF                       Number of Fields (Zones)
FLUX%VALUES[Flux%Nc,Flux%Nf]  Integrated Flux for each channel and Zone
.fi

For Cursor or Support defined regions, the enclosing polygon is
also accessible:
.nf
FLUX%NXY                      Number of polygon summits
FLUX%X                        X coordinates of summits
FLUX%Y                        Y coordinates of summits
.fi  

.ti -4
1 HOW__TO
.ti +4
[ADVANCED_\]HOW__TO  solve a simple problem

  Ask IMAGER informations to help you solving your problem, expressed
in a natural way. Examples
.nf
  HOW do i subtract continuum ?
  HOW do i control the display ?
.fi  
Rules:
.nf
  - simple words ("do" "i" "?" "the", etc...) are ignored. You can just 
    type them to have a normal syntax in your question.
  - all significant words (e.g. "subtract" and "continuum") must be
    found to have a matching topic. 
  - significant words use exact matching. "continuum" is not the same as 
    "cont".
  - partial match is possible if a significant word ends up by *.  
    "cont*" will match "continuum".
  - if no topic matches all significant words, a list of partial matches
    is given to guide you. Use a simpler question with less significant
    words among those proposed.
.fi
   
   HOW__TO ? 
.br
  will list all topics
    
.ti -4
1 MAP__CONTINUUM
.ti +4
[ADVANCED_\]MAP__CONTINUUM [DIRTY|CLEAN [Threshold]]

  Compute a continuum image from the Dirty or Clean data set.
The derivation of the continuum follows the same algorithm
than in UV__CONTINUUM, using the integrated spectrum over
the image. 

.ti -4
1 MASK
.ti +4
[ADVANCED_\]MASK [Key [Arguments ...]

  Handle the MASK buffer, which can be used to select regions
for Cleaning (see SUPPORT /MASK) or to mask any data cube.
    
  Without argument (or with argument INTERACTIVE), an interactive tool 
is used to manipulate the mask. Valid operations are
.nf
  ADD         Add a region to the mask
  APPLY       Apply the mask to a buffer
  CHECK       Check Clean and Mask consistency
  INITIALIZE  Initialize the Mask (2D or 3D)
  INTERACTIVE Interactively define mask planes Step by Step
  OVERLAY     Overlay the Mask to the Clean image
  READ        Read the Mask from a file
  REMOVE      Remove a region from the mask
  SHOW        Show the Mask (as SHOW MASK)
  THRESHOLD   Compute an automatic mask
  USE         Use the Mask in Clean (as SUPPORT /MASK)
  WRITE       Write the Mask on file (as WRITE MASK)
.fi

.ti -4
2 Tricks
.ti +4
  The MASK variable is ReadOnly. Yet, the user may want to modify it
directly by himself.  The following commands
.nf 
  DEFINE ALIAS WMASK MASK /GLOBAL
  LET WMASK /STATUS WRITE
.fi
will create an alias to MASK which can be written by the user at will.
This method is actually used in the Interactive MASK tool.

.ti -4
2 ADD
.ti +4
[ADVANCED_\]MASK ADD Shape [Arguments ...]

  Add the specified Shape to the current mask.
Shape can be 
.nf
  CIRCLE      Ox Oy Diameter
  ELLIPSE     Ox Oy Major Minor Angle
  RECTANGLE   Ox Oy Major Minor Angle
  POLYGON     File
.fi
where Ox Oy are the center of the shapes,  Major and Minor
the axes length (= side lengths for the Rectangle...) and Angle
the Position Angle of the Major axis.

For the POLYGON, the cursor is called if no File argument is given;
else the polygon is read from the specified File.
  
.ti -4
2 APPLY
.ti +4
[ADVANCED_\]MASK APPLY SicVariable

Apply the mask to the corresponding 3-D variable.

The space dimensions must coincide (pixel per pixel), but the spectral 
axes can differ. The command will select the appropriate Mask channel 
for each plane of the SicVariable.  If the Mask is 2-D only, it will be 
applied to all planes.

.ti -4
2 CHECK
.ti +4
[ADVANCED_\]MASK CHECK [SicVariable]

Check the Mask consistency against the specified SicVariable.
The default is against Clean.

.ti -4
2 INITIALIZE 
.ti +4
[ADVANCED_\]MASK INITIALIZE 2D|3D

  Initialize an empty 2-D or 3-D mask. For a 2-D mask, the 
interactive tool will use the mean image as a background
for the definition.

.ti -4
2 INTERACTIVE
.ti +4
[ADVANCED_\]MASK INTERACTIVE [Nchan]

  Enter the interactive tool, moving Nchan channels at each
  Next or Previous button. Default is 1.

.ti +4 
[ADVANCED_\]MASK 
.br
is equivalent to 
.ti +4 
[ADVANCED_\]MASK INTERACTIVE 1

.ti -4
2 OVERLAY
.ti +4
[ADVANCED_\]MASK OVERLAY

Display a SHOW-like overlay of the Mask on top of the current
image (default is Clean, normally). All SHOW parameters apply.

.ti -4
2 READ
.ti +4
[ADVANCED_\]MASK READ File.[msk]

  Read the Mask from a Gildas data-cube. 

.ti -4
2 REMOVE
.ti +4
[ADVANCED_\]MASK REMOVE Shape [Arguments ...]

  Remove the specified Shape from the current Mask.
Shape can be 
.nf
  CIRCLE      Ox Oy Diameter
  ELLIPSE     Ox Oy Major Minor Angle
  RECTANGLE   Ox Oy Major Minor Angle
  POLYGON     File
.fi
where Ox Oy are the center of the shapes,  Major and Minor
the axes length (= side lengths for the Rectangle...) and Angle
the Position Angle of the Major axis.

For the POLYGON, the cursor is called if no File argument is given;
else the polygon is read from the specified File.

.ti -4
2 SHOW
.ti +4
[ADVANCED_\]MASK SHOW

  Similar to SHOW MASK command, but useing a spacing equal 
  to 0.5 to illustrate the boundaries.
  
.ti -4
2 THRESHOLD
.ti +4
[ADVANCED_\]MASK THRESHOLD [Raw Smooth [Length [Guard]]

Define a Mask from thresholding the CLEAN image. If the CLEAN image
is 3-D, the Mask will be 3-D.   `

The method involves a first thresholding, followed by a smoothing
to extend the support and a second thresholding. 

The algorithm to define the mask is controlled by 4 parameters.
.ti +4  
Raw    
.br 
Initial threshold (in units of CLEAN image noise) under 
which the mask is set to 0.  Default is 6 sigma. The noise is
taken from the computed Clean noise (clean%gil%rms) if defined,
or from the theoretical noise (dirty%gil%noise) if not.
.ti +4  
Smooth 
.br 
Threshold under which the Mask is set to 0 after smoothing. The
default is 2 sigma.
.ti +4  
Length
.br 
FWHM of the smoothing gaussian to derive the smooth mask from
the initial mask.  The default is the Clean beam major axis.
.ti +4 
Guard 
.br 
Size of the guard band at edges where the mask is set to zero, in units
of image size. The default is 0.18, i.e. the mask can extends
a little more than the inner quarter.  This is to avoid the
edges where sidelobes aliasing occurs.

.ti -4
2 USE
.ti +4
[ADVANCED_\]MASK USE

  Use the MASK in Clean deconvolution. 

  Equivalent to SUPPORT /MASK command.

.ti -4
2 WRITE
.ti +4
[ADVANCED_\]MASK WRITE File

  Save the Mask on a File. Default extension is .msk.

  Equivalent to WRITE MASK command.
  
.!==============================

.ti -4
1 MFS
.ti +4
[ADVANCED_\]MFS

  ** NOT OPERATIONAL -- UNDER DEVELOPMENT **

  Multi-frequency synthesis, allowing to account for spectral
index changes across the observed field of view for very wide
bandwidths continuum imaging.

.ti -4
1 MOMENTS
.ti +4
[ADVANCED_\]MOMENTS  [/METHOD Mean|Peak|Parabolic]
                     [/RANGE Min Max TYPE] [/THRESHOLD Thre]


  Compute the 4 main "moments" of a data cube, and return them
as SIC Image variables.  The 4 moments are
.nf
M__AREA   Integrated area over the velocity range
M__PEAK   Peak brightness value
M__VELO   Mean or peak velocity 
M__WIDTH  Weighted line width
.fi
The options control the method, the selected part of
the cube (default channels from FIRST to LAST), and the
threshold for detection (default 3 sigma).

The resulting images can be displayed using command SHOW MOMENTS
and saved using WRITE MOMENTS.
.ti -4
2 /METHOD
.ti +4
[ADVANCED_\]MOMENTS  /METHOD Mean|Peak|Parabola
                     [/RANGE Min Max TYPE] [/THRESHOLD Thre]

Specify which method to be used to compute the velocity and peak
values. The default method, MEAN, computes an intensity weighted
velocity, and takes the peak intensity at each pixel.
Method PEAK takes the velocity at the peak intensity. Method
PARABOLA makes a parabolic fit over 3 channels around the peak
intensity channel to derive the velocity, and takes the peak
value of this parabola for the peak brightness.

MOMENTS works on either the CLEAN or the SKY
brightness data cubes (SKY has priority if both are defined).

.ti -4
2 /RANGE
.ti +4
[ADVANCED_\]MOMENTS /RANGE Min Max TYPE
      [/METHOD Mean|Peak|Parabola] [/THRESHOLD Thre]

Specify the range of channels to be selected. TYPE can be
VELOCITY, FREQUENCY or CHANNELS.  If not present, the range
is defined by FIRST and LAST variables.

.ti -4
2 /THRESHOLDS
.ti +4
[ADVANCED_\]MOMENTS /THRESHOLD Thre
      [/METHOD Mean|Peak|Parabola] [/RANGE Min Max TYPE]

Specify the minimum intensity of the input data cube to 
consider a given pixel,channel as valid. The default is
3 sigma. The unit is that of input data cube.


.ti -4
1 SELFCAL

.so imager-help-selfcal.nroff


.ti -4
1 SLICE
.ti +4
[ADVANCED_\]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 SLICE 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
1 STOKES
.ti +4
[CLEAN_\]STOKES Key /FILE UVin UVout 

Derive a single polarization UV table (UVout) with the polarization state 
specified by Key from a multi-polarization UV table (Uvin).  
Key is any of the following:
NONE, I, Q, U, V, RR, LL, HH, VV, XX, YY.

A typical use is after command FITS on CASA data:
.nf 
  FITS Fits.uvfits TO UVin.uvt
  STOKES NONE /File UVin Uvout
.fi

.ti -4
1 UV__ADD
.ti +4
[ADVANCED\]UV__ADD ITEM [Mode] [/FILE FileIn FileOut]

  Compute and add some missing information in a UV Table, such as the 
Doppler correction and the Parallactic Angle 

The information is derived from the Observatory coordinates, from 
the Telescope name in the input UV table. This can be supplied by 
the SPECIFY TELESCOPE command if not available.

ITEM can take values DOPPLER, PARALLACTIC or * for both.

Mode is a debug control integer which indicates in which column
the information should be placed. The default is 0, i.e. the
command will re-use the column of the appropriate type, or add it
if not present.  It may be set to 3, as often column 3 contains
the Scan number, which is not a relevant information for imaging.
Other values are at the user's peril...


.ti -4
2 /FILE
.ti +4
[ADVANCED\]UV__ADD ITEM [Mode] /FILE FileIn FileOut
  
Use the UV data in the file FileIn, and write the completed 
visibilities in the file FileOut.   

.ti -4
1 UV__DEPROJECT
. ti +4 
[ADVANCED\]UV__DEPROJECT x0 y0 Rota Incli 

Deproject a UV table for inclination and orientation (Incli, 
Rota, in Degrees) around a specified center (x0,y0  in Radians).
This can be useful for almost planar or cylindrical objects (e.g.
galaxies, or protoplanetary disks)

The result becomes the current UV table.

.ti -4
1 UV__FIT
. ti +4 
[ADVANCED\]UV__FIT  [Func1 .. FuncN]  [/QUIET] [/SAVE File] [/WIDGET N]
  
Fit UV data with a few simple functions. Func1 to FuncN
(currently N < 5) are the names of the functions to be fitted. If
not specified, the last names (or those attributed
by the /WIDGET options) are used.

The models are either simple functions or linear combinations
of simple functions.  The results of the fitting process are the position
offsets in R.A. and Dec (in arc second) of the model source from the phase
reference center, and its flux (Jansky).  Depending on the fitting
functions additional fit results are possible. Currently supported
distributions and additional fit parameters are:
.nf
POINT     Point source		    : None 	
E__GAUSS   Elliptic Gaussian source  : FWHM Axes (Major and Minor), Pos Ang
C__GAUSS   Circular Gaussian source  : FWHM Axis
C__DISK    Circular Disk             : Diameter
E__DISK    Elliptical (inclined) Disk: Axis (Major and Minor), Pos Ang
RING      Annulus		    : Diameter (Inner and Outer)	
EXPO      Exponential brightness    : FWHM Axis
POWER-2   B = 1/r^2		    : FWHM Axis
POWER-3   B = 1/r^3		    : FWHM Axis
E__RING    Inclined Annulus          : Inner, Outer, Pos Ang, Ratio
.fi

The function parameters are found in a SIC structure named
UVF% under names UVF%PARi%PAR[7] (starting values), 
UVF%PARi%RANGE[7] (starting ranges) and UVF%PARi%START[7]
(number of starts). The /WIDGET option is a convenient
way to set these variables.

UV__RESIDUAL will compute the fit residual when used after UV__FIT, 
while it computes the residual from the Clean component list if 
used after CLEAN.

WRITE UV__FIT file[.uvfit] will save the fit results in a GILDAS table,
in the same format than that of the UV__FIT task.

This command is similar to the task UV__FIT, but works on the current UV buffer. 

.ti -4
2 /QUIET
.ti +4 
[ADVANCED\]UV__FIT   /QUIET  [/WIDGET N]

Activate the quiet mode. Only a progress report (25%, 50% and 75% done)
is issued in this case, not a per-channel message.  This mode
is recommended for many channels.

.ti -4
2 /SAVE
.ti +4 
[ADVANCED\]UV__FIT   /SAVE OutputFile

Save the input parameters, into a text output file. This file is then
a script which can be re-executed to set the input parameters
for UV__FIT.

If the data has only 1 channel, the fit results (see HELP
UV__FIT ResultValues) are also written in the same file.

.ti -4
2 ResultValues
.ti +4

For data with only 1 channel, the fit UV__FIT results are available as
variables  UVF%PARi%RESULTS[7] (for the results) and UVF%PARi%ERRORS[7]
(for their formal errors) for every function number i. These variables
are written in the output file by the UV__FIT /SAVE OutputFile command.

They are also available in the internal table named UV__FIT, as for
any other number of channels (see HELP UV__FIT ResultTable)

.ti -4
2 /WIDGET
.ti +4  
[ADVANCED\]UV__FIT   /WIDGET N [/QUIET]

Create a Widget to specify the function names and input parameters 
for UV__FIT for N functions.  Once these are defined by the user,
clicking the GO button will launch the computation.

.ti -4
2 ResultTable

The UV__FIT results are stored in an internal table named UV__FIT. This 
table can later be saved using command WRITE UV__FIT FileName. The 
table is organized as a MxN matrix, where M is the number of channels 
in the UV data and the organization in N is the following:
.nf
N:  P1 P2 P3 Vel A1 A2 A3 Par1 Err1 Par2 Err2 ... A1 A2 A3 Par1 Err1 ...

where P1 = RMS of the fitting process
      P2 = number of supplied functions  (NF$)
      P3 = total number of parameter
     Vel = velocity of the i-th channel (i lies between 1 and M)
      A1 = 1 (for the first function), = 2 (for the second function)
      A2 = function code (POINT = 1, E__GAUSS = 2, ... , POWER-3 = 8)
      A3 = number of parameters of the function      
    Parx = result of the fit parameter (order of appearance in PARAMxx$)
    Errx = error of the fitting process for the parameter Parx
 	
.fi
For example, fitting models with the two functions POINT and C__GAUSS 
produce files with N=24.  

SHOW UV__FIT will display plots from this table.  

.ti -4
1 UV__MERGE
.ti +4

  [ADVANCED]\UV__MERGE OutFile /FILES In1 In2 ... Inn 
    [/MODE [STACK|CONTINUUM [Index [Frequency]]]
    [/SCALES F1 ... Fn] [/WEIGHTS W1 ... Wn ] 
  
  Merge many UV data files, with calibration factor and weight factors
and (for Line data) spectral resampling as in the first  one. OutFile
is the name of the output UV table.

  For Line data, the default is to merge lines of the same molecular
transition (same Rest Frequency). However the STACK mode allows 
stacking UV data from different spectral lines, re-aligned in velocity.
This can allow detection of molecules with many transitions.
  
  For Continuum data (1 channel and/or option /MODE CONTINUUM), a 
spectral index and a reference Frequency can be specified to 
merge all UV tables.

.ti -4
2 /FILES
.ti +4

  [ADVANCED]\UV__MERGE OutFile /FILES In1 In2 ... Inn 
    [/MODE [STACK|CONTINUUM [Index [Frequency]]]
    [/SCALES F1 ... Fn] [/WEIGHTS W1 ... Wn ] 
  
  Specify the names of the UV tables to be merged. The first one is
used as a reference for resampling (line data) or Frequency (continuum data).

.ti -4
2 /MODE
.ti +4

  [ADVANCED]\UV__MERGE OutFile /FILES In1 In2 ... Inn 
    /MODE [STACK|CONTINUUM [Index [Frequency]]
    [/SCALES F1 ... Fn] [/WEIGHTS W1 ... Wn ] 
  
  Specify the merging mode.
  
  For spectral line UV tables (more than 1 channel), the default is 
that the spectral lines must have the same Rest Frequency. Resampling
(in velocity, which is then identical in frequency) is done on
the grid of the first UV table In1.
  
  In mode STACK, the Rest Frequencies can differ. Resampling is then
done in velocity, and the (u,v) coordinates scaled as the Rest
Frequency ratios to conserve the angular resolution of the data.
The /SCALES and /WEIGHT factors can be used to incorporate prio knowledge
of the expected line rations to optimize S/N.
  
  For continuum UV tables (1 channel or option /MODE CONTINUUM), a 
spectral index can be specified, as well as a reference Frequency.
(u,v) coordinates are scaled appropriately, as well as Flux and
Weights in this case. The /SCALES and /WEIGHTS factors are applied
on top of this automatic spectral index scaling. Input Line UV Tables
are treated as multi-frequency Continuum ones (as in UV__CONTINUUM 
command).
  
.ti -4
2 /SCALES
.ti +4

  [ADVANCED]\UV__MERGE OutFile /FILES In1 In2 ... Inn 
    [/MODE [STACK|CONTINUUM [Index [Frequency]]]
    /SCALES F1 ... Fn [/WEIGHTS W1 ... Wn ] 
  
  Specify the flux scaling factors for each UV table.
  
  For /MODE CONTINUUM, the spectral index is applied separately from
this flux scale factor (by further multiplication).
  
.ti -4
2 /WEIGHTS
.ti +4

  [ADVANCED]\UV__MERGE OutFile /FILES In1 In2 ... Inn  
    [/MODE [STACK|CONTINUUM [Index [Frequency]]]
    [/SCALES F1 ... Fn] /WEIGHTS W1 ... Wn  
  
  Specify the weight scaling factors for each UV table. The weight
scaling factor is independent of the flux scaling factor. This means
that to conserve the Signa-to-Noise ration, one should normally use
Wi = 1/Fi^2.
  
  For /MODE CONTINUUM, the spectral index is applied separately from
this weight scaling factor (by further multiplication).
  
.ti -4
1 UV__PREVIEW
.ti +4
[ADVANCED_\]UV__PREVIEW [Ntapers [Threshold [NHist]]] [/FILE FileIn]

A fast previewer to figure out if there is signal and what
is its spectral shape.  The command attempts to find out
the line free regions and to estimate a continuum region.

The output of UV__PREVIEW can be used for further processing
commands (UV__BASELINE and UV__FILTER, UV__SPLIT, SPECIFY, etc...)

If a catalog is defined (see HELP CATALOG), it will also
display line identification (red for detected ones, blue
for the others).
  
  Optional arguments are
.nf
  Ntapers:      number of scale sizes  (default 4)
  Threshold:    Truncation level in Sigma (default 3.5)
  Nhist:        Histogram size  (default is variable)
.fi
  
.ti -4
2 /FILE
.ti +4 
[ADVANCED_\]UV__PREVIEW [Ntapers [Threshold [NHist]]] /FILE FileIn

Without /FILE, UV__PREVIEW works from the current UV data set.

With the /FILE option, it will pre-view the UV data set from the
specified file. Edge channels are automatically dropped in this
process, as many telescopes (NOEMA or ALMA) do not produce 
useable data in these ones. The default drop is 5% of bandwidth
on each side.

.ti -4
2 Algorithm
.ti +4

UV__PREVIEW computes for Ntapers different tapers the spectrum towards 
the phase center. The taper ranges are determined from the available 
baseline lengths and telescope diameter.  
  
For each spectrum, UV__PREVIEW then attempts to figure out if there is 
line emission and the line-free channels to define the continuum level. 
This is based on the histogram of the intensity distribution of all 
channels. The most likely value and the noise level is derived from 
this histogram. An iterative scheme, blanking out of range (presumably 
line emission) channels, is used for this to converge towards a 
Gaussian histogram, which normally represents the noise distribution 
around the continuum level.
  
As a last step, blanked channels are accumulated in a list of
channels, which thus contain possible line emission at any of the
Ntapers scales.

.ti -4  
2 Limitations
.ti +4
  
UV__PREVIEW cannot identify lines if there are two few channels. It 
will only display the spectra in this case. A minimum of 32 channels is 
required, but confused spectra may also prevent a proper line 
recognition.

The line detection is based on the current specified velocity. If 
this is incorrect, lines may appear shifted and considered has not 
detected. PREVIEW%TOLERANCE indicates the matching precision in 
frequency (default is 2 MHz).

If variable \sicvar{REDSHIFT} exists, the frequency scale is
corrected for the source Redshift, so that line identification
remains possible.

.ti -4
2 Output
.ti +4

  UV__PREVIEW returns the list of possible line channels through 
variable PREVIEW%CHANNELS. If no line emission was 
identified at any scale, the list is empty and the variable does not 
exist.
  
With this list, the user can compute the continuum image, using 
commands UV__FILTER /CHANNELS PREVIEW%CHANNELS (or simply UV__FILTER), 
then UV__CONTINUUM and the usual UV__MAP and CLEAN. Alternatively, 
the user can filter out the continuum emission using UV__BASELINE.

If a catalog is present
UV__PREVIEW also creates two other variables, PREVIEW%EDGES and 
PREVIEW%FREQUENCIES which contains the start and end channels (for %EDGES,
resp. frequencies for %FREQUENCIES) of each contiguous range of channels
in PREVIOUS%CHANNELS. These variables are used for line identification
and imaging in the 
.nf 
  @ image__lines
.fi
script.

Finally, UV__PREVIEW returns in PREVIEW%FMIN PREVIEW%FMAX the frequency
coverage, and in PREVIEW%FREQ the rest frequency of the most likely 
spectral line in the window, and in PREVIEW%LINES its name. 

If no spectral line has been identified,
PREVIEW%FREQ is just the mean of PREVIEW%FMIN and PREVIEW%FMAX, and
PREVIEW%LINES does not exist.

.ti -4
1 UV__RADIAL
.ti +4 
[ADVANCED_\]UV__RADIAL x0 y0 Rota Incli  [/SAMPLING QSTEP [QMIN QMAX]] [/U__ONLY]
[/ZERO [Flux]]

Compute a UV table containing the radial distribution of the azimutal average of the 
visibilities after deprojection for inclination and orientation (Incli, 
Rota, in Degrees) around a specified center (x0,y0  in Radians).

The result becomes the current UV table.

If not specified, x0 y0 Rota and Incli default to 0.

.ti -4
2 /SAMPLING
.ti +4
[ADVANCED_\]UV__RADIAL x0 y0 Rota Incli /SAMPLING QSTEP [QMIN QMAX] [/U__ONLY] [/ZERO [Flux]]

Specify the sampling of the UV distances: Qstep is the step, Qmin and Qmax
the min and max. Distances are in meter. If not present, an automatic
guess is made from the minimum and maximum baselines and the dish diameter.
 
.ti -4
2 /U__ONLY 
.ti +4 
[ADVANCED_\]UV__RADIAL x0 y0 Rota Incli /U__ONLY [/SAMPLING QSTEP [QMIN QMAX]] [/ZERO [Flux]]

Indicate that the resulting UV table should have all V values equal to
zero. This is convenient to display the azimutal average of the visibilities
as a function of UV distance, but cannot be used for further imaging.

If not present, the resulting UV table has a (u,v) coverage which
is extended by rotation, so that it can be used to image the
(rotationally symmetric) 2-D radial distribution using standard
commands like UV__MAP and CLEAN.   The radial profile of the
brightness distribution can then be recovered by using any
radial cut through this image.

.ti -4
2 /ZERO
.ti +4
[ADVANCED_\]UV__RADIAL x0 y0 Rota Incli /ZERO [Flux] [/SAMPLING QSTEP [QMIN QMAX]] [/U__ONLY]

Add  the zero spacing flux to the azimutal average.  If no value
is given, the zero spacing flux is extrapolated from the
shortest baselines using a parabolic interpolation centered on (u,v)=(0,0).


.ti -4
1 UV__SHORT
.ti +4
[ADVANCED_\]UV__SHORT [Arg] [/REMOVE]

.so imager-help-uvshort.nroff

.ti -4
1 XY__SHORT
.ti +4
[ADVANCED_\]XY__SHORT [Arg] 

Compute the Short Spacings image from the current Single Dish dataset 
(read by READ SINGLE) when this dataset is a Class table, 
and make it available as the SHORT image variable.
  If the SINGLE dish dataset is already a 3-D data cube, nothing
is done.

XY__SHORT uses the same input parameters as UV__SHORT. It corresponds
to Step__1 of UV__SHORT.
 
.ti -4
1 ENDOFHELP


