

NRAO Home > CASA > CASA Toolkit Reference Manual 

image.moments  Function
1.1.1 Compute moments from an image
Description
Summary
The primary goal of this function is to enable you to analyze a multidimensional image by generating moments of a specified axis. This is a timehonoured spectralline analysis technique used for extracting information about spectral lines.
You can generate one or more output moment images. The return value of this function is an onthefly Image tool holding the first of the output moment images.
The word ‘moment’ is used loosely here. It refers to collapsing an axis (the moment axis) to one pixel and setting the value of that pixel (for all of the other noncollapsed axes) to something computed from the data values along the moment axis. For example, take an RADECVelocity cube, collapse the velocity axis by computing the mean intensity at each RADEC pixel. This function offers many different moments and a variety of automatic methods to compute them.
We try to make a distinction between a ‘moment’ and a ‘method’. This boundary is a little blurred, but it claims to refer to the distinction between what you are computing, and how the pixels that were included in that computation were selected. For example, a ‘moment’ would be the average value of some pixel values in a spectrum. A ‘method’ for selecting those pixels would be a simple pixel value range specifying which pixels should be included.
There are many available moments, and you specify each one with an integer code as it would get rather cumbersome to refer to them via strings. In the list below, the value of the ith pixel of the spectrum is I_{i}, the coordinate of this pixel is v_{i} (of course it may not be velocity), and there are n pixels in the spectrum. The available moments are:
 1 – the mean value of the spectrum
 0 – the integrated value of the spectrum
where Δv is the width (in world coordinate units) of a pixel along the moment axis
 1 – the intensity weighted coordinate (this is traditionally used to get ’velocity
fields’)
 2 – the intensity weighted dispersion of the coordinate (this is traditionally used
to get ’velocity dispersion fields’)
 3 – the median of I
 4 – the median coordinate. Here we treat the spectrum as a probability distribution, generate the cumulative distribution, and then find the coordinate corresponding to the 50% value. This moment is not very robust, but it is useful for quickly generating a velocity field in a way that is not sensitive to noise. However, it will only give sensible results under certain conditions. The generation of the cumulative distribution and the finding of the 50% level really only makes sense if the cumulative distribution is monotonic. This essentially means only selecting pixels which are positive or negative. For this reason, this moment type is only supported with the basic method (see below – i.e. no smoothing, no windowing, no fitting) with a pixel selection range that is either all positive, or all negative
 5 – the standard deviation about the mean of the spectrum
 6 – the root mean square of the spectrum
 7 – the absolute mean deviation of the spectrum
 8 – the maximum value of the spectrum
 9 – the coordinate of the maximum value of the spectrum
 10 – the minimum value of the spectrum
 11 – the coordinate of the minimum value of the spectrum
Smoothing
The purpose of the smoothing functionality is purely to provide a mask. Thus, you can smooth the input image, apply a pixel include or exclude range, and generate a smoothed mask which is then applied before the moments are generated. The smoothed data are not used to compute the actual moments; that is always done from the original data.
Basic Method
The basic method is to just compute moments directly from the pixel values. This can be modified by applying pixel value inclusion or exclusion ranges (arguments includepix and excludepix).
You can then also convolve the image (arguments smoothaxes, smoothtypes, and smoothwidths) and find a mask based on the inclusion or exclusion ranges applied to the convolved image. This mask is then applied to the unsmoothed data for moment computation.
Window Method
The window method (invoked with argument method=’window’) does no pixelvaluebased selection. Instead a window is found (hopefully surrounding the spectral line feature) and only the pixels in that window are used for computation. This window can be found from the convolved or unconvolved image (arguments smoothaxes, smoothtypes, and smoothwidths).
The moments are always computed from the unconvolved data. The window can be found (for each spectrum) automatically. The automatic methods are via Bosma’s converging mean algorithm (method=’window’) or by fitting Gaussians and taking ±3σ as the window (method=’window,fit’). In Bosma’s algorithm, an initial guess for a range of pixels surrounding a spectral feature is refined by widening until the mean of the pixels outside of the range converges (to the noise).
Fit Method
The fit method (method=’fit’) fits Gaussians to spectral features automatically. The moments are then computed from the Gaussian fits (not the data themselves).
Other Arguments
 outfile  If you are creating just one moment image, and you specify outfile, then the image is created on disk with this name. If you leave outfile empty then a temporary image is created. In both cases, you can access this image with the returned Image tool. If you are making more than one moment image, then theses images are always created on disk. If you specify outfile then this is the root for the output file names. If you don’t specify it, then the input image name is used as the root.
 smoothing  If you smooth the image to generate a mask, you specify the kernel widths via the smoothwidths argument in the same way as in the sepconvolve function. See it for details.
 stddev  Some of the automatic methods also require an estimate of the noise level in the image. This is used to assess whether a spectrum is purely noise or not, and whether there is any signal worth digging out. If you don’t give it via the stddev argument, it will be worked out automatically from a Gaussian fit to the bins above 25% from a histogram of the entire image.

includepix,
excludepix

The
vectors
given
by
arguments
includepix
and
excludepix
specify
a
range
of
pixel
values
for
which
pixels
are
either
included
or
excluded.
They
are
mutually
exclusive;
you
can
specify
one
or
the
other,
but
not
both.
If
you
only
give
one
value
for
either
of
these,
say
includepix=b,
then
this
is
interpreted
as
includepix=[abs(b),abs(b)].
The convolving pointspread function is normalized to have a volume of unity. This means that point sources are depressed in value, but extended sources that are large with respect to the PSF remain essentially on the same intensity scale; these are the structures you are trying to find with the convolution so this is what you want. If you convolve the image, then arguments like includepix select based upon the convolved image pixel values. If you are having trouble getting these right, you can output the convolved image (smoothout) and assess the validity of your pixel ranges. Note also that if you are Hanning convolving (usually used on a velocity axis), then the width for this kernel must be 3 pixels (triangular smoothing kernels of other widths have no valid theoretical basis).
 doppler  If you compute the moments along a spectral axis, it is conventional to compute the world coordinate (needed for moments 0, 1 and 2) along that axis in ”km/s”. The argument doppler lets you specify what doppler convention the velocity will be calculated in. You can choose from doppler=radio, optical, true. See function summary for the definitions of these codes. For other momentaxis types, the world coordinate is computed in the native units.
 mask  The total input mask is the combination of the default pixel mask (if any) and the OTF mask. Once this mask has been established, then the moment method may make additional pixel selections.
 drop  If this is true (the default) then the moment axis is dropped from the output image. Otherwise, the output images have a moment axis of unit length and coordinate information that is the same as for the input image. This coordinate information may be totally meaningless for the moment images.
Finally, if you ask for a moment which requires the coordinate to be computed for each profile pixel (these are the intensity weighted mean coordinate [moment 1] and the intensity weighted dispersion of the coordinate [moment 2]), and the profile axis is not separable then there will be a performance loss. Examples of nonseparable axes are RA and Dec. If the axis is separable (e.g. a spectral axis) there is no penalty. In the latter case, the vector of coordinates for one profile is the same as the vector for another profile, and it can be precomputed (once).
Note that this function has no “virtual” output file capability. All output files are written to disk. The output mask for these images is good (T) unless the moment method fails to generate a value (e.g. the total input pixel mask was all bad for the profile) in which case it will be bad (F).
If an image has multiple (perchannel beams) and the moment axis is equal to the spectral axis, each channel will be convolved with a beam that is equal to the beam having the largest area in the beamset prior to moment determination.
Arguments
Inputs 
 
moments 
 List of moments that you would like to compute. Default
is integrated spectrum.
 
 allowed:  intArray 

 Default:  0  
axis 
 The moment axis. Default is the spectral axis if there is
one.  
 allowed:  int 

 Default:  10  
region 
 Region selection. See ”help par.region” for details.
Default is to use the full image.
 
 allowed:  any 

 Default:  variant


mask 
 Mask to use. See help par.mask. Default is none.
 
 allowed:  any 

 Default:  variant


method 
 List of windowing and/or fitting functions you would
like to invoke. Vector of strings from ’window’ and ’fit’.
The default is to not invoke the window or fit functions.  
 allowed:  stringArray 

 Default: 
 
smoothaxes 
 List of axes to smooth. Default is no smoothing.
 
 allowed:  intArray 

 Default:  1  
smoothtypes 
 List of smoothing kernel types, one for each axis
to smooth. Vector of strings from ’gauss’, ’boxcar’,
’hanning’. Default is no smoothing.
 
 allowed:  any 

 Default:  variant


smoothwidths 
 List of widths (full width for boxcar, full width at half
maximum for gaussian, 3 for Hanning) in pixels for
the smoothing kernels. Vector of numeric. Default is no
smoothing.
 
 allowed:  doubleArray 

 Default:  0.0 

includepix 
 Range of pixel values to include. Vector of 1 or 2 doubles.
Default is include all pixel.
 
 allowed:  doubleArray 

 Default:  1 

excludepix 
 Range of pixel values to exclude. Default is exclude no
pixels.
 
 allowed:  doubleArray 

 Default:  1 

peaksnr 
 The SNR ratio below which the spectrum will be rejected
as noise (used by the window and fit functions only)
 
 allowed:  double 

 Default:  3.0 

stddev 
 Standard deviation of the noise signal in the image (used
by the window and fit functions only)
 
 allowed:  double 

 Default:  0.0 

doppler 
 Velocity doppler definition for velocity computations
along spectral axes
 
 allowed:  string 

 Default:  RADIO 

outfile 
 Output image file name (or root for multiple moments).
Default is input + an autodetermined suffix.
 
 allowed:  string 

 Default: 


smoothout 
 Output file name for convolved image. Default is don’t
save the convolved image.
 
 allowed:  string 

 Default: 


overwrite 
 Overwrite (unprompted) preexisting output file?
 
 allowed:  bool 

 Default:  false 

drop 
 Drop moments axis from output images?
 
 allowed:  bool 

 Default:  true 

stretch 
 Stretch the mask if necessary and possible?
 
 allowed:  bool 

 Default:  false 

async 
 Run asynchronously?
 
 allowed:  bool 

 Default:  false 

image
Example
"""
#
print "\t\t moments Ex 1 \t"
ia.fromshape(shape=[32,32,32,32]) # replace with your own cube
im2 = ia.moments(moments=[1,1,2], axis=2, smoothaxes=[0,1,2],
smoothtypes=["gauss","gauss","hann"],
smoothwidths=[5.0,5.0,3], excludepix=[1e3],
smoothout=’smooth’, overwrite=true)
im2.done()
ia.close()
#
"""
In this example, standard moments (average intensity, weighted velocity
and weighted velocity dispersion) are computed via the convolve (spatially
convolved by gaussians and spectrally by a Hanning kernel) and clip
method (we exclude any pixels with absolute value less than $0.001$).
The output file names are automatically created for us and
the convolved image is saved. The returned image tool holds the first
moment image.
Example
"""
#
print "\t\t moments Ex 2 \t"
ia.fromshape(shape=[32,32,32,32])
im2 = ia.moments(moments=[3], method=["window"])
im2.done()
ia.close()
#
"""
In this example, the median of each spectrum is computed, after pixel
selection by the automatic window method. The output
image is temporary and accessed via the returned Image tool.
__________________________________________________________________
More information about CASA may be found at the
CASA web page
Copyright © 2016 Associated Universities Inc., Washington, D.C.
This code is available under the terms of the GNU General Public Lincense
Home  Contact Us  Directories  Site Map  Help  Privacy Policy  Search