AIPS HELP file for TVSPX in 31DEC25
As of Mon Feb 17 7:57:08 2025
TVSPX: Finds spectral index of each image row with edits
INPUTS
INNAME Input image name (name)
INCLASS Input image name (class)
INSEQ 0.0 9999.0 Input image name (seq. #)
INDISK 0.0 9.0 Input image disk unit #
OUTNAME Output image name (name)
OUTSEQ -1.0 9999.0 Output image name (seq. #)
OUTDISK 0.0 9.0 Output image disk unit #.
BLC Bottom left corner of input
TRC Top right corner of input
FLUX Use only data > FLUX
REFREQ Reference frequency in GHz
< 0 -> header, 0 -> 1 GHz
OPTYPE 'CURV' fit incl curvature
PBPARM Beam parameters:
(1) Cutoff: 0 -> no PB corr
(2) > 0 -> Use (3)-(7)
(3)-(7) Beam shape
DPARM Flag if bad answer levels:
(1) N < (2) Sp < (3) Sp >
(4) T/min < (5) T/max >
(6) T < (7) T > (8) c <
(9) c >
CPARM Flag if uncertainty >
(1) Brightness
(2) Spectral index
(3) Curvature
BADDISK Disk to avoid for scratch
HELP SECTION
TVSPX
Task: Fits each row of an image cube to make an image of spectral
index (intensity = frequency to the power spectral index).
It make images of the uncertainties and may be instructed
to fit the curvature as well. TVSPX actually fits the function
log(T(x,y,f)) = log(T(x,y,f0)) + S(x,y) log(f/f0) +
C(x,y) (log(f/f0))^2
and writes images of T(x,y,f0), S(x,y), and C(x,y). Note that
the logarithms are base 10 and f0 is set by the user with a
default of 1 GHz. These affect the values in the curvature
image.
It is an error to feed this task any data cube not having the
first axis as FREQ, FQID, or SEQ.NUM. One may build a data
cube for use in this task. First one must make the image at
each frequency lie on the same coordinate grid (OHGEO) and have
similar spatial resolution (CONVL). If it might matter, it
would be best to correct for the single-dish primary beam
pattern (PBCOR). Then build the cube with MCUBE using
DOCONCAT=TRUE. Finally run TRANS to transpose the cube, making
the frequency (FQID usually or SEQ.NUM.) axis first. If the
axis is SEQ.NUM. then, in TRANS, do not reverse the order of
the frequency pixels since TVSPX must read the history file to
find the true frequencies for each pixel number. If the axis
is FQID, this caution does not apply.
TVSPX provides only very elementary blanking capabilities.
Normally, users will wish to do more elaborate blanking with
BLANK before running TVSPX. The data cube must have the same
spatial resolution and units in all spectral channels. If not,
the resolutions and units issues alone will create erroneous
spectral indices. Running CONVL specifying BMAJ, BMIN, BPA
after running IMAGR with BMAJ=0 is recommended.
The TV options resemble those in XGAUS, RMFIT, and ZEMAN. The
model is fit to all voxels of the input cube, with results
blanked based on FLUX, CPARM, and DPARM. The main TV function
offers to display the images of the results of the fit and
offers editing options to try to improve and undesirable results.
See EXPLAIN TVSPX for more details.
Adverbs:
INNAME.....Input image name (name). Standard defaults.
INCLASS....Input image name (class). Standard defaults.
INSEQ......Input image name (seq. #). 0 => highest.
INDISK.....Disk drive # of input image. 0 => any.
OUTNAME....Output image name (name). Standard defaults.
The OUTCLASSes are 'B TEMP', 'D BT', 'SP CNT', 'SPIX',
'D SPIX', 'SPCU', 'D SPCU' for brightness, brightness
uncertainty, count, spectral index, spectral index
uncertainty, curvature, and curvature uncertainty.
OUTSEQ.....Output image name (seq. #). 0 => highest unique.
OUTDISK....Disk drive # of output image. 0 => highest
number with sufficient space.
BLC........Bottom right corner in input image of desired
subimage. Default is entire image.
TRC........Top right corner in input image of desired
subimage. Default is entire image.
FLUX.......A flux cutoff in the same units as the input image (i.e.
Jy/beam). Data values below FLUX are ignored in the
spectral index computation. NOTE that 0.0 is not a null
value. Instead, it means ignore all negative
brightnesses (which it has to do anyway).
REFREQ.....Compute total flux, spectra index and curvature with
reference frequency REFREQ in GHz
0 => use 1 GHz; < 0 => use header frequency
Output images will be assigned this as the frequency.
OPTYPE.....'CURV' => fit curvature as well as spectral index
anything else => fit only spectral index.
PBPARM.....Primary beam parameters: Adjust the cutoff levels to
account for the primary beam.
(1) Lowest beam value to believe: 0 -> do not do a
primary beam correction. The maximum correction is
a factor of 100.
(2) > 0 => Use beam parameters from PBPARM(3)-PBPARM(7)
Otherwise use default parameters for the VLA (or
ATCA where appropriate)
(3-7)..For all wavelengths, the beam is described by the
function:
1.0 + X*PBPARM(3)/(10**3) + X*X*PBPARM(4)/(10**7) +
X*X*X*PBPARM(5)/(10**10) + X*X*X*X*PBPARM(6)/(10**13)
X*X*X*X*X*PBPARM(7)/(10**16)
where X is (distance from the pointing position in arc
minutes times the frequency in GHz)**2.
See explain for details
DPARM......The images can be dominated by bad answers, making it
hard to see the good parts. Therefore flag the solution
for a pixel if
(1) Number samples > FLUX is < DPARM(1) 0 -> 0
NOTE: solutions will be found for only 2 or 3 (CURV)
samples - so this is a serious thing to test.
(2) Spectral index < DPARM(2) 0 -> -large
(3) Spectral index > DPARM(3) 0 -> +large
(4) Brightness/(min brightness) < DPARM(4) 0 -> 0
(5) Brightness/(max brightness) > DPARM(5) 0 -> +large
(6) Brightness < DPARM(6) 0 -> 0
(7) Brightness > DPARM(7) 0 -> +large
(8) Curvature < DPARM(8) 0 -> -large
(9) Curvature > DPARM(9) 0 -> +large
You should invoke some of these - 2,3 and 8,9 at least.
CPARM......The image can also be messed up by fits that are very
uncertain. Therefore, flag the solution for a pixel if
(1) Uncertainty in brightness > CPARM(1) 0 -> large
(2) Uncertainty in spectral index > CPARM(2) 0 -> large
(3) Uncertainty in curvature > CPARM(3) 0 -> large
BADDISK....Disk drives to avoid for scratch files.
EXPLAIN SECTION
TVSPX: One-dimensional spectral index fitting of data cubes
Documenter: E. W. Greisen NRAO
Related Programs: SPIXR, MCUBE, FQUBE
After all pixels that are strong enough have been given a solution,
TVSPX enters a menu-driven function. The menu has in the left column:
| EXIT | Exit TVSPX, writing output images
| ABORT | Exit TVSPX, deleting the output images.
| |
| SET BRIGHT RANGE | Set brightness range for okay solutions
| SET SPIX RANGE | Set range for okay spectral index solutions
| SET CURV RANGE | Set range for okay spectral curvature solutions
| SET MAX ERR BR | Set maximum error in brightness for okay
solutions
| SET MAX ERR SPIX | Set maximum error in spectral index for okay
solutions
| SET MAX ERR CURV | Set maximum error in curvature for okay solutions
| REDO ALL | Re-do all solutions which are not okay
| FLAG ALL | Mark bad all solutions which are not okay
| |
| ADD TO LIST | Type in output pixel coordinates to add to list
| CLEAR LIST | Clear the list
| SHOW LIST | Display coordinates in list
| REDO LIST | Re-do solutions for all pixels in list
| FLAG LIST | Flag solutions for all pixels in list
| |
| OFF ZOOM | Turn of TV zoom
| OFF TRANSFER | Turn off black & white and color TV enhancements
| RESET WINDOW | Display full view of current image
| LABEL WEDGE? | Turn on/off labeling of step wedge
| CHAR MULT | Change the character size multiplier
Two editing concepts are present in this menu. The first is to
establish what parameter values (brightness, spectral index, spectral
curvature, and errors thereof) constitute an "okay" solution. The
selected limits are displayed above the menu. Then you can choose to
try to REDO ALL solutions which are not okay or simply FLAG ALL,
marking them as bad. The second concept is to create a list of up to
1000 pixels which are thought to have some problem. You can enter
these pixels by hand (or remove pixels from the list by hand) with
ADD TO LIST. A faster way to add to the list is to show the image of
some parameter and then select interesting pixels while doing CURVALUE
(see below). The list of pixels can be re-done (REDO LIST) or marked
as bad (FLAG LIST). The list is cleared by these operations.
The right hand column of options include:
| SHOW IMAGE NP | Enter image interaction with number channels
| SHOW IMAGE BR | Enter image interaction with brightness
| SHOW IMAGE EBR | Enter image interaction with brightness error
| SHOW IMAGE SP | Enter image interaction with spectral index
| SHOW IMAGE ESP | Enter image interaction with spix error
| SHOW IMAGE CU | Enter image interaction with curvature
| SHOW IMAGE ECU | Enter image interaction with curv error
Selecting one of these causes the appropriate image to be displayed
and a new menu to appear:
| RETURN | Return to the above menus, image stays displayed
| |
| LOAD AS SQ | Re-load image with square root transfer function
| LOAD AS LG | Re-load image with log transfer function
| LOAD AS L2 | Re-load image with extreme log transfer function
| LOAD AS LN | Re-load image with linear transfer function
| SET WINDOW | Set a sub-image to view
| RESET WINDOW | Return to viewing the full image
| OFF TRANSF | Turn off enhancement done with TVTRANSF
| OFF COLOR | Turn off color enhancements
| TVTRANSF | Black & white image enhancement
| TVPSEUDO | Color enhancement of numerous sorts
| TVPHLAME | Color enhancement of flame type, multiple colors
| TVZOOM | Interactive zooming and centering of image
| CURVALUE | Display value under cursor, mark pixels for list
| IMSTAT | Compute statistics of current image window
| NEXT WINDOW | Move to next window in large images
Only one of the LOAD AS xx options is offered - SQ when the current
function type is LN, LG when the current function type is SQ, L2 when
the current function type is LG, and LN when the current type is L2.
Selecting this option, reloads the image with the newly selection
function type and changes the menu option accordingly. The options
OFF TRANSF through TVZOOM are essentially the same as the
corresponding verbs in AIPS. CURVALUE is like the verb of that name,
but, when you press buttons A or B, the pixel under the cursor is
added to the editing list.
Very large images may not be able to fit on your TV. When the image
exceeds the size of the TV, the top line will show the parameter
followed by a subimage number in parentheses and the NEXT WINDOW
option will appear. The first sub-image displayed is called number
0 and shows the full image every n'th pixel in X and Y. Sub-image 1
begins at the lower left, moves right, then back to the left and up,
and so forth until the top right is reached. Every pixel is
displayed in these sub-images. Use the NEXT WINDOW option to step
through the sub-images in a circular fashion.
The REDO ALL and REDO LIST invoke another display, one spectrum at a
time. The spectrum (as plus signs) and the current fit (as connected
line) are displayed. Then a menu if offered:
| CHAN RANGE | To select a range of channels in the spectrum
| RESET CHANS | To select all channels in the current spectrum
| FLAG POINTS | To mark samples to leave out of the fit
| UNDO FLAGS | To restore all samples
| NEW FIT | To fit the unflagged spectrum samples
| |
| GOOD | To return the current fit to the outputs
| BAD | To flag this pixel in the output images
| |
| QUIT | To terminate the current REDO ALL or REDO LIST
These functions allow you to omit certain spectral points from the fit
in the hopes of getting a better fit. The CHAN RANGE option allows
you to see the samples more clearly in a crowded spectrum display. The
channel range is used in FLAG POINTS but all channels are used in the
NEW FIT. If that fit fails for any reason including the limits in DPARM
and CPARM, the flagged samples will be unflagged. You have the choice
to assert BAD to flag the pixel, GOOD to keep the original fit, or to
try again with different flagging.
------------------------------------------
TVSPX has the option of scaling the cutoff values on a
pixel-by-pixel basis to "correct" for the primary beam. Thus, as the
beam value goes down the cutoff value goes up. This allows TVSPX to be
run on data cubes after the application of PBCOR. Since the primary
beam is a function of frequency, the spectral moments are affected by
the primary beam correction. Unfortunately this correction also
raises the noise, making the option to raise the cutoff useful.
TVSPX corrects an image for the primary beam attenuation of
the antennas. The function used to model the primary beam for normal
VLA frequencies
F(x) = 1.0
+ parm(3) * 10E-3 * x
+ parm(4) * 10E-7 * x*x
+ parm(5) * 10E-10 * x*x*x
+ parm(6) * 10E-13 * x*x*x*x
+ parm(7) * 10E-16 * x*x*x*x*x
where x is proportional to the square of the distance from the
pointing position in units of [arcmin * freq (GHz)]**2, and F(x)
is the multiplicative factor to divide into the image intensity at the
distance parameter x. For other antennas, the user may read
in appropriate constants in PBPARM(3) through PBPARM(7). The
flag, PBPARM(2) must be set to a positive number to invoke this
option and PBPARM(3) must not be zero.
This correction scales with frequency and has a cutoff
beyond which the map values are set to an undefined pixel value GIVEN
in PBPARM(1). At the VLA frequencies the default cutoff is
1.485 GHz 29.8 arcmin
4.885 GHz 9.13 arcmin
15 GHz 2.95 arcmin
22.5 GHz 1.97 arcmin
and occurs at a primary beam sensitivity of 2.3 percent of the value at
the beam center. Corrections factors < 1 are forced to be 1.
The estimated error of the algorithm is about 0.02 in (1/F(x))
and thus leads to very large errors for x>1500, or at areas
outside of the primary response of 20 percent. The cutoff level
may be specified with DPARM(1).
Default values of PBPARM for the VLA are given by Perley's fits:
0.0738 GHz -0.897 2.71 -0.242
0.3275 -0.935 3.23 -0.378
1.465 -1.343 6.579 -1.186
4.885 -1.372 6.940 -1.309
8.435 -1.306 6.253 -1.100
14.965 -1.305 6.155 -1.030
22.485 -1.417 7.332 -1.352
43.315 -1.321 6.185 -0.983
For the ATCA, these are by default:
1.5 GHz -1.049 4.238 -0.8473 0.09073 -5.004E-3
2.35 -0.9942 3.932 -0.7772 0.08239 -4.429E-3
5.5 -1.075 4.651 -1.035 0.12274 -6.125E-3
8.6 -0.9778 3.875 -0.8068 0.09414 -5.841E-3
20.5 -0.9579 3.228 -0.3807 0.0 0.0
For the Karl G Jansky VLA ("EVLA"), the defaults are frequency
dependent. If the observing frequency is between two tabulated
frequencies, then the beam is computed for each of the tabulated
frequencies and then interpolated to the observing frequency. The
values used are far too numerous to give here, see EVLA Memo 195,
"Jansky Very Large Array Primary Beam Characteristics" by Rick Perley,
revision dated June 2016. Obtain it from
http://library.nrao.edu/evla.shtml