AIPS HELP file for SYHIS in 31DEC26
As of Sat Jan 24 9:52:15 2026
SYHIS: Plots SY table values as histograms, smooths/filters
INPUTS
INNAME Image name(name).
INCLASS Image name(class).
INSEQ 0.0 9999.0 Image name(seq. #). 0=>high
INDISK Disk drive #. 0=>any
INVERS 0.0 46655.0 SY table version number
ANTENNAS Antennas included
SOURCES Source names to include
QUAL -10.0 Qualifier -1=>all
CALCODE Restrict to this calcode
STOKES 'R','L','V','H' or ''
SELBAND Bandwidth to select (kHz)
SELFREQ Frequency to select (MHz)
FREQID Freq. ID to select.
SUBARRAY 0.0 1000.0 Subarray, 0 => 1
BIF 0.0 Initial IF
EIF Last IF, IFs plotted
separately
TIMERANG Time range to use
FLAGVER -1.0 > 0 => apply flags to SY
NBOXES 32. 1024. Number cells in histograms
OPCODE 'RMS ' global histograms
'MWIN' MW diff histograms
'BOTH' both histogram types
else do everything
APARM (1)-(3) number sigmas for
clip range. 0 -> 4
(4)-(6) number sigmas for
MW clip range 0 -> 3
(7)-(9) MW smooth time
minutes. 0 -> 1
SAMPTYPE Smoothing function
BPARM Smoothing parameters
CUTOFF 0.0 Cutoff for functional forms
DOBLANK Blanked value interpolation
Following apply to plots
OPTYPE 'PDIF','PSUM','PSYS' plot
simple stats of this type
in MW stage
' ' -> all 3
OUTPRINT Not blank -> list means
and rmses in text file
NPLOTS 0.0 16. Number plots / page
DOPLOT -1.0 3.0 =1,3 Plot rms Gaussian
=2,3 Plot fit Gaussian
< 0 -> no plots
RPARM (1) Number sigmas around mean
Pdif for X plot ranges
(2) Number sigmas around mean
Psum for X plot ranges
(3) Number sigmas around mean
Psys for X plot ranges
(4,5) Pdif plot range
(6,7) Psum plot range
(8,9) Psys plot range
(10) Min Pdif X plot range
(11) Min Psum X plot range
(12) Min Psys X plot range
FUNCTYPE 'LG' -> log 10
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
DOTV > 0 plot on TV
GRCHAN 0.0 88.0 Main graphics channel
+ 10 * label graphics chan
BADDISK Disks to avoid for scratch
HELP SECTION
SYHIS
Type: Task
Use: SYHIS reads EVLA SY and CD tables and computes statistics of the
Pdif, Psum, and Tsys values found on a per IF and per antenna
basis. It can plot the resulting histograms with the mean and
rms and a Gaussian fit to the histogram. It can then clip these
data plus/minus N sigma to get rid of seriously bad points. Then
the data may be median-window filtered and the difference between
the data and the filtered data used to construct and fit new
histograms. These may be plotted and printed. The data are then
clipped based on the difference between the data and the MW
filtered values. This produces a new SY table with some number
of values blanked. That table may then be smoothed by a variety
of smoothing operations and the clipped or all of the values
replaced with the smoothed function. This is an experimental
algorithm and its output should be examined closely but it seems
to be a good thing. See the EXPLAIN for more details.
Adverbs:
INNAME.....Image name (name). Standard defaults.
INCLASS....Image name (class). Standard defaults.
INSEQ......Image name (seq. #). 0 => highest.
INDISK.....Disk unit #. 0 => any.
INVERS.....Version number of SY table to be examined.
ANTENNAS...A list of the antennas to be plotted. All 0 => all. If any
number is negative then all antennas listed are NOT to be
plotted and all others are.
SOURCES....List of sources to be printed. ' '=> all; if any
starts with a '-' then all except ANY source named.
QUAL.......Qualifier of source to be printed. -1 => all.
CALCODE....Calibrator code of sources to print. ' '=> all.
'* ' => any non blank code (cal. only)
'-CAL' => blank codes only (no calibrators)
anything else = calibrator code to select.
STOKES.....First character must be R, L for circular or V, H for
linear polarizations to restrict the polarization. All
else does both polarizations.
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/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 (.le. 0) then all FQ ids will
be selected.
SUBARRAY...Subarray number to print. 0 => 1.
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.
FLAGVER....> 0 => apply flag table version FLAGVER to SY table
NBOXES.....Number of boxes into which the histogram is counted.
32 to 1024
OPCODE.....If 'RMS ', then quit the task after plotting the main
histograms. Do not save an SY table.
If 'MWIN', do not plot the main histograms, but plot
the histograms following the median window
filter. Quit the task after those plots
and do not save an SY table.
If 'BOTH', plot both the main and median window based
histograms. Then quit the task and do not
save an SY table.
Other, do both sets of plots, clip and then smooth
a new SY table which is retained.
APARM......Data can then be clipped by comparison with the mean
and rms. The range of the clip is plus minus APARM(i)
times the rms in each antenna, IF, and polarization
individually. SYHIS will then clip relative to a
median window. SYHIS will plot histograms of the
deviation from the MW filter.
(1) => clip multiplier for Pdif
(2) => clip multiplier for Psum,
(3) => clip multiplier for Psum/Pdif/2*Tcal = Psys
0 for multiplier becomes 4.0.
Values < 0 or > 25 do no clipping.
(4) => MW clip multiplier for Pdif
(5) => MW clip multiplier for Psum (minutes),
(6) => MW clip multiplier for Psum/Pdif/2*Tcal = Psys
0 for multiplier becomes 3.0.
Values < 0 or > 25 do no clipping.
(7) => smoothing time for Pdif (minutes),
(8) => smoothing time for Psum (minutes),
(9) => smoothing time for Psum/Pdif/2*Tcal = Psys (min)
Smooth times of 0.0 become 1 minute,
values < 0 cause no smoothing.
SAMPTYPE...The type of smoothing to follow clipping (if any)
'BOX ' = boxcar smoothing (default)
'MWF ' = Median window filter
'GAUS' = Gaussian
'EXP ' = Exponential
'LINE' = Linear (1 - abs(t-t0)/sigma)
'2PT ' = Two-point
'2PTH' = Two-point + "Hanning"
BPARM......Parameters for smoothing function: note that we cannot
smooth Tsys in SY tables since that is the ratio of the
two measured quantities.
Function support full-width width in minutes
(1) => support time for Pdif, (0 -> skip)
(2) => support time for Psum, (0 -> skip)
Added parameter (FWHM) for GAUS, EXP, LINE in minutes
(6) => smoothing FWHM time for Pdif
(7) => smoothing FWHM time for Psum
In all cases, the substitution for blanked and good
solutions is governed by DOBLANK (see below)
CUTOFF.....Cutoff for GAUS, EXP, LINE. The sum of the weighting
function in the support region must exceed CUTOFF for the
smoothed value to be regarded as valid. Be careful, a
value of 1.5 means that the sample itself must be good
and the sum over other good samples in the support range
must exceed 0.5. < 1.e-6 => 1.e-6.
DOBLANK....Blanked value interpolation:
> 0: replace previously blanked values with smoothed
values, leave previously good values unchanged.
= 0: replace previously blanked and previously good
values with smoothed values.
< 0: replace previously good values with smoothed values,
leave previously blanked values blanked.
OPTYPE.....'DIFS' plot only Pdif information
'SUMS' plot only Psum information
'TSYS' plot only Tcal*Psum/Pdif information
else plot and list all three.
OUTPRINT...If not blank, text file to receive full list of all
mean and rms for each antenna, IF, and polarization.
Both the semi-robust and the Gaussian fit values are
printed.
NPLOTS.....Number of plots (1 antenna, 1 IF, 1 polarization) per
plotted page. 1 to 16
PIXRANGE...Range of Pdif, Psum, or Psys plotted on X axis. Default
is to use a separate range for each plot from minus N
sigma to plus N sigma around the mean (N is RPARM(1))
RPARM......(1) The default X plot range for Pdif is
-RPARM(1) * sigma to +RPARM(1) * sigma around the
mean. RPARM(1) <= 1 is set to 4.0
(2) The default X plot range for Psum is
-RPARM(2) * sigma to +RPARM(2) * sigma around the
mean. RPARM(2) <= 1 is set to 4.0
(3) The default X plot range for Psys is
-RPARM(3) * sigma to +RPARM(3) * sigma around the
mean. RPARM(3) <= 1 is set to 4.0
(4,5) The intensity range to use for Pdif if RPARM(4)
< RPARM(5). Otherwise the plot is self scaling.
(6,7) The intensity range to use for Psum if RPARM(6)
< RPARM(7). Otherwise the plot is self scaling.
(8,9) The intensity range to use for Pdif if RPARM(8)
< RPARM(9). Otherwise the plot is self scaling.
(10) The minimum X axis plot range for Pdif in counts.
(11) The minimum X axis plot range for Psum in counts.
(12) The minimum X axis plot range for Psys in degrees.
FUNCTYPE...'LG' plot the log10 of the histogram count, else plot
the count on a linear axis.
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.
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.
BADDISK....The disk numbers to avoid for scratch files (sorting
tables mostly).
EXPLAIN SECTION
SYHIS: Task to examine SY table values as histograms and then clean
them up
Documenter: E. W. Greisen, NRAO
Related programs: TYSMO, SNPLT, PRTSY, SYPRT
This task does a whole sequence of operations but the user may choose
not to do all of them. This allows the user to review the results of
the earlier steps before proceeding to the later ones.
The steps in the full process:
1. The input SY table is copied to a new table version. If FLAGVER
> 0, the specified flag table will be applied and any changes to
the table reported.
2. The task reads the selected portion of the SY table and determines
the mean and rms separately for each spectral window, polarization,
and antenna. It then redoes the determination, ignoring samples
more than twice the rms away from the mean. It repeats this 10
times to get something like a robust mean and rms.
3. Using the results of step 2, the task determines histograms for
each IF, polarization, and antenna. It even attempts a Gaussian
fit of the histogram.
3. If OPCODE is not 'MWIN', the program then prints the mean and rms
for each histogram if OUTPRINT specifies a text file. It then
plots the histograms NPLOTS (<= 16) to a page either on the TV or
in plot files. Note that there may be a large number of plots,
but when DOTV is true (> 0) you can stop the plotting at any point
with button D.
4. If OPCODE = 'RMS', the task exits deleting the new and temporary SY
table.
5. If OPCODE not equal 'RMS', the program continues and does:
a. Computes clip levels from mean - N*rms to mean + N*rms for each
of Pdif, Psum, Psys for each IF, polarization, and antenna.
N is set by APARM(1) through APARM(3).
b. Reads the SY table and prepares arrays of Pdif, Psum, and Psys
applying the clipping.
c. Runs a median window filter of widths set by APARM(7) through
APARM(9) in each array.
d. Compares each input array to the median window smoothed array
generating the mean and rms of the differences.
e. Re-runs the comparison generating histograms of the differences
for each IF, polarization, and antenna.
f. Sets new clip levels based on the mean and rms difference scaled
by APARM(4) through APARM(6).
g. Applies this clip to the median window smoothed array.
h. Re-reads the SY table and re-writes it with all clipped points
blanked.
6. The task then prints the mean and rms of each of the median window
filter differences if OUTPRINT is not blank. Then it plots the
difference histograms NPLOTS to a page either on the TV or in plot
files. Note that there may be a large number of plots, but when
DOTV is true (> 0) you can stop the plotting at any point with
button D.
7. If OPCODE is 'MWIN' or 'BOTH", the task exits deleting the new and
temporary SY table.
8. If OPCODE is not 'MWIN' or 'BOTH", the task then applies a
smoothing function to Pdif and Psum as arrays in memory. Adverbs
SAMPTYPE, BPARM, and CUTOFF control the type of smoothing. SYHIS
then re-reads the SY table, replaces the clipped values with
smoothed values (if DOBLANK > 0) or replaces both clipped and
unclipped values with the smoothed values (if DOBLANK = 0) or
replaces only the unclipped values with smoothed values
(if DOBLANK < 0). It re-writes the SY table with the replaced
values of Pdif and Psum.
9. SYHIS then adds information to the history file and exits keeping
the new, modified SY table.
******************************
Plotting suggestions:
Plotting and printing may be restricted to any one of Pdif, Psum, and
Psys by setting OPTYPE. Otherwise all 3 are printed and plotted.
The number of plots per page is set by NPLOTS and any number from 1
through 16 is allowed. DOPLOT controls whether the initial mean and
rms and the Gaussian fit to the histogram are plotted as Gaussians.
RPARM may be used to control the range of values on the plots.
RPARM(1) through (3) sets the number of sigmas around the mean.
RPARM(10) through (12) can force the X range to be larger if the sigma
is particularly small. RPARM(4) through (9) control the Y axis scale
while 0 => each plot is self-scaling.
SYHIS writes useful information one the left and right sides of each
plot. If the characters are too large these columns may overlap and
become unreadable. On the TV, set the characters to the smallest size
with the verb CHARMULT 1. When running LWPLA, you may find it useful
to choose a font size rather less than 13 points (DPARM(8) = 8, for
example).