This class is a base class for generating moments from an image or a spectral data. More...

#include <MomentsBase.h>

Inheritance diagram for casa::MomentsBase< T >:

Public Types
enum	MomentTypes { AVERAGE, INTEGRATED, WEIGHTED_MEAN_COORDINATE, WEIGHTED_DISPERSION_COORDINATE, MEDIAN, MEDIAN_COORDINATE, STANDARD_DEVIATION, RMS, ABS_MEAN_DEVIATION, MAXIMUM, MAXIMUM_COORDINATE, MINIMUM, MINIMUM_COORDINATE, NMOMENTS, DEFAULT }
	This `enum MomentTypes` is provided for use with the `setMoments` function. More...
enum	MethodTypes { WINDOW, FIT, INTERACTIVE, NMETHODS }
	The `enum MethodTypes` is provided for use with the `setWinFitMethod` function. More...
Public Member Functions
	MomentsBase (LogIO &os, Bool overWriteOutput=False, Bool showProgress=True)
	Constructor takes an image and a `LogIO` object for logging purposes.
virtual	~MomentsBase ()
	Destructor.
Bool	setMoments (const Vector< Int > &moments)
	Set the desired moments via an `Int` array.
virtual Bool	setMomentAxis (const Int &)
	Set the moment axis (0 relative).
Bool	setWinFitMethod (const Vector< Int > &method)
	The method by which you compute the moments is specified by calling (or not calling) the `setWinFitMethod` and `setSmoothMethod` functions.
virtual Bool	setSmoothMethod (const Vector< Int > &, const Vector< Int > &, const Vector< Quantum< Double > > &)
	This function invokes smoothing of the input image.
Bool	setSmoothMethod (const Vector< Int > &smoothAxes, const Vector< Int > &kernelTypes, const Vector< Double > &kernelWidths)
Bool	setInExCludeRange (const Vector< T > &include, const Vector< T > &exclude)
	You may specify a pixel intensity range as either one for which all pixels in that range are included in the moment calculation, or one for which all pixels in that range are excluded from the moment calculations.
Bool	setSnr (const T &peakSNR, const T &stdDeviation)
	This function is used to help assess whether a spectrum along the moment axis is all noise or not.
Bool	setSmoothOutName (const String &smOut)
	This is the output file name for the smoothed image.
Bool	setPlotting (PGPlotter &device, const Vector< Int > &nxy, const Bool yInd=False)
	This sets the name of the PGPLOT plotting device, the number of subplots in x and y per page and whether each spectrum plot is autoscaled individually (`yInd=False`) or they are plotted with the same range automatically determined from the image.
void	setVelocityType (MDoppler::Types type)
	Set Velocity type.
void	closePlotting ()
	CLose plotter.
void	resetError ()
	Reset argument error condition.
String	errorMessage () const
	Recover last error message.
virtual CoordinateSystem	coordinates ()
	Get CoordinateSystem.
virtual IPosition	getShape ()
Static Public Member Functions
static Vector< Int >	toMethodTypes (const String &methods)
	Helper function to convert a string containing a list of desired methods to the correct `Vector<Int>` required for the `setWinFitMethod` function.
Protected Member Functions
Bool	checkMethod ()
	Check that the combination of methods that the user has requested is valid List a handy dandy table if not.
Bool	setIncludeExclude (Vector< T > &range, Bool &noInclude, Bool &noExclude, const Vector< T > &include, const Vector< T > &exclude, ostream &os)
	Take the user's data inclusion and exclusion data ranges and generate the range and Booleans to say what sort it is.
Bool	setOutThings (String &suffix, Unit &momentUnits, const Unit &imageUnits, const String &momentAxisUnits, const Int moment, Bool convertToVelocity)
	Set the output image suffixes and units.
CoordinateSystem	makeOutputCoordinates (IPosition &outShape, const CoordinateSystem &cSysIn, const IPosition &inShape, Int momentAxis, Bool removeAxis)
	Make output Coordinates.
Static Protected Member Functions
static void	drawHistogram (const Vector< T > &values, const Vector< T > &counts, PGPlotter &plotter)
	Plot a histogram.
static void	drawLine (const Vector< T > &x, const Vector< T > &y, PGPlotter &plotter)
	Plot a line.
static void	drawVertical (const T &x, const T &yMin, const T &yMax, PGPlotter &plotter)
	Draw a vertical line of the given length at a given abcissa.
static Bool	getLoc (T &x, T &y, PGPlotter &plotter)
	Read the cursor and return its coordinates.
static Float	convertT (const T value)
	Convert a `T` to a `Float` for plotting.
static T	convertF (const Float value)
	Convert a `Float` (from plotting) to a `T`
static Bool	readCursor (PGPlotter &plotter, Float &x, Float &y, String &ch)
	Fish out cursor values.
Protected Attributes
LogIO	os_p
Bool	showProgress_p
Int	momentAxisDefault_p
T	peakSNR_p
T	stdDeviation_p
T	yMin_p
T	yMax_p
String	out_p
String	smoothOut_p
Bool	goodParameterStatus_p
Bool	doWindow_p
Bool	doFit_p
Bool	doAuto_p
Bool	doSmooth_p
Bool	noInclude_p
Bool	noExclude_p
Bool	fixedYLimits_p
Int	momentAxis_p
Int	worldMomentAxis_p
Vector< Int >	kernelTypes_p
Vector< Quantum< Double > >	kernelWidths_p
Vector< Int >	nxy_p
Vector< Int >	moments_p
Vector< T >	selectRange_p
Vector< Int >	smoothAxes_p
PGPlotter	plotter_p
Bool	overWriteOutput_p
String	error_p
Bool	convertToVelocity_p
MDoppler::Types	velocityType_p
Friends
class	MomentCalcBase< T >
	Note that if I don't put MomentCalcBase as a forward declaration and use instead "friend class MomentCalcBase<T>" The gnu compiler fails with a typedef problem.

Detailed Description

template<class T>
class casa::MomentsBase< T >

This class is a base class for generating moments from an image or a spectral data.

Intended use:

Public interface

Review Status

Date Reviewed:: yyyy/mm/dd

Prerequisite

Etymology

This class is an abstract class to compute moments from images or spectral data.

Synopsis

The primary goal of MSMoments, ImageMoments, and MSMoments are to help spectral-line astronomers analyze their multi-dimensional images or spectral data (in the form of MeasurementSet) by generating moments of a specified axis. ImageMoments is a specialized class to generate moments from images, while MSMoments is designed properly for MeasurementSet input. MSMoments class is an abstract class that is inherited by the above two concrete classes. MomentsBase provides interface layer to the MomentCalculators so that functionalities in MomentCalculators can be shared with ImageMoments and MSMoments. The word "moment" is used loosely here. It refers to collapsing an axis to one pixel and putting 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 class and its inheritances offer many different moments and a variety of interactive and automatic ways to compute them.

Motivation

MSMoments is defined so that moments can be generated from both images and spectral data (in the form of MeasurementSet).

Definition at line 96 of file MomentsBase.h.

Member Enumeration Documentation

template<class T>

enum casa::MomentsBase::MethodTypes

The enum MethodTypes is provided for use with the setWinFitMethod function.

It gives the allowed moment methods which are available with this function. The use of these methods is described further with the description of this function as well as in the general documentation earlier.

Enumerator:

WINDOW	Invokes the spectral windowing method.
FIT	Invokes Gaussian fitting.
INTERACTIVE	Invokes interactive methods.
NMETHODS

Definition at line 191 of file MomentsBase.h.

template<class T>

enum casa::MomentsBase::MomentTypes

This enum MomentTypes is provided for use with the setMoments function.

It gives the allowed moment types that you can ask for.

Enumerator:

AVERAGE	The average intensity.
INTEGRATED	The integrated intensity.
WEIGHTED_MEAN_COORDINATE	The intensity weighted mean coordinate (usually velocity)
WEIGHTED_DISPERSION_COORDINATE	The intensity weighted coordinate (usually velocity) dispersion.
MEDIAN	The median intensity.
MEDIAN_COORDINATE	The median coordinate (usually velocity). Treat the spectrum as a probability distribution, generate the cumulative distribution, and find the coordinate corresponding to the 50% value.
STANDARD_DEVIATION	The standard deviation about the mean of the intensity.
RMS	The rms of the intensity.
ABS_MEAN_DEVIATION	The absolute mean deviation of the intensity.
MAXIMUM	The maximum value of the intensity.
MAXIMUM_COORDINATE	The coordinate (usually velocity) of the maximum value of the intensity.
MINIMUM	The minimum value of the intensity.
MINIMUM_COORDINATE	The coordinate (usually velocity) of the minimum value of the intensity.
NMOMENTS	Total number.
DEFAULT	Default value is the integrated intensity.

Definition at line 122 of file MomentsBase.h.

Constructor & Destructor Documentation

template<class T>

casa::MomentsBase< T >::MomentsBase	(	LogIO &	os,
		Bool	overWriteOutput = `False`,
		Bool	showProgress = `True`
	)

Constructor takes an image and a LogIO object for logging purposes.

You specify whether output images are automatically overwritten if pre-existing, or whether an intercative choice dialog widget appears (overWriteOutput=F) You may also determine whether a progress meter is displayed or not.

template<class T>

virtual casa::MomentsBase< T >::~MomentsBase ( ) [virtual]

Destructor.

Member Function Documentation

template<class T>

Bool casa::MomentsBase< T >::checkMethod ( ) [protected]

Check that the combination of methods that the user has requested is valid List a handy dandy table if not.

template<class T>

void casa::MomentsBase< T >::closePlotting ( )

CLose plotter.

template<class T>

static T casa::MomentsBase< T >::convertF ( const Float value ) [inline, static, protected]

Convert a Float (from plotting) to a T

Definition at line 402 of file MomentsBase.h.

Referenced by casa::MomentCalcBase< T >::convertF().

template<class T>

static Float casa::MomentsBase< T >::convertT ( const T value ) [inline, static, protected]

Convert a T to a Float for plotting.

Definition at line 399 of file MomentsBase.h.

References casa::real().

Referenced by casa::MomentCalcBase< T >::convertT().

template<class T>

virtual CoordinateSystem casa::MomentsBase< T >::coordinates ( ) [virtual]

Get CoordinateSystem.

Reimplemented in casa::ImageMoments< T >, and casa::MSMoments< T >.

template<class T>

static void casa::MomentsBase< T >::drawHistogram	(	const Vector< T > &	values,
		const Vector< T > &	counts,
		PGPlotter &	plotter
	)		`[static, protected]`

Plot a histogram.

template<class T>

static void casa::MomentsBase< T >::drawLine	(	const Vector< T > &	x,
		const Vector< T > &	y,
		PGPlotter &	plotter
	)		`[static, protected]`

Plot a line.

template<class T>

static void casa::MomentsBase< T >::drawVertical	(	const T &	x,
		const T &	yMin,
		const T &	yMax,
		PGPlotter &	plotter
	)		`[static, protected]`

Draw a vertical line of the given length at a given abcissa.

template<class T>

String casa::MomentsBase< T >::errorMessage ( ) const [inline]

Recover last error message.

Definition at line 329 of file MomentsBase.h.

References casa::MomentsBase< T >::error_p.

template<class T>

static Bool casa::MomentsBase< T >::getLoc	(	T &	x,
		T &	y,
		PGPlotter &	plotter
	)		`[static, protected]`

Read the cursor and return its coordinates.

template<class T>

virtual IPosition casa::MomentsBase< T >::getShape ( ) [inline, virtual]

Reimplemented in casa::ImageMoments< T >, and casa::MSMoments< T >.

Definition at line 343 of file MomentsBase.h.

template<class T>

CoordinateSystem casa::MomentsBase< T >::makeOutputCoordinates	(	IPosition &	outShape,
		const CoordinateSystem &	cSysIn,
		const IPosition &	inShape,
		Int	momentAxis,
		Bool	removeAxis
	)		`[protected]`

Make output Coordinates.

template<class T>

static Bool casa::MomentsBase< T >::readCursor	(	PGPlotter &	plotter,
		Float &	x,
		Float &	y,
		String &	ch
	)		`[static, protected]`

Fish out cursor values.

template<class T>

void casa::MomentsBase< T >::resetError ( ) [inline]

Reset argument error condition.

If you specify invalid arguments to one of the above functions, an internal flag will be set which will prevent the createMoments function, which is defined in its inheritances, from doing anything (should you have chosen to igmore the Boolean return values of the functions). This function allows you to reset that internal state to good.

Definition at line 326 of file MomentsBase.h.

References casa::MomentsBase< T >::error_p, casa::MomentsBase< T >::goodParameterStatus_p, and casa::True.

template<class T>

Bool casa::MomentsBase< T >::setIncludeExclude	(	Vector< T > &	range,
		Bool &	noInclude,
		Bool &	noExclude,
		const Vector< T > &	include,
		const Vector< T > &	exclude,
		ostream &	os
	)		`[protected]`

Take the user's data inclusion and exclusion data ranges and generate the range and Booleans to say what sort it is.

template<class T>

Bool casa::MomentsBase< T >::setInExCludeRange	(	const Vector< T > &	include,
		const Vector< T > &	exclude
	)

You may specify a pixel intensity range as either one for which all pixels in that range are included in the moment calculation, or one for which all pixels in that range are excluded from the moment calculations.

One or the other of include and exclude must therefore be a zero length vector if you call this function. A return value of False indicates that you have given both an include and an exclude range. If you don't call this function, the default state of the class is to include all pixels.

template<class T>

virtual Bool casa::MomentsBase< T >::setMomentAxis ( const Int & ) [virtual]

Set the moment axis (0 relative).

A return value of False indicates that the axis was not contained in the image. If you don't call this function, the default state of the class is to set the moment axis to the spectral axis if it can find one. Otherwise an error will result.

Reimplemented in casa::MSMoments< T >.

template<class T>

Bool casa::MomentsBase< T >::setMoments ( const Vector< Int > & moments )

Set the desired moments via an Int array.

Each Int specifies a different moment; the allowed values and their meanings are given by the enum MomentTypes. A return value of False indicates you asked for an out of range moment. If you don't call this function, the default state of the class is to request the integrated intensity.

template<class T>

Bool casa::MomentsBase< T >::setOutThings	(	String &	suffix,
		Unit &	momentUnits,
		const Unit &	imageUnits,
		const String &	momentAxisUnits,
		const Int	moment,
		Bool	convertToVelocity
	)		`[protected]`

Set the output image suffixes and units.

template<class T>

Bool casa::MomentsBase< T >::setPlotting	(	PGPlotter &	device,
		const Vector< Int > &	nxy,
		const Bool	yInd = `False`
	)

This sets the name of the PGPLOT plotting device, the number of subplots in x and y per page and whether each spectrum plot is autoscaled individually (yInd=False) or they are plotted with the same range automatically determined from the image.

Plotting is not invoked for all states of the class. It is only needed for the interactive methods. If you ask for a method that needs to determine the noise from the image, and you set the plotting device, then this will be done interactively. Similarly, if you invoke the automatic window or fit methods, but set the plotting device, then you will see plots of the spectra and the selected windows and fits, respectively.

The default state of the class is that no plotting characteristics are set. However, if you set device but offer a zero length array for nxy then the latter is set to [1,1]. A return value of False indicates that you gave roo many values in the nxy vector.

template<class T>

virtual Bool casa::MomentsBase< T >::setSmoothMethod	(	const Vector< Int > &	,
		const Vector< Int > &	,
		const Vector< Quantum< Double > > &
	)		`[virtual]`

This function invokes smoothing of the input image.

Give Int arrays for the axes (0 relative) to be smoothed and the smoothing kernel types (use the enum KernelTypes) for each axis. Give a Double array for the widths (full width for BOXCAR and full width at half maximum for GAUSSIAN) in pixels of the smoothing kernels for each axis. For HANNING smoothing, you always get the quarter-half-quarter kernel (no matter what you might ask for). A return value of False indicates that you have given an inconsistent or invalid set of smoothing parameters. If you don't call this function the default state of the class is to do no smoothing. The kernel types are specified with the VectorKernel::KernelTypes enum

Reimplemented in casa::ImageMoments< T >, and casa::MSMoments< T >.

template<class T>

Bool casa::MomentsBase< T >::setSmoothMethod	(	const Vector< Int > &	smoothAxes,
		const Vector< Int > &	kernelTypes,
		const Vector< Double > &	kernelWidths
	)

Reimplemented in casa::ImageMoments< T >.

template<class T>

Bool casa::MomentsBase< T >::setSmoothOutName ( const String & smOut )

This is the output file name for the smoothed image.

It can be useful to have access this to this image when trying to get the pixel include or exclude range correct for the smooth-clip method. The default state of the class is to not output the smoothed image.

template<class T>

Bool casa::MomentsBase< T >::setSnr	(	const T &	peakSNR,
		const T &	stdDeviation
	)

This function is used to help assess whether a spectrum along the moment axis is all noise or not.

If it is all noise, there is not a lot of point to trying to computing the moment. This is only needed for the automatic window or fit methods. If you are using an interactive nethod, you assess yourself whether the spectrum contains signal or not.

peakSNR is the signal-to-noise ratio of the peak value in the spectrum below which the spectrum is considered pure noise. stdDeviation is the standard deviation of the noise for the input image.

Default values for one or the other parameter are indicated by giving zero.

The default state of the class then is to set peakSNR=3 and/or to work out the noise level from a Gaussian fit to a histogram (above 25%) of the entire image (it is very hard to get an accurate estimate of the noise a single spectrum). If you have specified a plotting device (see setPlotting) then you get to interact with the fitting procedure if you want to. A return value of False indicates you have set invalid values.

template<class T>

void casa::MomentsBase< T >::setVelocityType ( MDoppler::Types type )

Set Velocity type.

This is used for moments for which the moment axis is a spectral axis for which the coordinate is traditionally presented in km/s You can select the velocity definition. The default state of the class is to use the radio definition.

template<class T>

Bool casa::MomentsBase< T >::setWinFitMethod ( const Vector< Int > & method )

The method by which you compute the moments is specified by calling (or not calling) the setWinFitMethod and setSmoothMethod functions.

The default state of the class is to compute directly on all (or some according to setInExClude) of the pixels in the spectrum. Calling these functions modifies the computational state to something more complicated.

The setWinMethod function requires an Int array as its argument. Each Int specifies a different method that you can invoke (either separately or in combination). The allowed values and their meanings are given by the enum MethodTypes.

Both the windowing and fitting methods have interactive modes. The windowing method also has a fitting flavour, so if you set both MomentsBase::WINDOW and MomentsBase::FIT, you would be invoking the windowing method but determining the window by fitting Gaussians automatically (as MomentsBase::INTERACTIVE) was not given.

If you don't call this function, then neither the windowing nor fitting methods are invoked. A return value of False indicates that you asked for an illegal method.

template<class T>

static Vector<Int> casa::MomentsBase< T >::toMethodTypes ( const String & methods ) [static]

Helper function to convert a string containing a list of desired methods to the correct Vector<Int> required for the setWinFitMethod function.

This may be usful if your user interface involves strings rather than integers. A new value is added to the output vector (which is resized appropriately) if any of the substrings "window", "fit" or "interactive" (actually "win", "box" and "inter" will do) is present.

Friends And Related Function Documentation

template<class T>

friend class MomentCalcBase< T > [friend]

Note that if I don't put MomentCalcBase as a forward declaration and use instead "friend class MomentCalcBase<T>" The gnu compiler fails with a typedef problem.

But I can't solve it with say typedef MomentCalcBase<T> gpp_type; because you can only do a typedef with an actual type, not a T !

Reimplemented in casa::ImageMoments< T >, and casa::MSMoments< T >.

Definition at line 105 of file MomentsBase.h.