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 multi-dimensional image by generating moments of a specified axis. This is a time-honoured spectral-line 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 on-the-fly 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 non-collapsed axes) to something computed from the data values along the moment axis. For example, take an RA-DEC-Velocity cube, collapse the velocity axis by computing the mean intensity at each RA-DEC 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 Ii, the coordinate of this pixel is vi (of course it may not be velocity), and there are n pixels in the spectrum. The available moments are:

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 pixel-value-based 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

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 non-separable 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 (per-channel 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 auto-determined 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) pre-existing 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

Returns
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=[1e-3],  
                 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