A class for doing multi-dimensional cleaning. More...

#include <LatticeCleaner.h>

Inheritance diagram for casa::LatticeCleaner< T >:

Public Member Functions
	LatticeCleaner ()
	Create a cleaner : default constructor.
	LatticeCleaner (const Lattice< T > &psf, const Lattice< T > &dirty)
	Create a cleaner for a specific dirty image and PSF.
	LatticeCleaner (const LatticeCleaner< T > &other)
	The copy constructor uses reference semantics.
LatticeCleaner< T > &	operator= (const LatticeCleaner< T > &other)
	The assignment operator also uses reference semantics.
	~LatticeCleaner ()
	The destructor does nothing special.
void	update (const Lattice< T > &dirty)
	Update the dirty image only.
Bool	setscales (const Int nscales, const Float scaleInc=1.0)
	Set a number of scale sizes.
Bool	setscales (const Vector< Float > &scales)
	Set a specific set of scales.
Bool	setcontrol (CleanEnums::CleanType cleanType, const Int niter, const Float gain, const Quantity &aThreshold, const Quantity &fThreshold, const Bool choose=True)
	Set up control parameters cleanType - type of the cleaning algorithm to use (HOGBOM, MULTISCALE) niter - number of iterations gain - loop gain used in cleaning (a fraction of the maximum subtracted at every iteration) aThreshold - absolute threshold to stop iterations fThreshold - fractional threshold (i.e.
Bool	setcontrol (CleanEnums::CleanType cleanType, const Int niter, const Float gain, const Quantity &threshold, const Bool choose=True)
	This version of the method disables stopping on fractional threshold.
Int	iteration () const
	return how many iterations we did do
Int	numberIterations () const
void	startingIteration (const Int starting=0)
	what iteration number to start on
Int	clean (Lattice< T > &model, LatticeCleanProgress *progress=0)
	Clean an image.
void	setMask (Lattice< T > &mask, const T &maskThreshold=T(0.9))
	Set the mask mask - input mask lattice maskThreshold - if positive, the value is treated as a threshold value to determine whether a pixel is good (mask value is greater than the threshold) or has to be masked (mask value is below the threshold).
void	ignoreCenterBox (Bool huh)
	Tell the algorithm to NOT clean just the inner quarter (This is useful when multiscale clean is being used inside a major cycle for MF or WF algorithms) if True, the full image deconvolution will be attempted.
void	setSmallScaleBias (const Float x=0.5)
	Consider the case of a point source: the flux on all scales is the same, and the first scale will be chosen.
void	stopAtLargeScaleNegative ()
	During early iterations of a cycled MS Clean in mosaicing, it common to come across an ocsilatory pattern going between positive and negative in the large scale.
void	stopPointMode (Int nStopPointMode)
	Some algorithms require that the cycles be terminated when the image is dominated by point sources; if we get nStopPointMode of the smallest scale components in a row, we terminate the cycles.
Bool	queryStopPointMode () const
	After completion of cycle, querry this to find out if we stopped because of stopPointMode.
void	speedup (const Float Ndouble)
	speedup() will speed the clean iteration by raising the threshold.
Lattice< T > *	residual ()
	Look at what WE think the residuals look like Assumes the first scale is zero-sized.
Float	threshold () const
	Method to return threshold, including any speedup factors.
T	strengthOptimum () const
	Method to return the strength optimum achieved at the last clean iteration The output of this method makes sense only if it is called after clean.
Static Public Member Functions
static void	addTo (Lattice< T > &to, const Lattice< T > &add)
	Helper function to optimize adding.
Protected Member Functions
Bool	validatePsf (const Lattice< T > &psf)
	Make sure that the peak of the Psf is within the image.
void	makeScale (Lattice< T > &scale, const Float &scaleSize)
	Make an lattice of the specified scale.
Float	spheroidal (Float nu)
	Make Spheroidal function for scale images.
Bool	findMaxAbsMaskLattice (const Lattice< T > &lattice, const Lattice< T > &mask, T &maxAbs, IPosition &posMax)
	Find the Peak of the lattice, applying a mask.
Static Protected Member Functions
static Bool	findMaxAbsLattice (const Lattice< T > &lattice, T &maxAbs, IPosition &posMax)
	Find the Peak of the Lattice.
static void	makeBoxesSameSize (IPosition &blc1, IPosition &trc1, IPosition &blc2, IPosition &trc2)
	Helper function to reduce the box sizes until the have the same size keeping the centers intact.
Protected Attributes
CleanEnums::CleanType	itsCleanType
Float	itsGain
Int	itsMaxNiter
Quantum< Double >	itsThreshold
TempLattice< T > *	itsMask
IPosition	itsPositionPeakPsf
Private Member Functions
Int	index (const Int scale, const Int otherscale)
	Calculate index into PsfConvScales.
Bool	destroyScales ()
Bool	destroyMasks ()
Bool	makeScaleMasks ()
Private Attributes
TempLattice< T > *	itsDirty
TempLattice< Complex > *	itsXfr
Int	itsNscales
Vector< Float >	itsScaleSizes
PtrBlock< TempLattice< T > * >	itsScales
PtrBlock< TempLattice< Complex > * >	itsScaleXfrs
PtrBlock< TempLattice< T > * >	itsPsfConvScales
PtrBlock< TempLattice< T > * >	itsDirtyConvScales
PtrBlock< TempLattice< T > * >	itsScaleMasks
Bool	itsScalesValid
Int	itsIteration
Int	itsStartingIter
Quantum< Double >	itsFracThreshold
Float	itsMaximumResidual
T	itsStrengthOptimum
Vector< Float >	itsTotalFluxScale
Float	itsTotalFlux
Double	itsMemoryMB
	Memory to be allocated per TempLattice.
Bool	itsChoose
	Let the user choose whether to stop.
Bool	itsDoSpeedup
	Threshold speedup factors:
Float	itsNDouble
Bool	itsIgnoreCenterBox
Float	itsSmallScaleBias
Bool	itsStopAtLargeScaleNegative
Int	itsStopPointMode
Bool	itsDidStopPointMode
Bool	itsJustStarting
T	itsMaskThreshold
	threshold for masks.

Detailed Description

template<class T>
class casa::LatticeCleaner< T >

A class for doing multi-dimensional cleaning.

Intended use:

Public interface

 <h3>Review Status</h3><dl><dt>Date Reviewed:<dd>yyyy/mm/dd<dt>Test programs:<dd>tLatticeCleaner</dl>

Prerequisite

The mathematical concept of deconvolution

Etymology

The LatticeCleaner class will deconvolve Lattices.

Synopsis

This class will perform various types of Clean deconvolution on Lattices.

Example

Motivation

Thrown Exceptions

AipsError: if psf has more dimensions than the model.

To Do

Allow the psf to be specified with a Function .

Definition at line 103 of file LatticeCleaner.h.

Constructor & Destructor Documentation

template<class T>

casa::LatticeCleaner< T >::LatticeCleaner ( )

Create a cleaner : default constructor.

template<class T>

casa::LatticeCleaner< T >::LatticeCleaner	(	const Lattice< T > &	psf,
		const Lattice< T > &	dirty
	)

Create a cleaner for a specific dirty image and PSF.

template<class T>

casa::LatticeCleaner< T >::LatticeCleaner ( const LatticeCleaner< T > & other )

The copy constructor uses reference semantics.

template<class T>

casa::LatticeCleaner< T >::~LatticeCleaner ( )

The destructor does nothing special.

Member Function Documentation

template<class T>

static void casa::LatticeCleaner< T >::addTo	(	Lattice< T > &	to,
		const Lattice< T > &	add
	)		`[static]`

Helper function to optimize adding.

template<class T>

Int casa::LatticeCleaner< T >::clean	(	Lattice< T > &	model,
		LatticeCleanProgress *	progress = `0`
	)

Clean an image.

return value gives you a hint of what's happening 1 = converged 0 = not converged but behaving normally -1 = not converged and stopped on cleaning consecutive smallest scale -2 = not converged and either large scale hit negative or diverging -3 = clean is diverging rather than converging

template<class T>

Bool casa::LatticeCleaner< T >::destroyMasks ( ) [private]

template<class T>

Bool casa::LatticeCleaner< T >::destroyScales ( ) [private]

template<class T>

static Bool casa::LatticeCleaner< T >::findMaxAbsLattice	(	const Lattice< T > &	lattice,
		T &	maxAbs,
		IPosition &	posMax
	)		`[static, protected]`

Find the Peak of the Lattice.

template<class T>

Bool casa::LatticeCleaner< T >::findMaxAbsMaskLattice	(	const Lattice< T > &	lattice,
		const Lattice< T > &	mask,
		T &	maxAbs,
		IPosition &	posMax
	)		`[protected]`

Find the Peak of the lattice, applying a mask.

template<class T>

void casa::LatticeCleaner< T >::ignoreCenterBox ( Bool huh ) [inline]

Tell the algorithm to NOT clean just the inner quarter (This is useful when multiscale clean is being used inside a major cycle for MF or WF algorithms) if True, the full image deconvolution will be attempted.

Definition at line 184 of file LatticeCleaner.h.

References casa::LatticeCleaner< T >::itsIgnoreCenterBox.

template<class T>

Int casa::LatticeCleaner< T >::index	(	const Int	scale,
		const Int	otherscale
	)		`[private]`

Calculate index into PsfConvScales.

template<class T>

Int casa::LatticeCleaner< T >::iteration ( ) const [inline]

return how many iterations we did do

Definition at line 154 of file LatticeCleaner.h.

References casa::LatticeCleaner< T >::itsIteration.

template<class T>

static void casa::LatticeCleaner< T >::makeBoxesSameSize	(	IPosition &	blc1,
		IPosition &	trc1,
		IPosition &	blc2,
		IPosition &	trc2
	)		`[static, protected]`

Helper function to reduce the box sizes until the have the same size keeping the centers intact.

template<class T>

void casa::LatticeCleaner< T >::makeScale	(	Lattice< T > &	scale,
		const Float &	scaleSize
	)		`[protected]`

Make an lattice of the specified scale.

template<class T>

Bool casa::LatticeCleaner< T >::makeScaleMasks ( ) [private]

template<class T>

Int casa::LatticeCleaner< T >::numberIterations ( ) const [inline]

Definition at line 155 of file LatticeCleaner.h.

References casa::LatticeCleaner< T >::itsIteration.

template<class T>

LatticeCleaner<T>& casa::LatticeCleaner< T >::operator= ( const LatticeCleaner< T > & other )

The assignment operator also uses reference semantics.

template<class T>

Bool casa::LatticeCleaner< T >::queryStopPointMode ( ) const [inline]

After completion of cycle, querry this to find out if we stopped because of stopPointMode.

Definition at line 209 of file LatticeCleaner.h.

References casa::LatticeCleaner< T >::itsDidStopPointMode.

template<class T>

Lattice<T>* casa::LatticeCleaner< T >::residual ( ) [inline]

Look at what WE think the residuals look like Assumes the first scale is zero-sized.

Definition at line 223 of file LatticeCleaner.h.

References casa::LatticeCleaner< T >::itsDirtyConvScales.

template<class T>

Bool casa::LatticeCleaner< T >::setcontrol	(	CleanEnums::CleanType	cleanType,
		const Int	niter,
		const Float	gain,
		const Quantity &	aThreshold,
		const Quantity &	fThreshold,
		const Bool	choose = `True`
	)

Set up control parameters cleanType - type of the cleaning algorithm to use (HOGBOM, MULTISCALE) niter - number of iterations gain - loop gain used in cleaning (a fraction of the maximum subtracted at every iteration) aThreshold - absolute threshold to stop iterations fThreshold - fractional threshold (i.e.

given w.r.t. maximum residual) to stop iterations. This parameter is specified as Quantity so it can be given in per cents. choose - unused at the moment, specify False. Original meaning is to allow interactive decision on whether to continue iterations. This method always returns True.

template<class T>

Bool casa::LatticeCleaner< T >::setcontrol	(	CleanEnums::CleanType	cleanType,
		const Int	niter,
		const Float	gain,
		const Quantity &	threshold,
		const Bool	choose = `True`
	)

This version of the method disables stopping on fractional threshold.

Reimplemented in casa::MultiTermLatticeCleaner< T >.

template<class T>

void casa::LatticeCleaner< T >::setMask	(	Lattice< T > &	mask,
		const T &	maskThreshold = `T(0.9)`
	)

Set the mask mask - input mask lattice maskThreshold - if positive, the value is treated as a threshold value to determine whether a pixel is good (mask value is greater than the threshold) or has to be masked (mask value is below the threshold).

Negative threshold switches mask clipping off. The mask value is used to weight the flux during cleaning. This mode is used to implement cleaning based on the signal-to-noise as opposed to the standard cleaning based on the flux. The default threshold value is 0.9, which ensures the behavior of the code is exactly the same as before this parameter has been introduced.

template<class T>

Bool casa::LatticeCleaner< T >::setscales	(	const Int	nscales,
		const Float	scaleInc = `1.0`
	)

Set a number of scale sizes.

The units of the scale are pixels.

template<class T>

Bool casa::LatticeCleaner< T >::setscales ( const Vector< Float > & scales )

Set a specific set of scales.

Reimplemented in casa::MultiTermLatticeCleaner< T >.

template<class T>

void casa::LatticeCleaner< T >::setSmallScaleBias ( const Float x = 0.5 ) [inline]

Consider the case of a point source: the flux on all scales is the same, and the first scale will be chosen.

Now, consider the case of a point source with a little bit of extended structure: thats right, the largest scale will be chosen. In this case, we should provide some bias towards the small scales, or against the large scales. We do this in an ad hoc manner, multiplying the maxima found at each scale by 1.0 - itsSmallScaleBias * itsScaleSizes(scale)/itsScaleSizes(nScalesToClean-1); Typical bias values range from 0.2 to 1.0.

Definition at line 194 of file LatticeCleaner.h.

References casa::LatticeCleaner< T >::itsSmallScaleBias.

template<class T>

void casa::LatticeCleaner< T >::speedup ( const Float Ndouble )

speedup() will speed the clean iteration by raising the threshold.

This may be required if the threshold is accidentally set too low (ie, lower than can be achieved given errors in the approximate PSF).

threshold(iteration) = threshold(0) ( exp( (iteration - startingiteration)/Ndouble )/ 2.718 ) If speedup() is NOT invoked, no effect on threshold

template<class T>

Float casa::LatticeCleaner< T >::spheroidal ( Float nu ) [protected]

Make Spheroidal function for scale images.

template<class T>

void casa::LatticeCleaner< T >::startingIteration ( const Int starting = 0 ) [inline]

what iteration number to start on

Definition at line 158 of file LatticeCleaner.h.

References casa::LatticeCleaner< T >::itsStartingIter.

template<class T>

void casa::LatticeCleaner< T >::stopAtLargeScaleNegative ( ) [inline]

During early iterations of a cycled MS Clean in mosaicing, it common to come across an ocsilatory pattern going between positive and negative in the large scale.

If this is set, we stop at the first negative in the largest scale.

Definition at line 200 of file LatticeCleaner.h.

References casa::LatticeCleaner< T >::itsStopAtLargeScaleNegative, and casa::True.

template<class T>

void casa::LatticeCleaner< T >::stopPointMode ( Int nStopPointMode ) [inline]

Some algorithms require that the cycles be terminated when the image is dominated by point sources; if we get nStopPointMode of the smallest scale components in a row, we terminate the cycles.

Definition at line 205 of file LatticeCleaner.h.

References casa::LatticeCleaner< T >::itsStopPointMode.

template<class T>

T casa::LatticeCleaner< T >::strengthOptimum ( ) const [inline]

Method to return the strength optimum achieved at the last clean iteration The output of this method makes sense only if it is called after clean.

Definition at line 230 of file LatticeCleaner.h.

References casa::LatticeCleaner< T >::itsStrengthOptimum.

template<class T>

Float casa::LatticeCleaner< T >::threshold ( ) const

Method to return threshold, including any speedup factors.

template<class T>

void casa::LatticeCleaner< T >::update ( const Lattice< T > & dirty )