SpecFrame Attributes

SpecFrame Attributes

AlignSpecOffset

Align SpecFrames using the offset coordinate system? (bool)

This attribute is a boolean value which controls how a SpecFrame behaves when it is used (by Frame::findFrame or Frame::convert) as a template to match another (target) SpecFrame. It determines whether alignment occurs between the offset values defined by the current value of the SpecOffset attribute, or between the corresponding absolute spectral values.

The default value of zero results in the two SpecFrames being aligned so that a given absolute spectral value in one is mapped to the same absolute value in the other. A non-zero value results in the SpecFrames being aligned so that a given offset value in one is mapped to the same offset value in the other.

AlignStdOfRest

Standard of rest to use when aligning SpecFrames. (string)

This attribute controls how a SpecFrame behaves when it is used (by Frame::findFrame or Frame::convert) as a template to match another (target) SpecFrame. It identifies the standard of rest in which alignment is to occur. See the StdOfRest attribute for a desription of the values which may be assigned to this attribute. The default AlignStdOfRest value is "Helio" (heliographic).

When Frame::findFrame or Frame::convert is used on two SpecFrames (potentially describing different spectral coordinate systems), it returns a Mapping which can be used to transform a position in one SpecFrame into the corresponding position in the other. The Mapping is made up of the following steps in the indicated order:

• Map values from the system used by the target (wavelength, apparent radial velocity, etc) to the system specified by the AlignSystem attribute, using the target's rest frequency if necessary.
• Map these values from the target's standard of rest to the standard of rest specified by the AlignStdOfRest attribute, using the Epoch, ObsLon, ObsLat, ObsAlt, RefDec and RefRA attributes of the target to define the two standards of rest.
• Map these values from the standard of rest specified by the AlignStdOfRest attribute, to the template's standard of rest, using the Epoch, ObsLon, ObsLat, ObsAlt RefDec and RefRA attributes of the template to define the two standards of rest.
• Map these values from the system specified by the AlignSystem attribute, to the system used by the template, using the template's rest frequency if necessary.

RefDec

The declination of the reference point ("dd:mm:ss.s"). (string)

This attribute specifies the FK5 J2000.0 declination of a reference point on the sky. See the description of attribute RefRA for details. The default RefDec is "0:0:0".

RefRA

The right ascension of the reference point ("hh:mm:ss.ss"). (string)

This attribute, together with the RefDec attribute, specifies the FK5 J2000.0 coordinates of a reference point on the sky. For 1-dimensional spectra, this should normally be the position of the source. For spectral data with spatial coverage (spectral cubes, etc), this should be close to centre of the spatial coverage. It is used to define the correction for Doppler shift to be applied when using the Frame::findFrame or Frame::convert method to convert between different standards of rest.

The SpecFrame class assumes this velocity correction is spatially invariant. If a single SpecFrame is used (for instance, as a component of a CmpFrame) to describe spectral values at different points on the sky, then it is assumes that the doppler shift at any spatial position is the same as at the reference position. The maximum velocity error introduced by this assumption is of the order of V*SIN(FOV), where FOV is the angular field of view, and V is the relative velocity of the two standards of rest. As an example, when correcting from the observers rest frame (i.e. the topocentric rest frame) to the kinematic local standard of rest the maximum value of V is about 20 km/s, so for 5 arc-minute field of view the maximum velocity error introduced by the correction will be about 0.03 km/s. As another example, the maximum error when correcting from the observers rest frame to the local group is about 5 km/s over a 1 degree field of view.

The RefRA and RefDec attributes are stored internally in radians, but are converted to and from a string for access. The format "hh:mm:ss.ss" is used for RefRA, and "dd:mm:ss.s" is used for RefDec. The methods SpecFrame::setRefPos and SpecFrame::getRefPos may be used to access the values of these attributes directly as unformatted values in radians.

The default for RefRA is "0:0:0".

RestFreq

The rest frequency (GHz). (float, but can also be set as a string in other units)

This attribute specifies the frequency corresponding to zero velocity. It is used when converting between between velocity-based coordinate systems and and other coordinate systems (such as frequency, wavelength, energy, etc). The default value is 1.0E5 GHz.

When setting a new value for this attribute, the new value can be supplied either directly as a frequency, or indirectly as a wavelength or energy, in which case the supplied value is converted to a frequency before being stored. The nature of the supplied value is indicated by appending text to the end of the numerical value indicating the units in which the value is supplied. If the units are not specified, then the supplied value is assumed to be a frequency in units of GHz. If the supplied unit is a unit of frequency, the supplied value is assumed to be a frequency in the given units. If the supplied unit is a unit of length, the supplied value is assumed to be a (vacuum) wavelength. If the supplied unit is a unit of energy, the supplied value is assumed to be an energy. For instance, the following strings all result in a rest frequency of around 1.4E14 Hz being used: "1.4E5", "1.4E14 Hz", "1.4E14 s**-1", "1.4E5 GHz", "2.14E-6 m", "21400 Angstrom", "9.28E-20 J", "9.28E-13 erg", "0.58 eV", etc.

When getting the value of this attribute, the returned value is always a frequency in units of GHz.

SourceSys

Spectral system in which the source velocity is stored. (string)

This attribute identifies the spectral system in which the SourceVel attribute value (the source velocity) is supplied and returned. It can be one of the following:

• "VRAD" or "VRADIO": Radio velocity (km/s)
• "VOPT" or "VOPTICAL": Optical velocity (km/s)
• "ZOPT" or "REDSHIFT": Redshift (dimensionless)
• "BETA": Beta factor (dimensionless)
• "VELO" or "VREL": Apparent radial ("relativistic") velocity (km/s)

When setting a new value for the SourceVel attribute, the source velocity should be supplied in the spectral system indicated by this attribute. Likewise, when getting the value of the SourceVel attribute, the velocity will be returned in this spectral system.

If the value of SourceSys is changed, the value stored for SourceVel will be converted from the old to the new spectral systems.

The default value is "VELO" (apparent radial velocity).

SourceVel

The source velocity. (float)

This attribute (together with SourceSys, SourceVRF, RefRA and RefDec) defines the "Source" standard of rest (see attribute StdOfRest). This is a rest frame which is moving towards the position given by RefRA and RefDec at a velocity given by SourceVel. A positive value means the source is moving away from the observer. When a new value is assigned to this attribute, the supplied value is assumed to refer to the spectral system specified by the SourceSys attribute. For instance, the SourceVel value may be supplied as a radio velocity, a redshift, a beta factor, etc. Similarly, when the current value of the SourceVel attribute is obtained, the returned value will refer to the spectral system specified by the SourceSys value. If the SourceSys value is changed, any value previously stored for the SourceVel attribute will be changed automatically from the old spectral system to the new spectral system.

When setting a value for SourceVel, the value should be supplied in the rest frame specified by the SourceVRF attribute. Likewise, when getting the value of SourceVel, it will be returned in the rest frame specified by the SourceVRF attribute.

The default SourceVel value is zero.

Notes

• It is important to set an appropriate value for SourceVRF and SourceSys before setting a value for SourceVel. If a new value is later set for SourceVRF or SourceSys, the value stored for SourceVel will simultaneously be changed to the new standard of rest or spectral system.

SourceVRF

Rest frame in which the source velocity is stored. (string)

This attribute identifies the rest frame in which the source velocity or redshift is stored (the source velocity or redshift is accessed using attribute SourceVel). When setting a new value for the SourceVel attribute, the source velocity or redshift should be supplied in the rest frame indicated by this attribute. Likewise, when getting the value of the SourceVel attribute, the velocity or redshift will be returned in this rest frame.

If the value of SourceVRF is changed, the value stored for SourceVel will be converted from the old to the new rest frame.

The values which can be supplied are the same standards of rest as for the StdOfRest attribute (except that SourceVRF cannot be set to "Source"). The default value is "Helio".

SpecOrigin

The zero point for SpecFrame axis values. (float)

This specifies the origin from which all spectral values are measured. The default value (zero) results in the SpecFrame describing absolute spectral values in the system given by the System attribute (e.g. frequency, velocity, etc). If a SpecFrame is to be used to describe offset from some origin, the SpecOrigin attribute should be set to hold the required origin value. The SpecOrigin value stored inside the SpecFrame structure is modified whenever SpecFrame attribute values are changed so that it refers to the original spectral position.

When setting a new value for this attribute, the supplied value is assumed to be in the system, units and standard of rest described by the SpecFrame. Likewise, when getting the value of this attribute, the value is returned in the system, units and standard of rest described by the SpecFrame. If any of these attributes are changed, then any previously stored SpecOrigin value will also be changed so that refers to the new system, units or standard of rest.

StdOfRest

Standard of rest. (string)

This attribute identifies the standard of rest to which the spectral axis values of a SpecFrame refer, and may take any of the values listed in the "Standards of Rest" section (below).

The default StdOfRest value is "Helio".

Standards of Rest

The SpecFrame class supports the following StdOfRest values (all are case-insensitive):

• "Topocentric", "Topocent" or "Topo": The observers rest-frame (assumed to be on the surface of the earth). Spectra recorded in this standard of rest suffer a Doppler shift which varies over the course of a day because of the rotation of the observer around the axis of the earth. This standard of rest must be qualified using the Epoch, ObsLon, ObsLat, ObsAlt, RefRA and RefDec attributes.
• "Geocentric", "Geocentr" or "Geo": The rest-frame of the earth centre. Spectra recorded in this standard of rest suffer a Doppler shift which varies over the course of a year because of the rotation of the earth around the Sun. This standard of rest must be qualified using the Epoch, RefRA and RefDec attributes.
• "Barycentric", "Barycent" or "Bary": The rest-frame of the solar-system barycentre. Spectra recorded in this standard of rest suffer a Doppler shift which depends both on the velocity of the Sun through the Local Standard of Rest, and on the movement of the planets through the solar system. This standard of rest must be qualified using the Epoch, RefRA and RefDec attributes.
• "Heliocentric", "Heliocen" or "Helio": The rest-frame of the Sun. Spectra recorded in this standard of rest suffer a Doppler shift which depends on the velocity of the Sun through the Local Standard of Rest. This standard of rest must be qualified using the RefRA and RefDec attributes.
• "LSRK", "LSR": The rest-frame of the kinematical Local Standard of Rest. Spectra recorded in this standard of rest suffer a Doppler shift which depends on the velocity of the kinematical Local Standard of Rest through the galaxy. This standard of rest must be qualified using the RefRA and RefDec attributes.
• "LSRD": The rest-frame of the dynamical Local Standard of Rest. Spectra recorded in this standard of rest suffer a Doppler shift which depends on the velocity of the dynamical Local Standard of Rest through the galaxy. This standard of rest must be qualified using the RefRA and RefDec attributes.
• "Galactic", "Galactoc" or "Gal": The rest-frame of the galactic centre. Spectra recorded in this standard of rest suffer a Doppler shift which depends on the velocity of the galactic centre through the local group. This standard of rest must be qualified using the RefRA and RefDec attributes.
• "Local_group", "Localgrp" or "LG": The rest-frame of the local group. This standard of rest must be qualified using the RefRA and RefDec attributes.
• "Source", or "src": The rest-frame of the source. This standard of rest must be qualified using the RefRA, RefDec and SourceVel attributes.

Where more than one alternative System value is shown above, the first of these will be returned when an enquiry is made.