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

.nf
DENSITY     : Compute a 2D density of points from 2 columns
FITS        : Convert between FITS files and Gildas images
HEADER      : List the header of a Gildas image
RUN Task    : Activate a GILDAS task
SPY [Task]  : Look at current status of detached Tasks
SUBMIT Task : Submit a GILDAS Task in batch queue GILDAS__BATCH
TRANSPOSE   : Transpose data cubes or SIC Variables
.fi
.\"====================================================================
.ti -4
1 FITS
.ti +4
[VECTOR_\]FITS_ FitsFile
.ti +4
[VECTOR_\]FITS_ FitsFile_ _ TO_ _ GildasFile [/STYLE Style] [/HDU
Number] [/BLC Position...] [/TRC Position...] [/OVERWRITE]
.ti +4
[VECTOR_\]FITS_ FitsFile_ FROM GildasFile [/STYLE Style] [/BITS Nbit]
[/OVERWRITE]

With a single FITS file name as argument, give a summary of all HDUs
found in the file. With more arguments and options, convert between
FITS files and Gildas images or tables.

With the option /OVERWRITE, the command will silently overwrite the
output file if it already exists.
.\"--------------------------------------------------------------------
.ti -4
2 FROM
.ti +4
[VECTOR_\]FITS OutputFile.fits FROM InputFile.gdf [/STYLE Style] [/BITS Nbit]

Create a FITS file from a Gildas image or table. The layout of the
FITS file depends on the specified "Style", although default styles
will be used depending on the Gildas image (e.g. UVFITS is used for UV
Tables, STANDARD is used for images).

The number of bits is controlled by "Nbit". It defaults to -32 for
images, and +16 for UV data. See subtopic for details.

Options /BLC and /TRC are not available in this direction.
.\"--------------------------------------------------------------------
.ti -4
2 TO
.ti +4
[VECTOR_\]FITS InputFile.fits TO GildasFile.gdf [/STYLE Style]
[/HDU Number] [/BLC Min1 ... MinN] [/TRC Max1 ... MaxN]

Convert the InputFile.fits FITS file into a Gildas image in
GildasFile.gdf, using the appropriate "Style". A specific HDU can
be specified instead of the Primary FITS header (default is 1,
i.e. Primary).

A subset of the input file data can be extracted by specifying the
bottom left corner (/BLC) and the top right corner (/TRC)
coordinates. For example
.nf
  FITS ... /BLC 10 100 /TRC 20 200
.fi
will extract the range [10:20] in the first dimension, and [100:200]
in the second dimension. Dimensions omitted default to 0, which stands
for the largest possible corner position in the corresponding
direction.
.\"--------------------------------------------------------------------
.ti -4
2 /BITS
.ti +4
[VECTOR_\]FITS OutputFile.fits FROM InputFile.gdf /BITS Nbit

The number of bits offers two controls: the data size and the encoding
scheme. This value will be found in the resulting header under the
card BITPIX.

.in +4
.ti -4
Encoding scheme:
.br
It is controled by the Nbit sign.
.br
Positive sign means indexed encoding: the values are scaled as
integers distributed among the 2**abs(Nbit) values. The forward and
back-conversion from actual values to indexed values are based on the
data extrema. Beware they must be up-to-date in the GDF header before
converting a BITPIX>0 FITS (see command V_\HEADER /EXTREMA)! Blank
values are identified as the last integer of the indexed scale.
.br
Negative sign means the actual values are saved "as is" (IEEE floating
point format). Blank values are saved as IEEE NaN.
.ti -4
Data size:
.br
It is controled by the Nbit absolute value: 16, 32, or 64 will consume
respectively 2, 4 and 8 bytes per value, with a direct impact of the
file size.
.in -4

Nbits=+16 is worth only if the data dynamic (range of values) is low,
otherwise value precision loss will happen (2**16 values are not
enough to cover properly a large range of values). In the other cases,
Nbit<0 is more modern and should be prefered. The command supports
Nbits +16, +32, -32, -64.
.\"--------------------------------------------------------------------
.ti -4
2 /STYLE
.ti +4
[VECTOR_\]FITS ... /STYLE Name

From FITS to GILDAS, the command automatically chooses between an
IMAGE FITS (STANDARD style) and a UVFITS (UVFITS style). /STYLE option
can be used to customize the UVFITS import:
.in +8
.ti -4
STANDARD
.br
for IMAGE FITS (images, cubes,...),
.ti -4
UVFITS
.br
for UV FITS,
.ti -4
CASA__UVFITS
.br
same as UVFITS, but keep all Stokes parameters if relevant.
.in -8

From GILDAS to FITS, support styles are:
.in +8
.ti -4
STANDARD
.br
automatic choice between an IMAGE FITS (image, cube,...) and
regular UVFITS for UV data,
.ti -4
UVFITS
.br
default for UV data,
.ti -4
CASA__UVFITS
.br
same as AIPSFITS,
.ti -4
AIPSFITS
.br
enables writing the antenna table extension, a 7th "IF" axis, and
proper velocity description,
.ti -4
SORTED__AIPSFITS: same as AIPSFITS, with time-sorting of the
visibilities enabled.
.in -8
.\"====================================================================
.ti -4
1 HEADER
.ti +4
[VECTOR_\]HEADER GildasImage|VarName [/EXTREMA] [/TELESCOPE Args]

List the header of the GildasImage file or VarName variable.

The /EXTREMA option computes (or recomputes) and updates the extrema
section in the header of the GildasImage file (variables are not
supported).

The /TELESCOPE option creates or updates the telescope section. See
subtopic for details.
.\"--------------------------------------------------------------------
.ti -4
2 /TELESCOPE
.ti +4
[VECTOR_\]HEADER GildasImage /TELESCOPE [+-]Tel1 ... [+-]TelN

This option adds (leading +) or removes (leading -) one or more
telescope from the telescope section. If the + or - character is
omitted, + is assumed.

For example:
.nf
  SIC> HEADER myfile.gdf /TELESCOPE 30M
.fi
adds the 30M to the telescope section.
.nf
  SIC> HEADER myfile.gdf /TELESCOPE -ALMA +ACA
.fi
removes the ALMA telescope and adds ACA.

It is not an error to add a telescope already present, and it is not
error to remove a telescope already absent.

Only image file (on disk) are supported, not image variables.
.\"====================================================================
.ti -4
1 RUN
.ti +4
[VECTOR_\]RUN TaskName [Parameter__File] [/EDIT] [/NOWINDOW] [/WINDOW]

Execute a GILDAS task as a detached process.

See also:
.ti +2
HELP TASK for a summary of all available tasks.
.ti +2
HELP TASK GroupName for a summary of tasks in a group.
.ti +2
HELP RUN TaskName for details on a specific task.

Input file (*.init):
.in +2
The input parameters are read from the file Parameter__File. It is a
SIC procedure with commands from the TASK_\ language. The default name
of the parameter file is TaskName.init in the current working
directory. If it does not exists yet, a template duplicated from the
GAG__TASK: location is used. If this template file does not exist, it
may be that the Task you want to run does not exist either, or is not
yet debugged at all.

There are 3 ways to set up the input file:
.in +6
.ti -6
-_ Window mode: if the variable RUN__WINDOW is YES (default on
X-Window systems), or if the option /WINDOW is specified, a panel
appears to enter all parameters. Help if available by clicking on the
prompt string for each parameter, or on the HELP button. Once all
parameters have been adequately specified, the task can be activated
by clicking OK, or aborted by clicking ABORT.
.ti -6
-_ Editor mode: if the option /EDIT is specified, your favorite text
editor (see SIC EDIT) is invoked to edit the parameter file.
.ti -6
-_ No window mode: if the variable RUN__WINDOW is NO, or if the option
/NOWINDOW is specified, you won't be asked to edit the parameter
file. This is useful for non-interactive data processing. This assumes
you have created the parameter file previously, e.g. "by hand" or from
a previous call.
.in -6

Once the parameter file has been prepared in Edit-mode or Window-mode,
the RUN command will prompt you for all missing parameters in the .init
file.
.in -2

Parameter file (*.par):
.in +2
A temporary parameter file derived from the init file is created by
the RUN command in the GAG__SCRATCH: directory. It may be deleted
after Task execution. See also HELP SPY.
.br
At this stage a second SIC procedure is executed before task
submission to check the validity of input parameters. If any parameter
is invalid, an error is returned and the Task not submitted.
.in -2

Log file:
.in +2
The output messages of the task are logged in the file
GAG__LOG:TaskName.gildas. The Sic variable SIC%TEE controls wheter
the messages should be printed in real time (YES) or after the task
execution (NO). Default is NO. Beware the 'tee' program does not
always propagate task execution errors (this behavior is
system-dependent), which means the command flow may continue even if a
task fails, resulting in later troubles.
.in -2

Task location:
.in +2
If no directory is specified in the task name, the task is assumed to
be in the GILDAS__LOCAL: (if defined). Else it is searched in
TASK#DIR: default locations.
.in -2

Asynchronous execution:
.in +2
The task execution may be synchronous (the main program waiting for
task completion) or asynchronous (control returns to the main program
immediately). Note that an error status issued by the task does not
stop the main program in the case of asynchronous execution. If the
task terminates before you exit from the activating program, a
termination message will be typed on the terminal, giving the
termination status.
.in -2

Remote execution:
.in +2
Task may execute on a remote node rather than on the local machine.
The node name is controlled by logical name GILDAS__NODE. If
GILDAS__NODE = LOCAL, local execution is performed. If not,
GILDAS__NODE must be the node name of the computer on which execution
will be performed. No synchronisation is offered for remote execution.
.in -2
.\"====================================================================
.ti -4
1 SPY
.ti +4
[VECTOR_\]SPY [Task__Name]

Displays the status of all active GILDAS tasks, or lists the last
output from the specified task.
.\"====================================================================
.ti -4
1 SUBMIT
.ti +4
[VECTOR_\]SUBMIT Task__Name [Parameter__File] [/EDIT] [/NOWINDOW] [/WINDOW]

The SUBMIT command is similar to the RUN command, except that the Task
is submitted to a batch queue (named GILDAS__BATCH) instead of being
executed as a detached process. See RUN command for details.
.\"====================================================================
.ti -4
1 TRANSPOSE
.ti +4
[VECTOR_\]TRANSPOSE Input Output Order

Perform tranposition of disk data files (GDF or FITS) or SIC variables.

.in +4
.ti -4
Disk data files:

GDF or FITS files storing tables or N-dimensional cubes are transposed
to GDF files according to the transposition order specified by Order
(21, 312, 213, etc...). For example:
.ti +4
VECTOR_\TRANSPOSE TEST.VLM TEST.LMV 231
.br
The transposition takes place in RAM memory if the sic logical
SPACE__GILDAS (in MegaBytes unit) is big enough, else it takes place
on disk with more computation and disk access costs.

.ti -4
SIC variables:

For example
.ti +4
DEFINE REAL A[10,2] B[2,10]
.ti +4
VECTOR_\TRANSPOSE A B 21
.br
will transpose the A SIC variable to the B SIC variable. SIC variables
must be of the same type. If A and B are IMAGE variables, the header 
is also transposed accordingly. 
.in -4
.\"====================================================================
.ti -4
1 DENSITY
.ti +4
VECTOR_\DENSITY Xcol Ycol InputTable [OutName Npixel] 
  [/PERCENT Percent]

  Computes a 2-D image (OutName.gdf) holding the density of points 
from 2 columns (specified by the integers Xcol and Ycol)  of the 
table indicated by InputTable (default extension .tab).  Npixel
is the number of pixels along each axis.

Points that fall in pixels where the density is below a the given 
percentage of its maximum are kept in a separate table, names
OutName.tab. These two results can be used to nice contouting
and display of a distribution of points. This facility is
actually used by the ESHOW command. 

  OutName, Npixel and Percent are remanent (they are preserved
across invocations if not re-specified).

.ti -4
2 /PERCENT
.ti +4
VECTOR_\DENSITY Xcol Ycol InputTable [OutName Npixel] 
  /PERCENT Percent

  Indicate under which thresholed (in %) the individual data points
should be kept. Default at start is 30 %. 


.in -4
.\"====================================================================
.ti -4
1 ENDOFHELP
