A Class for performing the Clark Clean Algorithm on Arrays. More...

#include <ClarkCleanModel.h>

Inheritance diagram for casa::ClarkCleanModel:

Public Member Functions
	ClarkCleanModel ()
	The default constructor does nothing more than initialise a zero length array to hold the deconvolved model. More...

	ClarkCleanModel (casacore::Array< casacore::Float > &model)
	Construct the ClarkCleanModel object and initialise the model. More...

	ClarkCleanModel (casacore::Array< casacore::Float > &model, casacore::Array< casacore::Float > &mask)
	Construct the ClarkCleanModel object and initialise the model ans mask. More...

void	getMask (casacore::Array< casacore::Float > &mask) const

void	setMask (const casacore::Array< casacore::Float > &mask)

void	setMask (casacore::Array< casacore::Float > &mask)

void	getModel (casacore::Array< casacore::Float > &model) const

void	setModel (const casacore::Array< casacore::Float > &model)
	Set the current model. More...

void	setModel (casacore::Array< casacore::Float > &model)

virtual void	setProgress (ClarkCleanProgress &ccp)
	Set/get the progress display. More...

virtual ClarkCleanProgress &	getProgress ()

casacore::Bool	solve (ConvolutionEquation &eqn)
	Using a Clark clean deconvolution proceedure solve for an improved estimate of the deconvolved object. More...

casacore::Bool	singleSolve (ConvolutionEquation &eqn, casacore::Array< casacore::Float > &residual)

virtual void	setPsfPatchSize (const casacore::IPosition &psfPatchSize)
	These functions set various "knobs" that the user can tweak and are specific to the Clark clean algorithm. More...

virtual casacore::IPosition	getPsfPatchSize ()

virtual void	setHistLength (const casacore::uInt HistBins)
	Set the size of the histogram used to determine how many pixels are "active" in a minor iteration. More...

virtual casacore::uInt	getHistLength ()

virtual void	setMaxNumberMinorIterations (const casacore::uInt maxNumMinorIterations)
	Set the maximum number of minor iterations to perform for each major cycle. More...

virtual casacore::uInt	getMaxNumberMinorIterations ()

virtual void	setInitialNumberIterations (const casacore::uInt initialNumberIterations)
	Set and get the initial number of iterations. More...

virtual casacore::uInt	getInitialNumberIterations ()

virtual void	setMaxNumberMajorCycles (const casacore::uInt maxNumMajorCycles)
	Set the maximum number of major cycles to perform. More...

virtual casacore::uInt	getMaxNumberMajorCycles ()

virtual void	setMaxNumPix (const casacore::uInt maxNumPix)
	Set the maximum number of active pixels to use in the minor iterations. More...

virtual casacore::uInt	getMaxNumPix ()

virtual void	setMaxExtPsf (const casacore::Float maxExtPsf)
	Set the maximum exterior psf value. More...

virtual casacore::Float	getMaxExtPsf ()

virtual void	setSpeedup (const casacore::Float speedup)
	An exponent on the F(m,n) factor (see Clark[1980]) which influences how quickly active pixels are treated as unreliable. More...

virtual casacore::Float	getSpeedup ()

virtual void	setCycleSpeedup (const casacore::Float speedup)
	The structure of various AIPS++ algorithms creates major cycles around the Clark Clean (or other deconvolution algrithms. More...

virtual casacore::Float	getCycleSpeedup ()

virtual casacore::Float	threshold ()
	We are overwriting Iterate's threshold() method to put out speedup in it. More...

virtual void	setChoose (const casacore::Bool askForChoice)
	The user can be asked whether to stop after every minor cycle. More...

virtual casacore::Bool	getChoose ()

casacore::Float	getMaxResidual ()

Public Member Functions inherited from casa::ArrayModel< casacore::Float >
	ArrayModel ()

	ArrayModel (const casacore::Array< casacore::Float > &model)

	ArrayModel (casacore::Array< casacore::Float > &model)

virtual const casacore::Array < casacore::Float > &	getModel () const
	Return the current model. More...

Public Member Functions inherited from casa::LinearModel< casacore::Array< casacore::Float > >
virtual	~LinearModel ()
	A virtual destructor is necessary. More...

Public Member Functions inherited from casa::Iterate
	Iterate ()
	Constructor. More...

virtual	~Iterate ()

void	setFree ()
	Is this a free variable? More...

void	setNotFree ()

casacore::Bool	free ()

void	setNumberIterations (const casacore::Int n)

void	setGain (const casacore::Float g)

void	setTolerance (const casacore::Float t)

void	setThreshold (const casacore::Float t)

void	setMode (const casacore::String m)

casacore::Int	numberIterations ()

casacore::Float	gain ()

casacore::Float	tolerance ()

const casacore::String	mode ()

Private Member Functions
void	doMinorIterations (casacore::Array< casacore::Float > &model, casacore::Matrix< casacore::Float > &pixelValue, const casacore::Matrix< casacore::Int > &pixelPos, const casacore::Int numPix, casacore::Matrix< casacore::Float > &psfPatch, casacore::Float fluxLimit, casacore::uInt &numberIterations, casacore::Float Fmn, const casacore::uInt totalIterations, casacore::Float &totalflux)
	Do all the minor iterations for one major cycle. More...

casacore::Int	cacheActivePixels (casacore::Matrix< casacore::Float > &pixVal, casacore::Matrix< casacore::Int > &pixPos, const casacore::Array< casacore::Float > &data, const casacore::Float fluxLimit)
	Find all the pixels in the residual that are greater than fluxlimit, and store the values in the pixelsValue casacore::Matrix, and their positions in the pixelPos Matrix. More...

void	absHistogram (casacore::Vector< casacore::Int > &hist, casacore::Float &minVal, casacore::Float &maxVal, const casacore::Array< casacore::Float > &data)
	make histogram of absolute values in array More...

casacore::Float	biggestResiduals (casacore::Float &maxRes, const casacore::uInt maxNumPix, const casacore::Float fluxLimit, const casacore::Array< casacore::Float > &residual)
	Determine the flux limit if we only select the maxNumPix biggest residuals. More...

casacore::Float	getPsfPatch (casacore::Array< casacore::Float > &psfPatch, ConvolutionEquation &eqn)
	Work out the size of the Psf patch to use. More...

casacore::Float	maxResidual (const casacore::Array< casacore::Float > &residual)
	The maximum residual is the absolute maximum. More...

void	maxVect (casacore::Vector< casacore::Float > &maxVal, casacore::Float &absVal, casacore::Int &offset, const casacore::Matrix< casacore::Float > &pixVal, const casacore::Int numPix)

void	subtractComponent (casacore::Matrix< casacore::Float > &pixVal, const casacore::Matrix< casacore::Int > &pixPos, const casacore::Int numPix, const casacore::Vector< casacore::Float > &maxVal, const casacore::Vector< casacore::Int > &maxPos, const casacore::Matrix< casacore::Float > &psf)

casacore::Float	absMaxBeyondDist (const casacore::IPosition &maxDist, const casacore::IPosition &centre, const casacore::Array< casacore::Float > &array)

casacore::Bool	stopnow ()

Additional Inherited Members
Protected Attributes inherited from casa::ArrayModel< casacore::Float >
casacore::Array< casacore::Float >	theModel

Detailed Description

A Class for performing the Clark Clean Algorithm on Arrays.

Intended use:

Public interface

Review Status

Date Reviewed:: yyyy/mm/dd

Prerequisite

ResidualEquation/ConvolutionEquation
LinearModel/LinearEquation Paradigm

Etymology

This class is called ClarkCleanModel because thats the algorithm it uses deconvolve the model.

Synopsis

This class is used to perform the Clark Clean Algorithm on an Array. Only the deconvolved model of the sky are directly stored by this class. The point spread function (psf) and convolved (dirty) image are stored in a companion class which is must be derived from ResidualEquation.

The cleaning works like this. The user constructs a ClarkCleanModel by specifying an initial model of the sky. This can by be one,two,three... dimensional depending on the dimension of the psf (see below). The user then constructs a class which implements the forward equation between the model and the dirty image. Typically this will be the ConvolutionEquation class, although any class which has a ResidualEquation interface will be work (but perhaps very slowly, as the ConvolutionEquation class has member functions optimised for cleaning)

The user then calls the solve() function (with the appropriate equation class as an arguement), and this class will perform the Clark clean. The various clean parameters are set (prior to calling solve) using the functions derived from the Iterate class, in particular setGain(), setNumberIterations() & setThreshold() (to set a flux limit).

The solve() function does not return either the deconvolved model or the residuals. The solved model can be obtained using the getModel() function (derived from ArrayModel()) and the residual can be obtained using the residual() member function of the Convolution/Residual Equation Class.

The size and shape of the model used in this class MUST be the same as the convolved data (Dirty Image), stored in the companion ResidualEquation Class. However the model (and convolved data) can have more dimensions than the psf, as well as a different size (either larger or smaller). When the dimensionality is different the cleaning is done independendtly in each "plane" of the model. (Note this has not been implemented yet but is relatively simple to do if necessary).

This multi-dimensionalty is exploited when cleaning arrays of StokesVectors. Here the casacore::Array of StokesVectors is decomposed into a stack of 4 Floating point arrays and the cleaning is done on all the the arrays simultaneosly. The criterion for choosing the brightest pixel has been generalised by using the "length" of the Stokesvector in 4 dimensional space.

A companion class to this one is MaskedClarkCleanModel. This provides the same functionality but is used with MaskedArrays which indicate which regions of the model to search for clean components.

Example

 casacore::Matrix<casacore::Float> psf(12,12), dirty(10,10), initialModel(10,10);
...put appropriate values into psf, dirty, & initialModel...\.
 ClarkCleanModel<casacore::Float> deconvolvedModel(initialModel); 
 ConvolutionEquation convEqn(psf, dirty);
 deconvolvedModel.setGain(0.2); 
 deconvolvedModel.setNumberIterations(1000);
 casacore::Bool convWorked = deconvolvedModel.solve(convEqn);
 casacore::Array<casacore::Float> finalModel, residuals;
 if (convWorked){
 finalModel = deconvolvedModel.getModel();
 ConvEqn.residual(deconvolvedModel, finalResidual);
 }

Motivation

This class is needed to deconvolve images.

Template Type Argument Requirements (T)

have tested this class with Arrays of Float StokesVector

To Do

Make changes so that multidimensions work as advertised
compare timing with other clean implementations (ie, Mark's CleanTools, SDE, AIPS & miriad)

Definition at line 146 of file ClarkCleanModel.h.

Constructor & Destructor Documentation

casa::ClarkCleanModel::ClarkCleanModel ( )

The default constructor does nothing more than initialise a zero length array to hold the deconvolved model.

If this constructor is used then the actual model must be set using the setModel() function of the ArrayModel class.

casa::ClarkCleanModel::ClarkCleanModel ( casacore::Array< casacore::Float > & model )

Construct the ClarkCleanModel object and initialise the model.

casa::ClarkCleanModel::ClarkCleanModel	(	casacore::Array< casacore::Float > &	model,
		casacore::Array< casacore::Float > &	mask
	)

Construct the ClarkCleanModel object and initialise the model ans mask.

Member Function Documentation

void casa::ClarkCleanModel::absHistogram	(	casacore::Vector< casacore::Int > &	hist,
		casacore::Float &	minVal,
		casacore::Float &	maxVal,
		const casacore::Array< casacore::Float > &	data
	)

private

make histogram of absolute values in array

casacore::Float casa::ClarkCleanModel::absMaxBeyondDist	(	const casacore::IPosition &	maxDist,
		const casacore::IPosition &	centre,
		const casacore::Array< casacore::Float > &	array
	)

private

casacore::Float casa::ClarkCleanModel::biggestResiduals	(	casacore::Float &	maxRes,
		const casacore::uInt	maxNumPix,
		const casacore::Float	fluxLimit,
		const casacore::Array< casacore::Float > &	residual
	)

private

Determine the flux limit if we only select the maxNumPix biggest residuals.

Flux limit is not exact due to quantising by the histogram

casacore::Int casa::ClarkCleanModel::cacheActivePixels	(	casacore::Matrix< casacore::Float > &	pixVal,
		casacore::Matrix< casacore::Int > &	pixPos,
		const casacore::Array< casacore::Float > &	data,
		const casacore::Float	fluxLimit
	)

private

Find all the pixels in the residual that are greater than fluxlimit, and store the values in the pixelsValue casacore::Matrix, and their positions in the pixelPos Matrix.

Increases the size of the output matrices as necessary, but does not decrease them. So the actual number of "active" pixels is returned. This will always be less than (or equal to) the matrix size.

void casa::ClarkCleanModel::doMinorIterations	(	casacore::Array< casacore::Float > &	model,
		casacore::Matrix< casacore::Float > &	pixelValue,
		const casacore::Matrix< casacore::Int > &	pixelPos,
		const casacore::Int	numPix,
		casacore::Matrix< casacore::Float > &	psfPatch,
		casacore::Float	fluxLimit,
		casacore::uInt &	numberIterations,
		casacore::Float	Fmn,
		const casacore::uInt	totalIterations,
		casacore::Float &	totalflux
	)

private

Do all the minor iterations for one major cycle.

Cleaning stops when the flux or iteration limit is reached.

virtual casacore::Bool casa::ClarkCleanModel::getChoose ( )

virtual

virtual casacore::Float casa::ClarkCleanModel::getCycleSpeedup ( )

virtual

virtual casacore::uInt casa::ClarkCleanModel::getHistLength ( )

virtual

virtual casacore::uInt casa::ClarkCleanModel::getInitialNumberIterations ( )

virtual

void casa::ClarkCleanModel::getMask ( casacore::Array< casacore::Float > & mask ) const

virtual casacore::Float casa::ClarkCleanModel::getMaxExtPsf ( )

virtual

virtual casacore::uInt casa::ClarkCleanModel::getMaxNumberMajorCycles ( )

virtual

virtual casacore::uInt casa::ClarkCleanModel::getMaxNumberMinorIterations ( )

virtual

virtual casacore::uInt casa::ClarkCleanModel::getMaxNumPix ( )

virtual

casacore::Float casa::ClarkCleanModel::getMaxResidual ( )

inline

Definition at line 243 of file ClarkCleanModel.h.

References itsMaxRes.

void casa::ClarkCleanModel::getModel ( casacore::Array< casacore::Float > & model ) const

virtual

Reimplemented from casa::ArrayModel< casacore::Float >.

virtual ClarkCleanProgress& casa::ClarkCleanModel::getProgress ( )

inlinevirtual

Definition at line 172 of file ClarkCleanModel.h.

References itsProgressPtr.

casacore::Float casa::ClarkCleanModel::getPsfPatch	(	casacore::Array< casacore::Float > &	psfPatch,
		ConvolutionEquation &	eqn
	)

private

Work out the size of the Psf patch to use.

virtual casacore::IPosition casa::ClarkCleanModel::getPsfPatchSize ( )

virtual

virtual casacore::Float casa::ClarkCleanModel::getSpeedup ( )

virtual

casacore::Float casa::ClarkCleanModel::maxResidual ( const casacore::Array< casacore::Float > & residual )

private

The maximum residual is the absolute maximum.

void casa::ClarkCleanModel::maxVect	(	casacore::Vector< casacore::Float > &	maxVal,
		casacore::Float &	absVal,
		casacore::Int &	offset,
		const casacore::Matrix< casacore::Float > &	pixVal,
		const casacore::Int	numPix
	)

private

virtual void casa::ClarkCleanModel::setChoose ( const casacore::Bool askForChoice )

virtual

The user can be asked whether to stop after every minor cycle.

virtual void casa::ClarkCleanModel::setCycleSpeedup ( const casacore::Float speedup )

virtual

The structure of various AIPS++ algorithms creates major cycles around the Clark Clean (or other deconvolution algrithms.

The cycleSpeedup parameter causes the threshold to edge up as thresh = thresh_0 * 2^(iter/cycleSpeedup); ignored if cycleSpeedup <= 0.

virtual void casa::ClarkCleanModel::setHistLength ( const casacore::uInt HistBins )

virtual

Set the size of the histogram used to determine how many pixels are "active" in a minor iteration.

Default value is 1000 is OK for everything except very small cleans.

virtual void casa::ClarkCleanModel::setInitialNumberIterations ( const casacore::uInt initialNumberIterations )

virtual

Set and get the initial number of iterations.

void casa::ClarkCleanModel::setMask ( const casacore::Array< casacore::Float > & mask )

void casa::ClarkCleanModel::setMask ( casacore::Array< casacore::Float > & mask )

virtual void casa::ClarkCleanModel::setMaxExtPsf ( const casacore::Float maxExtPsf )

virtual

Set the maximum exterior psf value.

This is used to determine when to stop the minor itartions. This is normally determined from the psf and the number set here is only used if this cannot be determined. The default is zero.

virtual void casa::ClarkCleanModel::setMaxNumberMajorCycles ( const casacore::uInt maxNumMajorCycles )

virtual

Set the maximum number of major cycles to perform.

virtual void casa::ClarkCleanModel::setMaxNumberMinorIterations ( const casacore::uInt maxNumMinorIterations )

virtual

Set the maximum number of minor iterations to perform for each major cycle.

virtual void casa::ClarkCleanModel::setMaxNumPix ( const casacore::uInt maxNumPix )

virtual

Set the maximum number of active pixels to use in the minor iterations.

The specified number can be exceeded if the topmost bin of the histogram contains more pixels than specified here. The default is 10,000 which is suitable for images of 512by512 pixels. Reduce this for smaller images and increase it for larger ones.

void casa::ClarkCleanModel::setModel ( const casacore::Array< casacore::Float > & model )

virtual

Set the current model.

Reimplemented from casa::ArrayModel< casacore::Float >.

void casa::ClarkCleanModel::setModel ( casacore::Array< casacore::Float > & model )

virtual

Reimplemented from casa::ArrayModel< casacore::Float >.

virtual void casa::ClarkCleanModel::setProgress ( ClarkCleanProgress & ccp )

inlinevirtual

Set/get the progress display.

Definition at line 171 of file ClarkCleanModel.h.

References itsProgressPtr.

virtual void casa::ClarkCleanModel::setPsfPatchSize ( const casacore::IPosition & psfPatchSize )

virtual

These functions set various "knobs" that the user can tweak and are specific to the Clark clean algorithm.

The more generic parameters ie. clean gain, and maximum residual fluxlimit, are set using functions in the Iterate base class. The get functions return the value that was actually used after the cleaning was done.

set the size of the PSF used in the minor iterations. If not set it defaults to the largest useful Psf (ie. min(modelSize*2, psfSize))

virtual void casa::ClarkCleanModel::setSpeedup ( const casacore::Float speedup )

virtual

An exponent on the F(m,n) factor (see Clark[1980]) which influences how quickly active pixels are treated as unreliable.

Larger values mean more major iterations. The default is zero. I have no experience on when to use this factor.

casacore::Bool casa::ClarkCleanModel::singleSolve	(	ConvolutionEquation &	eqn,
		casacore::Array< casacore::Float > &	residual
	)

casacore::Bool casa::ClarkCleanModel::solve ( ConvolutionEquation & eqn )

Using a Clark clean deconvolution proceedure solve for an improved estimate of the deconvolved object.

The convolution/residual equation contains the psf and dirty image. When called with a ResidualEquation arguement a quite general interface is used that is slow. The convolution equation contains functions that speed things up. The functions return false if the deconvolution could not be done.

casacore::Bool casa::ClarkCleanModel::stopnow ( )

private

void casa::ClarkCleanModel::subtractComponent	(	casacore::Matrix< casacore::Float > &	pixVal,
		const casacore::Matrix< casacore::Int > &	pixPos,
		const casacore::Int	numPix,
		const casacore::Vector< casacore::Float > &	maxVal,
		const casacore::Vector< casacore::Int > &	maxPos,
		const casacore::Matrix< casacore::Float > &	psf
	)

private

virtual casacore::Float casa::ClarkCleanModel::threshold ( )

virtual

We are overwriting Iterate's threshold() method to put out speedup in it.

Reimplemented from casa::Iterate.

Member Data Documentation

casacore::Bool casa::ClarkCleanModel::itsJustStarting

private

Definition at line 304 of file ClarkCleanModel.h.

casacore::Float casa::ClarkCleanModel::itsMaxRes

private

Definition at line 306 of file ClarkCleanModel.h.

Referenced by getMaxResidual().

ClarkCleanProgress* casa::ClarkCleanModel::itsProgressPtr

private

Definition at line 303 of file ClarkCleanModel.h.

Referenced by getProgress(), and setProgress().

casacore::Bool casa::ClarkCleanModel::theChoose

private

Definition at line 295 of file ClarkCleanModel.h.

casacore::Float casa::ClarkCleanModel::theCycleSpeedup

private

Definition at line 294 of file ClarkCleanModel.h.

casacore::uInt casa::ClarkCleanModel::theHistBins

private

Definition at line 286 of file ClarkCleanModel.h.

casacore::uInt casa::ClarkCleanModel::theInitialNumberIterations

private

Definition at line 289 of file ClarkCleanModel.h.

casacore::Int casa::ClarkCleanModel::theIterCounter

private

There are too many iterations counters.

This one is required for theCycleSpeedup and threshold(), and just keeps track of the total iterations done by THIS ClarkCleanModel

Definition at line 302 of file ClarkCleanModel.h.

casacore::LogIO casa::ClarkCleanModel::theLog

private

Definition at line 297 of file ClarkCleanModel.h.

casacore::Array<casacore::Float> casa::ClarkCleanModel::theMask

private

Definition at line 296 of file ClarkCleanModel.h.

casacore::Float casa::ClarkCleanModel::theMaxExtPsf

private

Definition at line 287 of file ClarkCleanModel.h.

casacore::Int casa::ClarkCleanModel::theMaxNumberMajorCycles

private

Definition at line 290 of file ClarkCleanModel.h.

casacore::uInt casa::ClarkCleanModel::theMaxNumberMinorIterations

private

Definition at line 288 of file ClarkCleanModel.h.

casacore::uInt casa::ClarkCleanModel::theMaxNumPix

private

Definition at line 291 of file ClarkCleanModel.h.

casacore::IPosition casa::ClarkCleanModel::thePsfPatchSize

private

Definition at line 292 of file ClarkCleanModel.h.

casacore::Float casa::ClarkCleanModel::theSpeedup

private

Definition at line 293 of file ClarkCleanModel.h.

The documentation for this class was generated from the following file:

casa/code/synthesis/MeasurementEquations/ClarkCleanModel.h

Private Attributes
casacore::uInt	theHistBins

casacore::Float	theMaxExtPsf

casacore::uInt	theMaxNumberMinorIterations

casacore::uInt	theInitialNumberIterations

casacore::Int	theMaxNumberMajorCycles

casacore::uInt	theMaxNumPix

casacore::IPosition	thePsfPatchSize

casacore::Float	theSpeedup

casacore::Float	theCycleSpeedup

casacore::Bool	theChoose

casacore::Array< casacore::Float >	theMask

casacore::LogIO	theLog

casacore::Int	theIterCounter
	There are too many iterations counters. More...

ClarkCleanProgress *	itsProgressPtr

casacore::Bool	itsJustStarting

casacore::Float	itsMaxRes

Public Member Functions

Private Member Functions

Private Attributes

Additional Inherited Members

Detailed Description

Intended use:

Review Status

Prerequisite

Etymology

Synopsis

Example

Motivation

Template Type Argument Requirements (T)

To Do

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation