AIPS HELP file for POSSM in 31DEC24
As of Sat Oct 5 16:06:54 2024
POSSM: Task to plot total and cross-power spectra.
INPUTS
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.
UVRANGE 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.
PDVER PD table to apply (DOPOL>0)
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
POSSM HELP SPECIAL VALUES
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
version BPVER
= 3 => plot ACF
= 4 => plot XCF
= 5 => plot BD table
version BPVER
= 6 => plot PD table
version BPVER
= 7 => plot CP table
version BPVER
= 8 => plot CP table / I
version BPVER
= 9 => plot PC table
version BPVER
= 10 => plot PP table
version BPVER
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 'RMS ' -> do rms of data
'RMSN' -> do rms/amp
Option to display various
combinations of polzns to
plot: see help for allowed
values; 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: scale LOG10 plots by B(5)
6: > 0 -> Plot error bars on
PP plots
7: > 0 -> separate IFs with
vertical line
8: > 0 -> label across all
IFs
< 0 -> label each IF
= 0 -> label across IFs
if APARM(7) & (9) > 0
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 -410.0 410.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 88.0 Main graphics channel
+ 10 * label graphics chan
HELP SECTION
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).
WARNING: If SOLINT is not zero, the task will loop over
antennas, baselines, scans etc. quite assiduously. This can
take a lot of time. It helps a great deal in this case to help
the task find the data by providing SOURCES, ANTENNAS,
BASELINE, and/or other adverbs to limit how much of the search
will be attempted.
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. STOKES='I' or 'V' causes (R+L)/2 or
(R-L)/2 to be plotted.
Linear polarizations are also supported: 'VV', 'HH', "VH',
'HV', 'VVHH', 'VHHV', etc.
BD plots allow any polarization choice appropriate to the
table which can contain 1, 2, or 4 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.
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.
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 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 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, the PD table when APARM(8) = 6, and the CP
table when APARM(8) = 7 or 8.
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
To smooth after POSSM has summed up all the data and
just before plotting (the fastest and perhaps best):
9 => Hanning, 10 => Gaussian, 11 => Boxcar, 12 => Sinc
13 => Hanning, 14 => Gaussian, 15 => Boxcar, 16 => Sinc
(The second group honors but does not preserve flagging
while the first does.)
**** See HELP SMOOTH for a discussion of the interaction
**** of flagging and smoothing.
**** Unlike normal smoothing, the special POSSM smoothing
**** does not retain edge channels outside BCHAN-ECHAN so
**** there may be differences at the edges.
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.
NOTE - THIS CHANGED 2010-Sep-01
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
PC tables always do channels.
(You may want BPARM(8) > 0)
= 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
also those from BLPOLCAL (BLPCL).
= 6 will plot the PD (PCAL) table spectrum
= 7 will plot the CP (PCAL) table spectrum
The phase is plotted as the source
polarization angle (1/2 the CP phase)
= 8 will plot the CP (PCAL) table spectrum
relative to the total intensity
= 9 will plot the PC (VLBI) table tones
= 10 will plot the PP (RLDIF, XYDIF) table
spectrum. NPLOTS=0 plots only the global
solution (record 1 of the PP table). NPLOTS
> 0 plots the global solution and any
individual time solutions.
(BPARM(6)) controls plotting error bars
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....'RMS ' => plot the rms of the selected average spectrum
'RMSN' => plot the rms of the selected average spectrum
divided by the amplitude (or 'RMSD')
Allowed for UV, BP, and PC data.
Otherwise, 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',
'VH/VV', 'VH/HH', 'HV/VV', 'VH/HH', 'VV/HH', 'HH/VV',
'Q/I', 'U/I', 'V/I'
other => don't use this option.
The ratio option 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.
SOLINT is ignored for BD, PD, and CP table plots.
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 percent of the observing band.
(2) > 0 specifies the first channel ued to form
'channel 0'. Normally 'channel 0' is the
center 75 percent 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
For display purposes, use an integer. Note 10 gives
db in power, 20 gives db in voltage.
(6) > 0 => Plot error bars on plots of PP spectrum
(7) > 0 => include dividing lines between IFs when plotting
multiple IFs together (APARM(9)=1,3)
A dividing line is plotted between polarizations
always (APARM(9) = 2 or 3)
Dividing lines are always plotted when doing per-IF
labels
(8) Axis labeling may be done across all IFs when APARM(9)
is 1 or 3. In that case the data are plotted at the
correct frequency and all channels are plotted;
(channels < BCHAN and > ECHAN are not used in
determining the max/min and are not actually plotted
but space for them is included)
APARM(8) > 0 -> use this mode
APARM(8) < 0 -> label each IF separately and plot only
BCHAN through ECHAN
APARM(8) = 0 -> choose this mode if APARM(7) > 0 and
APARM(9) > 0.
(9) Unused
(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, see HELP LTYPE for details:
1 = border, 2 = no ticks, 3 or 7 = standard, 4 or 8 =
relative to ref. pixel, 5 or 9 = relative to subimage
(BLC, TRC) center, 6 or 10 = pixels. 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.
Add n * 100 to alter the metric scaling.
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. FACTOR
> 100.0 causes a scaling of (FACTOR-100.0) to be used and
the connecting lines to be omitted. 0 <= FACTOR < 0.4
-> FACTOR=1 and -0.4 < FACTOR < 0 -> FACTOR=-1.
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.
A value of 0 causes more than one graphics channel to be
used. To specify a channel to be used for plot labels
add 10 * that graphics channel number. If the label
channel is zero, it is set to GRCHAN. See HELP GRCHAN
for additional discussion.
EXPLAIN SECTION
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.