Basic Information on imrm

Task: imrm
Purpose: Compute rotation measure image from position angle images
Categories: image analysis

        IMRM computes rotation measure and zero wavelength position
        angle images from at least 2 position angle images at different
        frequencies.  This is done via a linear least squares fit to:
 
                        PA = PA_0 + RM*LAMBDA**2
 
        where RM is the rotation measure (rad/m**2) and PA_0 is the
        position angle at zero wavelength.  The output rotation measure
        image is in rad/m**2, and the output position angle image is in
        degrees.  Optionally, plots of the fits can be made.
 
        The more frequencies you have the better.  It is very important
        to try and get at least two sufficiently close that there is no
        ambiguity between them.
 
        By default, IMRM attempts to remove N*pi ambiguities from the
        data.  Its algorithm is (pixel by pixel)
 
          0) First remove angle according to the amount given by the
             user (keyword "rmi") and the equation PA = RM*LAMBDA**2
 
          1) Put the position angles of the first two frequencies in the
             range +/- 90 degrees.
 
          2) Remove 180 degree ambiguity from the position angles given
             by the FIRST TWO IMAGES (keyword in).  Thus, it modifies
             the position angle of the second frequency by 180 degrees
             so that the absolute value of the angle between the two
             position angles is less than 90 degrees.
 
          3) Compute the initial RM and PA_0 from these FIRST TWO
             position angles.
 
          4) This RM and PA_0 is used to predict the expected position
             angle at the other frequencies according to the expression
             PA = PA_0 + RM*LAMBDA**2.  Integer amounts of 180 degrees
             are then added or subtracted to the position angles at the
             remaining frequencies in order to make the position angle
             as close as possible to the expected value.
 
          5) Then a least squares fit is used to solve for the RM and
             PA_0
 
          6) Finally, the procedure is repeated from step 0) where the
             initial guess is now the value just determined above in
             step 5).
 
        The order in which the images are given is thus very important.
        You should generally give your images in order of decreasing
        frequency, with the assumption being that the smallest angle
        between the first two represents a rough guess for the RM
        with no ambiguities.  However, if you are very certain abou
        the lack of ambiguity between certain frequencies, or there
        are some of particularly high S/N and likely lack of ambiguity,
        you may like to try these.  Its a nasty business and it is VERY
        important that you look at the results carefully.
 
        The attempt to remove ambiguities can be turned off with keyword
        "options=ambiguous".  In this case, its algorithm is
 
          0) First remove angle according to the intial guess given by
             the user (keyword "rmi").
 
          1) Put all position angles in the range +/- 90 degrees.
 
          2) Then a least squares fit is used to solve for the RM and
             PA_0.
 
        In principle, you should never need to use this option.  If
        there are no ambiguities, the first algorithm shouldn't find
        any!
 
        There are also a variety of methods offered with which to
        blank the output images.  Most of these require error images
        associated with the input position angle images.  Use IMPOL to
        make the position angle images and position angle error images.
 

Key: in
        Up to 5 input position angle (positive N -> E) images (in
        degrees) at different frequencies.  Generally, you should give
        the images in order of decreasing frequency.  Wild card
        expansion is supported, no default.

Key: inerr
        Up to 5 position angle error images (in degrees) used for
        weighting the data during the least squares fit.  They are
        assumed to be in one-to-one association with the position angle
        images.  If no error images are given, each position angle image
        is given equal weight and we must assume a goodness of fit of
        unity in order to find the output image errors.  Wild card
        expansion is supported, default is no error images.

Key: rmi
        An amount of rotation measure to remove from the data before
        fitting.  If you have a good idea of this, it helps enormously
        in removing ambiguities.  See the detailed use in the discussion
        of the algorithm above.  See also options=guess where it is used
        slightly differently.  Default is 0.

Key: rm
        Two values. The output fitted rotation measure image in
        rad/m**2, and optionally, its associated error image.
        The default is no output RM images.

Key: pa0
        The output fitted (at zero wavelength) position angle image in
        degrees, and optionally, its associated error image.
        The default is no output PA images.

Key: qcut
        Blank the output image (RM or PA) pixels if the goodness of fit
        (Q) is less than this value.  If Q is larger than about 0.1 say,
        the fit is believable.  If it is greater than 0.001, the fit may
        be acceptable if the errors are non-normal or too small.  If Q
        is less than 0.001 the model can be called into question.  The
        probability distribution for position angle images approximates
        a Gaussian at high S/N ratios.  At low S/N ratios (roughly, when
        P/sigma < 2) it is non-Gaussian.  If you don't specify error
        images, Q cannot be determined and is assumed to be one.  This
        is also true if you give IMRM position angle images at two
        frequencies only.  Default is 0.001

Key: errcut
        Blank the output image (RM or PA) pixels if ANY of the input PA
        image pixels has an error greater than this value (degrees).
        Default is no input error based blanking.

Key: rmcut
        Blank pixels in BOTH the output RM and PA_0 images when the
        error in the fitted RM is greater than this value (rad/m**2).
        Errors can be worked out if you give input error images, or if
        you input images at more than two frequencies AND we assume the
        goodness of fit is unity.  Default is no fitted RM error based
        blanking.

Key: pacut
        Blank pixels in BOTH the output RM and PA_0 images when the
        error in the fitted PA_0 is greater than this value (degrees).
        Errors can be worked out if you give input error images, or if
        you input images at more than two frequencies AND we assume the
        goodness of fit is unity.  Default is no fitted PA_0 error based
        blanking.

Key: device
        PGPLOT plotting device to see the fits to the data.  The
        absolute pixel numbers in x and y are also written into the
        corner of the plot (unless options=accumulate).  No default.

Key: nxy
        Number of subplots per page in the x and y directions, to put on
        the plotting device.  See options=accumulate.  The default is
        2,2 (i.e. 2x2).

Key: csize
        PGPLOT character height.  Default is 1.0.

Key: options
        Task enrichment options.  Minimum match is active,
        "relax"      issue warnings instead of a fatal error when image
                     axis descriptors are inconsistent with each other,
                     and when the input image headers do not indicate
                     that they are position angle images
                     (btype=position_angle).
        "guess"      when removing ambiguities, this option causes IMRM
                     to use the rotation measure input through the
                     keyword "rmi" in step 3 above (on the first pass
                     only), rather than working it out from the first
                     two frequencies.  By default, angle is removed from
                     the data according to the value of "rmi" and then
                     the first guess made from the first two
                     frequencies.  The angle is not removed in this way
                     with this option.  This may prove useful if you
                     have two close but perhaps noisy frequencies which
                     is causing the initial guess of the RM to be wrong
                     (because of noise) and driving the subsequent turn
                     removal off.
        "ambiguous"  Do not try to remove ambiguites.
        "accumulate" means put all the plots on one sub-plot, rather
                     than the default, which is to put the plot for each
                     spatial pixel on a spearate subplot.
        "yindependent"
                     By default, the sub-plots are all drawn with the
                     same Y-axis scale, that embraces all sub-plots.
                     This option forces each sub-plot to be scaled
                     independently.
 
Revision: 1.11, 2021/06/02 04:45:09 UTC