As of Sun Jun 23 9:23:30 2024

XMOM: Finds the moments of each row of an image


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
ICUT                               Use only data > in abs value
                                   than ICUT (> 0).  Use only
                                   data < in abs value than
                                   ICUT (< 0.).
OPTYPE                             '': blank illegal velocities
                                   'MAX' do max instead of moms
PBPARM                             Beam parameters:
                                   (1) Cutoff: 0 -> no PB corr
                                   (2) > 0 -> Use (3)-(7)
                                   (3)-(7) Beam shape
BADDISK                            Disk to avoid for scratch


Task:  Fits one-dimensional moments to each row of an image.  (Normally
       XMOM will be used on images with frequency or velocity as the
       first axis, but it will proceed with others as well.)  The task
       fits 4 moments to each row and writes 5 n-1 dimensional images
       containing the moments and a count of the number of data samples
       used. XMOM provides only very elementary blanking capabilities.
       Normally, users will wish to do more elaborate blanking with
       BLANK before running XMOM.  The high order moments are evaluated
       around the 1st moment (e.g. central velocity).  Task MOMNT
       performs a similar function after smoothing the input image in 3
       dimensions.  This does make the flux cutoff more meaningful, but
       enormously more expensive.  XMOM is faster and will run on all
       AIPS systems.

       Users should be aware that the image of the first moment is in
       single-precision floating point.  If the first axis is frequency,
       there may be not be enough accuracy to represent the variation in
       frequency about some very high central frequency.  The task will
       subtract the central value from the image of the first moment
       whenever the difference in the axis values from one end to the
       other is < 10**-3 of the central value.  NOTE: THIS PRODUCES AN

       XMOM offers the option of writing an image of the maximum value
       found on each X axis and of the pixel coordinate at that
       point.  The moment images are not computed or written.  All of
       the cutoff and primary beam adverbs still apply in the 'MAX'
  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 for the moments are XMOMn, for n
             = 0 through 3.  The count image uses XMOMNC.
  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 moment
             computation.  NOTE that 0.0 is not a null value.  Instead,
             it means ignore all negative brightnesses.
  ICUT.......A flux cutoff in the same units as the input image (i.e.
             Jy/beam).  When ICUT > 0.0, data values less in absolute
             value than ICUT are ignored.  When ICUT < 0.0, data values
             greater in absolute value than ICUT are ignored.  NOTE that
             ICUT and FLUX are both always used.
  OPTYPE.....'' : blank illegal first moments. 'NBIV': do not blank
             illegal first moments. First moments are illegal when they
             fall outside the range of input channels. The blanking in
             XMOM would cause such a pixel to be blanked in ALL moment
             maps.  Especially for zero moment maps, one may want to
             keep such a pixel to avoid "ugly holes." Note that the use
             of FLUX = 0 forces all first moments to be legal.
             OPTYPE = 'MAX' means to write out an image containing the
             maximum brightness found along the X axis and an image of
             the X coordinate value at that pixel.  The moment images
             are not computed.
  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
                   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)
                where X is (distance from the pointing position in arc
                minutes times the frequency in GHz)**2.
                See explain for details
  BADDISK....Disk drives to avoid for scratch files.


     Using only those pixels included above the cutoffs, XMOM computes
Moment 0: S0 = Sum (T(i))
Moment 1: S1 = Sum (T(i) * i) / S0
Moment 2: S2 = sqrt (Sum (T(i) * i * i) / S0 - S1 * S1)
Moment 3: S3 = Sum (T(i) * i * i * i) / S0
          S3 = S3 - 3 * S1 * S2 + 2 * S1*S1*S1
          S3 = S3 ^(1/3)

     XMOM 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 XMOM 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.

     XMOM 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 appropraite 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

                 RICK PERLEY'S (OLD) REPORT

	Polynomial Coefficients from LSq Fit to VLA Primary
	Beam raster scans.

	Functional form fitted:

		1 + G1.X^2 + G2.X^4 + G3.X^6

	where X = r.F,

	and 	r = radius in arcminutes
		F = frequency in GHz.

	Fits were made to 3 percent cutoff in power for 24 antennas.
Poor fits, and discrepant fits were discarded, and the most
consistent subset of antennas had their fitted coefficients
averaged to produce the following 'best' coefficients.

Freq.		G1		G2		G3

1.285           -1.329E-3       6.445E-7        -1.146E-10  *
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 (old)    -1.350          6.526           -1.090      *
22.485 (new)    -1.417          7.332           -1.352
43.315          -1.321          6.185           -0.983

	The estimated errors (from the scatter in the fitted
coefficients) are generally very small:

	G1: .003 at all bands except Q (.014)
	G2: .03 to .07 at all bands except Q (.15)
	G3: .01 to .02 at all bands except Q (.04)

	R. Perley  21/Nov/00

* The 1.285 and 22.485 old feed values are not used.