AIPS NRAO AIPS HELP file for UFLAG in 31DEC18



As of Tue Sep 25 8:39:41 2018


UFLAG: Plots and edits data from a uv data base using TV

INPUTS

INNAME                             Input UV file name (name)
INCLASS                            Input UV file name (class)
INSEQ             0.0     9999.0   Input UV file name (seq. #)
INDISK                             Input UV file disk unit #
SOURCES                            Sources to plot, ' '=>all.
ISCALIB                            > 0 => treat as point source
QUAL            -10.0              Qualifier -1=>all
CALCODE                            Calibrator code '    '=>all
STOKES                             Stokes type to select.
SELBAND                            Bandwidth to select (kHz)
SELFREQ                            Frequency to select (MHz)
FREQID                             Freq. ID to select.
TIMERANG                           Time range to select
ANTENNAS                           Antennas to plot
BASELINE                           Baselines with ANTENNAS
UVRANGE                            UV range in kilolambda.
SUBARRAY          0.0     1000.0   Subarray, 0 => all
BCHAN             0.0     4096.0   1st spectral channel #
ECHAN             0.0     4096.0   Last spectral channel #
NCHAV             0.0     4096.0   # of channels to average
CHINC             0.0     4096.0   Increment in channel #
BIF                                Low IF number to plot
EIF                                Highest IF number to plot
DOCALIB          -1.0      101.0   > 0 calibrate data & weights
                                   > 99 do NOT calibrate weights
GAINUSE                            CAL (CL or SN) table to apply
DOPOL            -1.0       10.0   If >0 correct polarization.
PDVER                              PD table to apply (DOPOL>0)
BLVER                              BL table to apply.
FLAGVER                            Flag table version
OUTFGVER          0.0              Output FG table version
DOBAND           -1.0       10.0   If >0 apply bandpass cal.
                                   Method used depends on value
                                   of DOBAND (see HELP file).
BPVER                              Bandpass table version
SMOOTH                             Smoothing function. See
                                   HELP SMOOTH for details.
CELLSIZE      1.E-12               (X,Y) size of image cell
                                   in asec
IMSIZE                             IMAGR image size in pixels
DOWEIGHT                           >0 -> weighted sum into each
                                         cell
APARM                              (1) Factor times rms to
                                      examine cells in AUTO
                                   (2) Factor times rms to
                                      flag amplitudes in AUTO
                                   (3) Factor times rms to
                                      flag phases in AUTO
DOCENTER        -1.0        1.0    Place curvalue display at
                                   left, center, right: -1, 1, 0
DOALL          -1.0         7.0    bit 1 flag all channels
                                   bit 2 flag all IFs if 1
                                   bit 3 flag all parallel pol
                                   bit 4 do NOT flag cross-hand
                                         pol if flag parallel
PRTLEV                             > 1 -> generate lengthy flag
                                         report
                                   > 0 -> report on all pixels
                                         auto corrected
BADDISK                            Disk to avoid for scratch.

HELP SECTION

UFLAG
Type: Task
Use:  Plots data from a u,v data base, with calibration if desired, as
      a gray-scale plot on the TV gridded in u and v.  The image goes
      from -Umax to +Umax in U and from 0 to +Vmax in V (taking
      advantage of the Hermitian property of visibilities) and is kept
      in memory.  The cell size in the array is set by the cell size
      used in IMAGR when given adverbs IMSIZE and CELLSIZE.  This
      array is then displayed in whole, or in part, on the TV and
      various interactive editing options are available.  The pixels
      in the plot are, at the end, converted into flags in a new flag
      table.  Lines one pixel outside the plot, surrounding it, and a
      line at U and V value 0.0 are drawn when possible.  The plots
      are labeled when either the full image or a sub-image is
      plotted.

      During interactive editing, the image pixel coordinates, the U
      and V physical coordinates, the value of the pixel, and the
      first two baselines contributing to the pixel are plotted for
      the pixels selected by the TV cursor.  A plus sign is also shown
      if there are more than two baselines contributing.

      Details of the interactive operation of this task are given in
      the EXPLAIN file.  See also AIPS Memo 121, "Editing on a uv grid
      in AIPS", September 2016 for a more detailed description of the
      use of this task.

Adverbs:
  INNAME.....Input UV file name (name)    Standard defaults.
  INCLASS....Input UV file name (class)   Standard defaults.
  INSEQ......Input UV file name (seq. #)  0 => highest.
  INDISK.....Disk drive # of input UV file.  0 => any.
  SOURCES....List of sources to be plotted. '  '=> all; if any starts
             with a '-' then all except ANY source named.  It is best
             if only one source is selected.
  ISCALIB....> 0 => the source is a calibrator and so should have
             phases of zero and a limited range of amplitudes.  The
             AUTO FLAG VIS function flags calibrators on phase and
             both low and high amplitudes.  Non calibrators are not
             flagged on phase or on low amplitudes.
  QUAL.......Qualifier of source to be plotted. -1 => all.
  CALCODE....Calibrator code of sources to plot. ' '=> all.
  STOKES.....The desired single Stokes type of the plotted data:
               'I','Q','U','V','RR','LL', 'RL', 'LR', 'XX','YY', 'XY',
             and 'YX', are allowed depending on the Stokes present
             in the data.
  SELBAND....Bandwidth of data to be selected. If more than one IF is
             present SELBAND is the width of the first IF required.
             Units = kHz.  For data which contain multiple bandwidths or
             frequencies the task will insist that some form of
             selection be made by frequency or bandwidth.
  SELFREQ....Frequency of data to be selected. If more than one IF is
             present SELFREQ is the frequency of the first IF required.
             Units = MHz.
  FREQID.....Frequency identifier to select (you may determine which is
             applicable from the OPTYPE='SCAN' listing produced by
             LISTR). If either SELBAND or SELFREQ are set, their values
             override that of FREQID.  However, setting SELBAND and
             SELFREQ may result in an ambiguity.  In that case, the task
             will request that you use FREQID.  If all SELBAND, SELFREQ
             and FREQID are not specified (<= 0) then the task will loop
             over the frequency ID plotting all of them!
  TIMERANG...Time range of the data to be plotted. In order:
             Start day, hour, min. sec, end day, hour, min. sec.
             Days relative to reference date.
  ANTENNAS...A list of the antennas to plot.  If any number is negative
             then all antennas listed  are NOT desired and all others
             are.   All 0 => list all.
  BASELINE...Baselines are specified using BASELINE.
             Eg. for baselines 1-6,1-8, 2-6 and 2-8
             use ANTENNAS=1,2; BASELINE=6,8.
  UVRANGE....Range of projected spacings to be plotted in 1000's of
             wavelengths.  0  =>  1, 1.E10
  SUBARRAY...Subarray number to plot.        0 => all - the task will
             loop over subarray number.
  BCHAN......Beginning spectral line channel number.   0 => 1.
  ECHAN......Ending spectral line channel number.   0 => max.
  NCHAV......Number of spectral channels to average before plotting.
             0 => 1.  ECHAN will be adjusted downwards so that all
             averages will include the same number of spectral
             channels.
  CHINC......Increment in spectral line channel number.   0 => NCHAV
             Channels i through i+CHINC-1 are flagged if channel i is
             flagged.  All channels may be flagged by setting DOALL.
             CHINC is ignored if NCHAV >= ECHAN-BCHAN+1.
  BIF........First IF number to plot.              0 => 1
  EIF........Last IF number to plot.               0 => highest
  DOCALIB....If true (>0), calibrate the data using information in the
             specified Cal (CL) table for multi-source or SN table for
             single-source data.  Also calibrate the weights unless
             DOCALIB > 99 (use this for old non-physical weights).
  GAINUSE....Version number of the Cal. table to apply to the data if
             DOCALIB=1.  Refers to a CL table for multi-source data or
             an SN table for single-source.  0 => highest.
  DOPOL......If > 0 then correct data for instrumental polarization as
             represented in the AN or PD table.  This correction is
             only useful if PCAL has been run or feed polarization
             parameters have been otherwise obtained.  See HELP DOPOL
             for available correction modes: 1 is normal, 2 and 3 are
             for VLBI.  1-3 use a PD table if available; 6, 7, 8 are
             the same but use the AN (continuum solution) even if a PD
             table is present.
  PDVER......PD table to apply if PCAL was run with SPECTRAL true and
             0 < DOPOL < 6.  <= 0 => highest.
  BLVER......Version number of the baseline based calibration (BL) table
             to apply. <0 => apply no BL table, 0 => highest, if any.
  FLAGVER....Specifies the version of the flagging table to be applied.
             0 => highest numbered table.  <0 => no flagging to be
             applied.  If FLAGVER < 0, no input FG table is used or
             copied.
  OUTFGVER...Flag table version to be used on output for both single-
             and multi-source data sets.  If OUTFGVER is <= 0 or
             greater than FGmax (the previously highest FG version
             number), then a new FG table will be created for the new
             flags with version FGmax+1.  This new table will also
             contain the flags applied on input (if any) from FG
             version FLAGVER.  If OUTFGVER specifies a pre-existing FG
             version, then the input flags are not copied even if
             OUTFGVER and FLAGVER are not equal.
  DOBAND.....(multi-source) If true (>0), then correct the data for the
             shape of the antenna bandpasses using the BP table
             specified by BPVER.  The correction has five modes:
             (a) if DOBAND=1 all entries for an antenna in the table
             are averaged together before correcting the data.
             (b) if DOBAND=2 the entry nearest in time (including
             solution weights) is used to correct the data.
             (c) if DOBAND=3 the table entries are interpolated in
             time (using solution weights) and the data are then
             corrected.
             (d) if DOBAND=4 the entry nearest in time (ignoring
             solution weights) is used to correct the data.
             (e) if DOBAND=5 the table entries are interpolated in
             time (ignoring solution weights) and the data are then
             corrected.
  BPVER......(multi-source) specifies the version of the BP table to be
             applied. 0 => highest numbered table.
  SMOOTH.....Specifies the type of spectral smoothing to be applied to
             a uv database . The default is not to apply any smoothing.
             The elements of SMOOTH are as follows:
             SMOOTH(1) = type of smoothing to apply: 0 => no smoothing
               To smooth before applying bandpass calibration
                 1 => Hanning, 2 => Gaussian, 3 => Boxcar, 4 => Sinc
               To smooth after applying bandpass calibration
                 5 => Hanning, 6 => Gaussian, 7 => Boxcar, 8 => Sinc
             SMOOTH(2) = the "diameter" of the function, i.e. width
               between first nulls of Hanning triangle and sinc
               function, FWHM of Gaussian, width of Boxcar. Defaults
               (if < 0.1) are 4, 2, 2 and 3 channels for SMOOTH(1) =
               1 - 4 and 5 - 8, resp.
             SMOOTH(3) = the diameter over which the convolving
               function has value - in channels.  Defaults: 1,3,1,4
               times SMOOTH(2) used when input SMOOTH(3) < net
               SMOOTH(2).
  CELLSIZE...IMAGR (X,Y) pixel separation in asec.
  IMSIZE.....IMAGR (X,Y) The desired size of the image in pixels.
             UFLAG sets the U cell size as (3600 * 180) / (pi *
             CELLSIZE(1) * IMSIZE(1)) in wavelengths with a similar
             formula for the V cell size.  The gridded image is made a
             little bigger than the minimum to hold all values of U
             and V.
  DOWEIGHT...> 0 => use data weights when summing into cells.
  APARM......The AUTO FLAG VIS function uses a factor times the rms in
             setting value ranges to examine and to flag.  The user
             may employ APARM to set the factors.
             (1) is the factor for the examination range  0 => 3
             (2) is the factor for the amplitude flag range   0 => 3
             (3) is the factor for the phase flag range   0 => 4
             For target sources (ISCALIB <= 0), all unflagged cells
             above the mean plus APARM(1) * rms will be examined.
             Visibility amplitudes above the median plus APARM(2) *
             rms are flagged.  For calibrator sources, all unflagged
             cells more than APARM(1) * rms from the mean are
             examined.  Visibility amplitudes more than APARM(2) * rms
             aways from the median are flagged.  Visibility phases
             more than APARM(3) * rms / median (in radians) away from
             zero are flagged.
  DOCENTER...Rounding to nearest integer, if DOCENTER = -1 the
             curvalue-like display will appear at the upper left, = 1
             at the upper center, and = 0 at the upper right.
  DOALL......Bit pattern:
             = 1,3,5,7,9,11,13,15 -> flag all spectral channels in a
                     sample if any one is flagged (e.g. if you plotted
                     only one)
             = 2,3,7,11,12,15 -> flag all IFs if any 1 is flagged.
             = 4,5,6,7,12,13,14,15 -> flag both parallel polarizations
                     when flagging one (set true on Stokes I plots)
             = 8,9,10,11,12,13,14,15 -> do NOT flag all cross-hand
                     polarizations if a parallel-hand is flaggeD AND
                     do NOT flag all parallel-hand polarizations when
                     a cross-hand polarization is flagged
  PRTLEV.....> 1 => print matices showing the amount of flagging by
                    baseline and IF
             > 0 => print info about each pixel addressed by the auto
                    flag options
  BADDISK....Disk numbers to avoid for scratch files.  Scratch files
             may be created by the sorting routines if calibration or
             flagging is applied.

EXPLAIN SECTION

UFLAG:  Plots and edits data from a u,v data base.
RELATED PROGRAMS: UVPLT, EDITR, TVFLG, SPFLG

                      PURPOSE

     UFLAG is used to display, in gray-scale, visibility amplitudes
gridded in projected baseline coordinates u and v.  Since visibilities
have the Hermitian property, the full range in u, but only positive v,
are plotted.  Bad data may be visible with pixels well above (or below
in the case of calibrator sources) the neighboring pixels.  The task
constructs an image from covering the full range of u and abs (v)
using standard imaging adverbs to set the u and v cell sizes.  The
images available for viewing and editing are the averages of the
samples falling in each uv cell (pill-box convolution) of the scalar
average amplitude, the vector average amplitude, the vector average
phase, and the difference between scalar and vector average
amplitudes.  Up to 25 baseline values and visibility numbers are also
kept for each pixel as well as a complete list of the visibility
sample numbers contributing to that pixel.  The actual data being
flagged (i.e. spectral channel(s), IFs) cannot be identified during
interactive, TV-based editing functions.  However, a special data
examination function is available which shows the individual
visibilities in detail for all samples contributing to the pixel.
This function lets you specify which of those visibilities should be
flagged.  Data may be marked bad in this way and/or by marking pixels
as bad, either on a pixel-by-pixel basis or in a rectangular area.
(The "fat wiper" of the WIPER task is not offered here.)  When you
select "FLAG + EXIT", "FLAG + REPEAT", or "FLAG + SWITCH", the task
re-reads the uv file (applying the same adverbs as at the beginning)
and writes a flag table flagging all samples falling in pixels marked
as bad, all baselines listed as bad, and any specified visibilities
specified in the detailed examination routines.  The new
"FLAG + REPEAT" function does the operations of "FLAG + EXIT" but,
instead of exiting the task, it changes FLAGVER to the OUTFGVER, sets
OUTFGVER to write a new flag table, makes an entirely new image, and
then resumes the editing functions.  "FLAG + SWITCH" is like repeat
except that it also switches polarization.

     If the uv grid is too large top fit on the full TV display, the
plot will be shown on the TV with plot pixels averaged.  In this case,
you are only offered one "option" - to select a sub-image to be
displayed at full resolution.  The smoothed image and the selected
images will have plot labels displayed.

     When the image or selected sub-image is smaller than the TV (when
expanded to its maximum size), you are offered the following menu
panels.  Hit button A, B, or C to get the desired option, hit button
D to get helpful information about the option.  The left panel
includes

| ABORT         |   exits the task with no flagging saved
| FLAG + EXIT   |   stops plotting, converts flagging into FG table
                    and exits TASK
| FLAG + REPEAT |   stops plotting, converts flagging into FG table
                    and restarts task using the new flag table
| FLAG + SWITCH |   stops plotting, converts flagging into FG table
                    and restarts task using the new flag table and
                    switching the polarization
| OFF ZOOM      |   turn off any zoom magnification
| TVZOOM        |   interactive zoom magnification and center
| OFF TRANS     |   turn off any black & white enhancement
| OFF COLOR     |   turn off any pseudo-coloring
| TVTRANSF      |   black & white enhancement as in AIPS
| TVPSEUDO      |   many pseudo-colorings as in AIPS
| TVPHLAME      |   flame-like pseudo-colorings as in AIPS
| SET PIXRANGE  |   enter the range of gray-scale values to be
                    displayed for the image type being viewed
| LOAD xxxx     |   change the scaling function of grey-scale display
                    to xxxx
| VIEW yyyy     |   change the image being viewed/edited to yyyy
| VIEW ONLY     |   sets a value range to limit the pixels viewed to
                    only those in the selected range
| VIEW ALL      |   resets the intensity range allowed to all values
| FLAG PTS zzz  |   turns off/on the viewing of which pixels are
                    flagged (in the cyan graphics channel)


The image is displayed with a step wedge above.  The wedge is labeled,
from left to right, with the minimum image value, the image median
value, the image type and polarization (in parentheses), the image
mean and rms (in parentheses), and the image maximum.

The four images which may be viewed are in order VECTOR, PHASE,
SCAL-VEC, and SCALAR.  The "VIEW yyyy" command will display the next
type yyyy.  The "LOAD xxxx" command will reload the image to the TV
with the specified "xxxx" function type where the types are in order
LIN, LOG, SQRT, and LOG2.

The right panel includes

| SET WINDOW    |   interactive window setting to limit edit/display
                    area; if possible pixels will be replicated
| RESET WINDOW  |   turn off any windowing - may force you to select a
                    window before you can edit again
| FLAG POINT    |   flags plot cells one at a time on buttons A, B, C
| FLAG AREA     |   flags rectangles of cells set in the usual manner
| FLAG FAST     |   flags any cell at which the cursor is pointed
| FLAG BASELINE |   Records flagging for a pair of antennas and marks
                    cells appropriately (0 for one => all)
| UNFLAG POINT  |   unflags flagged cells one at a time with buttons
| UNFLAG AREA   |   unflags flagged cells in rectangles
| UNFLAG FAST   |   unflags any flagged cell at which cursor is
                    pointed
| UNFLAG BASEL  |   removes record of flagging for a pair of antennas
                    and unmarks cells appropriately (0 for one =>
                    all)
| EXAMINE VIS   |   displays all visibilities contributing to the
                    interactively selected pixel, allows some to be
                    flagged and the remaining cell value restored
| USER FLAG VIS |   auto-flags visibilities based on value ranges
                    entered on the terminal
| AUTO FLAG VIS |   auto-flags visibilities based on value ranges set
                    by the image statistics
| FLAG ALL      |   flags all pixels in the VIEW ONLY range
| FLAG ALL WIN  |   flags all pixels in the VIEW ONLY range in the
                    current sub-image
| UNDO FLAG ALL |   unflags a previous FLAG ALL range
| UNDO FLAG WIN |   unflags a previous FLAG ALL range but only in the
                    current sub-image


The interactive flagging (unflagging) options are of three types:
(1) The most basic flags unflagged points (unflags flagged points)
    toward which the cursor is first pointed  and then button A, B, or
    C is "pushed".  C causes an exit to the menu after flagging
    (unflagging) the point.
(2) The area type has the user set a rectangular area with the cursor,
    first setting a bottom left corner and then hitting button A to
    set the opposite corner.  Button B or C will cause all unflagged
    (flagged) points in the rectangle to be flagged (unflagged).  C
    causes an exit to the menu after flagging (unflagging) the
    points.
(3) The fast mode requires a button push to get started after which no
    further button pushes are required to flag (unflag) points.  Any
    unflagged (flagged) point selected by the cursor (with left mouse
    button down) will be flagged (unflagged).  After the first button
    hit, hit any button to exit to the menu.
In all modes, button D exits to the menu with no further flagging.

The FLAG BASELINE and UNFLAG BASEL ask you to enter 2 integers for the
two antennas in the baseline.  A 0 for one will flag all antennas to
the other one - both 0 exits.  They baseline(s) affected are recorded
in a list.  The plotted points are examined and any affected by the
baseline(s) have their attached baseline list modified to record the
flagging or unflagging.  If the plotted point has any "good" baselines
attached after this operation, it will be displayed as good (AND STILL
INCLUDE THE DATA FROM THE FLAGGED BASELINE).  Otherwise it will be
shown as flagged.  The plot is fully re-drawn after these operations.

The "VIEW ONLY" function allows you to select with the TV cursor along
the plotted step wedge the value range to be displayed at present with
all values below and above the range shown as black.  The cursor
starts at the right of the wedge (highest value) and buttons A and B
let you switch the setting of the value range between the high value
and the low value.  Button C exits the function with the specified
values, button D exits with the values not set.  When a "VIEW ONLY"
range has been specified, options "FLAG ALL" and, if a sub-image has
been displayed, "FLAG ALL WIN" will appear.  They allow you to flag
all pixels in the "VIEW ONLY" range over the full image or over only
the current sub-image.  The "VIEW ONLY" range is reset if one of these
flag options is selected or if the image being viewed is changed.
After a "VIEW ONLY" range has been flagged, options "UNDO FLAG ALL"
and, if a sub-image is displayed, "UNDO FLAG WIN" are displayed.
(Image types are handled separately in this matter.)  They will show
you all the ranges that have been flagged and, if there is more than
one, allow you to select the range you wish to unflag.  They unflag
all flagged pixels in the specified range over the full image or over
only the sub-image being viewed.

The "EXAMINE VIS" function starts an interaction where you select a
pixel by positioning the TV cursor and hitting buttons A, B, or C.
The task then rereads the visibility records involved, performs the
calibration and gridding functions, and lists all samples contributing
to the pixel.  It then asks for a sample number to flag and, if you
enter a valid number, it marks that sample and asks again for another
to flag (if there are any more).  Enter 0 to stop flagging.  If there
are remaining unflagged pixels, they are averaged and the image(s)
updated.  If there are no more, the pixel is set to empty in the
images.  All flagged visibilities are written to a flag command file
(FC table) which will be applied to the output flag (FG) table on
"FLAG + EXIT", "FLAG + REPEAT", AND "FLAG + SWITCH".

The "USER FLAG VIS" function allows some of the pixels in the current
window to be examined with visibility records that are out of range
being flagged.  This function asks for input from the terminal to
provide the range of pixel values to be examined, the minimum and
maximum acceptable visibility amplitude and phase, and whether only
flagged, only unflagged, or both pixels will be examined.  The "AUTO
FLAG VIS" sets these parameters for you and only works when viewing
SCALAR or VECTOR.  PHASE and SCALAR-VECTOR are bad ideas with
automatic parameters, but you can use USER FLAG VIS in that mode.  If
ISCALIB <= 0, they are set so that only unflagged pixels above a value
equal to the mean + 3 times the rms are examined and visiibility
amplitudes greater than the median + 3 times the rms are flagged.  If
ISCALIB > 0, they are set so that pixels below the median - 3 times
the rms and pixels above the mean + 3 times the rms are examined,
visibilities below the median - 3 times the rms and above the median +
3 times the rms in amplitude are flagged, and, when not looking at
PHASE, visibilities with phase in absolute value greater than 4 times
the rms divided by the median are flagged.  These flags go to an FC
table and are applied on the "FLAG +" commands.  The values in the
image pixels are corrected, leaving out the flagged values.  Note that
you cannot unflag a visibility once it has appeared in the FC table
except by choosing the ABORT option (or discarding the new output flag
table).  The median, mean, and rms are among the values displayed
above the step wedge image and are updated whenevr an image is
reloaded (after flagging or changing to another image or transfer
type).  These operations can be very slow if there are a lot
visibilities, so progress messages are given about every two minutes.


                     COMMENTS

BCHAN, ECHAN, NCHAV, CHINC, BIF, EIF:
     More than one frequency may be plotted from multi-channel, multi-IF
data sets.  The data will be plotted at u,v,w values corrected to the
frequency of the individual channel and IF.  This is useful in seeing
the effect of bandwidth synthesis.  IF-dependent and channel-dependent
errors may be spotted and edited in this way.  However, they may be
difficult to untangle.  Displaying a single range of channels
"averaged" may be better - NCHAV averages the data before they are
gridded (unlike IMAGR).

     Note that multiple subarrays and multiple FREQIDs may be plotted
and flagged.  Again this may be rather hard to disentangle.

SCALING :
     The plot scale is chosen by the task to encompass all of the data
included by the adverbs.  You may select the size of a pixel in the
image by specifying CELLSIZE and IMSIZE.  It is very helpful if the
image fits on the TV screen.  It is likely to be at least twice as
wide as high.


AIPS