casa  5.7.0-16
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Public Types | Public Member Functions | Static Public Member Functions | Private Member Functions | Private Attributes | Friends | List of all members
casa::ComponentList Class Reference

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. More...
 
 ComponentList (const casacore::Path &fileName, casacore::Bool readOnly=false, casacore::Bool rewriteTable=casacore::True)
 Read a componentList from an existing table. More...
 
 ComponentList (const ComponentList &other)
 The Copy constructor uses reference semantics. More...
 
 ~ComponentList ()
 The destructor saves the list to disk if it has a name (assigned using the setName member function) More...
 
ComponentListoperator= (const ComponentList &other)
 The assignment operator uses reference semantics. More...
 
casacore::Bool isPhysical (const casacore::Vector< casacore::Int > &index) const
 Returns true if all the specified components are physically plausable. More...
 
Flux< casacore::Doublesample (const casacore::MDirection &sampleDir, const casacore::MVAngle &pixelLatSize, const casacore::MVAngle &pixelLongSize, const casacore::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. More...
 
void sample (casacore::Cube< casacore::Double > &samples, const casacore::Unit &reqUnit, const casacore::Vector< casacore::MVDirection > &directions, const casacore::MeasRef< casacore::MDirection > &dirRef, const casacore::MVAngle &pixelLatSize, const casacore::MVAngle &pixelLongSize, const casacore::Vector< casacore::MVFrequency > &frequencies, const casacore::MeasRef< casacore::MFrequency > &freqRef) const
 Same as the previous function except that many directions & frequencies are done at once. More...
 
void add (SkyComponent component)
 Add a SkyComponent to the end of the ComponentList. More...
 
void addList (const ComponentList &list)
 Add a SkyComponents in a ComponentList to the end of this ComponentList. More...
 
void remove (const casacore::uInt &index)
 Remove the specified SkyComponent(s) from the ComponentList. More...
 
void remove (const casacore::Vector< casacore::Int > &indices)
 
casacore::uInt nelements () const
 returns how many components are in the list. More...
 
void deselect (const casacore::Vector< casacore::Int > &index)
 deselect the specified component. More...
 
void select (const casacore::Vector< casacore::Int > &index)
 select the specified component. More...
 
casacore::Vector< casacore::Intselected () const
 Returns a casacore::Vector whose indices indicate which components are selected. More...
 
void setLabel (const casacore::Vector< casacore::Int > &which, const casacore::String &newLabel)
 set the label on the specified components to the specified string More...
 
void getFlux (casacore::Vector< casacore::Quantity > &fluxQuant, const casacore::Int &which) const
 get the the flux as a double param: which - the component number (0 based) return The flux as a Quantity More...
 
void getFlux (casacore::Vector< casacore::Quantum< casacore::Complex > > &fluxQuant, const casacore::Int &which)
 
casacore::Vector
< casacore::String
getStokes (const casacore::Int &which) const
 get the associated polarizations as a vector of strings for the specified component. More...
 
void setFlux (const casacore::Vector< casacore::Int > &which, const Flux< casacore::Double > &newFlux)
 set the flux on the specified components to the specified flux More...
 
void convertFluxUnit (const casacore::Vector< casacore::Int > &which, const casacore::Unit &unit)
 convert the flux on the specified components to the specified units More...
 
void convertFluxPol (const casacore::Vector< casacore::Int > &which, ComponentType::Polarisation pol)
 convert the flux on the specified components to the specified polarisation representation More...
 
void setRefDirection (const casacore::Vector< casacore::Int > &which, const casacore::MVDirection &newDir)
 set the reference direction on the specified components to the specified direction. More...
 
void setRefDirectionFrame (const casacore::Vector< casacore::Int > &which, casacore::MDirection::Types newFrame)
 set the reference direction frame on the specified components to the specified one. More...
 
void convertRefDirection (const casacore::Vector< casacore::Int > &which, casacore::MDirection::Types newFrame)
 Convert the reference direction frame on the specified components to the specified one. More...
 
casacore::MDirection getRefDirection (casacore::Int which) const
 
void setShape (const casacore::Vector< casacore::Int > &which, const ComponentShape &newShape)
 set the shape on the specified components to the specified one. More...
 
const ComponentShapegetShape (casacore::Int which) const
 get the shape of the specified component as a const pointer. More...
 
void setShapeParms (const casacore::Vector< casacore::Int > &which, const ComponentShape &newShape)
 set the shape on the specified components to the specified one. More...
 
void setOptParms (const casacore::Vector< casacore::Int > &which, const ComponentShape &newShape)
 
void setSpectrum (const casacore::Vector< casacore::Int > &which, const SpectralModel &newSpectrum)
 set the spectrum on the specified components to the specified one. More...
 
void setSpectrumParms (const casacore::Vector< casacore::Int > &which, const SpectralModel &newSpectrum)
 set the spectrum on the specified components to the specified one. More...
 
void setRefFrequency (const casacore::Vector< casacore::Int > &which, const casacore::MVFrequency &newFreq)
 set the reference frequency on the specified components to the specified frequency. More...
 
void setRefFrequencyFrame (const casacore::Vector< casacore::Int > &which, casacore::MFrequency::Types newFrame)
 set the reference frequency frame on the specified components to the specified one. More...
 
void setRefFrequencyUnit (const casacore::Vector< casacore::Int > &which, const casacore::Unit &unit)
 set the reference frequency unit on the specified components to the specified one. More...
 
const SkyComponentcomponent (const casacore::uInt &index) const
 returns a reference to the specified element in the list. More...
 
SkyComponentcomponent (const casacore::uInt &index)
 
void rename (const casacore::Path &newName, const casacore::Table::TableOption option=casacore::Table::New)
 Make the ComponentList persistant by supplying a filename. More...
 
ComponentList copy () const
 Make a real copy of this componentList. More...
 
void sort (ComponentList::SortCriteria criteria)
 casacore::Sort the components in the list using the given criteria. More...
 
casacore::Bool ok () const
 casacore::Function which checks the internal data of this class for consistant values. More...
 
casacore::Bool fromRecord (casacore::String &error, const casacore::RecordInterface &inRec)
 methods to store itself as a casacore::Record and recover from a casacore::Record its state More...
 
casacore::Bool toRecord (casacore::String &error, casacore::RecordInterface &outRec) const
 
casacore::String summarize (casacore::uInt index) const
 Summarize specified component as a formatted string. More...
 
const casacore::TablegetTable () const
 get the underlying table. More...
 

Static Public Member Functions

static casacore::String name (ComponentList::SortCriteria enumerator)
 Convert the SortCriteria enumerator to a string. More...
 
static ComponentList::SortCriteria type (const casacore::String &criteria)
 Convert a given casacore::String to a Type enumerator. More...
 

Private Member Functions

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

void createTable(const casacore::Path& fileName, const casacore::Table::TableOption option, const casacore::Bool addOptCol); More...

 
void writeTable ()
 Private function to write the components to disk. More...
 
casacore::Table_getTable ()
 
void readTable (const casacore::Path &fileName, const casacore::Bool readOnly)
 Private function to read the components from disk. More...
 

Private Attributes

casacore::Block< SkyComponentitsList
 
casacore::uInt itsNelements
 
casacore::Table itsTable
 
casacore::Bool itsROFlag
 
casacore::Block< casacore::BoolitsSelectedFlags
 
casacore::Block< casacore::uIntitsOrder
 
casacore::Bool itsAddOptCol
 
casacore::Bool itsRewriteTable
 

Friends

class ComponentListImage
 

Detailed Description

A class for manipulating groups of components.

Intended use:

Public interface

Review Status

Date Reviewed:
yyyy/mm/dd

Prerequisite

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 casacore::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 casacore::Table). To read a componentList from a casacore::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 casacore::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

To Do

Definition at line 142 of file ComponentList.h.

Member Enumeration Documentation

Sorting criteria for components.

Enumerator
FLUX 

casacore::Sort the components by ABS(I flux), largest first.

POSITION 

casacore::Sort the components by distance from the reference, closest first.

POLARISATION 

casacore::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 145 of file ComponentList.h.

Constructor & Destructor Documentation

casa::ComponentList::ComponentList ( )

Construct a componentList with no members in the list.

casa::ComponentList::ComponentList ( const casacore::Path fileName,
casacore::Bool  readOnly = false,
casacore::Bool  rewriteTable = casacore::True 
)

Read a componentList from an existing table.

By default the casacore::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.

rewriteTable indicates if the table, if it exists and is not readOnly, should be rewritten on copies (operator=()) and on destruction. Rewriting this table is always how it has worked in the past (which is why the default is true), however, classes like ComponentListImage must be able to write things like metadata and subtables to the main table (so need write access), but do not alter data in the main table, so that rewriting the main table is unnecessary. Rewriting the table also causes an increase in the table size on disk. This occurs even when the data being written is identical to the the data being overwritten, and on the surface seems to be a bug, but requires more investigation.

In any case, rewriting the entire table seems overkill, and this needs to be addressed. The table should only be written to when data are changed. CAS-10717 is meant to address this, although it will take some effort to complete. The main issue is that the non-const version of method component() needs to be removed, because it allows callers to change SkyComponent data without the knowledge of the ComponentList object. This breaks encapsulation; when changing an object's data, the object should be aware.

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

casacore::Table& casa::ComponentList::_getTable ( )
private
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 casacore::uInt index) const

returns a reference to the specified element in the list.

Thrown Exceptions

  • casacore::AipsError - If the list is associated with a table that was opened readonly (non-const version only).
  • casacore::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 casacore::uInt index)
void casa::ComponentList::convertFluxPol ( const casacore::Vector< casacore::Int > &  which,
ComponentType::Polarisation  pol 
)

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

Thrown Exceptions

  • casacore::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 casacore::Vector< casacore::Int > &  which,
const casacore::Unit unit 
)

convert the flux on the specified components to the specified units

Thrown Exceptions

  • casacore::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 casacore::Vector< casacore::Int > &  which,
casacore::MDirection::Types  newFrame 
)

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

Changes the direction values.

Thrown Exceptions

  • casacore::AipsError - If the index is equal to or larger than the number of elements in the list or less than zero
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 casacore::Path fileName,
const casacore::Table::TableOption  option 
)
private

Privarte function to create the casacore::Table which will hold the components

void createTable(const casacore::Path& fileName, const casacore::Table::TableOption option, const casacore::Bool addOptCol);

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

deselect the specified component.

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

Thrown Exceptions

  • casacore::AipsError - If the index is equal to or larger than the number of elements in the list or less than zero
casacore::Bool casa::ComponentList::fromRecord ( casacore::String error,
const casacore::RecordInterface inRec 
)

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

void casa::ComponentList::getFlux ( casacore::Vector< casacore::Quantity > &  fluxQuant,
const casacore::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 ( casacore::Vector< casacore::Quantum< casacore::Complex > > &  fluxQuant,
const casacore::Int which 
)
casacore::MDirection casa::ComponentList::getRefDirection ( casacore::Int  which) const
const ComponentShape* casa::ComponentList::getShape ( casacore::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.

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

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

Returned vector always has 4 elements.

const casacore::Table& casa::ComponentList::getTable ( ) const

get the underlying table.

This method was added specifically for use by ComponenetListImage; it is not advised that it be called outside that class. casacore::Table& getTable();

casacore::Bool casa::ComponentList::isPhysical ( const casacore::Vector< casacore::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

  • casacore::AipsError - If the index is equal to or larger than the number of elements in the list or less than zero
static casacore::String casa::ComponentList::name ( ComponentList::SortCriteria  enumerator)
static

Convert the SortCriteria enumerator to a string.

casacore::uInt casa::ComponentList::nelements ( ) const

returns how many components are in the list.

casacore::Bool casa::ComponentList::ok ( ) const

casacore::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 casacore::Path fileName,
const casacore::Bool  readOnly 
)
private

Private function to read the components from disk.

Thrown Exceptions

void casa::ComponentList::remove ( const casacore::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

  • casacore::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 casacore::Vector< casacore::Int > &  indices)
void casa::ComponentList::rename ( const casacore::Path newName,
const casacore::Table::TableOption  option = casacore::Table::New 
)

Make the ComponentList persistant by supplying a filename.

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

Thrown Exceptions

Flux<casacore::Double> casa::ComponentList::sample ( const casacore::MDirection sampleDir,
const casacore::MVAngle pixelLatSize,
const casacore::MVAngle pixelLongSize,
const casacore::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 ( casacore::Cube< casacore::Double > &  samples,
const casacore::Unit reqUnit,
const casacore::Vector< casacore::MVDirection > &  directions,
const casacore::MeasRef< casacore::MDirection > &  dirRef,
const casacore::MVAngle pixelLatSize,
const casacore::MVAngle pixelLongSize,
const casacore::Vector< casacore::MVFrequency > &  frequencies,
const casacore::MeasRef< casacore::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 casacore::Vector< casacore::Int > &  index)

select the specified component.

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

Thrown Exceptions

  • casacore::AipsError - If the index is equal to or larger than the number of elements in the list or less than zero
casacore::Vector<casacore::Int> casa::ComponentList::selected ( ) const

Returns a casacore::Vector whose indices indicate which components are selected.

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

set the flux on the specified components to the specified flux

Thrown Exceptions

  • casacore::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 casacore::Vector< casacore::Int > &  which,
const casacore::String newLabel 
)

set the label on the specified components to the specified string

Thrown Exceptions

  • casacore::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 casacore::Vector< casacore::Int > &  which,
const ComponentShape newShape 
)
void casa::ComponentList::setRefDirection ( const casacore::Vector< casacore::Int > &  which,
const casacore::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

  • casacore::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 casacore::Vector< casacore::Int > &  which,
casacore::MDirection::Types  newFrame 
)

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

Does not convert the direction values.

Thrown Exceptions

  • casacore::AipsError - If the index is equal to or larger than the number of elements in the list or less than zero
void casa::ComponentList::setRefFrequency ( const casacore::Vector< casacore::Int > &  which,
const casacore::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

  • casacore::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 casacore::Vector< casacore::Int > &  which,
casacore::MFrequency::Types  newFrame 
)

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

Does not convert the frequency values.

Thrown Exceptions

  • casacore::AipsError - If the index is equal to or larger than the number of elements in the list or less than zero
void casa::ComponentList::setRefFrequencyUnit ( const casacore::Vector< casacore::Int > &  which,
const casacore::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.

Thrown Exceptions

  • casacore::AipsError - If the index is equal to or larger than the number of elements in the list or less than zero
void casa::ComponentList::setShape ( const casacore::Vector< casacore::Int > &  which,
const ComponentShape newShape 
)

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

Thrown Exceptions

  • casacore::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 casacore::Vector< casacore::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

  • casacore::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 casacore::Vector< casacore::Int > &  which,
const SpectralModel newSpectrum 
)

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

Thrown Exceptions

  • casacore::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 casacore::Vector< casacore::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

  • casacore::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)

casacore::Sort the components in the list using the given criteria.

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

Summarize specified component as a formatted string.

casacore::Bool casa::ComponentList::toRecord ( casacore::String error,
casacore::RecordInterface outRec 
) const
static ComponentList::SortCriteria casa::ComponentList::type ( const casacore::String criteria)
static

Convert a given casacore::String to a Type enumerator.

void casa::ComponentList::writeTable ( )
private

Private function to write the components to disk.

Thrown Exceptions

Friends And Related Function Documentation

friend class ComponentListImage
friend

Definition at line 490 of file ComponentList.h.

Member Data Documentation

casacore::Bool casa::ComponentList::itsAddOptCol
private

Definition at line 505 of file ComponentList.h.

casacore::Block<SkyComponent> casa::ComponentList::itsList
private

Definition at line 499 of file ComponentList.h.

casacore::uInt casa::ComponentList::itsNelements
private

Definition at line 500 of file ComponentList.h.

casacore::Block<casacore::uInt> casa::ComponentList::itsOrder
private

Definition at line 504 of file ComponentList.h.

casacore::Bool casa::ComponentList::itsRewriteTable
private

Definition at line 506 of file ComponentList.h.

casacore::Bool casa::ComponentList::itsROFlag
private

Definition at line 502 of file ComponentList.h.

casacore::Block<casacore::Bool> casa::ComponentList::itsSelectedFlags
private

Definition at line 503 of file ComponentList.h.

casacore::Table casa::ComponentList::itsTable
private

Definition at line 501 of file ComponentList.h.


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