.ec _
.ll 76
.ad b
.in 4
.\"====================================================================
.ti -4
1 Language
MAP_\ Language Summary

.nf
 XY__MAP             Build an LMV spectra cube from an XY table
.fi
.ti -4
.\"====================================================================
.ti -4
1 XY__MAP
.ti +4
MAP_\XY__MAP [TableName [CubeName]] [/NOGRID] [/TYPE LMV|VLM]

Build an LMV spectra cube and an associated weight image from an XY
table (usually produced with the command TABLE).

The input XY table name is given as first input. If its extension is
omitted, ".bat" table is selected if present, else ".tab" table is
assumed. If the XY table name is omitted, the name used at the last
command call is reused.
.br
The output cube (.lmv, .vlm, ...) and the weight image (.wei) names
are given as second input. If omitted, they share their names with the
XY table one.

By default, data is gridded with a convolution (general case), unless
/NOGRID option is invoked (typically when the data is already
regularly placed). See subtopic for details.

By default, the spatial grid of the LMV cube will be large enough to
use all the spectra of the XY table. The pixel size will ensure
Nyquist sampling (i.e. at least 2 pixels per beam). The grid position
reference and position angle will be taken from the XY table
header. The convolution kernel is a Gaussian of size one-third the
telescope beamwidth, the convolution being computed on a limited
support (large enough to ensure excellent accuracy). The gridding can
be customized with a set of parameters, see subtopic TUNING for
details.

For large datasets, XY__MAP will process the data by slices of
channels. This introduces reading, computing, and writing overheads,
but there are ways to limit those. See subtopic MEMORY for details.

Note that the output LMV cube can be then analysed with the standard
GreG image tools like GO VIEW. However, it is also possible to
reimport the cube in Class as a set of spectra thanks to the command
ANALYSE_\LMV (see HELP for details).
.\"--------------------------------------------------------------------
.ti -4
2 /NOGRID
.ti +4
MAP_\XY__MAP [Filename] /NOGRID

XY__MAP_ /NOGRID builds an LMV spectra cube and an associated weight
image from an XY table, but does not regrid the data with a
convolution.

The command checks that it encounters points which are regularly
spaced (i.e., on a grid), and it deduces from these the typical
parameters of the spatial grid (pixel size, map size, ...). The grid
alignment is checked with a tolerance. By default the tolerance is a
tenth of the beam, if the beam is known (see HELP XY__MAP TUNING for
the possible ways to declare the beam). If the beam is not known, the
tolerance can be explicitly set in the variable MAP%TOLE (in arcsec).

The parameters of the output cube can still be overridden by user's
MAP%LIKE and MAP% objects.
.\"--------------------------------------------------------------------
.ti -4
2 /TYPE
.ti +4
MAP_\XY__MAP [Filename] /TYPE LMV|VLM

By default, XY__MAP produces an LMV (position-position-velocity)
cube. This can be overridden by the option /TYPE to reorder the
dimensions as VLM (velocity-position-position).

VLM is the natural ordering of the XY__MAP internal buffers, i.e. it
should be faster to create the cube in this order. VLM cubes are also
useful when data has to be accessed by spectrum (e.g. to use the cube
with FILE IN mycube.vlm), as opposed to the LMV cubes which are
efficient for access by channel (image plane).
.\"--------------------------------------------------------------------
.ti -4
2 TUNING
.ti +4
MAP_\XY__MAP: tuning parameters

The gridding process may be finely tuned through user defined values
of the MAP structure.

The header of an existing LMV cube may be used as a template for the
grid definition. To do this, the user must set the variable
.nf
    MAP%LIKE       [string    ] Reference header for spatial parameters
.fi

When MAP%LIKE is set to an empty string, the user may define the grid
by hand through the following parameters
.nf
    MAP%CELL[2]    [arcsec    ] X and Y pixel size
    MAP%SIZE[2]    [pixel     ] X and Y map size
.fi
Each MAP%CELL sign indicates the axis orientation: East is left if
MAP%CELL[1]<0 and North is top if MAP%CELL[2]>0.

The projection parameters can be customized with:
.nf
    MAP%SHIFT      [logical   ] Reproject the grid?
    MAP%PTYPE      [code      ] Grid projection type
    MAP%RA         [  HH:MM:SS] Grid reference position
    MAP%DEC        [+DDD:MM:SS] Grid reference position
    MAP%ANGLE      [degree    ] Grid position angle
.fi
These parameters are applied only if MAP%SHIFT is YES. MAP%PTYPE is
one of the SIC%CODE%PROJ% codes (or H%PTYPE from the DEFINE HEADER
command); null code stands for automatic choice (projection taken from
the table, except radio which is converted to azimuthal). Empty MAP%RA
or MAP%DEC are taken from the table header. MAP%ANGLE is the target
angle (not the angle to be added).

The natural beamwidth of the telescope is derived from (in order of
precedence):
.nf
    TAB%MAJOR      [radian    ] The resolution in the table header
    MAP%TELE       [string    ] The telescope name (if no resolution in table)
    MAP%DIAM       [m         ] The telescope diameter (if MAP%TELE = "")
    MAP%BEAM       [arcsec    ] The beam size (if MAP%DIAM = 0)
.fi
Because of the convolution, the spatial resolution of the gridded data
will by default be 5.4% wider than the telescope beamwidth at the
observation frequency. It is however possible to grid the data with a
wider Gaussian in order to smooth the data (e.g. to increase the
signal-to-noise ratio of extended emission). On the other hand, it is
by construction impossible to request a final resolution smaller than
the intrinsic resolution (beam size). The user can define the required
resolution of the gridded data through
.nf
    MAP%RESO[2]    [arcsec    ] Final resolution of the gridded data
.fi
The resolution can not be smaller than the beam size (default 0 means
automatic resolution). The command will deduce the size of the
gridding kernel from the telescope beamwidth and the required
resolution.

In /NOGRID mode (see subtopic for details), XY__MAP will guess the X
and Y increments from the spectra positions, but it needs some
tolerance. The default is 1/10 of the beam, which is enough for
Nyquist sampled grids. However, if the beam is not known, or if the
grid is oversampled, the tolerance can be customized through the
variable
.nf
    MAP%TOLE       [arcsec    ] Tolerance for X and Y increments (/NOGRID mode)
.fi

It is advised to avoid changing the following more technical
parameters. However those parameters are tunable through
.nf
    MAP%COL[2]     [integer   ] Range of columns to grid
    MAP%WCOL       [integer   ] Column of weights
    MAP%CTYPE      [integer   ] Convolution kernel type
    MAP%SUPPORT[2] [arcsec    ] Convolution kernel support size
.fi

For ease of use, a sensible value of each gridding parameter will
automatically be computed from the context if the value of the
corresponding MAP structure component is set to its default value,
i.e. zero value and empty string. The only exception is the projection
definition position (changing them requires in addition to set
MAP%SHIFT to YES).
.\"--------------------------------------------------------------------
.ti -4
2 MEMORY
.ti +4
MAP_\XY__MAP: memory and efficiency

All the considerations below about memory consumption and file access
efficiency are described in details in the document
"class-gridding.pdf" in the CLASS documentation.

XY__MAP relies on the Sic logical VOLATILE__MEMORY as an upper limit
for its temporary memory comsuption. The current value of
VOLATILE__MEMORY can be checked and modified as follows:
.nf
  LAS> sic log volatile__memory        ! Current value
  volatile__memory = 90%
  LAS> sic log volatile__memory 50%    ! % of total RAM
  LAS> sic log volatile__memory 512MB  ! Explicit size
  LAS> sic log volatile__memory 4GB    !
.fi
90% is a correct value if you are not sharing the resources with
several people, or if you are not running other memory consuming
software at the same time.

If the problem (input table and output cube) fits in memory, the
context is ideal: XY__MAP will process all the channels in a single
run. This is the most efficient from a file access point of view. This
means that you should set VOLATILE__MEMORY as large as possible.

If the problem does not fit in memory, the good point is that XY__MAP
is still able to process the data. However, this implies processing
the channels by slices (intermediate smaller velocity ranges).

When slicing is enabled, the default ordering of the table is not
ideal, and each slice implies traversing the whole input table
(knowing that disk accesses are usually slow). If you want to avoid
this, it may be worth producing in advance a transposed ".bat" table
with the command:
.nf
  LAS> TRANSPOSE mytable.tab mytable.bat 21
.fi
This transposition takes also time, but the overall time will be
smaller than letting XY__MAP dealing with a ".tab" table. On the other
hand, this duplicates the table data on disk, and the .bat table must
be regenerated each time .tab table is updated.

Also when slicing is enabled, the default LMV order for the cube is
ideal. Trying to produce directly a VLM cube (/TYPE VLM) is still
possible to some point, but this enlarges the memory consumption (one
more buffer) and increases the number of slices and the processing
time. Prefer LMV order if possible.
.\"====================================================================
.ti -4
1 ENDOFHELP
