AIPS HELP file for EVAUV in 31DEC24
As of Mon Oct 14 9:40:55 2024
EVAUV: does statistics on comparison of model and uv data
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 #
SRCNAME Source name
QUAL -10.0 Calibrator qualifier -1=>all
CALCODE Calibrator code ' '=>all
STOKES Stokes of output ' ' -> HALF
TIMERANG Time range to use
SELBAND Bandwidth to select (kHz)
SELFREQ Frequency to select (MHz)
FREQID Freq. ID to select.
ANTENNAS Antennas to copy 0=>all
BASELINE Baselines with ANTENNAS
SUBARRAY 0.0 1000.0 Sub-array, 0=>all
BIF Low IF number to do
EIF Highest IF number to do
BCHAN 0.0 First channel included
ECHAN 0.0 last channel included
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.5 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.5 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.
NMAPS 0.0 4096.0 No. maps to use for model.
NGAUSS 0.0 Number Gaussians in NMAPS
IN2NAME Cleaned map name (name)
IN2CLASS Cleaned map name (class)
IN2SEQ 0.0 9999.0 Cleaned map name (seq. #)
IN2DISK Cleaned map disk unit #
INVERS -1.0 46655.0 CC file version #.
BCOMP First CLEAN comp to sub.
1 per field.
NCOMP Last CLEAN comp to sub.
to use (0 => all)
FLUX Lowest CC component used.
CMETHOD Modeling method:
'DFT','GRID',' '
SMODEL Source model, 1=flux,2=x,3=y
See HELP SMODEL for models.
(1) not 0 -> ignore IN2NAME
< 0 => solve for flux from
SU table (-2 curvature)
SPECINDX If SMODEL, spectral index
SPECURVE If SMODEL, spectra curvature
DOOUTPUT -1.0 1.0 > 0 save the UV files from
model subtraction & division
OUTNAME Output files name
OUTSEQ Output files sequence
OUTDISK Output files disk
SOLINT Closure averaging (min)
0 => do not do closure
DOPLOT > 0 => plot Re vs Im maps
= 2 => plot histograms too
CELLSIZE Cell size in asec (if SMODEL)
APARM 2-D Re/Im plot controls
(1) Plot subtracted data
over +/-APARM(1)*RMS(sub)
(2) Plot divided data over
+/- APARM(2)*RMS(div)
(3) Number pixels on a side
for these images
(4) Gaussian smoothing size
PIXRANGE Intensity range to use
FUNCTYPE 'LG' use logarithms in plot
of image intensities
LTYPE type of labeling
DOTV > 0 use TV, else plot file
GRCHAN TV graphics channel to use
BADDISK Disks to avoid for scratch
@ Output adverbs
RPARM @ Results (see help)
HELP SECTION
EVAUV
Task: Subtracts and divides a model into a uv data base. The model
may be a specific model, a set of CLEAN components files, or a
set of images. "CLEAN" models may be points, Gaussians or
uniform, optically thin spheres. The task will compute the
model and then both subtract it from the input UV data and
divide it into the UV data. It then reports on statistical
attributes of the two data sets. The mean and rms of the real
and imaginary parts and the amplitude are reported for the
model subtracted data set and for the divided data set (after a
constant 1.0 is subtracted from the real part). The amplitude
mean is computed in a robust fashion and controls which samples
enter into the real and imaginary part averages. Then the
number of samples more than 3 rms away from the mean amplitude,
the total number of samples, and the average of the absolute
difference of the bad samples and the mean are reported.
The model will use Clean Components if they are present and
otherwise will do the image. No correction for convolution by
the Clean Beam (if any) are made in the latter case. Offset
sub-images are not supported.
Following the UV analysis, the robust mean and rms over the
images are determined and reported. Note that this mean and
rms should omit any real source signals.
Model images made with both values of IMAGR's DO3DIMAG
option are handled correctly, as are multi-scale images. Set
NMAPS = NFIELD * NGAUSS.
EVAUV works only on single-source files.
Sample output:
--------------
Image mean -7.3490E-07 rms 1.5078E-04
method real part imaginary part amplitude
subtract 0.0002 +- 0.157 0.0002 +- 0.157 0.1977 +- 0.103
divide-1 -0.0040 +- 6.770 0.0017 +- 6.770 7.9390 +- 5.364
method # bad samples total samples avg bad amp
subtract 79124 5333006 0.3918
divide-1 267058 5333006 27.1805
--------------
The optional plots are
1. The average and rms of the model subtracted data in bins
of UV-plane radius.
2. The average and rms of the model divided - 1.0 data in
bins of UV-plane radius.
3. The histogram of image pixels over a pixel value range
selected by the user or the first of the model images.
4. The histogram of image pixels over a pixel range of
plus/minus 5 times the rms of the first of the model
images.
5. The real vs imaginary visibilities of the model subtracted
data over a range of APARM(1) times the amplitude rms.
The plot is a contour in logarithmic intervals of the 2-D
histogram image controlled by APARM. Contours are drawn
at 0.5, 1, 1.5, 2, 2.5, 3, etc in the log of the counts.
6. The real and imaginary gains minus (1,0) of the model
divided data over a range of APARM(2) times the amplitude
rms. Logarithmic contours also.
Actually plots 5 and 6 cover somewhat larger areas but some
data samples will not be plotted (totals on and off the plot
are reported).
The task will now compute and report closure phase and
amplitude statistics from the "visibilties" of the gain
data set (produced by division of the input data by the
model, not subtracting (1,0)). It will do this only when the
STOKES value is appropriate: HALF, RRLL, RR, LL, VVHH, VV, and
HH and when SOLINT is not zero.. It will do these as a
function of IF. Closure amplitude in the quadrangle of
antennas a, b, c, and d is defined as
LN [ (amp_ab * amp_cd) / (amp_ac * amp_bd) ]
which should be independent of any antenna-based instrumental
gains. Closure phase in the triangle of antennas a, b, and c
is defined as
Phase_ab - Phase_ac + Phase_bc
which should be independent of any antenna-based instrumental
phases. Since these apply to the RR and LL, closure amplitude
and phase are only meaningful in the STOKES values listed
above. The data/model data set should ideally be a point
source at the coordinate origin and so these closure parameters
should be zero, if the model is perfect.
The use of closure statistics to evaluate potential calibration
sources is discussed in detail in the paper Xu, M.H., Anderson,
J.M., Heinkelmann, R., Lunz, S., Schuh, H., Wang, G.L., 2019,
"Structure Effects for 3417 Celestial Reference Frame Radio
Sources", Ap. J. Suppl., 242:5. Available via:
https://doi.org/10.3847/1538-4365/ab16ea
Closure information is produced by the following tasks:
CLPLT Plots closure phases for individual triangles as a
funtion of time.
CAPLT Plots closure amplitudes for individual quadrangles as
a funtion of time.
EVACL Computes the RMS of closure phase and amplitude as a
function of IF for an individual Stokes.
EVAUV Computes two data sets: data-model and data/model. The
closure RMSes of the latter may be computed as
functions of polarization and IF. Other statistics
are computed and plotted.
CLOSE Computes the RMS closure phase or amplitude as a
function of spectral and IF channel. A plot is
produced and a text file may be written.
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.
SRCNAME....Source name to be gridded. Must specify if input is
a multi-source data set, otherwise all sources are
included.
QUAL.......Qualifier of source to be processed. -1 => all.
CALCODE....Calibrator code of source to be processed. ' '=> all.
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.
ANTENNAS...A list of the antennas to list. If any number is
negative then all antenna numbers in ANTENNAS are NOT
desired and all others are. All 0 => list all.
Note that antenna numbers that do not appear in the
relevant antenna file(s) or which appear with a name
containing the string 'OUT' are not displayed.
BASELINE...Baselines are specified for the LIST option using
BASELINE. Eg. baselines 1-6,1-8, 2-6 and 2-8 use
ANTENNAS=1,2; BASELINE=6,8.
SUBARRAY...Sub-array number to process. 0=>all (okay if not
calibration)
BIF........Start IF; 0 -> 1
EIF........End IF; 0 -> max
BCHAN......Start channel; 0 -> 1
ECHAN......End channel; 0 -> max
NCHAV......Number of channels to average. Note that ECHAN is
adjusted if necessary to make (ECHAN-BCHAN+1) and integer
multiple of NCHAV. 0 -> 1.
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 apply. <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.
IMAGR uses DOBAND as the nearest integer; 0.1 is therefore
"false".
BPVER......Specifies the version of the BP table to be applied
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).
NMAPS......Number of image files to use for model. For multi-scale
models, set NMAPS = NFIELD * NGAUSS to include the Clean
components of the extended resolutions. If more than one
file is to be used, the NAME, CLASS, DISK and SEQ of the
subsequent image files will be the same as the first file
except that the LAST 3 or 4 characters of the CLASS will
be an increasing sequence above that in IN2CLASS. Thus,
if INCLASS='ICL005', classes 'ICL005' through 'ICLnnn'
or 'ICnnnn', where nnn = 5 + NMAPS - 1 will be used. Old
names (in which the 4'th character is not a number) are
also supported: the last two characters are '01' through
'E7' for fields 2 through 512. In old names, the highest
field number allowed is 512; in new names it is 4096.
NGAUSS.....Number of Gaussians in NMAPS.
IN2NAME....Model map name (name). Standard defaults.
IN2CLASS...Model map name (class). Standard defaults.
IN2SEQ.....Model map name (seq. #). 0 => highest.
IN2DISK....Disk drive # of model map. 0 => any.
WARNING: SMODEL overrides the above model map
specification.
INVERS.....CC file ver. number. 0 => highest.
BCOMP......The first clean component to process. One value is
specified for each field used.
NCOMP......Number of Clean components to use for the model, one
value per field. If all values are zero, then all
components in all fields are used. If any value is not
zero, then abs(NCOMP(i)) (or fewer depending on FLUX and
negativity) components are used for field i, even if
NCOMP(i) is zero. If any of the NCOMP is less than 0,
then components are only used in each field i up to
abs(NCOMP(i)), FLUX, or the first negative whichever
comes first. If abs(NCOMP(i)) is greater than the number
of components in field i, the actual number is used. For
example
NCOMP = -1,0
says to use one component from field one unless it is
negative or < FLUX and no components from any other
field. This would usually not be desirable.
NCOMP = -1000000
says to use all components from each field up to the
first negative in that field.
NCOMP = -200 100 23 0 300 5
says to use no more than 200 components from field 1, 100
from field 2, 23 from field 3, 300 from field 5, 5 from
field 6 and none from any other field. Fewer are used if
a negative is encountered or the components go below
FLUX.
FLUX.......Only components > FLUX in absolute value are used in the
model.
CMETHOD....This determines the method used to compute the model
visibility values.
'DFT' uses the direct Fourier transform, this method is
the most accurate.
'GRID' does a gridded-FFT interpolation model computation
' ' allows the program to use the fastest method.
NOTE: data in any sort order may be used by the 'DFT'
method but only 'XY' sorted data may be used by the
'GRID' method.
NOTE: CMETHOD='GRID' does not work correctly for RL
and LR data; DO NOT USE CMETHOD='GRID' for RL, LR!
SMODEL.....A single component model to be used instead of a CLEAN
components model; if abs (SMODEL) > 0 then use of this
model is requested.
SMODEL(1) = flux density (Jy) at header frequency
SMODEL(2) = X offset in sky (arcsec)
SMODEL(3) = Y offset in sky (arcsec)
SMODEL(4) = Model type:
0 => point model
1 => elliptical Gaussian and
SMODEL(5) = major axis size (arcsec)
SMODEL(6) = minor axis size (arcsec)
SMODEL(7) = P. A. of major axis (degrees)
2 => uniform sphere and
SMODEL(5) = radius (arcsec)
If SMODEL(1) < 0, EVAUV will try to solve for the
spectrum using the SU table. SMODEL(1) < -1.5 means to
include curvature in the solution.
SPECINDX...Spectral index to use with SMODEL(1) > 0. Alternatively
it will be solved using the SU table if SMODEL(1) < 0.
Not used when SMODEL(1) = 0.
SPECURVE...Spectral curvature to use with SMODEL when SMODEL(1) > 0.
log(T(f)/T(f0) = S * log(f/f0) + C(1) * (log(f/f0))^2
+ C(2) * (log(f/f0))^3 + C(3) * (log(f/f0))^4
where S is SPECINDEX and C is SPECURVE, f0 is the header
frequency and all logs are base 10. Will be solved from
the SU table if SMODEL(1) < -1.5.
DOOUTPUT...> 0 => save the residual (data minus model) and gain
(data divided by model) files as cataloged files.
<=0 => delete these files at the end of the task.
OUTNAME....Output files name (name). ' ' -> INNAME
The classes will be EVAUVS and EVAUVD for subtracted and
divided data sets.
OUTSEQ.....Output files name (seq #). 0 -> next highest
OUTDISK....Output files disk number. 0 -> highest with space.
SOLINT.....= 0 => do not do closure phases and amplitudes
If SOLINT > 0, the time interval (minutes) over which to
average the data in order to form the closure phase and
amplitude. This function works on the gain (data / model)
which should, with an ideal model, be (1, 0). Use of a
very small value of SOLINT (but > 0) will cause
inadequately aligned data to be discarded in order to avoid
misleadingly high closure phases and amplitudes. However
larger SOLINTs appear to go faster.
If SOLINT < 0, the task will form a closure phase/amplitude
as soon as it has accumulated at least one sample for each
of the three/four baselines in the triangle/quadrangle.
These are then averaged over abs(SOLINT) minutes.
DOPLOT.....> 0 => Plot the two real versus imaginary histogram
images as contour maps with contours in the log
at intervals of 0.5, 1, 1.5, 2.0, 2.5 etc
> 1.5 => Also plot two plots showing the mean and rms
residual and (gain-1) versus baseline length
and two plots of the image histogram.
<= 0 => no plots
CELLSIZE...Cell size of images in arc seconds. Used when there are
no model images (i.e. when using SMODEL) to scale
histograms of data versus radius in UV plane. Default
0.1 asec which is not likely to be useful.
APARM......The real parts of the model subtracted and model divided
data are plotted against the corresponding imaginary
parts in two contour plots of the 2-D histogram images.
The contour intervals are 0.5 in the logarithm of the
counts in each cell of the images. APARM controls the
extent of these images, their size, and whether they are
smoothed:
(1)....The model subtracted data are plotted over a range
of +/- APARM(1) times the subtracted amplitude
rms. 0 -> 5
(2)....The model divided data are plotted over a range
of +/- APARM(2) times the divided amplitude rms.
0 -> 10
(3)....The plots are summed in images of APARM(3) pixels
on a side. 0 -> SQRT (Nvis * Nchan / 10) <= 1024
(4)....The images are smoothed by a Gaussian kernel of
APARM(4) pixels on a side before plotting.
0 -> no smoothing - will be set to an odd number
<= 33.
Hints: For large numbers of samples, you may wish to set
APARM(1) and APARM(2) to higher numbers, e.g. 15 and 25
and you will want to smooth by e.g. 5 or 9 before
plotting. For a small data set, a small image is a good
idea.
PIXRANGE...The range of image intensities to be used in the
histogram that is intended to encompass the full
interesting range of the image(s). 0 => use the range in
the header of the first image.
FUNCTYPE...'LG' => use logarithms in the plots of the image
histograms, else do a linear plot.
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 on the TV, else make plot files.
GRCHAN.....If plotting on the TV, use graphics plane GRCHAN. 0 =>
use more than one graphics plane, separating portions of
the plot by color.
BADDISK....The disk numbers to avoid for scratch files.
RPARM......Output adverb with results
( 1, 2) Subtracted real part mean, rms
( 3, 4) Subtracted imag part mean, rms
( 5, 6) Subtracted ampl part mean, rms
( 7, 8) Subtracted fraction bad and average bad
( 9,10) Divided - 1 real part mean, rms
(11,12) Divided - 1 imag part mean, rms
(13,14) Divided - 1 ampl part mean, rms
(15,16) Divided - 1 fraction bad and average bad
(17,20) Image mean, rms of mean, rms, rms of rms
(21,23) Average phase & amplitude closure pol #1
(24,25) Average phase & amplitude closure pol #2
(26) SMODEL(1) actually used (if > 0)
(27) SPECINDX if SMODEL used
(28,30) SPECURVE if SMODEL used
EXPLAIN SECTION