Base class for spectral models. More...

#include <SpectralModel.h>

Inheritance diagram for casa::SpectralModel:

Public Member Functions
virtual	~SpectralModel ()
	a virtual destructor is needed so that the actual destructor in the derived class will be used.
virtual ComponentType::SpectralShape	type () const =0
	return the actual spectral type.
virtual const String &	ident () const
	Specify the identification of the record (e.g.
void	setRefFrequency (const MFrequency &newRefFreq)
	set/get the reference frequency
const MFrequency &	refFrequency () const
const Unit &	frequencyUnit () const
	get the frequency unit, and change the default frequency unit to the specified one.
void	convertFrequencyUnit (const Unit &freqUnit)
void	setRefFrequencyError (const Quantum< Double > &newRefFreqErr)
	set/get the error in the reference frequency.
const Quantum< Double > &	refFrequencyError () const
virtual Double	sample (const MFrequency &centerFrequency) const =0
	Return the scaling factor that indicates what proportion of the flux is at the specified frequency.
virtual void	sample (Vector< Double > &scale, const Vector< MFrequency::MVType > &frequencies, const MFrequency::Ref &refFrame) const =0
	Same as the previous function except that many frequencies can be sampled at once.
virtual SpectralModel *	clone () const =0
	Return a pointer to a copy of the derived object upcast to a SpectralModel object.
virtual uInt	nParameters () const =0
	return the number of parameters in this spectral shape and set/get them.
virtual void	setParameters (const Vector< Double > &newParms)=0
virtual Vector< Double >	parameters () const =0
virtual void	setErrors (const Vector< Double > &newErrors)=0
virtual Vector< Double >	errors () const =0
virtual Bool	fromRecord (String &errorMessage, const RecordInterface &record)=0
	These functions convert between a record and a SpectralModel.
virtual Bool	toRecord (String &errorMessage, RecordInterface &record) const =0
	Convert the class to an Record representation.
virtual Bool	convertUnit (String &errorMessage, const RecordInterface &record)=0
	Convert the parameters of the spectral model to the specified units.
virtual Bool	ok () const
	Function which checks the internal data of this class for correct dimensionality and consistant values.
Static Public Member Functions
static ComponentType::SpectralShape	getType (String &errorMessage, const RecordInterface &record)
	Return the spectral shape that the supplied record represents.
Protected Member Functions
	SpectralModel ()
	The constructors and assignment operator are protected as only derived classes should use them.
	SpectralModel (const MFrequency &refFreq, const Unit &=Unit("GHz"))
	SpectralModel (const SpectralModel &other)
SpectralModel &	operator= (const SpectralModel &other)
Static Protected Member Functions
static Bool	badError (const Quantum< Double > &quantum)
	returns True if the quantum is not a non-negative quantity with units dimensionally identical to the Hz
Private Attributes
MFrequency	itsRefFreq
Unit	itsFreqUnit
Quantity	itsFreqErr

Detailed Description

Base class for spectral models.

Intended use:

Public interface

 <h3>Review Status</h3><dl><dt>Date Reviewed:<dd>yyyy/mm/dd<dt>Test programs:<dd>tConstantSpectrum<dt>Demo programs:<dd>dSpectralModel</dl>

Prerequisite

MFrequency

Synopsis

This abstract base class defines the interface for different classes which model the spectrum of a component. The most fundamental derived class is the ConstantSpectrum class but the SpectralIndex class is also available. These classes model the spectrum of emission from the sky.

Classes derived from the ComponentShape class are used to model the shape and the Flux class is used to model the flux. The SkyComponent class incorporates these three characteristics (flux, shape & spectrum) and the ComponentList class handles groups of SkyComponent objects.

This class parameterises spectral models with two quantities.

A reference frequency.: This is specified using an MFrequency object and defines a frequency where the model is interesting. See the description of derived classes for the specific interpretation of the reference frequency.
A Vector of parameters.: This contains other parameters that the are defined differently for different spectral models. The length of the vector may vary for different spectral models.

The basic operation of classes using this interface is to model the flux as a function of frequency. Classes derived from this one do not know what the flux is at the reference frequency. Instead the sample functions return factors that are used to scale the flux and calculate the amount of flux at a specified frequency.

Any allowed frequency reference frame can be used. However the reference frame must be adequately specified in order to allow conversions to other reference frames. For example if the reference frame code for the frequency is MFrequency::TOPO then the reference frame must also contain the time, position on the earth, and direction of the observation that corresponds to the specified frequency. This way the sample functions can convert the frequency to a value in the LSR reference frame (if you specify the sample frequency in the LSR frame).

Example

Because this is an abstract base class, an actual instance of this class cannot be constructed. However the interface it defines can be used inside a function. This is always recommended as it allows functions which have SpectralModels as arguments to work for any derived class.

In this example the plotSpectrum function prints out the type of spectral model it is working with and the reference frequency of that model. It then uses the model to calculate the proportion of the flux at other frequencies. This example is coded in the dSpectralModel.cc file.

    void plotSpectrum(const SpectralModel& modelSpectrum) {
      cout << "This is a "
           << ComponentType::name(modelSpectrum.type())
           << " spectrum with a reference frequency of: "
           << setprecision(4) << modelSpectrum.refFrequency().get("GHz") << " ("
           << modelSpectrum.refFrequency().getRefString() << ")"
           << endl;
      const MVFrequency step(Quantity(100.0, "MHz"));
      MVFrequency sampleFreq(Quantity(1, "GHz"));
      MeasFrame obsFrame;
      {
        Quantity obsRa; MVAngle::read(obsRa, "19:39:");
        Quantity obsDec; MVAngle::read(obsDec, "-63.43.");
        Quantity obsDay; MVTime::read(obsDay, "1996/11/20/5:20");
        obsFrame.set(MEpoch(obsDay, MEpoch::UTC),
                    MDirection(obsRa, obsDec, MDirection::J2000));
      }
      MFrequency::Ref obsRef(MFrequency::GEO, obsFrame);
      cout << "Frequency\t scale\n";
      for (uInt i = 0; i < 11; i++) {
         cout << setprecision(7) << sampleFreq.get("GHz")
          << "\t\t " << modelSpectrum.sample(MFrequency(sampleFreq, obsRef))
          << endl;
         sampleFreq += step;
      }
    }

Motivation

The SpectralModel base class was seperated from the ComponentShape base class so that mixing components with different spatial and spectral shapes did not result in a combinatorial explosion in the number of classes required.

To Do

I would not be surprised if the base class will need to be updated when classes modelling spectral lines are written.

Definition at line 155 of file SpectralModel.h.

Constructor & Destructor Documentation

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

a virtual destructor is needed so that the actual destructor in the derived class will be used.

casa::SpectralModel::SpectralModel ( ) [protected]

The constructors and assignment operator are protected as only derived classes should use them.

casa::SpectralModel::SpectralModel	(	const MFrequency &	refFreq,
		const Unit &	= `Unit("GHz")`
	)		`[protected]`

casa::SpectralModel::SpectralModel ( const SpectralModel & other ) [protected]

Member Function Documentation

static Bool casa::SpectralModel::badError ( const Quantum< Double > & quantum ) [static, protected]

returns True if the quantum is not a non-negative quantity with units dimensionally identical to the Hz

virtual SpectralModel* casa::SpectralModel::clone ( ) const [pure virtual]

Return a pointer to a copy of the derived object upcast to a SpectralModel object.

The class that uses this function is responsible for deleting the pointer. This is used to implement a virtual copy constructor.

Implemented in casa::SpectralIndex, casa::TabularSpectrum, and casa::ConstantSpectrum.

void casa::SpectralModel::convertFrequencyUnit ( const Unit & freqUnit )

virtual Bool casa::SpectralModel::convertUnit	(	String &	errorMessage,
		const RecordInterface &	record
	)		`[pure virtual]`

Convert the parameters of the spectral model to the specified units.

The Record must contain the same fields that the to/from Record functions have (with the exception of the frequency & type fields). These fields will contain strings (and not Quantums) that specify the new units for these parameters. The new units must have the same dimensions as the existing ones. If there is any problem parsing the record then an error message is appended to the supplied string and the function returns False.

Implemented in casa::SpectralIndex, casa::TabularSpectrum, and casa::ConstantSpectrum.

virtual Vector<Double> casa::SpectralModel::errors ( ) const [pure virtual]

Implemented in casa::SpectralIndex, casa::TabularSpectrum, and casa::ConstantSpectrum.

const Unit& casa::SpectralModel::frequencyUnit ( ) const

get the frequency unit, and change the default frequency unit to the specified one.

This will only affect the units used in the Record returned by the toRecord function.

virtual Bool casa::SpectralModel::fromRecord	(	String &	errorMessage,
		const RecordInterface &	record
	)		`[pure virtual]`

These functions convert between a record and a SpectralModel.

This way derived classes can interpret fields in the record in a class specific way. They return False if the record is malformed and append an error message to the supplied string giving the reason. These functions define how a spectral model is represented in glish. All records should have 'type' & 'frequency' fields which contain respectively; a string indicating which spectral model is actually used, and a record representation of a frequency measure. The interpretation of all other fields depends on the specific spectral model used.

Implements casa::RecordTransformable.

Implemented in casa::SpectralIndex, casa::TabularSpectrum, and casa::ConstantSpectrum.

static ComponentType::SpectralShape casa::SpectralModel::getType	(	String &	errorMessage,
		const RecordInterface &	record
	)		`[static]`

Return the spectral shape that the supplied record represents.

The spectral shape is determined by parsing a 'type' field in the supplied record. Returns ComponentType::UNKNOWN_SPECTRAL_SHAPE if the type field (which contains a string) could not be translated into a known spectral shape. It then appends an appropriate error message to the errorMessage String.

virtual const String& casa::SpectralModel::ident ( ) const [virtual]

Specify the identification of the record (e.g.

'meas', 'quant'). The default implementation returns a empty string.

Reimplemented from casa::RecordTransformable.

virtual uInt casa::SpectralModel::nParameters ( ) const [pure virtual]

return the number of parameters in this spectral shape and set/get them.

Implemented in casa::SpectralIndex, casa::TabularSpectrum, and casa::ConstantSpectrum.

virtual Bool casa::SpectralModel::ok ( ) const [virtual]

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

Returns True if everything is fine otherwise returns False.

Reimplemented in casa::SpectralIndex, casa::TabularSpectrum, and casa::ConstantSpectrum.

SpectralModel& casa::SpectralModel::operator= ( const SpectralModel & other ) [protected]

virtual Vector<Double> casa::SpectralModel::parameters ( ) const [pure virtual]

Implemented in casa::SpectralIndex, casa::TabularSpectrum, and casa::ConstantSpectrum.

const MFrequency& casa::SpectralModel::refFrequency ( ) const

const Quantum<Double>& casa::SpectralModel::refFrequencyError ( ) const

virtual Double casa::SpectralModel::sample ( const MFrequency & centerFrequency ) const [pure virtual]

Return the scaling factor that indicates what proportion of the flux is at the specified frequency.

ie. if the centreFrequency argument is the reference frequency then this function will always return one. At other frequencies it will return a non-negative number.

Implemented in casa::SpectralIndex, casa::TabularSpectrum, and casa::ConstantSpectrum.

virtual void casa::SpectralModel::sample	(	Vector< Double > &	scale,
		const Vector< MFrequency::MVType > &	frequencies,
		const MFrequency::Ref &	refFrame
	)		const `[pure virtual]`

Same as the previous function except that many frequencies can be sampled at once.

The reference frame must be the same for all the specified frequencies. A default implementation of this function is available that uses the sample function described above. However customised versions of this function will be more efficient as intermediate values only need to be computed once.

Implemented in casa::SpectralIndex, casa::TabularSpectrum, and casa::ConstantSpectrum.

virtual void casa::SpectralModel::setErrors ( const Vector< Double > & newErrors ) [pure virtual]

Implemented in casa::SpectralIndex, casa::TabularSpectrum, and casa::ConstantSpectrum.

virtual void casa::SpectralModel::setParameters ( const Vector< Double > & newParms ) [pure virtual]

Implemented in casa::SpectralIndex, casa::TabularSpectrum, and casa::ConstantSpectrum.

void casa::SpectralModel::setRefFrequency ( const MFrequency & newRefFreq )

set/get the reference frequency

void casa::SpectralModel::setRefFrequencyError ( const Quantum< Double > & newRefFreqErr )

set/get the error in the reference frequency.

Values must be positive angular quantities otherwise an AipsError exception is thrown. The errors are usually interpreted as the 1-sigma bounds in latitude/longitude and implicitly assume a Gaussian distribution. They must have units with the same dimensions as the Hz.

virtual Bool casa::SpectralModel::toRecord	(	String &	error,
		RecordInterface &	outRecord
	)		const `[pure virtual]`

Convert the class to an Record representation.

The input record may already contain fields and these fields may be silently overridden. New fields may be added to the input Record. If the transformation succeeds then the error String is unchanged and the function returns True. Otherwise the function returns False and appends an error message to the supplied String giving the reason why the conversion failed.

Implements casa::RecordTransformable.

Implemented in casa::SpectralIndex, casa::TabularSpectrum, and casa::ConstantSpectrum.

virtual ComponentType::SpectralShape casa::SpectralModel::type ( ) const [pure virtual]

return the actual spectral type.

The ident function returns it as a String.

Implemented in casa::SpectralIndex, casa::TabularSpectrum, and casa::ConstantSpectrum.