[ Basic Info | User Guide ]

Basic Information on pgflag


Task: pgflag
Purpose: displays waterfall plots of uv data and allows flagging
Categories: flagging

      PGFLAG is a MIRIAD task that allows interactive baseline
      editing of a UV data set. It is much like the MIRIAD task
      TVFLAG, but it uses the PGPLOT display devices instead of
      of the TV devices, which should make it more accessible.
 
      When this program is run, the first selectable baseline is
      displayed as a greyscale waterfall plot. The x-axis is
      labelled as channel number (increasing to the right), while
      the y-axis represents time (later is toward the top of the
      plot). The colour intensity represents the amplitude or phase
      (depending on the value of the keyword ``mode'') of the
      visibility. At the very right and bottom edges of the plot
      are averages of the data over all the channels and times
      respectively. Between the right-hand average and the main
      plot is a colour wedge that shows the amplitude/phase scaling.
      At the top of the plot is a box with information about the
      baseline that is being viewed, the last taken measurement,
      and a guide to the commonly required action keys.
 
      Selecting data:
      The user may edit the data by selecting a range of channels
      and times with the mouse, and then flagging or unflagging them.
      This is done by selecting two points - one with the left mouse button
      and one with the right mouse button - that bound the desired range.
      When a selection is made with either the left mouse button or
      the right mouse button, a green point will be placed on the screen
      at the selected location. If both a left mouse selection and
      a right mouse selection have been made, a green box will be displayed
      that will have the two selected points as opposite corners.
      Selecting another point with either the left mouse button or
      the right mouse button will move the appropriate corner of the box
      to form a new selection.
 
      To act upon this selection, or the plot itself, the user
      should press one of the following keys while the cursor is
      inside the main plot area:
      aAbcCdDfFgGhHjJkKlLmMnpPqrRsStTuvVwWxXzZ ,<.?;[]12=!@*
 
      Exiting PGFLAG:
        a                Abort the editing procedure and quit
                         PGFLAG immediately without applying
                         any flags.
        q                Apply any flagging that was requested
                         and then exit PGFLAG.
 
      Editing data:
        w                Apply the flagging specified by the patch
                         file.
        W                Apply the flagging specified by the patch
                         file, in reverse (ie. good <-> bad)
        b                Blow away the dust: flag all visibilities
                         with less than 3 good neighbours.
        e                Extend the flagging to all sequences in
                         time or channel with less than 20% good data.
                         Only apply this once per baseline.
        f                Flag the selected range of data on the
                         currently displayed baseline only.
        F                Flag the selected range of data on all
                         the selectable baselines.
        g                Unflag the selected range of data on the
                         currently displayed baseline only.
        G                Unflag the selected range of data on all
                         the selectable baselines.
        u                Undo the last flagging action - if the
                         last flagging action was an undo of a
                         previous flagging action, then the effect
                         will be to redo the flagging.
        1                Flag the selected range of data on all
                         baselines A-n formed with the currently
                         displayed antenna A.
        !                Unflag the selected range of data on all
                         baselines A-n formed with the currently
                         displayed antenna A.
        2                Flag the selected range of data on all
                         baselines n-B formed with the currently
                         displayed antenna B.
        @                Unflag the selected range of data on all
                         baselines n-B formed with the currently
                         displayed antenna B.
        v                Flag all visibilities that have values
                         greater than the current maximum on the
                         scale on the displayed baseline, for this
                         baseline only.
        V                Flag all visibilities that have values
                         greater than the current maximum on the
                         scale on the displayed baseline, for all
                         baselines.
        <                Flag using SumThreshold method, using
                         the parameters in flagpar
        T                Change the Threshold and other parameters
                         of the SumThreshold algorithm
        rr               Remove all current user-specified flags
                         on this baseline; r must be pressed twice
                         in a row for safety as this procedure
                         cannot be undone.
        RR               Remove all current user-specified flags
                         on all baselines; R must be pressed twice
                         in a row for safety as this procedure
                         cannot be undone.
        ?                Print some information about how many flagging
                         operations have been made so far in total
                         and on this baseline.
 
      Manipulating the selection:
        c                Extend the selection box to include all
                         the displayed channels; press it twice in a row
                         to extend to all channels.
        t                Extend the selection box to include all
                         the displayed times; press it twice in a row to
                         extend to all times.
        C                Clear the selected points.
 
      Manipulating the plot:
        z                Zoom into the selected region, ie. make
                         the selected region cover the entire plot,
                         and display green arrows on the sides of
                         the plot to indicate available scrolling
                         directions.
        Z                Unzoom to show all the available data.
        s                Unzoom to show all the available channels.
        S                Unzoom to show all the available times.
        h                Move the plot left by half the range shown
                         on the plot.
        H                Move the plot left by the range shown on the
                         plot.
        j                Move the plot down by half the range shown
                         on the plot.
        J                Move the plot down by the range shown on the
                         plot.
        k                Move the plot up by half the range shown
                         on the plot.
        K                Move the plot up by the range shown on the
                         plot.
        l                Move the plot right by half the range shown
                         on the plot.
        L                Move the plot right by the range shown on the
                         plot.
        n                Display the next selectable baseline in the
                         main plot, leaving the selection and zoom
                         as is.
        p                Display the previous selectable baseline in
                         the main plot, leaving the selection and
                         zoom as is.
        x                Subtract the average channel value from each
                         channel value in the main plot. Pressing this
                         key again adds back the average channel value
                         to each channel value. When the channel average
                         is being subtracted, the channel average box
                         at the bottom of the plot will be outlined in
                         red, otherwise it will be outlined in white.
        d                Subtract the average time value from each
                         time value in the main plot. Pressing this
                         key again adds back the average time value to
                         each time value. When the time average is being
                         subtracted, the time average box at the right
                         of the plot will be outlined in red, otherwise
                         it will be outlined in white.
        *                Subtract off a convolved version of the plot,
                         the convolution parameters are specified by
                         the flagpar parameters 2 and 3
        ,                Fiddle the amplitude scale; press this key
                         then click the left mouse button in the colour
                         wedge to set the maximum value, or the right
                         mouse button to set the minimum value.
        .                Reset the user-set colour amplitude scale.
        =                Autoscale plot from -10 to +10 times the
                         median absolute deviation
        [                Enable switch to use only the currently
                         displayed points when deciding the colour
                         amplitude scale.
        ]                Set the colour amplitude scale from the current
                         selection region.
        ;                Lock the colour amplitude scale until it is
                         reset or fiddled.
 
      Displaying information:
        m                Display information about the sample
                         underneath the cursor, including the channel
                         number (and associated frequency), the
                         time, and the amplitude (or phase depending
                         on the ``mode'' setting); all this information
                         is shown at the top left of the plot in the red
                         box.
        spacebar         Does the same thing as 'm', except it will show
                         the currently displayed value, which will be
                         different from the value displayed by 'm' if
                         the averages have been subtracted from the
                         display.
        M                Locate the sample with the maximum value on
                         the currently displayed baseline, and print
                         information about it into the controlling
                         terminal. Pressing it twice in succession will
                         make PGFLAG create a selection region of 20
                         chans and 20 times centred on this sample.
        P                Display the current selection on the secondary
                         plot device as a spectrum. This command will
                         work only if device2 is specified.
        D                Dump the current page on to the tertiary plot
                         device. This command will only work if
                         device3 is specified.
 
      Non interactive flagging:
      Using the command parameter and the flagpar parameters you can use
      pgflag in non-interactive mode. The recommended strategy is to run
      pgflag interactively, work out what flagpar parameters work best
      using the * command to see the effect of background subtraction and
      the < command to see the effects of SumThreshold flagging.
      If too much or too little was flagged, change the parameters with
      the 'T' command and undo the flagging with the 'rr' command and try
      again. Once the right parameters are found you can abort with 'a'
      and run pgflag with command set to "<" or "<be" to flag the entire
      dataset. You can use options=nodisp if you don't want to watch the
      flagging. If you do want to see what is happening, you'll want to
      specify command='.=<' or the like to scale the data for the display.
 

Key: vis
      Input visibility dataset to be flagged. No default.

Key: line
      This is the normal linetype specification. See the help on
      line for more information. The default is all channels.

Key: select
      This selects which visibilities to be used. Default is all
      visibilities. See the Users Guide for information about how
      to specify uv data selection.
      Default is all data

Key: stokes
      Select Stokes parameter(s) or polarization(s) from:
        xx, yy, xy, yx,  i, q, u, v,
        rr, ll, rl, lr
      Default is Stokes i.
      If more than one polarization is specified only the LAST one is
      displayed.
      If one 'raw' polarization is specified, only that one is flagged.
      If multiple 'raw' polarizations or one or more 'converted'
      polarizations are specified, all polarizations in the data are
      flagged.

Key: device
      PGPLOT plot device/type, which must be interactive. No default.

Key: device2
      PGPLOT plot device/type, which must be interactive. This optional
      plot device will be used to display spectra from the selected
      region, if requested.

Key: device3
      PGPLOT plot device/type, which does not need to be interactive.
      This optional plot device is the destination for the D command.

Key: mode
      Display ``amplitude'' or ``phase''. By default, ``amplitude''
      is selected. For mode=``phase'', the phase is in degrees.

Key: flagpar
      Parameters for SumThreshold flagging, dusting and extending
      (see Offringa et al,2010, MNRAS 405,155)
      1 : Threshold in estimated sigma's (estimated using the
          median absolute deviation), default 7
      2 : Convolution size for channel direction (in channels), used
          to generate a smooth background, default 1. Zero disables
          convolution in the channel direction.
      3 : Convolution size for time direction (in integrations), used
          to generate a smooth background, default 1. Zero disables
          convolution in the time direction
      4 : Number of iterations of the convolve/subtract/threshold
          operation.The threshold level decreases by a factor of two
          each iteration. Default 3
      5 : Power of two of the maximum number of points used in the
          SumThreshold operation (e.g., 5 -> 32 points). Default 5.
      6 : Dust the plot - flag points with less than flagpar(6)
          unflagged neighbours. Useful range 1-4, default 3.
      7 : Extend flags to all points which are in a time or
          channel sequence with less than flagpar(7) % good data,
          default 20. This process 'eats' away at the data from the
          flagged areas. (See Offringa et al 2012, A&A 539,A95)

Key: patch
      The name of the flagging patch file, either to write (if the
      'patch' option is specified), or to use for the 'w' or 'W'
      commands.

Key: log
      The name of a log file to which will be output the entire set
      of flagging actions, in text format.

Key: command
      Specify a series of commands for non-interactive flagging.
      E.g., '<be' will apply SumThreshold flagging followed
       by blowing away the dust and extending the flags for each baseline;
      '.=vx=v' will autoscale the data, do a clip operation, then
       subtract the channel average, autoscale and clip again before
      moving on to the next baseline. Note that '=' cannot be the first
      character of the command parameter or it will be skipped.
      There is no need to specify a 'q' in the command sequence,
      unless you want to quit before all baselines are processed.
      Default is no command.

Key: options
      Task enrichment parameters. Several can be given, separated by
      commas. Minimum match is used. Possible values are:
        patch   Generate a flagging patch file that contains all the
                flagging operations that are done by this run of
                pgflag.
        selgen  Generate a file appropriate for selecting the bad data
                (via a 'select' keyword). The output is two text files
                called 'pgflag_flag.select' (for flagging operations),
                and 'pgflag_unflag.select' (for unflagging operations).
                Unfortunately, since 'select' does not support the use
                of a 'channel' selection, this option is of limited use,
                but is supplied in case time-based selection is all that
                is required.
        nosrc   Do not cause a break in the display when the source
                changes. Normally PGFLAG puts a gap in the display
                whenever the source changes.
        noapply Do not apply the flagging.
        nodisp  Do not use the display, just use the specified command
                to flag all baselines in the dataset.
      The following options can be used to disable calibration.
        nocal   Do not apply antenna gain calibration.
        nopass  Do not apply bandpass correction.
        nopol   Do not apply polarisation leakage correction.
 
Revision: 1.34, 2021/06/02 04:45:09 UTC

Generated by miriad@atnf.csiro.au on 02 Jun 2021