casa::MatrixCleaner Class Reference

A copy of LatticeCleaner but just using 2-D matrices. More...

#include <MatrixCleaner.h>

Inheritance diagram for casa::MatrixCleaner:

Public Member Functions
	MatrixCleaner ()
	Create a cleaner : default constructor.
	MatrixCleaner (const Matrix< Float > &psf, const Matrix< Float > &dirty)
	Create a cleaner for a specific dirty image and PSF.
	MatrixCleaner (const MatrixCleaner &other)
	The copy constructor uses reference semantics.
MatrixCleaner &	operator= (const MatrixCleaner &other)
	The assignment operator also uses reference semantics.
	~MatrixCleaner ()
	The destructor does nothing special.
void	defineScales (const Vector< Float > &scales)
	just define the scales...nothing else is done the user will need to call setPsf+makePsfScales+setDirty+makeDirtyScales to be in a good state to clean.
void	setDirty (const Matrix< Float > &dirty)
	Set the dirty image without calculating convolutions.
void	makeDirtyScales ()
	Calculate the convolutions for the dirt Obviously the.
void	update (const Matrix< Float > &dirty)
	Update the dirty image only (equiv of setDirty + makeDirtyScales).
void	setPsf (const Matrix< Float > &psf)
	change the psf don't forget to redo the setscales or run makePsfScales, followed by makeDirtyScales
void	makePsfScales ()
	calculate the convolutions of the psf
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)
	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)
	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
Float	totalFlux () const
	Total flux accumulated so far.
Int	clean (Matrix< Float > &model, Bool doPlotProgress=False)
	Clean an image.
void	setMask (Matrix< Float > &mask, const Float &maskThreshold=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).
Bool	makeScaleMasks ()
	Call the function below if the psf is changed ..no need to setMask again.
void	unsetMask ()
	remove the mask; useful when keeping object and sending a new dirty image to clean one can set another mask then
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.
Matrix< Float >	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.
Float	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.
Protected Member Functions
Bool	validatePsf (const Matrix< Float > &psf)
	Make sure that the peak of the Psf is within the image.
void	makeScale (Matrix< Float > &scale, const Float &scaleSize)
	Make an array of the specified scale.
Float	spheroidal (Float nu)
	Make Spheroidal function for scale images.
Int	findBeamPatch (const Float maxScaleSize, const Int &nx, const Int &ny, const Float psfBeam=4.0, const Float nBeams=20.0)
Bool	findMaxAbsMask (const Matrix< Float > &lattice, const Matrix< Float > &mask, Float &maxAbs, IPosition &posMax)
	Find the Peak of the lattice, applying a mask.
Static Protected Member Functions
static Bool	findMaxAbs (const Matrix< Float > &lattice, Float &maxAbs, IPosition &posMax)
	Find the Peak of the matrix.
static Bool	findPSFMaxAbs (const Matrix< Float > &lattice, Float &maxAbs, IPosition &posMax, const Int &supportSize=100)
	This is made static since findMaxAbs is static(!).
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
CountedPtr< Matrix< Float > >	itsMask
IPosition	itsPositionPeakPsf
Float	itsSmallScaleBias
Block< Matrix< Float > >	itsScaleMasks
Block< Matrix< Complex > >	itsScaleXfrs
Bool	itsScalesValid
Int	itsNscales
Float	itsMaskThreshold
Private Member Functions
Int	index (const Int scale, const Int otherscale)
	Calculate index into PsfConvScales.
Bool	destroyScales ()
Bool	destroyMasks ()
Private Attributes
CountedPtr< Matrix< Float > >	itsDirty
CountedPtr< Matrix< Complex > >	itsXfr
Vector< Float >	itsScaleSizes
Block< Matrix< Float > >	itsScales
Block< Matrix< Float > >	itsPsfConvScales
Block< Matrix< Float > >	itsDirtyConvScales
Int	itsIteration
Int	itsStartingIter
Quantum< Double >	itsFracThreshold
Float	itsMaximumResidual
Float	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
Bool	itsStopAtLargeScaleNegative
Int	itsStopPointMode
Bool	itsDidStopPointMode
Bool	itsJustStarting
IPosition	psfShape_p
	threshold for masks.
Bool	noClean_p
Friends
class	MatrixNACleaner
	Helper function to optimize adding static void addTo(Matrix<Float>& to, const Matrix<Float> & add);.

Detailed Description

A copy of LatticeCleaner but just using 2-D matrices.

Synopsis

It is a mimic of the LatticeCleaner class but avoid a lot of of the lattice to array and back copies and uses openmp in the obvious places

A class for doing multi-dimensional cleaning

Intended use:

Public interface

Review Status

Date Reviewed:: yyyy/mm/dd
Test programs:: tLatticeCleaner

Prerequisite

The mathematical concept of deconvolution

Etymology

The MatrixCleaner class will deconvolve 2-D arrays of floats.

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.

Definition at line 89 of file MatrixCleaner.h.

Constructor & Destructor Documentation

casa::MatrixCleaner::MatrixCleaner ( )

Create a cleaner : default constructor.

casa::MatrixCleaner::MatrixCleaner	(	const Matrix< Float > &	psf,
		const Matrix< Float > &	dirty
	)

Create a cleaner for a specific dirty image and PSF.

casa::MatrixCleaner::MatrixCleaner ( const MatrixCleaner & other )

The copy constructor uses reference semantics.

casa::MatrixCleaner::~MatrixCleaner ( )

The destructor does nothing special.

Member Function Documentation

Int casa::MatrixCleaner::clean	(	Matrix< Float > &	model,
		Bool	doPlotProgress = `False`
	)

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

void casa::MatrixCleaner::defineScales ( const Vector< Float > & scales )

just define the scales...nothing else is done the user will need to call setPsf+makePsfScales+setDirty+makeDirtyScales to be in a good state to clean.

Bool casa::MatrixCleaner::destroyMasks ( ) [private]

Bool casa::MatrixCleaner::destroyScales ( ) [private]

Int casa::MatrixCleaner::findBeamPatch	(	const Float	maxScaleSize,
		const Int &	nx,
		const Int &	ny,
		const Float	psfBeam = `4.0`,
		const Float	nBeams = `20.0`
	)			`[protected]`

static Bool casa::MatrixCleaner::findMaxAbs	(	const Matrix< Float > &	lattice,
		Float &	maxAbs,
		IPosition &	posMax
	)			`[static, protected]`

Find the Peak of the matrix.

Bool casa::MatrixCleaner::findMaxAbsMask	(	const Matrix< Float > &	lattice,
		const Matrix< Float > &	mask,
		Float &	maxAbs,
		IPosition &	posMax
	)			`[protected]`

Find the Peak of the lattice, applying a mask.

static Bool casa::MatrixCleaner::findPSFMaxAbs	(	const Matrix< Float > &	lattice,
		Float &	maxAbs,
		IPosition &	posMax,
		const Int &	supportSize = `100`
	)			`[static, protected]`

This is made static since findMaxAbs is static(!).

Why is findMaxAbs static??? --SB

void casa::MatrixCleaner::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 203 of file MatrixCleaner.h.

References itsIgnoreCenterBox.

Int casa::MatrixCleaner::index	(	const Int	scale,
		const Int	otherscale
	)			`[private]`

Calculate index into PsfConvScales.

Int casa::MatrixCleaner::iteration ( ) const [inline]

return how many iterations we did do

Definition at line 162 of file MatrixCleaner.h.

References itsIteration.

static void casa::MatrixCleaner::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.

void casa::MatrixCleaner::makeDirtyScales ( )

Calculate the convolutions for the dirt Obviously the.

void casa::MatrixCleaner::makePsfScales ( )

calculate the convolutions of the psf

void casa::MatrixCleaner::makeScale	(	Matrix< Float > &	scale,
		const Float &	scaleSize
	)			`[protected]`

Make an array of the specified scale.

Bool casa::MatrixCleaner::makeScaleMasks ( )

Call the function below if the psf is changed ..no need to setMask again.

Int casa::MatrixCleaner::numberIterations ( ) const [inline]

Definition at line 163 of file MatrixCleaner.h.

References itsIteration.

MatrixCleaner& casa::MatrixCleaner::operator= ( const MatrixCleaner & other )

The assignment operator also uses reference semantics.

Bool casa::MatrixCleaner::queryStopPointMode ( ) const [inline]

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

Definition at line 228 of file MatrixCleaner.h.

References itsDidStopPointMode.

Matrix<Float> casa::MatrixCleaner::residual ( ) [inline]

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

Definition at line 242 of file MatrixCleaner.h.

References itsDirtyConvScales.

Bool casa::MatrixCleaner::setcontrol	(	CleanEnums::CleanType	cleanType,
		const Int	niter,
		const Float	gain,
		const Quantity &	threshold
	)

This version of the method disables stopping on fractional threshold.

Bool casa::MatrixCleaner::setcontrol	(	CleanEnums::CleanType	cleanType,
		const Int	niter,
		const Float	gain,
		const Quantity &	aThreshold,
		const Quantity &	fThreshold
	)

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.

void casa::MatrixCleaner::setDirty ( const Matrix< Float > & dirty )

Set the dirty image without calculating convolutions.

\. can be done by calling makeDirtyScales or setscales if one want to redo the psfscales too.

void casa::MatrixCleaner::setMask	(	Matrix< Float > &	mask,
		const Float &	maskThreshold = `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.

void casa::MatrixCleaner::setPsf ( const Matrix< Float > & psf )

change the psf don't forget to redo the setscales or run makePsfScales, followed by makeDirtyScales

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

Set a specific set of scales.

Reimplemented in casa::MultiTermMatrixCleaner.

Bool casa::MatrixCleaner::setscales	(	const Int	nscales,
		const Float	scaleInc = `1.0`
	)

Set a number of scale sizes.

The units of the scale are pixels. The 2 functions below assume you have the dirty image and the psf set the convolutions are calculated automatically and the masks ones too if it is set ....kept so as to be compatible function wise with LatticeCleaner

void casa::MatrixCleaner::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 213 of file MatrixCleaner.h.

References itsSmallScaleBias.

void casa::MatrixCleaner::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

Float casa::MatrixCleaner::spheroidal ( Float nu ) [protected]

Make Spheroidal function for scale images.

void casa::MatrixCleaner::startingIteration ( const Int starting = 0 ) [inline]

what iteration number to start on

Definition at line 166 of file MatrixCleaner.h.

References itsStartingIter.

void casa::MatrixCleaner::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 219 of file MatrixCleaner.h.

References itsStopAtLargeScaleNegative, and casacore::True.

void casa::MatrixCleaner::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 224 of file MatrixCleaner.h.

References itsStopPointMode.

Float casa::MatrixCleaner::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 249 of file MatrixCleaner.h.

References itsStrengthOptimum.

Float casa::MatrixCleaner::threshold ( ) const

Method to return threshold, including any speedup factors.

Float casa::MatrixCleaner::totalFlux ( ) const [inline]

Total flux accumulated so far.

Definition at line 169 of file MatrixCleaner.h.

References itsTotalFlux.