HTML automatically generated with rman
Table of Contents

Name

ccdmom - moment or accumulate along an axis of an image

Synopsis

ccdmom [parameter=value]

Description

ccdmom takes special moments (in position, or image intensity) along an axis of an image/cube. It can optionally also accumulate along the selected axis.

For datacubes that need to produce velocity fields a number of alternate options (gaussian fit, envelope tracing etc.) are available via pvtrace(1NEMO) .

To get the intensity weighted shape of an object using the moments of inertia, use ccdshape(1NEMO) .

Continuum subtraction is needed for reliable moments where applicable.

If moments needs to be taken across many images, like cubes with axis=4, use ccdmoms(1NEMO) .

Parameters

The following parameters are recognized in any order if the keyword is also given:
in=
Input image file. No default.
out=
Output image file. No default.
axis=
Axis to take moment along (1=x 2=y 3=z). Unless keep=t, this axis will be reduced. [Default: 3]
mom=
Moment to take along the selected axis. For convenience referring to the selected axis as "velocity" we have the following moments: 
0    total emission
1    mean velocity
2    sigma, the velocity dispersion (FWHM = 2.355 * sigma)
3    velocity of peak fit (around the max and the two points on either side)
8    peak value along axis
-1    average intensity along the axis
-2    dispersion around the mean intensity along the axis
-3    differentials along an axis (forces keep=true)
-4    clumping factor (only axis=3 supported now)
30    total emission in the Nth (peak=) peak
31    mean velocity of the Nth peak
32    sigma, velocity dispersion, of the Nth peak
33    h3 (like a skewness) of the Nth peak, 
34    h4 (like a kurtosis) of the Nth peak
The mom=30,31,32,33,34 computes moments based on the "single profile near the peak", useful for smooth high S/N profiles. For a description of the h3 and h4 see S2.4 in van der Marel & Franx (1993ApJ...407..525V) [Default: 0].
keep=t|f
Boolean value if to keep the moment axis. If you keep the axis (instead of compressing it), the values are replaced with the computed moment. This can be useful if you want to subtract an cube/image with the mean value along a certain axis. Only in this case (but see also cumulative=t below) will the output image have the same shape and dimension as the input image. [Default: f].
cumulative=t|f
Boolean value if the values should accumulate instead along the selected axis. The mom= keyword is ignored, and the input and output datasets will now have the same shape and dimension. [Default: f]
oper=
If supplied, this is an extra operator supplied to the input file and output file, to create the final output file. This is to prevent having to type two commands such as 
    ccdmom map0 tmp0 axis=1 mom=-1 keep=t
    ccdmath map0,tmp0 map1 %1-%2
instead of 
    ccdmom map0 map1 axis=1 mom=-1 oper=-
peak=N
For mom=3,30-34 where it finds the peak, this allows you to find the N-th peak instead of the first. This is achieved by visiting each peak, and assigning a peak membership downwards from the peak and then finding the next one.
clip=
Exclude pixels with values in the range -clip to clip. Default: 0
rngmsk=t|f
Don’t assign a 1st moment if the value results in a value outside the range of the axis. This can easily happen for noisy data. Default: false.
abs=t|f
Use absolute values of the intensities for weights to a moment analysis. This is useful for low S/N data where at the wings a sign change can bias the moments. It is assumed the data have been continuum subtracted.
zero=t|f
Mask out values below zero for mom=30,31,32 (**experimental**) [f]
contsub=t|f
Fake a continuum subtraction for mom=30,31,32 (**experimental**) [t]
integrate=t|f
When using mom=0 the signal is summed along an axis, you can either just sum the numbers (this used to be the old default), or integrate, ie. multiply the sum by the cell-size along that axis. This is now the default, to make it more consistent with the new units in snapgrid(1NEMO) .
pos=[ix0,iy0]
If used, this should contain two (zero-based) pixel coordinates, at which position a spectrum is printed to stdout. Currently only implemented along the Z direction, hence X and Y. At some future time it may also support spectra along Y or X, but most advanced features are only implemented along axis=3. Default: none

arange=[k0,k1,k2,....]
Pixels along the axis to include in the moment. By default the whole axis is used, but with this keyword select pixels can be selected, for example arange=0:20,40:60. Default: all pixels.

Examples

In this example we examine a cube with independent values drawn from a gaussian distribution with mean 0 and dispersion 1. The dispersion of the values along the 3rd axis are compared with the dispersion in the differentials (mom=-3). For a normal distribution the latter should be sqrt(2) higher than the intrinsic dispersion. Comparing the two, maps in this case, could say something about correllations along the 3rd axis (see also examples in tabtrend(1NEMO) ) 


      1% ccdgen "" cube1 noise spar=0,1 size=100,100,1000 seed=123
      # intrinsic dispersion
      2% ccdmom cube1 -  mom=-2 | ccdstat - qac=t
      QAC_STATS: - 0.999886 0.0224798 0.922334 1.08579  9998.86 1
      # dispersion of the adjacent differences
      3% ccdmom cube1 - mom=-3 | ccdmom - - mom=-2 | ccdstat - qac=t
      QAC_STATS: - 1.4138 0.0388857 1.28338 1.55915  14138 1
      
      # dispersion of a hanning smoothed cube
      % ccdsmooth cube1 - dir=z | ccdmom - - mom=-2 | ccdstat - qac=t
      QAC_STATS: - 0.611611 0.0191999 0.541171 0.685092  6116.11 1

Python

For those more familiar with python, here are some cross-walks, where I denotes the numpy cube, and V a one-dimensional WCS value along the the picked axis. the axis= keyword in the numpy functions to pick another but our default of axis=3. 
       mom=0    m0 = I.sum(axis=2)
       ?    I.mean(axis=2)
       mom=-1    m1 = I.mean(axis=2)
       mom=-2    m2 = I.std(axis=2)
       mom=1    v = (V*I).sum(axis=2)/I.sum(axis=2)
       mom=2    s=
       mom=8    peak = I.max(axis=2)

See Also

pvtrace(1NEMO) , ccdmoms(1NEMO) , ccdsub(1NEMO) , ccdrt(1NEMO) , ccdshape(1NEMO) , snapgrid(1NEMO) , mom2cube(1NEMO) , tabtrend(1NEMO) , image(5NEMO) , qac(5NEMO)

Caveats

Cannot compute straight moments, e.g. the 2nd moment along an axis, such as e.g. snapgrid can do. This program only computes user friendly numbers (sum, mean, dispersion) and gives special meaning to negative values of mom= and axis=.

Files

src/image/misc/ccdmom.c

Author

Peter Teuben

Update History


09-jun-95    V0.1 Created    PJT
19-oct-95    V0.2 simple implementation of axis=3    PJT
12-dec-98    V0.3 finished mom=0,1,2 for all axes    PJT
31-dec-98    V0.4 added keep=    PJT
21-feb-01    V0.4a added mom=3, and fixed major bugs in computing moments    PJT
25-mar-01    V0.5 added mom=-1    PJT
18-oct-05    V0.6 added mom=-2 and cumulative option     PJT
16-sep-11    V0.8 added clip= and rngmsk= [lost code]    PJT
27-nov-12    V1.0 added oper=    PJT
14-feb-13    V2.0 integrate=t is now the new default for mom=0    PJT
21-jun-2016    V2.3 added mom=30,31,32,33,34    PJT
10-may-2017    V2.4 force q&d cont subtraction on mom=30,31,....    PJT
15-jun-2017    V2.5 add pos= option    PJT
21-jun-2017    V2.6 add abs= option    PJT
17-apr-2022    V3.0 add arange=    PJT
14-may-2022    V3.1 add mom=8 option    PJT

Table of Contents