
  (documentation for Version 3.13 of command UV__SHORT)

Compute the Short Spacings from the current Single Dish dataset (read by
READ SINGLE) and merge it to the current UV data. If the SINGLE dish
data is a Class table, UV__SHORT also creates the SHORT image variable, 
containing the 3-D data cube from which short spacings are computed.
 
  UV__SHORT takes sensible default guesses for most parameters.  UV__SHORT ?
lists the essential parameter values, UV__SHORT ?? some additional ones,
and UV__SHORT ??? even the debugging control variables.
  
    The current values can be overriden by the user, who need to set (and if
needed to  define  first)  the  corresponding  SHORT__whatever  variable.
SHORT__SD__FACTOR  is the main one which may need to be specified by the 
user, as the Single Dish data is rarely in the appropriate unit.
 
  The resulting UV table becomes the current UV data, and can  be  imaged,
written, etc... 

.ti -4
2 /CHECK
.ti +4
UV__SHORT /CHECK

  Verify the spectral compatibility between the "Short Spacing" data set
(obtained by READ SINGLE) and the UV data obtained by READ UV.
The compatibility is returned in variable SHORT__STATUS, which is
set to YES if both data sets can be merged by UV__SHORT.

  If SHORT__STATUS is set to NO, one may use command UV__SHORT /RESAMPLE
to perform the appropriate resampling.

.ti -4 
2 /REMOVE
.ti +4
UV__SHORT /REMOVE

  Removes any short spacing from the current UV data set.
  
.ti -4
2 /RESAMPLE
.ti +4
UV__SHORT /RESAMPLE

  Automatically resample the Short Spacing dataset onto the
spectral characteristics of the UV data set.

  *** Caution *** 
  
Currently, the resampling is not limited to the intersection
of the velocity/frequency coverage of the Short Spacing and
UV data set, neither is the spectral resolution limited to the
coarsest one.  The user may prefer to resample separately
both data sets to a common coverage using command MAP__RESAMPLE
(after using XY__SHORT if needed) instead of using this simpler
method.

.ti -4 
2 Algorithm

UV__SHORT task computes pseudo-visibilities for short or zero spacings 
from a single dish table of spectra (Class table) or LMV data cube. 
These pseudo visibilities are  appended to the current (presumably
a Mosaic) UV table.


Short spacings are computed when the Interferometer dish diameter
is smaller than the Single-dish diameter, Zero spacings otherwise
(see HELP UV__SHORT Zero__Spacing for this case)

For short spacings, the command performs two steps
.nf
  (1) Creation of a "well behaved" map from the spectra.
  (2) Extraction of UV visibilities from this map.
.fi

See HELP UV__SHORT Step__i for detailed explanations of the method steps.

With recent UV tables and Single Dish CLASS table, most parameters are 
automatically determined. The only parameter to be specified remains
SHORT__SD__FACTOR (although that one may also be determined automatically
if the input single dish data set is in main-beam brightness
temperature).

A parameter set to 0 value indicates the appropriate default should be used.

.ti -4
2 Zero__Spacing
.ti +4

  Zero spacings are computed when the single dish diameter is the
same as the interferometer dish diameter. Zero spacing extraction
proceeds differently for Class data tables and 3-D data cubes.

In the data cube case, the nearest pixel matching
the direction of each field is taken as the Zero spacing for this
field. If there is no point close enough, according to the
specified position tolerance SHORT__TOLE, an error occurs.

In the Class data table case, all spectra within the specified
position tolerance of a field center are averaged together
to produce the Zero spacing. If none is found, an error occcurs.


.ti -4
2 Step__1
.ti +4 

  Step (1) Creation of a "well behaved" map from the spectra.
This map is made available to the user as the SHORT datacube, and
can be saved by WRITE SHORT.

  Step (1) only can be performed independently by command XY__SHORT, 
to use the SHORT image in command FEATHER for example, or for
specific spectral resampling using command MAP__RESAMPLE SHORT. 

Step (1) only occurs if the input single-dish data set (read by READ 
SINGLE) is a table of spectra. The table format  is described in  the 
CLASS_\GRID command of CLASS. 
  The identification of the input single-dish data set as a table of
spectra is based on the Header. 

It is recommended that this input  table is a collection of 
single-dish, Nyquist sampled  spectra  covering the  
interferometric field  of  view  of interest plus at least two
primary beams as a guard band on the periphery. However, UV__SHORT does 
*NOT* make any  assumption about the provided coverage. 
It thus tries to compute  a "well behaved" map by linear operations  
(convolutions) from the  original spectra,  
in an  optimum way  from signal  to noise  point of view. The  map is  
extrapolated smoothly  towards zero at  the map  edge in order  to  
avoid  further  aliasing  in the  Fourier  transform  operations 
required in  Step (2).  This extrapolation  has a scale  length of  twice 
the single-dish beam, in order to avoid spurious Fourier components.

In detail, UV__SHORT (or XY__SHORT) performs the following operations:
.nf
  - Resampling  (in space) of  the original  spectra on  a regular  grid by
    convolution  with  a small  (typically  1/4  of  the single-dish  beam)
    gaussian convolving kernel. In  this process, the weights of individual
    spectra is carried on a weight map.
  - Extrapolation to  zero outside  the convex hull  of the  mapped region.
  - Convolution  of  the  result  by  a  gaussian  twice  as  wide  as  the
    single-dish beam.   Within the  convex hull of  the mapped  region, the
    smoothed map is replaced by the original map.
.fi

.ti -4
2 Step__2
.ti +4
  Step (2) Extraction of UV visibilities from this map.

From the given input data cube, or the "well behaved" data cube created
by Step (1), UV__SHORT  computes the visibilities in the following way:

.nf
  - Fourier transform of the single dish map;
  - Division by  the Fourier  transform of  the single dish  beam, up  to a
    maximum spacing (SHORT__SD__DIAM, in meters);
  - Inverse Fourier transform to the image plane and then for each pointing
    center;
    - Multiplication of the  image by the primary beam  of the interferometer
      elements;
    - Fourier transform back to the UV plane;
    - Creation  of the  visibilities,  with  a given  weight  SHORT__SD__WEIGHT 
      and an appropriate calibration factor to Janskys SHORT__SD__FACTOR.
.fi

Both the  single-dish and the  interferometer antennas are assumed  to have
gaussian beams (SHORT__SD__BEAM and SHORT__IP__BEAM, in radians).

.ti -4
2 Variables:

  Control variables for UV__SHORT are not predefined, except for 
the 4 main ones:  SHORT__SD__FACTOR, SHORT__SD__WEIGHT, SHORT__UV__MIN
and SHORT__UV__MAX. 

  All others should be defined by the user in case the default value
is not appropriate, with their appropriate (Real, Char or Logical) types.
  
.ti -4
2 SHORT__CHANNEL

  INTEGER value that indicates that noise level should be re-computed 
for the short spacing data cube if 0 < SHORT__CHANNEL < Number of channels 
in UV data. The noise level is estimated from differences between adjacent
channels. This method avoids the bias due to strong lines, but assumes
channels are uncorrelated. If channels are correlated, SHORT__SD__WEIGHT
should be adjusted accordingly.

  Used for tests only.
  
.ti -4
2 SHORT__DO__SINGLE

LOGICAL value, should be YES except for test purposes.

.ti -4
2 SHORT__DO__PRIMARY

LOGICAL value, should be YES except for test purposes.

.ti -4
2 SHORT__FTOLE

REAL value that specifies the tolerance in frequency / velocity alignment. 
The default is 0.1 channel at edges. This is used by the /CHECK and /RESAMPLE option
as a decision criterium.

.ti -4
2 SHORT__IP__BEAM

REAL value giving the half-power beam width of the interferometer antennas, 
in  radians. The beam is assumed to be gaussian or taken from the beam model
of the Telescope when possible.

  Default value is 0, meaning that the beam is taken from the
Telescope section if present.

.ti -4
2 SHORT__IP__DIAM

REAL value giving the interferometer diameter for which UV__SHORT will compute 
short spacing visibilities.

  Default value is 0, meaning that the diameter is taken from the
Telescope section if present.

.ti -4
2 SHORT__MCOL

  *** Obsolescent ***

See READ SINGLE ClassTable.tab /RANGE  command for an equivalent 
method of selecting the appropriate channel range. 
  
INTEGER arrays of 2 elements giving the first and last column to be mapped. 
For tables produced by GRID command
of CLASS, SHORT__MCOL[1] should be 4 and SHORT__MCOL[2] can be set to 0 to 
process all channels.

  Default value: 4 0, appropriate for tables coming from CLASS_\GRID command.

  
.ti -4
2 SHORT__MIN__WEIGHT

REAL value giving the minimum (relative) weight under which a given point in the map should
be filled by the smooth map rather than by the gridded (original] map.

  Default value: 0.01 

.ti -4
2 SHORT__MODE

INTEGER code used for backward compatibility with an 
older version of the UV__SHORT task, and also for test purpose.

Allowed values are :

.nf
-1  indicates to create a single UV table with columns for the Phase
    center offsets only
-2  indicates to create a UV table with columns for the Pointing
    center offsets
-3  indicates to create a UV table with the additional columns 
    type being Pointing or Phase, as in the original UV__TABLE$
-4  Allow to override the antenna diameter in the Telescope section
+1  indicates to append to the initial UV table the short spacings
    with Phase center offsets (which must thus match the initial UV
    table shape)
+2  indicates to append to the initial UV table the short spacings
    with Pointing center offsets (which must thus match the initial
    UV table shape)
+3  indicates to append to the initial UV table the short spacings
    (The extra column type being determined automatically).
+4  Allow to override the antenna diameter in the Telescope section
.fi

The default value is 3, i.e. automatic merging with the current
UV table.

.ti -4
2 SHORT__PIXEL__BEAM

REAL value indicating the number of pixels per single-dish beam in the XY__SHORT step. Default
is 4. Used for tests only, in principle.

.ti -4
2 SHORT__SD__BEAM

REAL value giving the Half-power beam width of the single dish antenna, in arcseconds.  The  beam
is assumed to be gaussian.

  Default value is 0, meaning that the beam is taken from the
Telescope section if present.

.ti -4
2 SHORT__SD__DIAM

REAL value giving the single dish diameter used to produce the input spectra, in meters. 

  Default value is 0, meaning that the diameter is taken from the
Telescope section if present.

.ti -4
2 SHORT__SD__FACTOR

REAL multiplicative calibration factor; it is used to convert from the single
dish map units (e.g., main-beam brightness temperature) to janskys.

A default value of 0 can be used if the original data file is
in unit of Tmb, the main beam brightness temperature, because
in this case the conversion factor can be derived from the beam
size. UV__SHORT will complain if it cannot derive the appropriate value.

.ti -4
2 SHORT__SD__WEIGHT

REAL weight scaling factor for the generated visibilities. 

It is a relative scaling factor in the weights compared
to a supposedly optimal weighting to give the best combined synthesized
beam. That optimal weighting essentially gives the same weight density
par unit area in the UV plane than the shortest baselines measured
with the interferometer only.  However, if the single-dish data
has not been observed long enough, or has baselines problems for
example, this weight may add noise to the overall data set, so could
be down-weighted.

  Default: 1.0

See also SHORT__CHANNELS for other issues about noise estimate.
.ti -4
2 SHORT__TOLE

REAL value of the tolerance in position (in radians). The behaviour differs
for Short and Zero spacings and  Table or 3-D cubes as Single-Dish data.

If the Single-Dish data is a table of spectra, Spectra differing by less than 
this amount will be added together prior to gridding. A recommended 
value is below 1/10th of the Single Dish primary beam. This is
valid for Short Spacings and Zero Spacing cases.

If the Single-Dish data is 3-D data cube, SHORT__TOLE is used only
for Zero Spacings. If no pixel is within SHORT__TOLE of an Interferometer
pointing center, no short spacing is added for this field and an
error occurs.

  Default value is 0, meaning using  1/16th of the Single Dish primary beam.
  

.ti -4
2 SHORT__UV__MAX

REAL number: No visibility at spacings higher than SHORT__UV__MAX is generated. Theoretical
consideration on the method used in this task implies that SHORT__UV__MAX
should be at most (SHORT__SD__DIAM-SHORT__IP__DIAM).  Smaller values
may need to be applied if, for example, the pointing accuracy of
the Single Dish is insufficient.

  Default value is 0, meaning to use SHORT__SD__DIAM-SHORT__IP__DIAM
  
.ti -4
2 SHORT__UV__MIN

REAL number: No visibility at spacings shorter than SHORT__UV__MIN is generated. 
If the "short spacing" data comes from a single-dish, this value
could be set to Zero.

However, if, for example, one uses an ACA image as short spacings
for an ALMA data set, the shortest baseline is the ACA antenna
diameter, 7 m. SHORT__UV__MIN should then be set to 7 in this case
(unless the ACA image includes the total power data in it already).

  Default value is 0.
  
.ti -4
2 SHORT__WCOL


INTEGER number for tests only: The column of the spectra table containing the weights. 

  Default value: 0=3, appropriate for tables coming from CLASS_\GRID command.

.ti -4
2 SHORT__WEIGHT__MODE

CHARACTER string giving the weighting mode (NATURAL, UNIFORM or GRIDDED). 
It is advised to use 'NA' for Natural weighting. Other values are reserved
for tests.


.ti -4
2 SHORT__XCOL

INTEGER number for tests only: The column of the spectra table containing X offsets. 

  Default value: 0=1, appropriate for tables coming from CLASS_\GRID command.

.ti -4
2 SHORT__YCOL

INTEGER number for tests only: The column of the spectra table containing Y offsets.

  Default value: 0=2, appropriate for tables coming from CLASS_\GRID command.

