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

#include <ClarkCleanLatModel.h>

Inheritance diagram for casa::ClarkCleanLatModel:

Public Member Functions
	ClarkCleanLatModel ()
	The default constructor does nothing more than initialise a zero length array to hold the deconvolved model.
	ClarkCleanLatModel (Lattice< Float > &model)
	Construct the ClarkCleanLatModel object and initialise the model.
	ClarkCleanLatModel (Lattice< Float > &model, Lattice< Float > &mask)
	Construct the ClarkCleanLatModel object and initialise the model ans mask.
	ClarkCleanLatModel (Lattice< Float > &model, Lattice< Float > &residual, Lattice< Float > &mask)
	Construct the ClarkCleanLatModel object and initialise the model ans mask.
virtual	~ClarkCleanLatModel ()
	Destroy!
virtual const Lattice< Float > &	getModel () const
	Return the current model.
virtual void	setModel (const Lattice< Float > &model)
	Set the current model.
virtual void	setModel (Lattice< Float > &model)
const Lattice< Float > &	getMask () const
void	setMask (const Lattice< Float > &mask)
void	setResidual (Lattice< Float > &residual)
Float	getMaxResidual ()
Bool	solve (LatConvEquation &eqn)
	Using a Clark clean deconvolution proceedure solve for an improved estimate of the deconvolved object.
Bool	singleSolve (LatConvEquation &eqn, Lattice< Float > &residual)
virtual void	setChoose (const Bool askForChoice)
	The user can be asked whether to stop after every minor cycle.
virtual Bool	getChoose ()
virtual void	setPsfPatchSize (const IPosition &psfPatchSize)
	These remaining functions set various "knobs" that the user can tweak and are specific to the Clark clean algorithm.
virtual IPosition	getPsfPatchSize ()
virtual void	setHistLength (const uInt histBins)
	Set the size of the histogram used to determine how many pixels are "active" in a minor iteration.
virtual uInt	getHistLength ()
virtual void	setMaxNumberMinorIterations (const uInt maxNumMinorIterations)
	Set the maximum number of minor iterations to perform for each major cycle.
virtual uInt	getMaxNumberMinorIterations ()
virtual void	setInitialNumberIterations (const uInt initialNumberIterations)
	Set and get the initial number of iterations.
virtual uInt	getInitialNumberIterations ()
virtual void	setMaxNumberMajorCycles (const uInt maxNumMajorCycles)
	Set the maximum number of major cycles to perform.
virtual uInt	getMaxNumberMajorCycles ()
virtual void	setMaxNumPix (const uInt maxNumPix)
	Set the maximum number of active pixels to use in the minor iterations.
virtual uInt	getMaxNumPix ()
virtual void	setMaxExtPsf (const Float maxExtPsf)
	Set the maximum exterior psf value.
virtual Float	getMaxExtPsf ()
Float	modelFlux ()
	The total flux density in the model.
virtual void	setSpeedup (const Float speedup)
	An exponent on the F(m,n) factor (see Clark[1980]) which influences how quickly active pixels are treated as unreliable.
virtual Float	getSpeedup ()
virtual void	setCycleFactor (const Float factor)
	Set the cycle factor....the larger this is the shallower is the minor cycle.
virtual void	setProgress (ClarkCleanProgress &ccp)
	Set/get the progress display.
virtual ClarkCleanProgress &	getProgress ()
Private Member Functions
void	doMinorIterations (CCList &activePixels, Matrix< Float > &psfPatch, Float fluxLimit, uInt &numberIterations, Float Fmn, const uInt totalIterations, Float &totalFlux)

void	cacheActivePixels (CCList &activePixels, const Lattice< Float > &residual, Float fluxLimit)
void	absHistogram (Vector< Int > &hist, Float &minVal, Float &maxVal, const Lattice< Float > &data)
	make histogram of absolute values in array
Float	biggestResiduals (Float &maxRes, const uInt maxNumPix, const Float fluxLimit, const Lattice< Float > &residual)
	Determine the flux limit if we only select the maxNumPix biggest residuals.
Float	getPsfPatch (Matrix< Float > &psfPatch, LatConvEquation &eqn)
	Work out the size of the Psf patch to use.
Float	maxResidual (const Lattice< Float > &residual)
	The maximum residual is the absolute maximum.
void	maxVect (Block< Float > &maxVal, Float &absVal, Int &offset, const CCList &activePixels)
void	subtractComponent (CCList &activePixels, const Block< Float > &maxVal, const Block< Int > &maxPos, const Matrix< Float > &psf)
Float	absMaxBeyondDist (const IPosition &maxDist, const IPosition &centre, const Lattice< Float > &psf)
Bool	stopnow ()
Int	getbig (Float const pixValPtr, Int const pixPosPtr, const Int nPix, const Float fluxLimit, const Float const residualPtr, const Float const maskPtr, const uInt npol, const Int nx, const Int ny)
void	updateModel (CCList &cleanComponents)
Private Attributes
Lattice< Float > *	itsModelPtr
Lattice< Float > *	itsResidualPtr
const Lattice< Float > *	itsSoftMaskPtr
uInt	itsMaxNumPix
uInt	itsHistBins
uInt	itsMaxNumberMinorIterations
uInt	itsInitialNumberIterations
Int	itsMaxNumberMajorCycles
Float	itsMaxExtPsf
Float	itsMaxRes
IPosition	itsPsfPatchSize
Bool	itsChoose
Float	itsSpeedup
Float	itsCycleFactor
LogIO	itsLog
ClarkCleanProgress *	itsProgressPtr
Bool	itsJustStarting
Bool	itsWarnFlag

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/LatConvEquation
LinearModel/LinearEquation Paradigm

Etymology

This class is called ClarkCleanLatModel because thats the algorithm it uses deconvolve the lattice-based 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 ClarkCleanLatModel 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 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 MaskedClarkCleanLatModel. This provides the same functionality but is used with MaskedArrays which indicate which regions of the model to search for clean components.

Example

    Matrix<Float> psf(12,12), dirty(10,10), initialModel(10,10);
    ...put appropriate values into psf, dirty, & initialModel...\.
    ClarkCleanLatModel<Float> deconvolvedModel(initialModel); 
    ConvolutionEquation convEqn(psf, dirty);
    deconvolvedModel.setGain(0.2); 
    deconvolvedModel.setNumberIterations(1000);
    Bool convWorked = deconvolvedModel.solve(convEqn);
    if (convWorked)
      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 145 of file ClarkCleanLatModel.h.

Constructor & Destructor Documentation

casa::ClarkCleanLatModel::ClarkCleanLatModel ( )

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 LatticeModel class.

casa::ClarkCleanLatModel::ClarkCleanLatModel ( Lattice< Float > & model )

Construct the ClarkCleanLatModel object and initialise the model.

casa::ClarkCleanLatModel::ClarkCleanLatModel	(	Lattice< Float > &	model,
		Lattice< Float > &	mask
	)

Construct the ClarkCleanLatModel object and initialise the model ans mask.

casa::ClarkCleanLatModel::ClarkCleanLatModel	(	Lattice< Float > &	model,
		Lattice< Float > &	residual,
		Lattice< Float > &	mask
	)

Construct the ClarkCleanLatModel object and initialise the model ans mask.

virtual casa::ClarkCleanLatModel::~ClarkCleanLatModel ( ) [virtual]

Destroy!

Member Function Documentation

void casa::ClarkCleanLatModel::absHistogram	(	Vector< Int > &	hist,
		Float &	minVal,
		Float &	maxVal,
		const Lattice< Float > &	data
	)		`[private]`

make histogram of absolute values in array

Float casa::ClarkCleanLatModel::absMaxBeyondDist	(	const IPosition &	maxDist,
		const IPosition &	centre,
		const Lattice< Float > &	psf
	)		`[private]`

Float casa::ClarkCleanLatModel::biggestResiduals	(	Float &	maxRes,
		const uInt	maxNumPix,
		const Float	fluxLimit,
		const Lattice< 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

void casa::ClarkCleanLatModel::cacheActivePixels	(	CCList &	activePixels,
		const Lattice< Float > &	residual,
		Float	fluxLimit
	)		`[private]`

void casa::ClarkCleanLatModel::doMinorIterations	(	CCList &	activePixels,
		Matrix< Float > &	psfPatch,
		Float	fluxLimit,
		uInt &	numberIterations,
		Float	Fmn,
		const uInt	totalIterations,
		Float &	totalFlux
	)		`[private]`

Do all the minor iterations for one major cycle. Cleaning stops when the flux or iteration limit is reached.

Int casa::ClarkCleanLatModel::getbig	(	Float const *	pixValPtr,
		Int const *	pixPosPtr,
		const Int	nPix,
		const Float	fluxLimit,
		const Float *const	residualPtr,
		const Float *const	maskPtr,
		const uInt	npol,
		const Int	nx,
		const Int	ny
	)		`[private]`

virtual Bool casa::ClarkCleanLatModel::getChoose ( ) [virtual]

virtual uInt casa::ClarkCleanLatModel::getHistLength ( ) [virtual]

virtual uInt casa::ClarkCleanLatModel::getInitialNumberIterations ( ) [virtual]

const Lattice<Float>& casa::ClarkCleanLatModel::getMask ( ) const

virtual Float casa::ClarkCleanLatModel::getMaxExtPsf ( ) [virtual]

virtual uInt casa::ClarkCleanLatModel::getMaxNumberMajorCycles ( ) [virtual]

virtual uInt casa::ClarkCleanLatModel::getMaxNumberMinorIterations ( ) [virtual]

virtual uInt casa::ClarkCleanLatModel::getMaxNumPix ( ) [virtual]

Float casa::ClarkCleanLatModel::getMaxResidual ( ) [inline]

Definition at line 177 of file ClarkCleanLatModel.h.

References itsMaxRes.

virtual const Lattice<Float>& casa::ClarkCleanLatModel::getModel ( ) const [inline, virtual]

Return the current model.

Implements casa::LinearModel< Lattice< Float > >.

Definition at line 168 of file ClarkCleanLatModel.h.

References itsModelPtr.

virtual ClarkCleanProgress& casa::ClarkCleanLatModel::getProgress ( ) [inline, virtual]

Definition at line 274 of file ClarkCleanLatModel.h.

References itsProgressPtr.

Float casa::ClarkCleanLatModel::getPsfPatch	(	Matrix< Float > &	psfPatch,
		LatConvEquation &	eqn
	)		`[private]`

Work out the size of the Psf patch to use.

virtual IPosition casa::ClarkCleanLatModel::getPsfPatchSize ( ) [virtual]

virtual Float casa::ClarkCleanLatModel::getSpeedup ( ) [virtual]

Float casa::ClarkCleanLatModel::maxResidual ( const Lattice< Float > & residual ) [private]

The maximum residual is the absolute maximum.

void casa::ClarkCleanLatModel::maxVect	(	Block< Float > &	maxVal,
		Float &	absVal,
		Int &	offset,
		const CCList &	activePixels
	)		`[private]`

Float casa::ClarkCleanLatModel::modelFlux ( )

The total flux density in the model.

virtual void casa::ClarkCleanLatModel::setChoose ( const Bool askForChoice ) [virtual]

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

virtual void casa::ClarkCleanLatModel::setCycleFactor ( const Float factor ) [virtual]

Set the cycle factor....the larger this is the shallower is the minor cycle.

virtual void casa::ClarkCleanLatModel::setHistLength ( const uInt histBins ) [virtual]

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

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

virtual void casa::ClarkCleanLatModel::setInitialNumberIterations ( const uInt initialNumberIterations ) [virtual]

Set and get the initial number of iterations.

void casa::ClarkCleanLatModel::setMask ( const Lattice< Float > & mask )

virtual void casa::ClarkCleanLatModel::setMaxExtPsf ( const 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::ClarkCleanLatModel::setMaxNumberMajorCycles ( const uInt maxNumMajorCycles ) [virtual]

Set the maximum number of major cycles to perform.

virtual void casa::ClarkCleanLatModel::setMaxNumberMinorIterations ( const uInt maxNumMinorIterations ) [virtual]

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

virtual void casa::ClarkCleanLatModel::setMaxNumPix ( const 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.

virtual void casa::ClarkCleanLatModel::setModel ( const Lattice< Float > & model ) [virtual]

Set the current model.

Implements casa::LinearModel< Lattice< Float > >.

virtual void casa::ClarkCleanLatModel::setModel ( Lattice< Float > & model ) [virtual]

virtual void casa::ClarkCleanLatModel::setProgress ( ClarkCleanProgress & ccp ) [inline, virtual]

Set/get the progress display.

Definition at line 273 of file ClarkCleanLatModel.h.

References itsProgressPtr.

virtual void casa::ClarkCleanLatModel::setPsfPatchSize ( const IPosition & psfPatchSize ) [virtual]

These remaining 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))

void casa::ClarkCleanLatModel::setResidual ( Lattice< Float > & residual )

virtual void casa::ClarkCleanLatModel::setSpeedup ( const 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.

Bool casa::ClarkCleanLatModel::singleSolve	(	LatConvEquation &	eqn,
		Lattice< Float > &	residual
	)

Bool casa::ClarkCleanLatModel::solve ( LatConvEquation & 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.

Bool casa::ClarkCleanLatModel::stopnow ( ) [private]

void casa::ClarkCleanLatModel::subtractComponent	(	CCList &	activePixels,
		const Block< Float > &	maxVal,
		const Block< Int > &	maxPos,
		const Matrix< Float > &	psf
	)		`[private]`