A class for manipulating groups of components. More...

#include <ComponentList.h>

Public Types
enum	SortCriteria { FLUX, POSITION, POLARISATION, UNSORTED, NUMBER_CRITERIA }
	Sorting criteria for components. More...
Public Member Functions
	ComponentList ()
	Construct a componentList with no members in the list.
	ComponentList (const Path &fileName, const Bool readOnly=False)
	Read a componentList from an existing table.
	ComponentList (const ComponentList &other)
	The Copy constructor uses reference semantics.
	~ComponentList ()
	The destructor saves the list to disk if it has a name (assigned using the setName member function)
ComponentList &	operator= (const ComponentList &other)
	The assignment operator uses reference semantics.
Bool	isPhysical (const Vector< Int > &index) const
	Returns True if all the specified components are physically plausable.
Flux< Double >	sample (const MDirection &sampleDir, const MVAngle &pixelLatSize, const MVAngle &pixelLongSize, const MFrequency &centerFreq) const
	Calculate the integrated flux of all the members of the componentlist at the specified direction & frequency, in a pixel of specified size.
void	sample (Cube< Double > &samples, const Unit &reqUnit, const Vector< MVDirection > &directions, const MeasRef< MDirection > &dirRef, const MVAngle &pixelLatSize, const MVAngle &pixelLongSize, const Vector< MVFrequency > &frequencies, const MeasRef< MFrequency > &freqRef) const
	Same as the previous function except that many directions & frequencies are done at once.
void	add (SkyComponent component)
	Add a SkyComponent to the end of the ComponentList.
void	addList (const ComponentList &list)
	Add a SkyComponents in a ComponentList to the end of this ComponentList.
void	remove (const uInt &index)
	Remove the specified SkyComponent(s) from the ComponentList.
void	remove (const Vector< Int > &indices)
uInt	nelements () const
	returns how many components are in the list.
void	deselect (const Vector< Int > &index)
	deselect the specified component.
void	select (const Vector< Int > &index)
	select the specified component.
Vector< Int >	selected () const
	Returns a Vector whose indices indicate which components are selected.
void	setLabel (const Vector< Int > &which, const String &newLabel)
	set the label on the specified components to the specified string
void	getFlux (Vector< Quantity > &fluxQuant, const Int &which) const
	get the the flux as a double param: which - the component number (0 based) return The flux as a Quantity
void	getFlux (Vector< Quantum< Complex > > &fluxQuant, const Int &which)
Vector< String >	getStokes (const Int &which) const
	get the associated polarizations as a vector of strings for the specified component.
void	setFlux (const Vector< Int > &which, const Flux< Double > &newFlux)
	set the flux on the specified components to the specified flux
void	convertFluxUnit (const Vector< Int > &which, const Unit &unit)
	convert the flux on the specified components to the specified units
void	convertFluxPol (const Vector< Int > &which, ComponentType::Polarisation pol)
	convert the flux on the specified components to the specified polarisation representation
void	setRefDirection (const Vector< Int > &which, const MVDirection &newDir)
	set the reference direction on the specified components to the specified direction.
void	setRefDirectionFrame (const Vector< Int > &which, MDirection::Types newFrame)
	set the reference direction frame on the specified components to the specified one.
void	convertRefDirection (const Vector< Int > &which, MDirection::Types newFrame)
	Convert the reference direction frame on the specified components to the specified one.
MDirection	getRefDirection (Int which) const
void	setShape (const Vector< Int > &which, const ComponentShape &newShape)
	set the shape on the specified components to the specified one.
const ComponentShape *	getShape (Int which) const
	get the shape of the specified component as a const pointer.
void	setShapeParms (const Vector< Int > &which, const ComponentShape &newShape)
	set the shape on the specified components to the specified one.
void	setOptParms (const Vector< Int > &which, const ComponentShape &newShape)
void	setSpectrum (const Vector< Int > &which, const SpectralModel &newSpectrum)
	set the spectrum on the specified components to the specified one.
void	setSpectrumParms (const Vector< Int > &which, const SpectralModel &newSpectrum)
	set the spectrum on the specified components to the specified one.
void	setRefFrequency (const Vector< Int > &which, const MVFrequency &newFreq)
	set the reference frequency on the specified components to the specified frequency.
void	setRefFrequencyFrame (const Vector< Int > &which, MFrequency::Types newFrame)
	set the reference frequency frame on the specified components to the specified one.
void	setRefFrequencyUnit (const Vector< Int > &which, const Unit &unit)
	set the reference frequency unit on the specified components to the specified one.
const SkyComponent &	component (const uInt &index) const
	returns a reference to the specified element in the list.
SkyComponent &	component (const uInt &index)
void	rename (const Path &newName, const Table::TableOption option=Table::New)
	Make the ComponentList persistant by supplying a filename.
ComponentList	copy () const
	Make a real copy of this componentList.
void	sort (ComponentList::SortCriteria criteria)
	Sort the components in the list using the given criteria.
Bool	ok () const
	Function which checks the internal data of this class for consistant values.
Bool	fromRecord (String &error, const RecordInterface &inRec)
	methods to store itself as a Record and recover from a Record its state
Bool	toRecord (String &error, RecordInterface &outRec) const
String	summarize (uInt index) const
	Summarize specified component as a formatted string.
Static Public Member Functions
static String	name (ComponentList::SortCriteria enumerator)
	Convert the SortCriteria enumerator to a string.
static ComponentList::SortCriteria	type (const String &criteria)
	Convert a given String to a Type enumerator.
Private Member Functions
void	createTable (const Path &fileName, const Table::TableOption option)
	Privarte function to create the Table which will hold the components void createTable(const Path& fileName, const Table::TableOption option, const Bool addOptCol);.
void	writeTable ()
	Private function to write the components to disk.
void	readTable (const Path &fileName, const Bool readOnly)
	Private function to read the components from disk.
Private Attributes
Block< SkyComponent >	itsList
uInt	itsNelements
Table	itsTable
Bool	itsROFlag
Block< Bool >	itsSelectedFlags
Block< uInt >	itsOrder
Bool	itsAddOptCol

Detailed Description

A class for manipulating groups of components.

Intended use:

Public interface

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

Prerequisite

SkyCompBase

Etymology

Because the SkyComponents were originally stored in a linked list ComponentList seemed like a good name for this class. Now the list is gone (in favour of a Block<SkyComponent>) but the name has stuck.

Synopsis

This class is a container that allows many SkyComponents to be grouped together and manipulated as one large compound component. The major operations of this class are:

Functions to traverse the list and extract individual components: See the nelements & component functions
Functions to add and delete components.: See the add, remove & copy functions
Functions to designate components as being selected or not.: See the select, deselect & selected functions
Functions to sample the flux of the components in any direction and frequency or to grid them onto an Image.: See the sample & project functions.
Functions to save the components to a table and read them back again: See the rename function and the appropriate constructor.
Functions to manipulate the flux of all components: See the setFlux, convertFluxUnit & convertFluxPol functions.
Functions to manipulate the reference direction of all components: See the setRefDirection & convertRefFrame functions.
functions to sort the components: See the sort, type & namel functions.

ComponentLists are memory based objects that can write their contents to and from disk (ie a Table). To read a componentList from a Table the appropriate constructor must be used. Alternatively an empty componentlist can be created that is not associated with a Table. To save the list to disk it must be given a name. This is done using the rename function. This will rename the Table if the ComponentList was already associated with a Table. Saving changes to the table on disk happens automatically when the list is destructed or reset via the assignment operator (unless the table was opened read-only).

The elements of a componentlist (ie., SkyComponents) are accessed via the component functions. These functions return the SkyComponent by reference and hence manipulating the supplied component manipulates the specified element of the list.

Example

These examples are coded in the tComponentList.h file.

Example 1:

In this example a ComponentList object is created and used to calculate the ...

Motivation

A way was needed to read/write groups of components to disk and manipulate them as a whole.

Thrown Exceptions

AipsError - If an internal inconsistancy is detected, when compiled in debug mode only.

To Do

Nothing I hope. But I expect users will disagree.

Definition at line 138 of file ComponentList.h.

Member Enumeration Documentation

enum casa::ComponentList::SortCriteria

Sorting criteria for components.

Enumerator:

FLUX	Sort the components by ABS(I flux), largest first.
POSITION	Sort the components by distance from the reference, closest first.
POLARISATION	Sort the components by fractional polarisation, biggest first.
UNSORTED	No sorting is necessary.
NUMBER_CRITERIA	The number of criteria in this enumerator.

Definition at line 141 of file ComponentList.h.

Constructor & Destructor Documentation

casa::ComponentList::ComponentList ( )

Construct a componentList with no members in the list.

casa::ComponentList::ComponentList	(	const Path &	fileName,
		const Bool	readOnly = `False`
	)

Read a componentList from an existing table.

By default the Table is opened read-write. Any subsequent changes made to a list opened read-only (i.e. via add(), remove(), or editing a non-const member component returned by component()) will not be saved to disk.

casa::ComponentList::ComponentList ( const ComponentList & other )

The Copy constructor uses reference semantics.

casa::ComponentList::~ComponentList ( )

The destructor saves the list to disk if it has a name (assigned using the setName member function)

Member Function Documentation

void casa::ComponentList::add ( SkyComponent component )

Add a SkyComponent to the end of the ComponentList.

The list length is increased by one when using this function. By default the newly added component is not selected. Note that it is possible to add a component to a list that was opened read-only; however, the table on disk will not be updated with new component.

void casa::ComponentList::addList ( const ComponentList & list )

Add a SkyComponents in a ComponentList to the end of this ComponentList.

The list length is increased by the number of components in the added list. By default the newly added components are not selected. Note that it is possible to add a component list to a list that was opened read-only; however, the table on disk will not be updated with new components.

const SkyComponent& casa::ComponentList::component ( const uInt & index ) const

returns a reference to the specified element in the list.

Thrown Exceptions

AipsError - If the list is associated with a table that was opened readonly (non-const version only).
AipsError - If the index is equal to or larger than the number of elements in the list.

Referenced by casa::UVMod::skycomp().

SkyComponent& casa::ComponentList::component ( const uInt & index )

void casa::ComponentList::convertFluxPol	(	const Vector< Int > &	which,
		ComponentType::Polarisation	pol
	)

convert the flux on the specified components to the specified polarisation representation

Thrown Exceptions

AipsError - If the index is equal to or larger than the number of elements in the list or less than zero

void casa::ComponentList::convertFluxUnit	(	const Vector< Int > &	which,
		const Unit &	unit
	)

convert the flux on the specified components to the specified units

Thrown Exceptions

AipsError - If the index is equal to or larger than the number of elements in the list or less than zero

void casa::ComponentList::convertRefDirection	(	const Vector< Int > &	which,
		MDirection::Types	newFrame
	)

Convert the reference direction frame on the specified components to the specified one.

Changes the direction values.

<h3>Thrown Exceptions</h3><ul>  <li> AipsError - If the index is equal to or larger than the number of
                  elements in the list or less than zero
</ul>

ComponentList casa::ComponentList::copy ( ) const

Make a real copy of this componentList.

As the copy constructor and the assignment operator use reference semantics this is the only way to get a distinct version of the componentList.

void casa::ComponentList::createTable	(	const Path &	fileName,
		const Table::TableOption	option
	)		`[private]`

Privarte function to create the Table which will hold the components void createTable(const Path& fileName, const Table::TableOption option, const Bool addOptCol);.

void casa::ComponentList::deselect ( const Vector< Int > & index )

deselect the specified component.

Throws an exception (AipsError) if any element in the index is out of range, ie. index >= nelements().

Thrown Exceptions

AipsError - If the index is equal to or larger than the number of elements in the list or less than zero

Bool casa::ComponentList::fromRecord	(	String &	error,
		const RecordInterface &	inRec
	)

methods to store itself as a Record and recover from a Record its state

void casa::ComponentList::getFlux	(	Vector< Quantity > &	fluxQuant,
		const Int &	which
	)		const

get the the flux as a double param: which - the component number (0 based) return The flux as a Quantity

void casa::ComponentList::getFlux	(	Vector< Quantum< Complex > > &	fluxQuant,
		const Int &	which
	)

MDirection casa::ComponentList::getRefDirection ( Int which ) const

const ComponentShape* casa::ComponentList::getShape ( Int which ) const

get the shape of the specified component as a const pointer.

No need to delete it, it will be deleted when the variable goes out of scope.

Vector<String> casa::ComponentList::getStokes ( const Int & which ) const

get the associated polarizations as a vector of strings for the specified component.

Returned vector always has 4 elements.

Bool casa::ComponentList::isPhysical ( const Vector< Int > & index ) const

Returns True if all the specified components are physically plausable.

See the isPhysical function in the SkyCompBase class for a precise definition of what this means.

Thrown Exceptions

AipsError - If the index is equal to or larger than the number of elements in the list or less than zero

static String casa::ComponentList::name ( ComponentList::SortCriteria enumerator ) [static]

Convert the SortCriteria enumerator to a string.

uInt casa::ComponentList::nelements ( ) const

returns how many components are in the list.

Bool casa::ComponentList::ok ( ) const

Function which checks the internal data of this class for consistant values.

Returns True if everything is fine otherwise returns False.

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

The assignment operator uses reference semantics.

void casa::ComponentList::readTable	(	const Path &	fileName,
		const Bool	readOnly
	)		`[private]`

Private function to read the components from disk.

Thrown Exceptions

AipsError - If the table is not readable
AipsError - If the table is not writable (and readOnly==False)

void casa::ComponentList::remove ( const uInt & index )

Remove the specified SkyComponent(s) from the ComponentList.

After removing a component all the components with an indices greater than this one will be reduced by one. For example in a five element list removing elements [0,2,4] will result in a two element list, now indexed as elements zero and one, containing what was previously the second and fourth components. Note that it is possible to remove a component from a list that was opened read-only; however, the table on disk will not be updated accordingly.

Thrown Exceptions

AipsError - If the index is equal to or larger than the number of elements in the list or is negative.

void casa::ComponentList::remove ( const Vector< Int > & indices )

void casa::ComponentList::rename	(	const Path &	newName,
		const Table::TableOption	option = `Table::New`
	)

Make the ComponentList persistant by supplying a filename.

If the ComponentList is already associated with a Table then the Table will be renamed. Hence this function cannot be used with ComponentLists that are constructed with readonly=True.

Thrown Exceptions

AipsError - If the list is associated with a table that was opened readonly
AipsError - If option is Table::Old as this does not make sense

Flux<Double> casa::ComponentList::sample	(	const MDirection &	sampleDir,
		const MVAngle &	pixelLatSize,
		const MVAngle &	pixelLongSize,
		const MFrequency &	centerFreq
	)		const

Calculate the integrated flux of all the members of the componentlist at the specified direction & frequency, in a pixel of specified size.

void casa::ComponentList::sample	(	Cube< Double > &	samples,
		const Unit &	reqUnit,
		const Vector< MVDirection > &	directions,
		const MeasRef< MDirection > &	dirRef,
		const MVAngle &	pixelLatSize,
		const MVAngle &	pixelLongSize,
		const Vector< MVFrequency > &	frequencies,
		const MeasRef< MFrequency > &	freqRef
	)		const

Same as the previous function except that many directions & frequencies are done at once.

The Flux is added into the values supplied in the samples argument and this cube must have dimensions of: [4, nDirs, nFreqs]. The polarisation and units of the flux added are specified with the reqUnit and reqPol arguments.

void casa::ComponentList::select ( const Vector< Int > & index )

select the specified component.

Throws an exception (AipsError) if any element in the index is out of range, ie. index >= nelements().

Thrown Exceptions

AipsError - If the index is equal to or larger than the number of elements in the list or less than zero

Vector<Int> casa::ComponentList::selected ( ) const

Returns a Vector whose indices indicate which components are selected.

void casa::ComponentList::setFlux	(	const Vector< Int > &	which,
		const Flux< Double > &	newFlux
	)

set the flux on the specified components to the specified flux

Thrown Exceptions

AipsError - If the index is equal to or larger than the number of elements in the list or less than zero

void casa::ComponentList::setLabel	(	const Vector< Int > &	which,
		const String &	newLabel
	)

set the label on the specified components to the specified string

Thrown Exceptions

AipsError - If the index is equal to or larger than the number of elements in the list or less than zero

void casa::ComponentList::setOptParms	(	const Vector< Int > &	which,
		const ComponentShape &	newShape
	)

void casa::ComponentList::setRefDirection	(	const Vector< Int > &	which,
		const MVDirection &	newDir
	)

set the reference direction on the specified components to the specified direction.

The reference frame is not changed, use the setRefFrame function to do that.

Thrown Exceptions

AipsError - If the index is equal to or larger than the number of elements in the list or less than zero

void casa::ComponentList::setRefDirectionFrame	(	const Vector< Int > &	which,
		MDirection::Types	newFrame
	)

set the reference direction frame on the specified components to the specified one.

Does not convert the direction values.

<h3>Thrown Exceptions</h3><ul>  <li> AipsError - If the index is equal to or larger than the number of
                  elements in the list or less than zero
</ul>

void casa::ComponentList::setRefFrequency	(	const Vector< Int > &	which,
		const MVFrequency &	newFreq
	)

set the reference frequency on the specified components to the specified frequency.

The reference frame is not changed, use the setRefFrequencyFrame function to do that.

Thrown Exceptions

AipsError - If the index is equal to or larger than the number of elements in the list or less than zero

void casa::ComponentList::setRefFrequencyFrame	(	const Vector< Int > &	which,
		MFrequency::Types	newFrame
	)

set the reference frequency frame on the specified components to the specified one.

Does not convert the frequency values.

<h3>Thrown Exceptions</h3><ul>  <li> AipsError - If the index is equal to or larger than the number of
                  elements in the list or less than zero
</ul>

void casa::ComponentList::setRefFrequencyUnit	(	const Vector< Int > &	which,
		const Unit &	unit
	)

set the reference frequency unit on the specified components to the specified one.

The unit must have the same dimensions as the Hz.

<h3>Thrown Exceptions</h3><ul>  <li> AipsError - If the index is equal to or larger than the number of
                  elements in the list or less than zero
</ul>

void casa::ComponentList::setShape	(	const Vector< Int > &	which,
		const ComponentShape &	newShape
	)

set the shape on the specified components to the specified one.

Thrown Exceptions

AipsError - If the index is equal to or larger than the number of elements in the list or less than zero

void casa::ComponentList::setShapeParms	(	const Vector< Int > &	which,
		const ComponentShape &	newShape
	)

set the shape on the specified components to the specified one.

However this function unlike the previous one does not change the reference direction to the one specified in the newShape object.

Thrown Exceptions

AipsError - If the index is equal to or larger than the number of elements in the list or less than zero

void casa::ComponentList::setSpectrum	(	const Vector< Int > &	which,
		const SpectralModel &	newSpectrum
	)

set the spectrum on the specified components to the specified one.

Thrown Exceptions

AipsError - If the index is equal to or larger than the number of elements in the list or less than zero

void casa::ComponentList::setSpectrumParms	(	const Vector< Int > &	which,
		const SpectralModel &	newSpectrum
	)

set the spectrum on the specified components to the specified one.

However this function unlike the previous one does not change the reference frequency to the one specified in the newSpectrum object.

Thrown Exceptions

AipsError - If the index is equal to or larger than the number of elements in the list or less than zero

void casa::ComponentList::sort ( ComponentList::SortCriteria criteria )

Sort the components in the list using the given criteria.

String casa::ComponentList::summarize ( uInt index ) const

Summarize specified component as a formatted string.

Bool casa::ComponentList::toRecord	(	String &	error,
		RecordInterface &	outRec
	)		const

static ComponentList::SortCriteria casa::ComponentList::type ( const String & criteria ) [static]

Convert a given String to a Type enumerator.

void casa::ComponentList::writeTable ( ) [private]

Private function to write the components to disk.

Thrown Exceptions

AipsError - If the table is not writable

Member Data Documentation

Bool casa::ComponentList::itsAddOptCol [private]

Definition at line 472 of file ComponentList.h.

Block<SkyComponent> casa::ComponentList::itsList [private]

Definition at line 466 of file ComponentList.h.

uInt casa::ComponentList::itsNelements [private]

Definition at line 467 of file ComponentList.h.

Block<uInt> casa::ComponentList::itsOrder [private]

Definition at line 471 of file ComponentList.h.

Bool casa::ComponentList::itsROFlag [private]

Definition at line 469 of file ComponentList.h.

Block<Bool> casa::ComponentList::itsSelectedFlags [private]

Definition at line 470 of file ComponentList.h.

Table casa::ComponentList::itsTable [private]

Definition at line 468 of file ComponentList.h.

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

casacore/components/ComponentModels/ComponentList.h

Public Types

Public Member Functions

Static Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Intended use:

Prerequisite

Etymology

Synopsis

Example

Example 1:

Motivation

Thrown Exceptions

To Do

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Thrown Exceptions

Thrown Exceptions

Thrown Exceptions

Thrown Exceptions

Thrown Exceptions

Thrown Exceptions

Thrown Exceptions

Thrown Exceptions

Thrown Exceptions

Thrown Exceptions

Thrown Exceptions

Thrown Exceptions

Thrown Exceptions

Thrown Exceptions

Thrown Exceptions

Thrown Exceptions

Thrown Exceptions

Thrown Exceptions

Member Data Documentation