AIPS HELP file for OBITMAP in 31DEC24
As of Sat Oct 5 16:06:46 2024
OBITMAP: Make/Clean images with OBIT task Imager
INPUTS
DOWAIT -1.0 3.0 > wait for and display output
DOCRT -4.0 132.0 > 0 display output on
terminal, else message file
OBITVERS 0.0 =2 for python2, else 3
INNAME Input UV data (name)
INCLASS Input UV data (class)
INSEQ Input UV data (seq. #)
INDISK Input UV data disk drive #
STOKES Desired Stokes: I, Q, U, or V
BCHAN 0.0 8192.0 Low freq. channel 0 for cont.
ECHAN 0.0 8192.0 Highest freq channel
NCHAV Number of chan. to average.
CHINC Channel incr. between maps.
BIF First IF in average.
EIF Last IF in average.
OUTNAME end of output image name
OUTSEQ -1.0 9999.0 Output seq. no.
OUTDISK Output image disk drive #
FOV 1.E-6 Radius of the desired field
of view (in degrees)
CELLSIZE 0.0 (X,Y) size of grid in asec
UVTAPER 0. (U,V) Gaussian taper
units are kilo-lambda
ROBUST Robustness power: -5 -> pure
uniform weights, 5 => natural
NITER 0.0 Maximum # of Clean components
FLUX Stop Clean when max residual
< FLUX
IM2PARM (1) > 0 => automatically find
Clean boxes - do this!
PRTLEV -1.0 5.0 Amount of messages desired:
0 -> 2.
DOTV -1.0 512.0 Display residuals on OBIT TV
NTHREAD 1.0 Maximum number threads to use
BADDISK -1.0 1000.0 Disks to avoid for scratch.
HELP SECTION
OBITMAP
Type: "Verb"
Use: The OBIT package of astronomy software written by Bill Cotton
of NRAO Charlottesville is available at some institutions. If
it is available and in your $PATH, then you may use this verb
to run a simplified version of the OBIT imaging task Imager.
It does not offer multi-scale, SDI, peeling, self-cal,
re-centering or other complicated options of Imager. It does a
multi-facet, DO3DIM false image, followed by a FLATN. The
Clean components are retained with the flattened image and may
be used for self-cal. It limits Imager to using pre-calibrated,
single-source data.
The log and run file for each execution of OBITMAP will appear
in your $HOME area. The UV work file will appear on OUTDISK,
named with the source name, a class of 'Imager', and a new
higher sequence number.
The input adverbs are saved with a TPUT equivalent when this
verb is invoked.
The Explain file attached contains the full help file for
Imager.
Adverbs:
DOWAIT.....A log file is written into your $HOME area from the obit
task. If DOWAIT <= 0.0, AIPS does not wait for the OBIT
task Imager and you will need to look at the log file
with more, less, cat, or an editor. If 0 < DOWAIT < 2,
the messages from Imager will appear as the OBIT task
generates them. If DOWAIT >= 2, AIPS will wait for
Imager to finish and then echo the log file under control
of DOCRT.
DOCRT......> 0 Use the terminal, the full length of the log file
lines will appear so widen it at least a little.
<= 0 Write log file to message file at level 0 (no echo
to the terminal). Some messages may get truncated.
DOCRT is not used when DOWAIT < 2.
OBITVERS...OBIT now is designed to run on python 3 or 2.7. If you
have a newer version of OBIT (post 01-Apr-2021) then you
may want the python3 version which is now the default.
If you need the older version, set OBITVERS=2.
INNAME.....Input UV data file (name). Standard defaults.
INCLASS....Input UV data file (class). Standard defaults.
INSEQ......Input UV data file (seq. #). 0 => highest.
INDISK.....Input UV data file disk drive #. 0 => any.
BCHAN......First channel number to image, 0=>1. Channel numbers are 1
relative as defined in the input data file.
ECHAN......Highest channel number to to include in image,
0 => max The actual # of output channels will be
(BCHAN-ECHAN+1-NCHAV)/CHINC + 1
Thus, ECHAN is the highest channel in the input averaged
into the output and is the highest output channel only if
NCHAV and CHINC are 1.
NCHAV......NCHAV is the number of channels to be averaged together
in in the gridding process. 0 => 1. If this value is less
than the total number of channels, then a multi-channel
image will result.
CHINC......Number of input channels to skip between images. 0 => 1
BIF........The lowest numbered IF to include. Multiple IFs can be
included in a bandwidth synthesis average. 0 => 1.
EIF........The highest numbered IF to include. 0 =>highest.
Note: not all data sets will have IFs.
OUTNAME....The output image name will be the source name + Stokes +
the contents of OUTNAME in that order.
OUTSEQ.....Output sequence number. 0 => highest to produce unique maps
and beam. Note that this will produce, potentially, maps
and beams with a variety of sequence numbers depending on
what files are already on disk. If OUTSEQ > 0, all images
and beams for all fields are assigned that sequence number
and pre-existing files are reused. An error will occur if
the pre-exsitng files are of different sizes than the ones
currently being requested.
OUTDISK....The disk drive # of output images. 0 => highest with space
Image and Beam go on same disk. Note: OUTCLASS='xCLnnn'
where x=Stokes, nnn=field number and 'xBMnnn' is the beam
CLASS. If NITER=0, OUTCLASS='xIMnnn'
FOV........Radius of the field-of-view to be imaged in degrees.
NO DEFAULT.
CELLSIZE...(X,Y) pixel separation in asec. 0,0 => let Imager
choose which is a reasonable option. Imager will choose
the IMSIZE for you in any case.
UVTAPER....(U,V) Gaussian taper (kilo-lambda) at 30 percent level
0,0 => no taper.
ROBUST.....Briggs' "robustness" parameter. "Uniform" weights are
tempered by a constant being added to the local density of
weights. ROBUST = -4 is nearly pure uniform weighting,
ROBUST = +4 is nearly pure natural weighting. Use of this
option requires a second array in the "AP" memory and may
therefore force the data to be sorted. The option is
turned off if ROBUST < -7 and uniform weighting is turned
off is ROBUST > 7. See HELP ROBUST - the AIPS ROBUST
differs numerically from that of Briggs.
NITER......Clean iteration limit. 0 => no Cleaning.
FLUX.......Stop Clean when abs(resid. image max) < FLUX (Jy) If FLUX
< 0 then Clean stops at first negative Clean Component.
IM2PARM....(1) > 0 => automatically find Clean boxes - Bill Cotton
recommends this option highly.
<= 0 => Clean the full inscribed circle.
PRTLEV.....Level of messages desired. 0 -> 2 which is the usual
IMAGR level of messages. Use 1 for a modest set of
messages and 3 for more than you would normally want.
DOTV.......> 0 => try to use ObitView to view and interact with the
imaging process. ObitView needs to be running for
this to work probably.
<= 0 => don't try.
NTHREAD....Use this number of threads when executing Imager. 0 ->
1. Imager will make excellent use of multi-threading.
BADDISK....This array contains the numbers of disks on which it is
desired that scratch files not be located. BADDISK has no
effect on input and output maps.
EXPLAIN SECTION
***************************************************************
***************************************************************
Note that most of these capablities are not offered by
the OBITMAP verb. The full Imager help file follows:
***************************************************************
***************************************************************
Imager Imaging task for radio interferometry data
Type: Task
Use: Batch processing of radio interferometry data
The products of this task are a CLEAN image.
Unless otherwise specified, a fly's eye pattern of
fields with circular CLEAN boxes will be used to cover the specified
field of view (FOV). When processing is finished, the CLEAN images
are "flattened" onto a single image.
If multiple sources are being processed, some failures are allowed.
In this case, the error messages will be displayed and the Status in
the PS table set to "Failed " rather than "Done ".
Greisen variant of Steer-Dewdney-Ito CLEAN implemented via
SDIGain
If BLFact > 1.0 then the input data will be subjected to a
baseline dependent time averaging.
Adverbs:
DataType..'FITS' or 'AIPS' type of input
inFile.....FITS input uvdata if Type=='FITS'
inName.....Input multisource UV data file
inClass....Input UV data file (class). Standard defaults.
inSeq......Input UV data file (seq. #). 0 => highest.
inDisk.....Input UV data file disk drive #. 0 => any.
Data selection
doPS.......If true, the PS (Processing Summary) table,
if it exists, is searched and fields already processed,
present and Status 'Done' will not be reprocessed.
Sources....List of sources (pointings) to be processed.
'*' or blank = all; a "-" before a source name
means all except ANY source named.
Qual.......Only sources with a source qualifier number in the
SU table matching Qual will be used if Qual is not
-1. Qual affects the selection of both the list of
sources and the list of calibrators.
souCode....Calibrators may be selected on the basis of the
calibrator code given in the SU table.
' ' => any calibrator code selected
'* ' => any non blank code (cal. only)
'-CAL' => blank codes only (no calibrators)
anything else = calibrator code to select.
NB: The souCode test is applied in addition to the
other tests, i.e. Sources and Qual, in the
selection of sources to process.
timeRange..Time range of the data to be processed. In order:
Start and end times in days relative to ref. date.
Use dhms2day to convert from human readable form
Stokes.....Stokes parameters to process.
'I' = Stokes I only, 'IQU' = also Q, U
'RR', 'LL' also.
' ' => I, Q, U,
'F'=> formal I (both orthogonal Stokes needed)
FreqID.....Frequency identifier to select , <=0=>any
BChan......First channel number to image, 0=>1. Channel numbers are 1
relative as defined in the input data file.
EChan......Highest channel number to to include in image,
0 => max
RChan......Channel number to restart CLEAN
0 => BChan
chInc......Increment between channels to image in spectral cube.
This is after averaging due to BLchAvg
chAvg......Number of channels to average, 0=> all
This is after averaging due to BLchAvg
BIF........First IF to process. 0=>1
EIF........Highest IF to process 0=> do BIF to highest.
Note: not all data sets will have IFs.
subA.......Sub-array number to use. 0=>all.
doCalib....If true, apply SN or CL table
gainUse....CL/SN table version number to apply. 0=> highest.
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.
Imager uses doBand as the nearest integer; 0.1 is therefore
no correction.
BPVer......Specifies the version of the AIPS BP table to be applied
0 => highest numbered table.
<0 => no bandpass correction to be applied.
flagVer....AIPS FG table to use for editing. 0 => highest.
doPol......>=1 apply polarization calibration
Alpha......If != 0.0 then correct data by spectral index Alpha before
imaging and self calibration.
-0.7 is typical for synchrotron.
BLFact.....Baseline dependent time averaging factor.
If BLFact>1.00 then the input data is time averaged in
a baseline dependent fashion and written to the output
data for further processing.
Use the following parameters:
BLFact = Maximum allowable amplitude loss due to time
averaging
BLFOV = Field of view over which the amplitude distortion
is not to exceed BLFact.
The lesser of solPInt and solAInt is used for the
maximum averaging time.
If both are zero, 1 min. is used
This option can substantially reduce the data volume and
reduce processing time.
A value between 1.004 and 1.01 give a good tradeoff between
dynamic range and data reduction.
BLFOV......The radius of the field of view over which baseline
dependent averaging is not to distort amplitudes by more
than BLFact. Defaults to FOV.
BLchAvg....If doing baseline dependent averaging then also average
selected channels by no more than will give bandwidth
smearing of BLFact.
doFull.....If True make full field (flattened) image
Output files
outDType..'FITS' or 'AIPS' type of output
Defaults to DataType.
outFile....Ending of output FITS image file name
filename = source_name+Stokes+outFile
outName....Ending of output AIPS Image Name,
Name = source_name+Stokes+outName
outClass...Output image class. Default = 'ICLEAN'
Only the last 5 characters given are used and the
first is replaced with the Stokes.
Output image name = pointing name (SOURCES)
The output CLEAN image will be used during
execution as the residual image.
outSeq.....Output image sequence number.
outDisk....The disk drive # of output images. 0 => highest
with space (note: map and Beam go on same disk.
CCVer......CC table version number for continuum data only.
For line data the channel number is used for the
version number.
out2File...Ending of output FITS UV data file name
filename = source_name+Stokes+out2File
Defaults to 'UV'
This file will contain the last selected data
with any calibration tables.
out2Name...Ending of output AIPS UV data Name,
Name = source_name+Stokes+out2Name
Defaults to 'UV'
This file will contain the last selected data
with any calibration tables.
out2Class..Output uv data class. Default = 'IMAGER'
out2Seq....Output AIPS uv data sequence number.
out2Disk...The disk drive # of output uv date. 0 => highest
with space. default = outDisk
The following control imaging:
FOV........Radius of the desired field of view in deg..
NField.....Optional parameter to specify fields and overrides
the FOV parameter. Up to 64 may be specified as
parameters; you should have a good reason for doing
this as the default behavior is usually what is
desired.
xCells [optional] Image cell spacing in X in asec.
If left 0 then the program will compute the value
from the data. All fields use the same value.
yCells [optional] Image cell spacing in Y in asec.
If left 0 then the program will compute the value
from the data. All fields use the same value.
nx.........[optional] Number of x pixels in each field specified.
ny.........[optional] Number of y pixels in each field specified.
RAShift....[optional] RA shift (asec) per field
DecShift...[optional] Dec shift (asec) per field
Catalog....Name of FITS file containing outlier catalog
Default NVSSVZ.FIT
This must be in the form of an "AIPS VZ" table.
'None' =. Use no outliers
OutlierDist..max. distance from pointing to include (deg)
default = 10
OutlierFlux..min. estimated flux density (Jy)
default = 0.05
OutlierSI....Spectral index to use, default = -0.7
OutlierSize.. Size in pixels of confusing fields, default 50
NB: This should not be so large as to cause the
outlying fields to be larger than the fields tiling
the FOV or the program may die.
UVTaper....(U,V) Gaussian taper (kilo-lambda) at 30 percent level
as (major, minor axis, position angle)
UVRange....(Minimum,Maximum) baseline (kilo-lambda) to
process.
Robust.....Briggs' "robustness" parameter. "Uniform" weights are
tempered by a constant being added to the local density of
weights. Robust = -4 is nearly pure uniform weighting,
Robust = +4 is nearly pure natural weighting. Use of this
option requires a second array in the memory and may
therefore force the data to be sorted. The option is
turned off if Robust < -7 and uniform weighting is turned
off is Robust > 7.
WtBox......(U,V) box size for weighting. This is the support radius
over which a sample is counted. I.e., the sample or its
weight is counted over an area 2*WtBox+1 cells on each side
in the UV plane, where the UV cell size is (after
correcting units) given by 1 / (UVSIZE(i) * Cellsize).
WtFunc.....If WtBox > 0, WtFunc controls how the samples are counted
as a function of u and v (WtFunc < 0) or of radius (WtFunc
> 0). In the latter case, the function is 0 for radius >
WtBox. Functions are pill box, linear, exponential, and
Gaussian for abs(WtFunc) = 1-4, resp. 0 -> 1.
doFull.....Make full field (flattened) image?
Otherwise only make facets and leave them.
doRestore..Restore CCs to images?
do3D.......If True, make the reference pixel in each facet tangent
to the celestial sphere, else on single tangent plane.
If False, CLEAN components are left on flattened image.
The following control CLEANing:
CLEANBox...A 4x50 array with the specification of a search
area.
Box(1,i)=-1 indicates a circle of radius Box(2,i)
pixels centered on (Box(3,i), Box(4,i))
Box(1,i) >= 0 indicates a rectangular box.
0 => full and inner fields.
If a round box is specified with pixel positions<=0 then
the box will be centered on the center of the image.
Note: the default boxes are set on the basis of
the image size, tilling pattern and autoWindow
autoWindow.If true, automatically set boxes around significant
emission. (Highly recommended)
Gain.......The CLEAN loop gain. 0 => 0.10.
minFlux...Stop Clean when abs(resid. image max) < minFlux (Jy)
If minFlux < 0 then Clean stops at first negative Clean
Component.
minPatch..Minimum half width of the portion of the beam
which is used in the minor CLEAN. Default 500
Niter.....CLEAN iteration limit. 0 => 1500
ccfLim....Limit CLEAN in each major cycle not to CLEAN below
ccfLim times the initial residual peak.
If using SDIGain, set to the maximum value of 0.9.
SDIGain...Fraction of pixels in the upper half of the pixel
histogram to trigger SDI mode. <=0 -> no SDI CLEAN.
If this test is satisfied then all pixels above
a threshold determined will be the site of a new CLEAN
component with a value depending on the local density
of pixels above this threshold.
This is the Greisen implementation of Steer-Dewdney-Ito
CLEAN.
A value of 0.1 is a reasonable initial value
Beam......CLEAN restoring beam major, minor axis size in asec and
the position angle. If zeroes, fit beam.
Reuse.....If >0 then each cycle of self cal after the first will
begin with all summed components whose abs value exceeds
Reuse*RMS(Field 1). Default 10
autoCen...If the sum of the clean components within 1.5 pixels
of any pixel exceeds autoCen and is not within 0.05 of a cell
of a pixel then the image is remade and deconcolved with the
bright sources (>autoCen, one per facet) on a pixel.
This is necessary to achieve high dynamic range.
If the initial dirty image has a pixel brighter than autoCen
then it presumes that the final image will need centering and
the initial CLEAN is stopped at minFlux=0.1*autoCen
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.
PBCor......Apply Frequency dependent primary beam corrections?
antSize....Diameter of antenna for PBCor (m), default = 25
CCFilter...Clean component filtering parameters.
If [0] > 0.0 then for each CLEAN conponent, the
sum of all components within CCFilter[1] cells
is determined, and if less than CCFilter[0], the
component is rejected.
This is done after all self-calibration, CLEANing is done
and if necessary the residuals remade.
maxPixel...The maximum number of pixels that are searched for
components in each major cycle. < 3000
=> 20050. This number affects the cpu usage significantly.
Too many causes the task to search over many points it will
never use. Too few causes the task to do many more small
major cycles, also at great expense. Use this with great
caution, but big wins are possible using larger sizes on
very large Cleans.
Selfcal info
Either phase only or amplitude and phase or both types of
Self calibration can be performed. If both are done, then
phase calibration is done first and applied to the data before
Amp & Phase self calibration. In any case, there will be an
SN table attached to the output uv data which is needed to
fully calibrate it.
maxPSCLoop..Maximum number of phase self calibration loops
minFluxPSC..Min. peak flux density required for phase self cal (Jy)
solPInt.....phase SC Solution interval (min)
solPType....phase SC Solution Type: ' ', 'L1',
solPMode....phase SC Solution Mode:'A&P', 'P', 'P!A',
maxASCLoop..Maximum number of A&P self calibration loops
minFluxASC..Min. peak flux density required for A&P self cal (Jy)
solAInt.....A&P SC Solution interval (min)
solAType....A&P SC Solution Type: ' ', 'L1',
solAMode....A&P SC Solution Mode:'A&P', 'P', 'P!A',
refAnt......Reference antenna number for selfcal
WtUV........Weighting (wrt 1) to use outside of basic uv range in SC
avgPol......Average Polarizations in self calibration?
avgIF.......Average IFs in self calibration?
noNeg.......If True, exclude negative summed CLEAN components from the
self-cal model calculation. This is useful if the initial
calibration is poor and there are negative components due
to phase errors but is harmful if the initial calibration is
relatively good and the negative components are needed to
describe a high dynamic range image (say DR>1000:1)
doMGM.......Apply mean gain modulus to A&P selfcal soln.
minSNR......Min. allowed SNR in self cal solution
minNo.......Min. allowed no. antennas in selfcal
prtLv.......Print level in selfcal, 0=>none
Peeling
PeelFlux....Peeling is the procedure of doing a self calibration on
a single source, removing it and reverting to the
previous calibration. This is useful for a very strong
source whose artifacts disturb the other parts of the
field. If the maximum pixel value in any image
(as defined by the CLEAN components) exceeds PeelFlux,
then the facet in which the maximum value occured is
peeled. This procedure is iterated until no facet has a
pixel in excess of PeelFlux.
NB: peeling of many sources will likely degrade the
results.
It is strongly recommended that autoCen be no larger
than PeelFlux so that the source is properly centered in
its facet.
PeelLoop....Maximum number of peeling self calibration loops
PeelRefAnt..Reference antenna number for Peel selfcal
PeelSNRMin..Min. allowed SNR in peeling self cal solution
PeelSolInt..Peel SC Solution interval (min)
PeelType....Peel SC Solution type ' ', 'L1'
PeelMode....Peel SC Solution mode:'A&P', 'P', 'P!A',
"P" is used for all but the last peel which uses PeelMode
PeelNiter...Max. number of components in Peel CLEAN
PeelMinFlux.Min. Peel CLEAN flux density
PeelAvgPol..Average Polarizations in Peel self calibration?
PeelAvgIF ..Average IFs in Peel self calibration?
Multiresolution CLEAN
A multiresolution CLEAN is enabled using nTaper>0.
This allows multiple circular imaging tapers to be
specified in units of pixels; full resolution is
generally 3-8 pixels. The full mosaic is reproduced in
each resolution
Each major cycle, which resolution is to be used is
picked on the basis of image statistics, the weightings
of which are controled by MResKnob.
The objective function used to chose the resolution is
given by:
fact1 * (maxTaper - Taper)/maxTaper +
fact2 * (resid_peak/resid_RMS) +
fact3 * quality
where
fact1 is from the reduced MResKnob[0]
fact2 = MResKnob[1]
fact3 = MResKnob[2]
maxTaper is the highest beam taper (lowest res)
Taper is the beam taper of the given resolution
resid_peak is the peak residual in the facet
resid_RMS is the robust RMS of the residual
quality is the measure used to pick amoung the facets
at a given resolution and is a function of peak and
average residual.
The comparison is performed on the facet at each
resolution with the highest "quality".
nTaper......Number of resolutions expressed as the number of tapers
to be applied to the data
Tapers......List of circular Gaussian tapers in (x) pixels.
MResKnob....Controls on selecting resolution to be CLEAned next.
[0] Bias towards higher resolution, 0=>0.2
As the CLEAN progresses, this factor is reduced by
(1-iteration/niter)**3
[1] SNR factor, 0=>0.35
[2] "Quality" factor, 0=>0.2
Interactive display
dispURL.....The URL of the display server to use. "None"=>none
"ObitView" = "http://localhost:8765/RPC2"
This will display fields being CLEANed and allow
interactive editing of the CLEAN window.
If the display is running on a machine on which the
data is not visible, use "http://myhost:port/RPC2"
where myhost is the network name and port is the port
number (usually 8765), Example:
dispURL="http://canis.cv.nrao.edu:8765/RPC2"
nThreads....If The Obit libraries are compiled with multiple
thread operation enabled, this parameter sets the
number of threads that can be used for parallel
operations.
NB: This only improves performance if there are
multiple processors and/or cores in the host.
taskLog.....Log file to write messages to INSTEAD of the terminal
This is useful in long runs or batch files where
a bug in the ObitTalk message handling may cause
tasks to hang. Path is absolute or relative to where
the task executes.
noScrat.....A list of AIPS disk numbers on which you do not
wish scratch files