; HLPRMFIT ;--------------------------------------------------------------- ;! Polarization fitting task RMFIT - run-time help ;# TASK MODELING INTERACTIVE TV-APPL POLARIZATION ;----------------------------------------------------------------------- ;; Copyright (C) 2013-2016 ;; Associated Universities, Inc. Washington DC, USA. ;; ;; This program is free software; you can redistribute it and/or ;; modify it under the terms of the GNU General Public License as ;; published by the Free Software Foundation; either version 2 of ;; the License, or (at your option) any later version. ;; ;; This program is distributed in the hope that it will be useful, ;; but WITHOUT ANY WARRANTY; without even the implied warranty of ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the ;; GNU General Public License for more details. ;; ;; You should have received a copy of the GNU General Public ;; License along with this program; if not, write to the Free ;; Software Foundation, Inc., 675 Massachusetts Ave, Cambridge, ;; MA 02139, USA. ;; ;; Correspondence concerning AIPS should be addressed as follows: ;; Internet email: aipsmail@nrao.edu. ;; Postal address: AIPS Project Office ;; National Radio Astronomy Observatory ;; 520 Edgemont Road ;; Charlottesville, VA 22903-2475 USA ;----------------------------------------------------------------------- C----------------------------------------------------------------------- EXIT This option causes the interactive portion of RMFIT to finish. The task then resumes, AIPS, releases the TV device, and, if DOOUTPUT is greater than zero, writes the output cataloged images. The residual is written if DOOUTPUT = 1 or 3 and the parameter images are written if DOOUTPUT = 2 or 3. C----------------------------------------------------------------------- SET MIN S/N This option allows you to specify the minimum signal to noise ratio in total polarization for acceptable solutions. One ratio for each of the NGAUSS components will be required. The REDO ALL and FLAG ALL operations use this value to test whether a solution should be redone or flagged, resp. A value of 0 or less will cause the test for the specific polarization component to be ignored. The current values of these parameters are displayed above the menu. C----------------------------------------------------------------------- SET MIN P1 This option allows you to specify the total polarization (at 1 GHz) for acceptable solutions. One minium for each of the NGAUSS components will be required. The REDO ALL and FLAG ALL operations use this value to test whether a solution should be redone or flagged, resp. A value of 0 or less will cause the test for the specific polarization component to be ignored. The current values of these parameters are displayed above the menu. C----------------------------------------------------------------------- SET MAX RESID This option allows you to specify the maximum residual for acceptable solutions. You will be prompted in the terminal window to enter one value in the units of the input image. The REDO ALL and FLAG ALL operations use this value to test whether a solution should be redone or flagged, resp. A value of 0 or less will cause the test for peak residual to be ignored. The current value of this parameter is displayed above the menu. C----------------------------------------------------------------------- SET RM RANGE This option allows you to specify the minimum and maximum rotation measure in acceptable solutions. One range for each of the NGAUSS components will be required. Units are radians per meter squared. The REDO ALL and FLAG ALL operations use these values to test whether a solution should be redone or flagged, resp. When the maximum is less than or equal the minimum the test on rotation measure for the specific polarization component is ignored. The current values of these parameters are displayed above the menu. C----------------------------------------------------------------------- SET MAX THETA ERR This option allows you to specify the maximum uncertainty in component POLARIZATION ANGLE for acceptable solutions. One maximum for each of the NGAUSS components will be required. The REDO ALL and FLAG ALL operations use this value to test whether a solution should be redone or flagged, resp. A value of 0 or less will cause the test for the specific polarization component to be ignored. The current values of these parameters are displayed above the menu. C----------------------------------------------------------------------- REDO ALL This option allows you to try to improve selected solutions. The operation examines all pixels for which there is a solution. If (1) the signal-to-noise ratio in total polarization in any component is below the minimum for that component, (2) the rotation measure in any component is outside the range of rotation measures for that component, (3) the uncertainty in the polarization angle of any component is greater than the maximum for that component, or (4) the peak residual after the fit components are subtracted is greater than the maximum residual, the solution for that row of the input image is done over. TV control of the initial guess is allowed even for single polarization fits in the hope of forcing a better solution. C----------------------------------------------------------------------- FLAG ALL This option allows you to flag selected solutions. The operation examines all pixels for which there is a solution. If (1) the signal-to-noise ratio in total polarization in any component is below the minimum for that component, (2) the rotation measure in any component is outside the range of rotation measures for that component, (3) the uncertainty in the polarization angle of any component is greater than the maximum for that component, or (4) the peak residual after the fit components are subtracted is greater than the maximum residual, the solution for that row of the input image is marked as failed. C----------------------------------------------------------------------- OFF ZOOM This option in the main menu allows you to turn off the zoom function selected with TVZOOM in the image display menu. C----------------------------------------------------------------------- OFF TRANSFER This option in the main menu turns of any black-and-white enhancements done by TVTRANSF and any coloring done by TVPSEUDO or TVPHLAME in the image display menu. C----------------------------------------------------------------------- SET DOOUTPUT The option cycles the value of the DOOUTPUT adverb from 0 through 3 and back to 0. The value of DOOUTPUT, displayed at the top of the TV screen, when the EXIT option is selected determines whether the residual image is written to disk (DOOUTPUT = 1 or 3) and whether the parameter images are written to disk (DOOUTPUT = 2 or 3). C----------------------------------------------------------------------- ADD TO LIST This option prompts you in the terminal window to enter 2 integers which specify the X, Y pixel coordinates in the output image of a pixel for which you would like to revisit the fit. You can prepare a list of pixels for revisiting using this option or CURVALUE in the image display menu. You can list these pixels (SHOW LIST) and you can the repeat the fitting of them with REDO LIST or simply flag them out with FLAG LIST. If you want to remove a pixel from the list, enter its pixel coordinates with negative signs. Note that the list may include pixels for which there is not currently a solution. C----------------------------------------------------------------------- SHOW LIST This option displays in the message window the current list of output image pixels which will be revisited with the REDO LIST and FLAG LIST options. ADD TO LIST may be used to add a pixel to or remove a pixel from this list. C----------------------------------------------------------------------- REDO LIST The output image pixels in the current list are revisited to see if it is possible to improve upon the current solutions (if any). The usual options to mark BAD, to REDO, to QUIT, and to turn off the TV interaction are all offered. The list is processed in inverse order and its length reduced as one goes. Thus a QUIT in the middle will leave the first part of the list untouched. Note that turning off the TV will eliminate any chance to enter better guesses to force a better fit. C----------------------------------------------------------------------- FLAG LIST The output pixels in the current list are revisited in the solutions table and those solutions are marked as failed. The list is reset after this operation. C----------------------------------------------------------------------- SWAP LIST 1-2 This option allows you to swap the solutions for polarization component 1 with those of polarization component 2 at all of the pixels in the list. The list is reset after this operation. C----------------------------------------------------------------------- SWAP LIST 1-2 This option allows you to swap the solutions for polarization component 1 with those of polarization component 3 at all of the pixels in the list. The list is reset after this operation. C----------------------------------------------------------------------- SWAP LIST 2-3 This option allows you to swap the solutions for polarization component 2 with those of polarization component 3 at all of the pixels in the list. The list is reset after this operation. C----------------------------------------------------------------------- SWAP LIST 1-4 This option allows you to swap the solutions for polarization component 1 with those of polarization component 4 at all of the pixels in the list. The list is reset after this operation. C----------------------------------------------------------------------- SWAP LIST 2-4 This option allows you to swap the solutions for polarization component 2 with those of polarization component 4 at all of the pixels in the list. The list is reset after this operation. C----------------------------------------------------------------------- SWAP LIST 3-4 This option allows you to swap the solutions for polarization component 3 with those of polarization component 4 at all of the pixels in the list. The list is reset after this operation. C----------------------------------------------------------------------- SHOW IMAGE P0_ These options allow you to enter an image display mode while displaying an image of the total polarization of the selected component. The value range in the image is displayed on the message terminal and at the top of the TV screen in input image units. The image display mode offers a menu including OFF TRANSF, OFF COLOR, TVTRANSF, TVPSEUDO, TVPHLAME, TVZOOM, CURVALUE, and RETURN. All are the familiar operations except that CURVALUE allows you to add to a pixel list for later re-examination of the solutions. You can also choose to re-load the image to the TV with a selection of transfer functions. C----------------------------------------------------------------------- SHOW IMAGE EP0_ These options allow you to enter an image display mode while displaying an image of the uncertainty in the total polarization of the selected component. The value range in the image is displayed on the message terminal and at the top of the TV screen in input image units. The image display mode offers a menu including OFF TRANSF, OFF COLOR, TVTRANSF, TVPSEUDO, TVPHLAME, TVZOOM, CURVALUE, and RETURN. All are the familiar operations except that CURVALUE allows you to add to a pixel list for later re-examination of the solutions. You can also choose to re-load the image to the TV with a selection of transfer functions. C----------------------------------------------------------------------- SHOW IMAGE TH_ These options allow you to enter an image display mode while displaying an image of the polarization position angle at zero wavelength of the selected component. The value range in the image is displayed on the message terminal and at the top of the TV screen in degrees. The image display mode offers a menu including OFF TRANSF, OFF COLOR, TVTRANSF, TVPSEUDO, TVPHLAME, TVZOOM, CURVALUE, and RETURN. All are the familiar operations except that CURVALUE allows you to add to a pixel list for later re-examination of the solutions. You can also choose to re-load the image to the TV with a selection of transfer functions. C----------------------------------------------------------------------- SHOW IMAGE ETH_ These options allow you to enter an image display mode while displaying an image of the uncertainty in the polarizatopn position angle at zero wavelength of the selected component. The value range in the image is displayed on the message terminal and at the top of the TV screen in degrees. The image display mode offers a menu including OFF TRANSF, OFF COLOR, TVTRANSF, TVPSEUDO, TVPHLAME, TVZOOM, CURVALUE, and RETURN. All are the familiar operations except that CURVALUE allows you to add to a pixel list for later re-examination of the solutions. You can also choose to re-load the image to the TV with a selection of transfer functions. C----------------------------------------------------------------------- SHOW IMAGE RM_ These options allow you to enter an image display mode while displaying an image of the rotation of the selected component. The value range in the image is displayed on the message terminal and at the top of the TV screen in radians/m/m. The image display mode offers a menu including OFF TRANSF, OFF COLOR, TVTRANSF, TVPSEUDO, TVPHLAME, TVZOOM, CURVALUE, and RETURN. All are the familiar operations except that CURVALUE allows you to add to a pixel list for later re-examination of the solutions. You can also choose to re-load the image to the TV with a selection of transfer functions. C----------------------------------------------------------------------- SHOW IMAGE ERM_ These options allow you to enter an image display mode while displaying an image of the uncertainty in the rotation measure of the selected component. The value range in the image is displayed on the message terminal and at the top of the TV screen in radians/m/m. The image display mode offers a menu including OFF TRANSF, OFF COLOR, TVTRANSF, TVPSEUDO, TVPHLAME, TVZOOM, CURVALUE, and RETURN. All are the familiar operations except that CURVALUE allows you to add to a pixel list for later re-examination of the solutions. You can also choose to re-load the image to the TV with a selection of transfer functions. C----------------------------------------------------------------------- SHOW IMAGE Q0_ These options allow you to enter an image display mode while displaying an image of the Q polarization at zero wavelength of the selected component. The value range in the image is displayed on the message terminal and at the top of the TV screen in image units. The image display mode offers a menu including OFF TRANSF, OFF COLOR, TVTRANSF, TVPSEUDO, TVPHLAME, TVZOOM, CURVALUE, and RETURN. All are the familiar operations except that CURVALUE allows you to add to a pixel list for later re-examination of the solutions. You can also choose to re-load the image to the TV with a selection of transfer functions. C----------------------------------------------------------------------- SHOW IMAGE EQ0_ These options allow you to enter an image display mode while displaying an image of the uncertainty in the Q polarization at zero wavelength of the selected component. The value range in the image is displayed on the message terminal and at the top of the TV screen in image units. The image display mode offers a menu including OFF TRANSF, OFF COLOR, TVTRANSF, TVPSEUDO, TVPHLAME, TVZOOM, CURVALUE, and RETURN. All are the familiar operations except that CURVALUE allows you to add to a pixel list for later re-examination of the solutions. You can also choose to re-load the image to the TV with a selection of transfer functions. C----------------------------------------------------------------------- SHOW IMAGE U0_ These options allow you to enter an image display mode while displaying an image of the U polarization at zero wavelength of the selected component. The value range in the image is displayed on the message terminal and at the top of the TV screen in image units. The image display mode offers a menu including OFF TRANSF, OFF COLOR, TVTRANSF, TVPSEUDO, TVPHLAME, TVZOOM, CURVALUE, and RETURN. All are the familiar operations except that CURVALUE allows you to add to a pixel list for later re-examination of the solutions. You can also choose to re-load the image to the TV with a selection of transfer functions. C----------------------------------------------------------------------- SHOW IMAGE EU0_ These options allow you to enter an image display mode while displaying an image of the uncertainty in the U polarization at zero wavelength of the selected component. The value range in the image is displayed on the message terminal and at the top of the TV screen in image units. The image display mode offers a menu including OFF TRANSF, OFF COLOR, TVTRANSF, TVPSEUDO, TVPHLAME, TVZOOM, CURVALUE, and RETURN. All are the familiar operations except that CURVALUE allows you to add to a pixel list for later re-examination of the solutions. You can also choose to re-load the image to the TV with a selection of transfer functions. C----------------------------------------------------------------------- RETURN This option returns from the image display menu to the primary menu to select a different image to display, to set data selection values, and to revisit selected solutions in order to modify or flag them. C----------------------------------------------------------------------- LOAD AS LN This option re-loads the current image using a linear transfer function from the image minimum to its maximum. The image you are now viewing was loaded with the L2 (extreme log) transfer function. C----------------------------------------------------------------------- LOAD AS SQ This option re-loads the current image using a square root transfer function from the image minimum to its maximum. The image you are now viewing was loaded with the LN (linear) transfer function. C----------------------------------------------------------------------- LOAD AS LG This option re-loads the current image using a logarithmic transfer function from the image minimum to its maximum. The image you are now viewing was loaded with the SQ (square root) transfer function. C----------------------------------------------------------------------- LOAD AS L2 This option re-loads the current image using a more extreme logarithmic transfer function from the image minimum to its maximum. The image you are now viewing was loaded with the LG (logarithmic) transfer function. C----------------------------------------------------------------------- SET WINDOW This option turns on a standard TVWINDOW operation to set the lower left corner and upper right corner of a sub-image that you would like to view in more detail. Buttons A and B switch between corners and buttons C and D set the desired window which is immediately displayed. C----------------------------------------------------------------------- RESET WINDOW This option returns the image display to the full image. C----------------------------------------------------------------------- OFF TRANSF This option turns of any black-and-white enhancements done in TVTRANSF. C----------------------------------------------------------------------- OFF COLOR This options turns of any color enhancements done in TVPSEUDO or TVPHLAME. Has no effect if the image is in black and white. C----------------------------------------------------------------------- TVTRANSF This option allows you to set the black-and-white transfer function using the TV cursor to control intercept and slope. Buttons A and B turn a plot of the LUT on and off, button C reverses the sign of the slope, and button D ends the enhancement and returns to the menu. Instructions appear on the message screen. C----------------------------------------------------------------------- TVPSEUDO This option allows you to set the color transfer function using the TV cursor. Button A loops through all possible RGB triangles, button B selects a circle in hue (which is very useful for phase displays), button C selects several color contours, and button D ends the enhancement and returns to the menu. As in AIPS, the TV cursor is used to adjust the colors within the selected function. Instructions appear on the message screen. C----------------------------------------------------------------------- TVPHLAME This option allows you to set the color transfer function using the TV cursor and a flame-like color scheme. Buttons A and B cycle through the sequence of all possible color combinations, while buttons C and D end the enhancement and return to the menu. The TV cursor X position adjusts the image intensity at which the color turns more white, while the Y position adjusts the way colors add (the gamma). Instructions appear on the message screen. C----------------------------------------------------------------------- TVZOOM This option lets you set the TV zoom magnification factor and to set the point about which the zoom takes place. The cursor points at the zoom center which will be shifted to the center of the screen. A hit on buttons A or B increments the magnification factor and on button C decrements the magnification factor in a circular fashion. Hit button D to exit. Instructions appear on the message screen. C----------------------------------------------------------------------- CURVALUE To perform an interactive display of the pixel locations and values of the image visible on the TV. The X and Y pixel coordinates, the pixel value, and the units of the pixel value are displayed in TV graphics channel 1 at the upper left of the display. The cursor position determines which pixel is shown. Unlike other CURVALUEs in AIPS, buttons A and B allow you to add the selected pixel to a list of pixels to be flagged or re-fit at a later time. Buttons C and D end the display and returns to the menu. Instructions appear on the message screen. The pixel values are read from the image in memory and hence preserve accuracy. C----------------------------------------------------------------------- SWAP 1-2 This option allows you to select polygonal regions for which you wish to swap the solution for component 1 with that of component 2. The interactive polygon setting operation starts in the "set polygon n" mode where button A selects a vertex in the polygon, B sets the last vertex in the polygon and gets ready to set polygon n+1, C sets the last vertex and enters a vertex editing mode, and D sets the last vertex and exits the polygon setting. In the vertex editing mode, move the cursor to a vertex to be moved and press button A or B to reset its position. After moving it to the desired point, press button A or B to fix that point and restart the vertex editing mode. Press button C to fix that point and then start creating polygon n+1. Press button D to fix that point and exit the polygon setting. Once button D has been set, the selected areas of pixels have their solutions swapped. The images are updated and reloaded automatically. C----------------------------------------------------------------------- SWAP 1-3 This option allows you to select polygonal regions for which you wish to swap the solution for component 1 with that of component 3. The interactive polygon setting operation starts in the "set polygon n" mode where button A selects a vertex in the polygon, B sets the last vertex in the polygon and gets ready to set polygon n+1, C sets the last vertex and enters a vertex editing mode, and D sets the last vertex and exits the polygon setting. In the vertex editing mode, move the cursor to a vertex to be moved and press button A or B to reset its position. After moving it to the desired point, press button A or B to fix that point and restart the vertex editing mode. Press button C to fix that point and then start creating polygon n+1. Press button D to fix that point and exit the polygon setting. Once button D has been set, the selected areas of pixels have their solutions swapped. The images are updated and reloaded automatically. C----------------------------------------------------------------------- SWAP 2-3 This option allows you to select polygonal regions for which you wish to swap the solution for component 2 with that of component 3. The interactive polygon setting operation starts in the "set polygon n" mode where button A selects a vertex in the polygon, B sets the last vertex in the polygon and gets ready to set polygon n+1, C sets the last vertex and enters a vertex editing mode, and D sets the last vertex and exits the polygon setting. In the vertex editing mode, move the cursor to a vertex to be moved and press button A or B to reset its position. After moving it to the desired point, press button A or B to fix that point and restart the vertex editing mode. Press button C to fix that point and then start creating polygon n+1. Press button D to fix that point and exit the polygon setting. Once button D has been set, the selected areas of pixels have their solutions swapped. The images are updated and reloaded automatically. C----------------------------------------------------------------------- SWAP 1-4 This option allows you to select polygonal regions for which you wish to swap the solution for component 1 with that of component 4. The interactive polygon setting operation starts in the "set polygon n" mode where button A selects a vertex in the polygon, B sets the last vertex in the polygon and gets ready to set polygon n+1, C sets the last vertex and enters a vertex editing mode, and D sets the last vertex and exits the polygon setting. In the vertex editing mode, move the cursor to a vertex to be moved and press button A or B to reset its position. After moving it to the desired point, press button A or B to fix that point and restart the vertex editing mode. Press button C to fix that point and then start creating polygon n+1. Press button D to fix that point and exit the polygon setting. Once button D has been set, the selected areas of pixels have their solutions swapped. The images are updated and reloaded automatically. C----------------------------------------------------------------------- SWAP 2-4 This option allows you to select polygonal regions for which you wish to swap the solution for component 2 with that of component 4. The interactive polygon setting operation starts in the "set polygon n" mode where button A selects a vertex in the polygon, B sets the last vertex in the polygon and gets ready to set polygon n+1, C sets the last vertex and enters a vertex editing mode, and D sets the last vertex and exits the polygon setting. In the vertex editing mode, move the cursor to a vertex to be moved and press button A or B to reset its position. After moving it to the desired point, press button A or B to fix that point and restart the vertex editing mode. Press button C to fix that point and then start creating polygon n+1. Press button D to fix that point and exit the polygon setting. Once button D has been set, the selected areas of pixels have their solutions swapped. The images are updated and reloaded automatically. C----------------------------------------------------------------------- SWAP 3-4 This option allows you to select polygonal regions for which you wish to swap the solution for component 3 with that of component 4. The interactive polygon setting operation starts in the "set polygon n" mode where button A selects a vertex in the polygon, B sets the last vertex in the polygon and gets ready to set polygon n+1, C sets the last vertex and enters a vertex editing mode, and D sets the last vertex and exits the polygon setting. In the vertex editing mode, move the cursor to a vertex to be moved and press button A or B to reset its position. After moving it to the desired point, press button A or B to fix that point and restart the vertex editing mode. Press button C to fix that point and then start creating polygon n+1. Press button D to fix that point and exit the polygon setting. Once button D has been set, the selected areas of pixels have their solutions swapped. The images are updated and reloaded automatically. C----------------------------------------------------------------------- NEXT WINDOW 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 component number followed by a subimage number in parentheses and the NEXT WINDOW option will appear. The first sub-images 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. C----------------------------------------------------------------------- DO FIT Selecting this option tells RMFIT to use the current initial guess to try to fit the model parameters. C----------------------------------------------------------------------- RE-GUESS Selecting this option tells RMFIT to request the input of a new initial guess of the model parameters using the TV. You will be prompted, one component at a time, to point at the position in RM of the component (only the X position, the RM, matters). C----------------------------------------------------------------------- BAD Selecting this option tells RMFIT to mark the current pixel as "bad" in the model file and then go on to the next pixel. C----------------------------------------------------------------------- QUIT Selecting this option causes RMFIT to exit cleanly. It may be re-started later with the same model file to continue model fitting and image editing. C----------------------------------------------------------------------- GOOD Selecting this option tells RMFIT that the fit appears to be good. The task stores the parameters in the model file and goes on to the next pixel. C----------------------------------------------------------------------- TVOFF Selecting this option turns off the TV interaction and tells RMFIT to ncontinue fitting with its own self-generated initial guesses. The interactive mode will be turned back on when the fit parameters are outside a reasonable range of values, the RMS exceeds RMSLIMIT, or when RMFIT reaches the image editing stage. C----------------------------------------------------------------------- HAND Selecting this options tells the task that you wish to enter an initial guess by typing in values in the AIPS terminal window (after prompting). In RMFIT, the parameters are the polarization (Jy/beam), intrinsic angle (degrees), rotation measure (radians/m/m), and possibly the spectral index (unitless) or thickness (radians/m/m). C----------------------------------------------------------------------- Selecting this option tells RMFIT to try the fitting again using only the specified number of Components. C----------------------------------------------------------------------- PIXRANGE Selecting this option tells RMFIT to re-plot the Q and U spectra using the intensity ranges you type in the AIPS terminal window. If you type only 2 numbers, they will be used as the minimum and maximum plot value in both Q and U. To have different plot ranges, enter 4 numbers where the first number must be less than the second number and the third number must be less than the fourth. C-----------------------------------------------------------------------