.ec _
.ll 80
.ad b
.in 4
.ti -4
1 Language
.nf
COMBINE        : Combine Images with automatic resampling
EXPLORE        : Make a plot of spectra around a 2-D map
KEPLER         : Optimal line detection for Keplerian disk
SELFCAL        : Perform a self calibration
SPECTRAL__CLEAN : Multi-Spectral Spatial Deconvolution
UV__DETECT      : UV plane matched filter detection tool
.fi
 
.!==========================================================
.ti -4
1 COMBINE
.ti +4
[BUNDLES_\]COMBINE OutCube CODE In1 In2 [Off] [/FACTOR A1 A2]
  [/THRESHOLD T1 T2] [/BLANKING Bval] [/RELATIVE]
  
  or
  
[BUNDLES_\]COMBINE OutCube = [A1*]In1 Oper [A2*]In2 [Off]
  [/THRESHOLD T1 T2] [/BLANKING Bval] [/RELATIVE]
  
This is a superset of the MAP__COMBINE command, that automatically 
resamples and reproject the In1 and/or In2 data sets so that they match
spatially (according to In1, in Absolute positions or only
in Offsets if /RELATIVE is preseent) and spectrally (when both are data cubes). 

  See HELP MAP__COMBINE for details on the combination codes,
factors, thresholds and blanking. In the second "natural" form, Oper
can be any of the recognized values for CODE, or the classical operators
+, -, * and | (the / would conflict with the option separator).

Cube, In1 and In2 are names of files or SIC Image variables, depending
on whether a dot (.) is present in them or not.

.ti -4
2 CODE
.ti +4
[BUNDLES_\]COMBINE OutCube CODE In1 In2 [Off] [/FACTOR A1 A2]
  [/THRESHOLD T1 T2] [/BLANKING Bval]

  CODE is the operation code. Allowed values are
.nf
ADD      or PLUS    OutCube = A1*In1 + A2*In2 + Off 
SUBTRACT or MINUS   OutCube = A1*In1 - A2*In2 + Off  
DIVIDE   or OVER    OutCube = A1*In1 / A2*In2 + Off    
MULTIPLY or TIMES   OutCube = A1*In1 * A2*In2 + Off    
OPACITY             OutCube = -Log( A1*In1 / A2*In2 + Off)  
INDEX               OutCube = Log( A1*In1 / A2*In2) / Log(Nu1/Nu2)  
.fi  
where Nu1 is the Frequency of In1, and Nu2 that of In2.
Off is 0 if not specified.
  
.ti -4
2 /BLANKING
.ti +4
[BUNDLES_\]COMBINE OutCube CODE In1 In2 [/FACTOR A1 A2]
  [/THRESHOLD T1 T2] /BLANKING Bval

Specify the Blanking value to be used in the OutCube. If not
specified, the Blanking from In1 is used instead, and
that of In2 if In1 has no Blanking.

.ti -4
2 /FACTOR 
.ti +4
[BUNDLES_\]COMBINE OutCube CODE In1 In2 /FACTOR A1 A2
  [/THRESHOLD T1 T2] [/BLANKING Bval]

Specify the factors to apply to In1 and In2. Default is 1.0

.ti -4
2 /THRESHOLD 
.ti +4
[BUNDLES_\]COMBINE OutCube CODE In1 In2 [/FACTOR A1 A2]
  /THRESHOLD T1 T2 [/BLANKING Bval]

Specify the thresholds above which the computation is
valid for In1 and In2.  For pixels below this threshold,
the OutCube is blanked.

Default is no threshold (-huge(0.)). 

.ti -4
2 /RELATIVE
.ti +4
[BUNDLES_\]COMBINE OutCube CODE In1 In2 /FACTOR A1 A2
  [/THRESHOLD T1 T2] [/BLANKING Bval] /RELATIVE
  
  Ignore absolute positions when reprojecting the In2
data set on the In1 grid: only consider offsets.

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

.ti -4
1 KEPLER
.ti +4
[BUNDLES_\]KEPLER [?|DataCube|INIT|SHOW [Arg]] [/MASK File Threshold] 
  [/RESET [Script]  [/VSYSTEM Value]  [/VELOCITY R function(R)]
  [/HFS File [Opacity]] 

Re-align spectra from a rotating thin disk according to the projected
rotation velocity at any point in the disk, and computes the
combined integrated spectrum and brightness radial distribution. 
The projection assumes a thin disk (no flaring). By default,
the disk is assumed to be in Keplerian rotation.

The command is controlled by a set of KEPLER__* variables, whose
values can be verified by KEPLER ?  and modified by the user.
In addition to the built-in KEPLER__* variables, KEPLER__RMAX
indicates the radius

DataCube is the name of the data cube to be used. It can a SIC 3-D
variable or the name of a GILDAS (or FITS) data file. The default is
CLEAN.

.ti -4
2 INIT
.ti +4
  KEPLER INIT
  
Declare and Initialize all KEPLER related variables. This may be needed
to specify some of them before further use of the KEPLER command.

.ti -4 
2 SHOW
.ti +4
  KEPLER SHOW Name|? [/HFS File.hfs [Opacity]]
.br
or
.ti +4
  SHOW KEPLER Name|? 
  
  KEPLER SHOW ? 
will list the control parameters of command KEPLER SHOW.

  Command KEPLER SHOW Name (where KEPLER__Name is any of the result
variable names, i.e. Name can be PV, PROFILE, SPECTRUM, or VELO) 
can be used to graphically display the results.
KEPLER SHOW ALL will display a combined plot.

  KEPLER SHOW SPECTRUM and KEPLER SHOW ALL also perform a Gaussian fit into
the integrated line profile to derive the integrated flux, the disk
systemic velocity (if the option /VDISK was not present) and the line
width.  

.ti -4
2 /HFS
.ti +4
  KEPLER SHOW Name /HFS File.hfs [Opacity]
   
  Use an Hyperfine structure file, described in File.hfs to fit the
velocity re-aligned, integrated spectrum.  The corresponding hyperfine
structure is stored in SIC structure HFS%. The optional argument Opacity
can be used to specify the total opacity (sum over the hyperfine components),
the default being 0.1.  If Opacity is negative, the opacity
is then adjusted by the profile fitting procedure, using -Opacity 
as starting value.
 
  Fit results are available in SIC structure G__%...

.ti -4
2 /MASK
.ti +4
[BUNDLES_\]KEPLER /MASK [File [Threshold]] [/VSYSTEM Value]  [/VELOCITY R function(R)] 
  
  (Experimental)
  
  Generate an approximate spatial mask for further use, e.g. in CLEAN
or other masking operations. The brightness is assumed to decrease
with radius, and a local line width of 0.3 km/s is assumed to
derive the channel-dependent mask. Convolution by the current
Clean beam is performed. 

  If a File argument is present, the
resulting mask data cube is stored in File (with default extension
.msk); if not it is available in the current MASK internal buffer.

  If present, Threshold (in range [0,1]) indicates that pixels below 
the apparent peak brightness times the Threshold should be out of the mask
(i.e. have a value 0), the others in the mask (a value 1).

  If Threshold is not present, the mask values are just taken "as is",
without being re-mapped to a 0,1 mask. A simple SIC formula can be used
to convert them to a 0,1 mask later.

.ti -4
2 /RESET
.ti +4
  KEPLER /RESET [Script]

Deletes the result variables (see HELP KEPLER Results) and, if present,
executes the specified Script file that can contain any command to
reset the KEPLER__... input variables.

.ti -4
2 /VELOCITY
.ti +4
[BUNDLES_\]KEPLER [/VSYSTEM Value]  /VELOCITY R Function(R)

  Use the functional form specified by Function(R) for the rotation
velocity as a function of Radius. The default is the Keplerian law
KEPLER__VMASS*sqrt(R/100).

  Note: This can allow to use the KEPLER command to handle
rotation curves for galaxies, for example. However, the choice
of radial units is not obvious in this case. It can be made simple
by setting the "distance" KEPLER__DIST to 1 pc, so that the radii
R are then just in arcsecond. 

.ti -4
2 /VSYSTEM
.ti +4
  KEPLER [DataCube] /VSYSTEM [Value] [/VELOCITY R Function(R)]
  
Specify that radial profile should be computed at velocity KEPLER__VDISK
(and optionally reset KEPLER__VDISK = Value]. No fit for the disk velocity
is performed by KEPLER SHOW PROFILE after that.

.ti -4
2 /WIDGET
.ti +4

  KEPLER /WIDGET
  
Activate the Widget to control KEPLER command variables and actions.
Still under development, so all functions may not be controlled
in this way.
, e.g. no HFS mode, no velocity function
control yet.

.ti -4
2 Variables:
.ti +4

  Most input variables are pre-defined by the code. The exception
is KEPLER__RMAX, which can be defined by the user but has a
default value derived from KEPLER__ROUT otherwise.

.so kepler-help-variables.nroff-so

.!======================================================================  
.ti -4
1 SELFCAL

.so imager-help-selfcal.nroff-so
 

.!======================================================================  
.ti -4
1 SPECTRAL__CLEAN
.ti +4
[BUNDLES_\]SPECTRAL__CLEAN MODE [Control ]

  Perform a Clean with different spectral scales.

   MODE can be
.nf
     FFT       Clean the Fourier Transform of the spectra
     WAVE      Clean a Wavelet Transform of the spectra
     DUAL Ns   Clean at two different spectral resolutions
     MULTI Ns  Clean at two (or more) spectral resolutions.
.fi
Instead of Cleaning separately individual channels, SPECTRAL__CLEAN
cleans either Spectral Transform of the data cube (along the velocity
axis), and performs the
inverse transformation to restore the channel-based Clean components.

The SPECTRAL__CLEAN method can improve deconvolution of spectrally 
well resolved faint line wings, yielding more accurate 
integrated line fluxes, at the cost of some extra computations.
However, SPECTRAL__CLEAN can be hampered by strong velocity gradient, 
that require supports that differ widely among channels. 


Standard CLEAN control parameters apply. However the METHOD
must allow retrieving Clean Componentes: MRC is thus excluded.
SPECTRAL__CLEAN can also work on Mosaics.


.ti -4 
2 DUAL
.ti +4
  [BUNDLES_\]SPECTRAL__CLEAN DUAL NSmooth

In DUAL mode, SPECTRAL__CLEAN cleans a (spectrally) smoothed version 
of the data cube, and the difference between this smooth version
and the original ones. The two Clean component tables are then
merged to restore the final image using UV__RESTORE.

NSmooth is the number of channels being smoothed together.

The DUAL methods involves Cleaning two data cubes, so is a somewhat slower than 
a simple CLEAN.  SPCLEAN%MEMORY indicates whether intermediate results are
kept in memory (faster) or on temporary files (slower, but allowing
to work on larger files).

Mode MULTI should in general be preferred, but does not include
the final UV__RESTORE.

.ti -4
2 FFT
.ti +4
  [BUNDLES_\]SPECTRAL__CLEAN FFT

Clean the Fourier Transform along the spectral axis of the DIRTY cube,
and transform back the Clean components to retrieve the per-channel
Clean components. The final Clean image is produced using UV__RESTORE.

The usual Clean convergence parameters apply, although CLEAN__NKEEP 
may need small adjustment because of the non-positive nature of the signal.

The Fourier Transform leads to a Complex valued data set, whose 
Hermiticity is not considered. Real and Imaginary parts are 
cleaned separately, so the method is about twice slower than
a standard Clean.
 
.ti -4
2 MULTI
.ti +4
[BUNDLES_\]SPECTRAL__CLEAN MULTI  Ns1 [Ns2 ...]

Clean a (spectrally) smoothed version of the data cube,
then start from this result to continue Cleaning with the original
spectral resolution. 

To be implemented: the method can be generalized to more than 1 smoothing
scale, by performing the smoothing in descending order (Ns1 > Ns2 > ... > 1).
This may allow to catch signals that have widely different widths. 

.ti -4
2 WAVE
.ti +4
[BUNDLES_\]SPECTRAL__CLEAN WAVE

Clean a Wavelet Transform along the spectral axis of the DIRTY cube,
and transform back the Clean components to retrieve the per-channel
Clean components. The final Clean image is produced using UV__RESTORE.

The noise level is not the same for the wavelet components of the
data cube: this is taken into account by the method to Clean each
wavelet image plane to its proper noise level.

Apart for the time required by the Wavelet transform, the method 
has a comparable speed to a standard Clean.

.!======================================================================
.ti -4
1 UV__DETECT
.ti +4
[BUNDLES_\]UV__DETECT [Result] [/FILE UVData ImageData]

.ti +4
[BUNDLES_\]UV__DETECT [Result] 

  Apply a matched filter defined by the CLEAN image to the current
UV data and save results as above. It is recommended that the
continuum emission has been removed before, e.g. using UV__BASELINE.

Result.uvt will be a pseudo UV table with only the (0,0) visibility,
which can be viewed by UV__PREVIEW.

Result.dat is a column data file, useable in GreG by command COLUMN.
Column 1 is the velocity, 2 the frequency, 3 the filter intensity.

The default for argument Result is gag__scratch:detect. 
.ti -4 
2 /FILE
.ti +4
[BUNDLES_\]UV__DETECT [Result] /FILE UVData[.uvt] ImageData[.lmv-clean]

  Apply a matched filter defined by the image model available in 
file ImageData (default extension .lmv-clean) to the UV data set 
available in file UVData (default extension .uvt), and save
the filtered result into files Result.uvt and Result.dat. Continuum
emission is automatically removed using UV__BASELINE, with line windows
defined by UV__PREVIEW. 

  If argument Result is not present, the intermediate files are stored in
  gag__scratch::detect.uvt and gag__scratch:detect.dat
  
.ti -4
2 Algorithm
.ti +4

  The UV__DETECT algorithm is basically that described by Loomis et al
2018  (2018AJ....155..182L, see https://arxiv.org/pdf/1803.04987.pdf). 
Here, instead of being implemented as a Python / CASA script, it
is coded in Fortran and embedded into IMAGER. UV__DETECT calls an 
imager script that reads the data set, computes a UV__MODEL from
the ImageData using the UV coverage found in the UV data set, resamples
this UV__MODEL at the same velocity resolution than the UV data, and
ultimately calls command UV__CORRELATE to apply the UV plane filter.

  As described in the original paper, the UV data set and source model
available in ImageModel must have the same centering. The ImageModel
must also cover a sufficient width around its specified source velocity.

  The command will complain if the smoothing kernel described by the
ImageModel is insufficient. 
  
.ti -4
1 ENDOFHELP


