DOcomponentlist.h

Classes

componentlist -- A simplified class for manipulating groups of components (full description)

class componentlist: public ApplicationObject

Types

enum methods

ADD = 0

COMPONENT

REPLACE

CONCATENATE

REMOVE

PURGE

RECOVER

LENGTH

INDICES

SORT

SAMPLE

IS_PHYSICAL

RENAME

CLOSE

SELECT

DESELECT

SELECTED

GETFLUXVALUE

GETFLUXUNIT

GETFLUXPOL

GETFLUXERROR

SETFLUX

CONVERTFLUXUNIT

CONVERTFLUXPOL

SIMULATE

GETREFDIR

GETREFDIRRA

GETREFDIRDEC

GETREFDIRFRAME

SETREFDIR

SETREFDIRFRAME

CONVERTREFDIR

SHAPETYPE

SPECTRUMTYPE

GETLABEL

SETLABEL

SETSHAPE

SETSPECTRUM

GETSHAPE

GETSHAPEERROR

CONVERTSHAPE

GETSPECTRUM

CONVERTSPECTRUM

GETFREQ

GETFREQVALUE

GETFREQUNIT

GETFREQFRAME

SETFREQ

SETFREQFRAME

CONVERTFREQUNIT

NUM_METHODS

Interface

Public Members

componentlist()

componentlist(const String& filename, const Bool& readonly=False)

componentlist(const componentlist& other)

virtual ~componentlist()

componentlist& operator=(const componentlist& other)

void add(SkyComponent component)

SkyComponent component(const Index& which) const

void replace(const Vector<Index>& which, const ObjectID& list, const Vector<Index>& whichones)

void concatenate(const ObjectID& list, const Vector<Index>& which)

void remove(const Vector<Index>& which)

void purge()

void recover()

Int length() const

Vector<Index> indices() const

void sort(const String& criteria)

Bool is_physical(const Vector<Index>& which) const

Vector<Double> sample(const MDirection& sampleDir, const MVAngle& pixelLatSize, const MVAngle& pixelLongSize, const MFrequency& centerFreq) const

void rename(const String& newName)

void close()

void select(const Vector<Index>& which)

void deselect(const Vector<Index>& which)

Vector<Index> selected() const

String getlabel(const Index& which) const

void setlabel(const Vector<Index>& which, const String& label)

Vector<DComplex> getfluxvalue(const Index& which) const

String getfluxunit(const Index& which) const

String getfluxpol(const Index& which) const

Vector<DComplex> getfluxerror(const Index& which) const

void setflux(const Vector<Index>& which, const Vector<DComplex>& values, const String& unitString, const String& polString, const Vector<DComplex>& errors)

void convertfluxunit(const Vector<Index>& which, const String& unitString)

void convertfluxpol(const Vector<Index>& which, const String& polString)

MDirection getrefdir(const Index& which) const

String getrefdirra(const Index& which, const String& unit, const Int prec) const

String getrefdirdec(const Index& which, const String& unit, const Int prec) const

String getrefdirframe(const Index& which) const

void setrefdir(const Vector<Index>& which, const String& raval, const String& raunit, const String& decval, const String& decunit)

void setrefdirframe(const Vector<Index>& which, const String& frame)

void convertrefdir(const Vector<Index>& which, const String& frame)

String shapetype(const Index& which)

GlishRecord getshape(const Index& which) const

GlishRecord getshapeerror(const Index& which) const

void setshape(const Vector<Index>& which, const String& newType, const GlishRecord& parameters)

void convertshape(const Vector<Index>& which, const GlishRecord& parameters)

String spectrumtype(const Index& which)

GlishRecord getspectrum(const Index& which) const

MFrequency getfreq(const Index& which) const

Double getfreqvalue(const Index& which) const

String getfrequnit(const Index& which) const

String getfreqframe(const Index& which) const

void setfreq(const Vector<Index>& which, const Double& value, const String& unit)

void setfreqframe(const Vector<Index>& which, const String& frame)

void convertfrequnit(const Vector<Index>& which, const String& unit)

void setspectrum(const Vector<Index>& which, const String& newType, const GlishRecord& parameters)

void convertspectrum(const Vector<Index>& which, const GlishRecord& parameters)

void simulate(const Int howMany)

Bool DOok() const

virtual String className() const

virtual Vector<String> methods() const

virtual Vector<String> noTraceMethods() const

virtual MethodResult runMethod(uInt which, ParameterSet& parameters, Bool runMethod)

Private Members

ComponentType::Polarisation checkFluxPol(const String& polString)

String formatAngle(const Double angle, const String& unit, const Int prec) const

Int checkIndex(const Index& which, const String& function) const

Vector<Int> checkIndicies(const Vector<Index>& which, const String& function, const String& message) const

Description

Review Status

Date Reviewed:: yyyy/mm/dd

Prerequisite

Etymology

The name MUST have the 'DO' prefix as this class is derived from ApplicationObject, and hence is classified as a distributed object. For the same reason the rest of its name must be in lower case. This class is a simplified version of the ComponentList class.

Synopsis

This class is a container that allows many SkyComponents to be grouped together and manipulated as a group. In this respect this class is identical to the ComponentList class. The user is encouraged to read the synopsis of that class for a general description of the capabilities of this class.

This class is differs from the ComponentList class in the following ways:

All components are indexed starting at one. This means the first component in this class is obtained by component(1) rather than component(0) in the ComponentList class.
Copies of the components, rather than references, are returned to the user. This means that this class needs a replace function whereas ComponentList does not.
Components that have been removed from the list are stored in a temporary place. In the ComponentList class once they are deleted they are gone.
This class is derived from ApplicationObject and follows the AIPS++ conventions for "distributed objects". Hence the fuunctions in this class can be made accessible from glish.
This class can generate simulated components and add them to the list.

There is a one-to-one correspondence between the functions in the glish componentlist object (see the AIPS++ User Reference manual) and functions in this class. This is make simplify the porting from glish to C++ of a glish script using the componentlist distributed object.

Example

These examples are coded in the tDOcomponentlist.h file.

Example 1:

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

Motivation

This class was written to make the componentlist classes usable from glish

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.

Member Description

componentlist()

Construct a componentlist with no components

componentlist(const String& filename, const Bool& readonly=False)

Read a componentlist from an existing table. By default the Table is opened read-write. It is recommended that you create a const componentlist if you open the Table read-only. This will insure that you can determine at compile time that you are using functions which do not modify the list. This prevents a runtime exception for being thrown.

componentlist(const componentlist& other)

The copy constructor uses reference semantics

virtual ~componentlist()

The destructor saves the list to disk if it has a name A name can be assigned using the rename member function or specified at construction time.

componentlist& operator=(const componentlist& other)

The assignment operator uses reference semantics

void add(SkyComponent component)

Add a SkyComponent to the end of the componentlist. The list length is increased by one when using this function.

SkyComponent component(const Index& which) const

returns a copy of the specified element in the list.

void replace(const Vector<Index>& which, const ObjectID& list, const Vector<Index>& whichones)

Replace the specified components with the ones in the supplied list.

void concatenate(const ObjectID& list, const Vector<Index>& which)

Copy the specified components from the specified componentlist to the end of the current componentlist.

void remove(const Vector<Index>& which)

Remove the specified SkyComponents from the componentlist. After removing a component all the components with an indices greater than this one will be reduced. For example in a five element list removing elements [1,3,5] will result in a two element list, now indexed as elements one and two, containing what was previously the second and fourth components. which is a vector than contains indices that MUST be greater than zero and less than or equal to the number of components in the list, as the first component is at which=1. Components are not completely deleted from the list until the purge function is called.

void purge()

Permanently remove all the components from the list that have been deleted using the remove function.

void recover()

Replace all the components removed from the list. This cannot replace components that have been removed before the list was last purged.

Int length() const

returns the number of elements in the list.

Vector<Index> indices() const

returns a Vector whose length is the number of elements in the list, and contents are from 1 to the list length. If the list contains no elements the an empty Vector is returned.

void sort(const String& criteria)

Sort the components in the list using the given criteria. The criteria string is identical to those in the ComponentList::Sort enumerator but the string matching is case insensitive.

Thrown Exceptions

AipsError - If the string cannot be converted into a known criteria

Bool is_physical(const Vector<Index>& which) 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.

Vector<Double> sample(const MDirection& sampleDir, const MVAngle& pixelLatSize, const MVAngle& pixelLongSize, const MFrequency& centerFreq) const

Return the flux (in Jy) of the component in a pixel of specified size at the specified frequency & direction, . The Vector contains all the polarizations (Stokes I,Q,U,V) of the radiation and will be of length 4. The pixel size is assumed to be square.

void rename(const String& newName)

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 componentlist's that are opened readonly. If a file with the specified filename already exists then a AipsError will be thrown.

void close()

If the current componentlist is associated with a Table then write the list to disk and close the Table. After executation of this function the componentlist always contains no elements and is not associated with any Table. It is as if the default constructor had just been called. If the current list is not associated with a Table then its contents are lost.

void select(const Vector<Index>& which)

select the specified component. Throws an exception (AipsError) if the index is out of range, ie. index > length().

void deselect(const Vector<Index>& which)

deselect the specified component. Throws an exception (AipsError) if the index is out of range, ie. index > length().

Vector<Index> selected() const

Returns a Vector indicating which components are selected.

String getlabel(const Index& which) const

get the label of the specified component

void setlabel(const Vector<Index>& which, const String& label)

set the label of the specified components

Vector<DComplex> getfluxvalue(const Index& which) const

get the flux values of the specified component

String getfluxunit(const Index& which) const

get the flux unit of the specified component

String getfluxpol(const Index& which) const

get the polarisation of the flux of the specified component

Vector<DComplex> getfluxerror(const Index& which) const

get the errors in the flux of the specified component

void setflux(const Vector<Index>& which, const Vector<DComplex>& values, const String& unitString, const String& polString, const Vector<DComplex>& errors)

set the flux on the specified components to the specified values with the specified units and polarisation representation.

void convertfluxunit(const Vector<Index>& which, const String& unitString)

convert the flux on the specified components to the specified units

void convertfluxpol(const Vector<Index>& which, const String& polString)

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

MDirection getrefdir(const Index& which) const

Return the reference direction of the specified component

String getrefdirra(const Index& which, const String& unit, const Int prec) const

get the RA or dec of the reference direction as a string. The units and precision can be specified. Valid units are any angular units (eg., "rad", "deg") or "time" or "angle". For the latter two the returned string will be HH:MM:SS.sss or +DDD.MM.SS.sss respectively. Parsing of the unit string is case insensitive. The precision is the number of significant digits in the returned value. For time and angle units a precision of two returns only the degrees or hours, four adds the minutes and six includes the integral seconds. Note that RA and Dec really mean the latitude or longitude if the reference is something other than J2000 or B1950.

String getrefdirdec(const Index& which, const String& unit, const Int prec) const

String getrefdirframe(const Index& which) const

return as an uppercase string the reference frame of the current reference direction for the specified component.

void setrefdir(const Vector<Index>& which, const String& raval, const String& raunit, const String& decval, const String& decunit)

set the reference direction of the specified components to the specified value. The units must be either, "time", "angle" or an angular unit (eg., "rad" or "deg"). If the units are "time" or "angle" then the ra/dec string will be parsed (for special characters like ":" or .) to generate the angular unit. Otherwise the ra/dec string will be treated as a floating point number in the units specified by the corresponding unit string. The parsing of all strings is case insensitive.

void setrefdirframe(const Vector<Index>& which, const String& frame)

set the reference direction frame, of the specified components, to the specified value. No conversions are performed.

void convertrefdir(const Vector<Index>& which, const String& frame)

convert the reference direction frame, of the specified components, to the specified value.

String shapetype(const Index& which)

get the shape used by the specified component.

GlishRecord getshape(const Index& which) const

get the shape part of the component. The returned record may be empty (for a point shape) or contain fields (typically majoraxis, minoraxis and positionangle) that depend on the shape.

GlishRecord getshapeerror(const Index& which) const

get the errors in the shape part of the component. The returned record may be empty (for a point shape) or contain fields (typically majoraxis, minoraxis and positionangle) that represent the errors in the shape parameters.

void setshape(const Vector<Index>& which, const String& newType, const GlishRecord& parameters)

change the shape used by the specified components. The parameters for the shape are contained in the parameters record. Only the fields appropriate to the specified shape are used, other fields are ignored. Does not change the shape if the newType string cannot be translated into a valid shape.

void convertshape(const Vector<Index>& which, const GlishRecord& parameters)

change the units used by the shape parameters in the specified components. The parameters for the shape are contained in the parameters record and are identical to those used in the setshape function. Only the fields appropriate shape of the specified components are used, other fields are ignored. The specified units must have the same dimensions as the ones currently in use for the specified parameter.

String spectrumtype(const Index& which)

get the spectral model used by the specified component.

GlishRecord getspectrum(const Index& which) const

get the spectrum part of the component. The returned record always contains a type field (as a string), a frequency field (a frequency measure) and may contain other fields depending on the spectral model.

MFrequency getfreq(const Index& which) const

Return the reference frequency of the specified component

Double getfreqvalue(const Index& which) const
String getfrequnit(const Index& which) const
String getfreqframe(const Index& which) const

get the value, unit or reference frame of the reference frequency. The frame is always returned as an uppercase string.

void setfreq(const Vector<Index>& which, const Double& value, const String& unit)

set the reference frequency of the specified components to the specified value and unit. The units must have the same dimensions as the "Hz".

void setfreqframe(const Vector<Index>& which, const String& frame)

set the reference direction frame, of the specified components, to the specified value. No conversions are performed.

void convertfrequnit(const Vector<Index>& which, const String& unit)

convert the reference frequency value to the specified unit.

void setspectrum(const Vector<Index>& which, const String& newType, const GlishRecord& parameters)

change the spectrum used by the specified components. The parameters for the spectrum are contained in the parameters record. Only the fields appropriate to the specified spectrum are used, other fields are ignored. Does not change the spectrum if the newType string cannot be translated into a valid spectral type or if there is any other error.

void convertspectrum(const Vector<Index>& which, const GlishRecord& parameters)

change the units used by the spectrum parameters in the specified components. The parameters for the spectrum are contained in the parameters record and are identical to those used in the setspectrum function. Only the fields appropriate to the spectrum model of the specified components are used, other fields are ignored. The specified units must have the same dimensions as the ones currently in use for the specified parameter.

void simulate(const Int howMany)

Add the specified number of components to the list. All the components will be Point components with a flux of 1 Jy in I only, at the J2000 North pole The spectrum is constant. This behaviour will probably change so that all the simulated components are different.

Thrown Exceptions

AipsError - If the number of components to be added is negative.

Bool DOok() const

Function which checks the internal data of this class for consistant values. Returns True if everything is fine otherwise returns False.

virtual String className() const

return the name of this object type the distributed object system. This function is required as part of the DO system

virtual Vector<String> methods() const

the returned vector contains the names of all the methods which may be used via the distributed object system. This function is required as part of the DO system

virtual Vector<String> noTraceMethods() const

the returned vector contains the names of all the methods which are to trivial to warrent automatic logging. This function is required as part of the DO system

virtual MethodResult runMethod(uInt which, ParameterSet& parameters, Bool runMethod)

Run the specified method. This is the function used by the distributed object system to invoke any of the specified member functions in thios class. This function is required as part of the DO system