; POSSM
;---------------------------------------------------------------
;! Task to plot total and cross-power spectra.
;# Task SPECTRAL UV
;-----------------------------------------------------------------------
;;  Copyright (C) 1995-2000, 2002-2006, 2008-2009
;;  Associated Universities, Inc. Washington DC, USA.
;;
;;  This program is free software; you can redistribute it and/or
;;  modify it under the terms of the GNU General Public License as
;;  published by the Free Software Foundation; either version 2 of
;;  the License, or (at your option) any later version.
;;
;;  This program is distributed in the hope that it will be useful,
;;  but WITHOUT ANY WARRANTY; without even the implied warranty of
;;  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;;  GNU General Public License for more details.
;;
;;  You should have received a copy of the GNU General Public
;;  License along with this program; if not, write to the Free
;;  Software Foundation, Inc., 675 Massachusetts Ave, Cambridge,
;;  MA 02139, USA.
;;
;;  Correspondence concerning AIPS should be addressed as follows:
;;         Internet email: aipsmail@nrao.edu.
;;         Postal address: AIPS Project Office
;;                         National Radio Astronomy Observatory
;;                         520 Edgemont Road
;;                         Charlottesville, VA 22903-2475 USA
;-----------------------------------------------------------------------
POSSM     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
POSSM     Task to plot total and cross-power spectra.
USERID                             User number - ignored
INNAME                             Input UV file name (name)
INCLASS                            Input UV file name (class)
INSEQ             0.0     9999.0   Input UV file name (seq. #)
INDISK            0.0        9.0   Input UV file disk unit #
SOURCES                            Source list
QUAL            -10.0              Source qualifier -1=>all
CALCODE                            Calibrator code '    '=>all
SELBAND                            Bandwidth to select (kHz)
SELFREQ                            Frequency to select (MHz)
FREQID                             Freq. ID to select.
UVRANG                             UV range to be plotted
TIMERANG                           Time range to be plotted
STOKES                             Stokes type(s) to select.
BIF               0.0      100.0   Lowest IF number 0=>all
EIF               0.0      100.0   Highest IF number 0=>all
BCHAN             0.0     2048.0   Lowest channel number 0=>all
ECHAN             0.0     2048.0   Highest channel number 0=>all
SUBARRAY          0.0     1000.0   Subarray, 0=>1
ANTENNAS                           Antennas to select
BASELINE                           Baselines with ANTENNAS
DOCALIB          -1.0      101.0   > 0 calibrate data & weights
                                   > 99 do NOT calibrate weights
GAINUSE                            CL (or SN) table to apply
DOPOL            -1.0       10.0   If >0 correct polarization.
BLVER                              BL table to apply.
FLAGVER                            Flag 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.
SHIFT                              Position shift:
                                   RA, Dec (arcsec)
                                   0 => no shift
APARM                              Control information:
                                   1: = 0 => scalar average
                                      > 0 => vector average
                                   2: = 0 => self-scale
                                      > 0 => fixed scale
                                       (use APARM(3-6))
                                   3: min. amplitude
                                   4: max. amplitude
                                   5: min. phase (degrees)
                                   6: max. phase
                                   7: x-axis labelling
                                      = 0 = > in channels.
                                      = 1 = > in Hz (or secs
                                          if corr. fn)
                                      = 2 = > in m/s
                                   8: = 0 => plot cross power
                                      = 1 => plot total power
                                      = 2 => plot BP table
                                      = 3 => plot ACF
                                      = 4 => plot XCF
                                      = 5 => plot BD table
                                   9: > 0 => plot several IF's
                                      and/or polarizations
                                      together as though one
                                      long spectrum (see HELP)
                                   10: > 0 => reverse direction
                                      of plotted spectrum, so
                                      velocity increases to
                                      right.
CODETYPE                           'A&P ', 'AMP ', 'PHAS',
                                   'R&I ', 'REAL', 'IMAG'
                                   'LA&P', 'LAMP'
                                   other => 'A&P '
POLPLOT                            Option to display various
                                   combinations of polzns to
                                   plot: 'RL/RR', 'RL/LL',
                                   'LR/RR', 'LR/LL', 'RR/LL'
                                   'LL/RR'; other = don't use
                                   this option.
SOLINT                             If SOLINT > 0 then it enables
                                   the user to make multiple
                                   plots per pass of POSSM.
                                   It defines the averaging time
                                   for each individual plot.
                                   Task will start at TIMERANG
                                   and make a plot for every
                                   SOLINT minutes. If SOLINT
                                   = -1 will do the same but
                                   will do scan averages if NX
                                   table is present.
NPLOTS            0.0       9.0    Number of plots per page
BPARM                              More control information:
                                   1: If = 1 divide by 'channel
                                      0' before plotting data.
                                      0 => do not divide.
                                   2: Start chn. of 'channel 0'
                                      (0 => determined by POSSM)
                                   3: Stop chn. of 'channel 0'
                                      (0 => determined by POSSM)
                                   4: ignore spectrum when ampl.
                                      channel 0 < BPARM(4) Jy
                                   5-9: unused
                                   10: =1 => don't write header
                                   info when writing to outfile
                                   useful for appending several
                                   spectra into a single outfile
                                   [see EXPLAIN POSSM]
OUTTEXT
                                   Filename in which to write
                                   spectrum. Default = ' ' =
                                   do not write spectrum. The
                                   file is written only if
                                   NPLOTS = 0
LTYPE         -10.0        10.0    Type of labeling: 1 border,
                                   2 no ticks, 3 - 6 standard,
                                   7 - 10 only tick labels
                                   <0 -> no date/time
FACTOR                             Scale plus signs by FACTOR
XYRATIO           0.0              XY plot ratio: 0 -> 1.636
BADDISK           0.0     9999.0   Disks to avoid for scratch
DOTV           -1.0         1.0    > 0 Do plot on the TV, else
                                   make a plot file
GRCHAN          0.0         8.0    Graphics channel 0 => 1.
----------------------------------------------------------------
POSSM
Type:  Task
Use:   To create a 'PL' extension file containing a spectrum generated
       by either scalar or vector averaging a data set.  The task can
       plot cross-power spectra with appropriate averaging, or
       total-power spectra if they exist in your database.  It can
       also plot the BP spectra generated by program BPASS.  The data
       to be plotted can be selected using a variety of criteria e.g.
       UVrange, timerange or by selecting data from various baselines
       by using the ANTENNAS and BASELINE adverbs.  Calibration and
       flagging can be applied to the data before the spectrum is
       generated by setting the adverb DOCALIB to 1.  The program will
       work with single-source data files, or  multi-source files.
       Multiple plots may be placed on a page using the adverb NPLOTS.
       Multiple IFs and/or polarizations may be plotted as one long
       spectrum (correctly separated and labeled).
Adverbs:
  USERID.....Input file user number.  Ignored
  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....Source list.  If the data is a multi-source file POSSM
             will form the spectrum for the first source specified. If
             the data is a single source file no source name need be
             specified.
  QUAL.......Only sources with a source qualifier number in the SU
             table matching QUAL will be used if QUAL is not -1.
  CALCODE....Calibrators may be selected on the basis of the
             calibrator code:
                  '    ' => any calibrator code selected
                  '*   ' => any non blank code (cal. only)
                  '-CAL' => blank codes only (no calibrators)
                  anything else = calibrator code to select.
             NB: The CALCODE test is applied in addition to the other
             tests, i.e. CALSOUR and QUAL, in the selection of sources
             for which to choose solutions to be applied.
  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, 0=> all
  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, 0=> all
  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
             overide that of FREQID, however setting SELBAND and
             SELFREQ may occasionally result in an ambiguity, in which
             case the task will request that you use FREQID.
  UVRANGE....Range (min, max) of projected baselines to include
             0,0 => all baselines (units: klamda)
  TIMERANG...Time range of the data to be selected. In order:
                Start day, hour, min. sec, end day, hour, min. sec.
             Days relative to reference (header) date.
  STOKES.....The desired Stokes type of the output data:
             'I','V','Q','U','IQU','IQUV','IV','RR','LL','RL',
             'LR','HALF' (=RR,LL), 'FULL' (=RR,LL,RL,LR)
             ' ' => a sensible choice to include all data.  For
             example, for a RR, LL, RL, LR data set ' ' -> FULL, while
             one with only parallel hands will default to HALF.
             For bandpass plots, 'R' and 'L' are okay.  If more than
             one is selected, POSSM will loop over the chosen
             polarizations.
  BIF........First IF to plot. 0=>all.
  EIF........Highest IF to plot. 0=>all higher than BIF
  BCHAN......First channel to select. 0=>all. When plotting
             correlation functions all channels are used to generate
             the function but BCHAN/ECHAN are used to select the range
             of lags to display.
  ECHAN......Highest channel to select.  0 => all higher than BCHAN.
  SUBARRAY...Subarray number to select. 0=>1.
  ANTENNAS...A list of the antennas to be plotted.  If any number is
             negative then all antennas listed are NOT to be plotted
             and all others are.
  BASELINE...Baselines between antennas named in ANTENNAS and those
             named in BASELINE are selected..  There are four possible
             combinations of ANTENNAS and BASELINE:
             1. ANTENNAS = 0; BASELINE = 0.
                All possible baselines are selected.
             2. ANTENNAS <>0; BASELINE = 0.
                a)All ANTENNAS > 0
                  Baselines including an antenna in the ANTENNAS list
                  are selected;
                b)Some ANTENNAS < 0
                  All baselines NOT including an antenna in the ANTENNAS
                  list are selected;
             3. ANTENNAS = 0; BASELINE <> 0.
                a)All BASELINE > 0
                  Baselines including an antenna in the BASELINE list
                  are selected;
                b)Some BASELINE < 0
                  All baselines NOT including an antenna in the BASELINE
                  list are selected;
             4. ANTENNAS <> 0; BASELINE <> 0.
                a)All ANTENNAS>0 and all BASELINE>0
                  Baselines between antennas named in ANTENNAS and those
                  named in BASELINE are selected.
                b)Some ANTENNAS<0 .OR. some BASELINE<0
                  Baselines between antennas named in ANTENNAS  and
                  those named in BASELINE are DE-selected, all others
                  are selected.
             When plotting total power quantities,e.g. total power
             spectra or BP spectra only ANTENNAS is used.  BASELINE is
             ignored except when antennas is empty.
  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 CL table to apply to multi-source
             files or the SN table for single source files.  0 =>
             highest.
  DOPOL......If > 0 then correct data for instrumental polarization as
             represented in the AN 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.
  BLVER......Version number of the baseline based calibration (BL)
             table to appply. <0 => apply no BL table,  0 => highest.
  FLAGVER....specifies the version of the flagging table to be
             applied. 0 => highest numbered table.
             <0 => no flagging to be applied.
  DOBAND.....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......Specifies the version of the BP table to be either
             plotted (if APARM(8)=2) or applied (if DOBAND > 0 and
             APARM(8) not equal 2 or 5).  Is used for BD table when
             APARM(8) = 5.
             0  => highest numbered table.
             <0 => no bandpass correction to be applied.
  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).
  SHIFT......Desired position shift in the tangent point coordinates
             in arcseconds to be made before plotting.  The new
             tangent point coordinates will be RA' = RA + SHIFT(1) and
             DEC' = DEC + SHIFT(2) where all coordinates are in
             arcseconds.  NOTE: SHIFT(1)=n will cause a shift on the
             sky of about n*cos(declination).
  APARM......Control information:
             APARM(1) <= 0.0 => data will be scalar averaged.
                      >  0.0 => data will be vector averaged.
             APARM(2) <= 0.0 => plot axes will be self-scaled
                      >  0.0 => the plot scales are set by the
                                user using APARM(3) - APARM(6).
             APARM(3) = the minimum amplitude to be plotted.
             APARM(4) = the maximum amplitude to be plotted.
                        Self-scaled if APARM(3) >= APARM(4).
             APARM(5) = the minimum phase to be plotted.
             APARM(6) = the maximum phase to be plotted.
                        Self-scaled if APARM(5) >= APARM(6).
                        Phase is assumed to lie in the range
                        -540.0 to 540.0 degrees.
             When NPLOTS > 1, user-scaled plots are shown next to each
             other, while self-scaled plots "waste" space with axis
             labeling.
             APARM(7) <= 0 the frequency axis (x-axis) will be
                           labelled with channel numbers
                       = 1 the frequency axis will be labelled
                           in Hertz, or seconds if plotting
                           a correlation function.
                       = 2 the frequency axis will be labelled
                           in km/s (or m/s), but only if an
                alternative definition of the frequency parm has been
                applied by ALTDEF, or the relevant information is in
                the SU table (if you have a multi-source file). If for
                some reason you have a multi-source file and the
                relevant information is not in the SU table use the
                task SETJY to put it there.
             APARM(8) <= 0 will plot cross-power spectra, baselines n-m
                              where n not equal m.
                      =  1 will plot total power spectra, baselines n-n
                              phase is plotted if STOKES='RL' or 'LR'
                      =  2 will plot BandPass table spectra.
                              STOKES=' ' or 'I' averages both
                              polerizations in a single plot.
                      =  3 will plot autocorrelation functions
                      =  4 will plot cross-correlation functions
                      =  5 will plot the BD (BLCHN) table spectrum
             APARM(9) <= 0 will plot each IF and polarization
                           separately.
                      = 1, the spectra of the selected IF's will be
                           plotted side by side in the same frame.
                      = 2, the spectra of the selected polarizations
                           will be plotted side by side in the same
                           frame.
                      > 2, the spectra of the selected IFs and then
                           polarizations will be plotted side by side
                           in the same frame.
                      All plots are clearly and correctly labeled.
             APARM(10) > 0 => reverse direction of plotted spectrum.
             This will often cause velocity to increase to the right.
  CODETYPE...Selects which parameters are plotted from 'A&P',
             'AMP ','PHAS','R&I','REAL','IMAG'.
             Plot BPARM(5) * log10(amplitude) with 'LAMP' and 'LA&P'.
             All others => 'A&P'
  POLPLOT....An option to display the ratio of various correlated
             values. Allowed combinations are: 'RL/RR', 'RL/LL',
             'LR/RR', 'RL/LL', 'RR/LL', 'LL/RR'; other => don't use
             this option.  This turns off the multiple polarization
             plotting (but not multiple IFs) of APARM(9).
  SOLINT.....If SOLINT > 0 then the user can make multiple plots per
             pass of POSSM. All other parameters will be obeyed. POSSM
             will start at TIMERANGE, make a plot covering the range
             TIMERANGE + SOLINT, etc.  The units of SOLINT are minutes.
             If SOLINT = -1 then POSSM will make scan averages starting
             at scan nearest to the start time specified in TIMERANGE
             and finishing at the scan end closest in time to the stop
             time specified in TIMERANGE. If TIMERANGE is all zero then
             every scan will be averaged and plotted. This function is
             predicated, of course, on there being an NX table in order
             to determine the scan boundaries.  The data must be in time
             order for SOLINT not 0.
  NPLOTS.....This adverb is used to control whether POSSM plots multiple
             spectra per page. If NPLOTS = 0 it will produce one plot
             and all selected data will be averaged together to produce
             that plot. The only exception is when SOLINT is non-zero in
             which case data within the specified average intervals are
             averaged and plotted, the task will then loop back for the
             next time interval.  If NPLOTS >= 1 then each baseline or
             antenna will be plotted in a seperate frame on the page.
             NPLOTS cannot be greater than 9 - or the labels are
             unreadable.
  BPARM......(1) = 1 => divide the line data by 'channel 0'.
                   Channel 0 is a 'VLAism' for the vector
                   averaged centre 75% of the observing band.
             (2) > 0 specifies the first channel ued to form
                   'channel 0'. Normally 'channel 0' is the
                   center 75% of the band, setting this BPARM
                   will override the default.
             (3) > 0 specifies the last channel used to form
                   'channel 0'.
             (4) Drop all spectra for which the amplitude of
                 channel 0 is < BPARM(4) in Jy.  This prevents
                 visibilities near nulls from contributing to
                 averages their very noisy ratios.
             (5) If 'LA&P' or 'LAMP', scale logs by BPARM(5).  0 -> 1
             (6) - (9) are not used at present
             (10) = 1 => don't write header info when writing to the
                 OUTTEXT.  Normally, each spectrum which is written to
                 the outfile specified by OUTTEXT is prefaced by a text
                 describing the spectrum.  Setting BPARM(10) = 1
                 prevents writing this preface.  This would be useful if
                 it is desired to write multiple spectra to the outfile
                 and then plot them with minimal human intervention.
                 Note that even the column identifiers are not written
                 to the OUTTEXT.  The columns of the output file are:
                   channel#, IF, polarization, frequency, velocity,
                   Real(Jy), Imag(Jy)
                 [Run POSSM with BPARM(10) = 0 to check that this
                 description of the outfile format is current]
                 ** Unfortunately, the resulting file may not be
                 properly sorted in either frequency OR velocity.  This
                 should be done manually outside of AIPS; under UNIX
                 'sort -n +3 OUTTEXT' will produce frequency sorted
                 output.
  OUTTEXT....The name of a disk file into which the raw spectrum to be
             plotted is written. The file is written only if NPLOTS = 0.
  LTYPE......Labelling type: 1 = border, 2 = no ticks, 3 - 10 =
             standard, with  7-10 all labels other than tick numbers and
             axis type are omitted.  Less than 0 is the same except that
             the plot file version number and create time are omitted.
  FACTOR.....FACTOR scales the plus signs used to mark samples.  All
             plot types are plotted with plus signs and all but phase
             are also plotted with connected lines.  Set FACTOR < 0 to
             have the plus signs omitted from non-phase plots.
  XYRATIO....Adjust the relative plot size of the X and Y axes.
             0 -> 9/5.5 (1.636) for plot files and full screen for
             TV.  Smaller numbers make the plot relatively taller.
  BADDISK....A list of disks on which scratch files are not to be placed.
  DOTV.......> 0 => plot directly on the TV device, otherwise make a
             plot file for later display on one or more devices
             (including the TV if desired).
  GRCHAN.....Graphics channel (1 - 7) to use for line drawing. 0 => 1.
----------------------------------------------------------------

EXPLAIN BPARM(10) and its use:

BPARM(10) can be used to make OUTTEXTs easier to use as per the
following example.

Consider a data set containing 6 FQid's, at each FQid, there are 2 IFs,
each one containing two stokes 'RR' and 'LL'.  If it is desired to plot
all spectra in a given timerange for, say stokes 'RR', the following
could be done:

1) set STOKES = 'RR'
2) set BIF = 1 ; EIF = 0
3) set TIMERANGE as desired
4) set OUTTEXT = 'FITS:NEWFILENAME'
5) set other POSSM options as desired per individual plot: [AC?, XC?,
   BP?, vector average?, spectral smoothing?, DOCAL = 1?, ...]
6) now run POSSM over all FQid's, perhaps like this:
  for FREQID = 1,6 ; go POSSM; wait POSSM ; end

Now the file NEWFILENAME in the $FITS area will contain   all the
desired spectra for all frequencies selected.  After sorting this file
by frequency [under unix, possibly like this:
     sort -n +2 NEWFILENAME > NEWFILENAME.sorted ]
you have a file containing spectra as a function of frequency [or
velocity...] that can be easily plotted or examined outside of AIPS.

