Module casacore.measures¶

Measures¶

Measures are e.g. an epoch or coordinates which have in addition to values - casacore.quanta.Quantity - also a reference specification and possibly an offset. They are represented as records with fields describing the various entities embodied in the measure. These entities can be obtained by the access methods:

• get_type()
• get_ref()
• get_offset()
• get_value().

Each measure has its own list of reference codes (see the individual methods for creating them, like direction()). If an empty or no code reference code is given, the default code for that type of measure will be used (e.g. it is J2000 for a direction()). If an unknown code is given, this default is also returned, but with a warning message.

The values of a measure (like the right-ascension for a direction()) are given as casacore.quanta.quantity(). Each of them can be either a scalar quantity with a scalar or vector for its actual value (see the following example):

>>> from casacore.quanta import quantity
>>> dm.epoch('utc','today') # note that your value will be different
{'m0': {'unit': 'd', 'value': 55147.912709756973},
 'refer': 'UTC',
 'type': 'epoch'}
>>> dm.direction('j2000','5h20m','-30.2deg')
{'m0': {'unit': 'rad', 'value': 1.3962634015954634},
 'm1': {'unit': 'rad', 'value': -0.52708943410228748},
 'refer': 'J2000',
 'type': 'direction'}
>>> a = dm.direction('j2000','5h20m','-30.2deg')
>>> print a['type']
direction
>>> dm.get_offset(a)
None
>>> dm.getref(a)
J2000
>>> dm.get_value(a)
[1.3962634016 rad, -0.527089434102 rad]
>>> dm.get_value(a)[0]
1.3962634016 rad
>>> dm.get_value(a)[1]
-0.527089434102 rad
>>> # try as a scalar quantity with multiple values
>>> a = dm.direction('j2000', quantity([10,20],'deg'),
                 quantity([30,40], 'deg'))
>>> dm.get_value(a)[0]
[0.17453292519943295, 0.3490658503988659] rad
>>> dm.get_value(a)[0].get_value()[1]
0.3490658503988659
>>> print a
{'m0': {'unit': 'rad', 'value': array([ 0.17453293,  0.34906585])},
 'm1': {'unit': 'rad', 'value': array([ 0.52359878,  0.6981317 ])},
 'refer': 'J2000',
 'type': 'direction'}

Known measures are:

• epoch(): an instance in time (internally expressed as MJD or MGSD)
• direction(): a direction towards an astronomical object (including planets, sun, moon)
• position(): a position on Earth
• frequency(): electromagnetic wave energy
• radialvelocity(): radial velocity of astronomical object
• doppler(): doppler shift (i.e. radial velocity in non-velocity units like Optical, Radio.
• baseline(): interferometer baseline
• uvw(): UVW coordinates
• earthmagnetic(): Earth’ magnetic field

In addition to the reference code (like J2000), a measure needs sometimes more information to be convertable to another reference code (e.g. a time and position to convert it to an azimuth/elevation). This additional information is called the reference frame, and can specify one or more of ‘where am i’, ‘when is it’, ‘what direction”, ‘how fast’.

The frame values can be set using the method measures.do_frame().

Since you would normally work from a fixed position, the position frame element (‘where you are’), can be specified in your .aipsrc if its name is in the Observatory list (obslist) tool function. You can set your preferred position by adding to your .casarc file:

measures.default.observatory:       atca

API¶

casacore.measures.is_measure(v)¶

Return if this is a true measures dictionary

Parameters:	v – The object to check

class casacore.measures.measures¶

The measures server object. This should be used to set frame information and create the various measures and do conversion on them.

The measures types are:

• direction()
• position()
• epoch()
• frequency()
• doppler()
• baseline()
• radialvelocity()
• uvw()
• earthmagnetic()

Typical usage:

from casacore.measures import measures
dm = measures() # create measures server instance
dirmeas = dm.direction()

as_baseline(pos)¶

Convert a position measure into a baseline measure. No actual baseline is calculated, since operations can be done on positions, with subtractions to obtain baselines at a later stage.

Parameters:	pos – a position measure
Returns:	a baseline measure

baseline(rf='', v0='0..', v1='', v2='', off=None)¶

Defines a baselin measure. It has to specify a reference code, uvw quantity values (see introduction for the action on a scalar quantity with either a vector or scalar value, and when a vector of quantities is given), and optionally it can specify an offset, which in itself has to be a baseline.

Parameters:	rf – reference code string; Allowable reference codes are: ITRF and direction() codes Note that additional ones may become available. Check with: dm.listcodes(dm.baseline()) v0 – longitude or x as quantity or string v1 – latitude or y as quantity or string v2 – height or z as quantity or string off – an optional offset measure of same type

direction(rf='', v0='0..', v1='90..', off=None)¶

Defines a direction measure. It has to specify a reference code, direction quantity values (see introduction for the action on a scalar quantity with either a vector or scalar value, and when a vector of quantities is given), and optionally it can specify an offset, which in itself has to be a direction.

Parameters:

rf – reference code string; allowable reference codes are: J2000 JMEAN JTRUE APP B1950 BMEAN BTRUE GALACTIC HADEC AZEL SUPERGAL ECLIPTIC MECLIPTIC TECLIPTIC MERCURY VENUS MARS JUPITER SATURN URANUS NEPTUNE PLUTO MOON SUN COMET. Note that additional ones may become available. Check with: dm.list_codes(dm.direction()) v1 (v0,) – Direction quantity values should be longitude (angle) and latitude (angle) or strings parsable by quantity(). None are needed for planets: the frame epoch defines coordinates. See quantity() for possible angle formats. off – an optional offset measure of same type

Example:

>>> dm.direction('j2000','30deg','40deg')
>>> dm.direction('mars')

do_frame(v)¶

This method will set the measure specified as part of a frame.

If conversion from one type to another is necessary (with the measure function), the following frames should be set if one of the reference types involved in the conversion is as in the following lists:

Epoch

• UTC
• TAI
• LAST - position
• LMST - position
• GMST1
• GAST
• UT1
• UT2
• TDT
• TCG
• TDB
• TCD

Direction

• J2000
• JMEAN - epoch
• JTRUE - epoch
• APP - epoch
• B1950
• BMEAN - epoch
• BTRUE - epoch
• GALACTIC
• HADEC - epoch, position
• AZEL - epoch, position
• SUPERGALACTIC
• ECLIPTIC
• MECLIPTIC - epoch
• TECLIPTIC - epoch
• PLANET - epoch, [position]

Position

• WGS84
• ITRF

Radial Velocity

• LSRK - direction
• LSRD - direction
• BARY - direction
• GEO - direction, epoch
• TOPO - direction, epoch, position
• GALACTO - direction

Doppler

• RADIO
• OPTICAL
• Z
• RATIO
• RELATIVISTIC
• BETA
• GAMMA

Frequency

• REST - direction, radialvelocity
• LSRK - direction
• LSRD - direction
• BARY - direction
• GEO - direction, epoch
• TOPO - direction, epoch, position
• GALACTO

doppler(rf='', v0=0.0, off=None)¶

Defines a doppler measure. It has to specify a reference code, doppler quantity value (see introduction for the action on a scalar quantity with either a vector or scalar value, and when a vector of quantities is given), and optionally it can specify an offset, which in itself has to be a doppler.

Parameters:

rf – reference code string; Allowable reference codes are: RADIO OPTICAL Z RATIO RELATIVISTIC BETA GAMMA. Note that additional ones may become available. Check with: dm.listcodes(dm.doppler()) v0 – doppler ratio as quantity, string or float value. It should be either non-dimensioned to specify a ratio of the light velocity, or in velocity. (examples all give same doppler): off – an optional offset measure of same type

Example:

>>> from casacore import quanta
>>> dm.doppler('radio', 0.4)
>>> dm.doppler('radio', '0.4')
>>> dm.doppler('RADIO', quanta.constants['c']*0.4))

earthmagnetic(rf='', v0='0G', v1='0..', v2='90..', off=None)¶

Defines an earthmagnetic measure. It needs a reference code, earthmagnetic quantity values (see introduction for the action on a scalar quantity with either a vector or scalar value, and when a vector of quantities is given) if the reference code is not for a model, and optionally it can specify an offset, which in itself has to be a earthmagnetic. In general you specify a model (IGRF is the default and the only one known) and convert it to an explicit field. (See http://fdd.gsfc.nasa.gov/IGRF.html for information on the International Geomagnetic Reference Field). The earthmagnetic quantity values should be either longitude (angle), latitude(angle) and length(field strength); or x,y,z (field). See quantity() for possible angle formats.

Parameters:	rf – reference code string; Allowable reference codes are: IGRF v0 – longitude or x as quantity or string v1 – latitude or y as quantity or string v2 – height or z as quantity or string off – an optional offset measure of same type

epoch(rf='', v0='0.0d', off=None)¶

Defines an epoch measure. It has to specify a reference code, an epoch quantity value (see introduction for the action on a scalar quantity with either a vector or scalar value, and when a vector of quantities is given), and optionally it can specify an offset, which in itself has to be an epoch.

Parameters:	rf – reference code string; Allowable reference codes are: UTC TAI LAST LMST GMST1 GAST UT1 UT2 TDT TCG TDB TCB Note that additional ones may become available. Check with: dm.listcodes(dm.position()) v0 – time as quantity or string off – an optional offset measure of same type

expand(v)¶

Calculates the differences between a series of given measure values: it calculates baseline values from position values.

Params v:	a measure (of type ‘baseline’, ‘position’ or ‘uvw’)
Returns:	a dict with the value for key measures being a measure and the value for key xyz a quantity containing the differences.

Example:

>>> from casacore.quanta import quantity
>>> x = quantity([10,50],'m')
>>> y = quantity([20,100],'m')
>>> z = quantity([30,150],'m')
>>> sb = dm.baseline('itrf', x, y, z)
>>> out = dm.expand(sb)
>>> print out['xyz']
[40.000000000000014, 80.0, 120.0] m

frame_now()¶

Set the time (epoch) frame to the current time and day.

frequency(rf='', v0='0Hz', off=None)¶

Defines a frequency measure. It has to specify a reference code, frequency quantity value (see introduction for the action on a scalar quantity with either a vector or scalar value, and when a vector of quantities is given), and optionally it can specify an offset, which in itself has to be a frequency.

Parameters:

rf – reference code string; Allowable reference codes are: REST LSRK LSRD BARY GEO TOPO GALACTO Note that additional ones may become available. Check with: dm.listcodes(dm.frequency()) v0 – frequency value as quantity or string. The frequency quantity values should be in one of the recognised units (examples all give same frequency): value with time units: a period (0.5s) value as frequency: 2Hz value in angular frequency: 720deg/s value as length: 149896km value as wave number: 4.19169e-8m-1 value as enery (h.nu): 8.27134e-9ueV value as momentum: 4.42044e-42kg.m off – an optional offset measure of same type

get_lines()¶

Return a list of known spectral line names, which can be used as input to line().

Return type:	list of strings

get_observatories()¶

Return a list of known observatory names, which can be used as input to observatory().

Return type:	list of strings

get_offset(m)¶

Get the offset measure.

Parameters:	m – a measure (dictionary)
Return type:	a measure

get_ref(m)¶

Get the reference frame of the measure.

Parameters:	m – a measure (dictionary)
Return type:	string

get_sources()¶

Return a list of known sources names, which can be used as input to source().

Return type:	list of strings

get_type(m)¶

Get the type of the measure.

Parameters:	m – a measure (dictionary)
Return type:	string

get_value(v)¶

Return a list of quantities making up the measures’ value.

Parameters:	v – a measure

line(name)¶

Get a (frequency) measure for the given spectral line name.

Parameters:	name – the name of the spectral line. Minimum match applies. At the time of writing the following are recognised (but check get_lines()): C109A CI CII166A DI H107A H110A H138B H166A H240A H272A H2CO HE110A HE138B HI OH1612 OH1665 OH1667 OH1720 CO115271 H2O22235 SiO86847 CO230538
Returns:	a frequency measure

list_codes(m)¶

Get the known reference codes for a specified measure type. It will return a dict with two keys. The first is a string list of all normal codes; the second a string list (maybe empty) with all extra codes (like planets).

Parameters:	m – the measures with the type to get codes for

measure(v, rf, off=None)¶

Create/convert a measure using the frame state set on the measures server instance (via do_frame())

Parameters:	v – The measure to convert rf – The frame reference to convert to off – The optional offset for the measure

observatory(name)¶

Get a (position) measure for the given obervatory.

Parameters:	name – the name of the observatory. At the time of writing the following observatories are recognised (but check get_observatories()): ALMA ATCA BIMA CLRO DRAO DWL GB JCMT MOPRA NRAO12M PKS VLA WSRT
Returns:	a position measure

posangle(m0, m1)¶

This method will give the position angle from a direction to another i.e. the angle in a direction between the direction to the North pole and the other direction.

Parameters:	m0 – a measure m1 – another measure

Example:

>>> a = dm.direction('j2000','0deg','70deg')
>>> b = dm.direction('j2000','0deg','80deg')
>>> print dm.posangle(a,b)
-0.0 deg

position(rf='', v0='0..', v1='90..', v2='0m', off=None)¶

Defines a position measure. It has to specify a reference code, position quantity values (see introduction for the action on a scalar quantity with either a vector or scalar value, and when a vector of quantities is given), and optionally it can specify an offset, which in itself has to be a position. Note that additional ones may become available. Check with:

dm.listcodes(dm.position())

The position quantity values should be either longitude (angle), latitude(angle) and height(length); or x,y,z (length). See quantity() for possible angle formats.

Parameters:	rf – reference code string; Allowable reference codes are: WGS84 ITRF (World Geodetic System and International Terrestrial Reference Frame) v0 – longitude or x as quantity or string v1 – latitude or y as quantity or string v2 – height or z as quantity or string off – an optional offset measure of same type

Example:

dm.position('wgs84','30deg','40deg','10m')
dm.observatory('ATCA')

radialvelocity(rf='', v0='0m/s', off=None)¶

Defines a radialvelocity measure. It has to specify a reference code, radialvelocity quantity value (see introduction for the action on a scalar quantity with either a vector or scalar value, and when a vector of quantities is given), and optionally it can specify an offset, which in itself has to be a radialvelocity.

Parameters:	rf – reference code string; Allowable reference codes are: LSRK LSRD BARY GEO TOPO GALACTO Note that additional ones may become available. Check with: dm.listcodes(dm.radialvelocity()) v0 – longitude or x as quantity or string off – an optional offset measure of same type

rise(crd, ev='5deg')¶

This method will give the rise/set hour-angles of a source. It needs the position in the frame, and a time. If the latter is not set, the current time will be used.

Parameters:	crd – a direction measure ev – the elevation limit as a quantity or string
Returns:	dict with rise and set sidereal time quantities or a 2 strings “below” or “above”

riseset(crd, ev='5deg')¶

This will give the rise/set times of a source. It needs the position in the frame, and a time. If the latter is not set, the current time will be used.

Parameters:	crd – a direction measure ev – the elevation limit as a quantity or string
Returns:	The returned value is a dict with a ‘solved’ key, which is False if the source is always below or above the horizon. In that case the rise and set fields will all have a string value. The dict also returns a rise and set dict, with ‘last’ and ‘utc’ keys showing the rise and set times as epochs.

separation(m0, m1)¶

This method will give the separation of a direction from another as an angle.

Parameters:	m0 – a measure m1 – another measure

Example:

>>> a = dm.direction('j2000','0deg','70deg')
>>> b = dm.direction('j2000','0deg','80deg')
>>> print dm.separation(a,b)
10.0 deg

set_data_path(pth)¶

Set the location of the measures data directory.

Parameters:	pth – The absolute path to the measures data directory.

source(name)¶

Get a (direction) measure for the given atsronomical source.

Parameters:	name – the name of the source. Minimum match applies. Check get_sources() for the list of known sources
Returns:	a frequency measure

Example:

>>> print dm.source('1936-6')
{'m0': {'unit': 'rad', 'value': -1.1285176426372401},
 'm1': {'unit': 'rad', 'value': -1.0854059868642842},
 'refer': 'ICRS',
 'type': 'direction'}

to_doppler(rf, v0, rfq)¶

Convert a radialvelocity measure or a frequency measure to a doppler measure. In the case of a frequency, a rest frequency has to be specified. The type of doppler wanted (e.g. RADIO) has to be specified.

Parameters:	rf – doppler reference code (see doppler()) v0 – a radialvelocity or frequency measure rfq – frequency measure or quantity

Example:

f = dm.frequency('lsrk','1410MHz')     # specify a frequency
dm.todoppler('radio', f, dm.constants('HI')) # give doppler, using HI rest

to_frequency(rf, v0, rfq)¶

Convert a Doppler type value (e.g. in radio mode) to a frequency. The type of frequency (e.g. LSRK) and a rest frequency (either as a frequency quantity (e.g. dm.constants('HI')) or a frequency measure (e.g. dm.frequency('rest','5100MHz')) should be specified.

Parameters:	rf – frequency reference code (see frequency()) v0 – a doppler measure rfq – frequency measure or quantity

Example:

dop = dm.doppler('radio',0.4)
freq = dm.tofrequency('lsrk', dop, dm.constants('HI'))

to_radialvelocity(rf, v0)¶

Convert a Doppler type value (e.g. in radio mode) to a real radialvelocity. The type of velocity (e.g. LSRK) should be specified

Parameters:	rf – radialvelocity reference code (see radialvelocity()) v0 – a doppler measure

Example:

a = dm.doppler('radio',0.4)
dm.toradialvelocity('topo',a)

to_restfrequency(f0, d0)¶

Convert a frequency measure and a doppler measure (e.g. obtained from another spectral line with a known rest frequency) to a rest frequency.

Parameters:	f0 – frequency reference code (see frequency()) v0 – a doppler measure

Example:

dp = dm.doppler('radio', '2196.24984km/s')  # a measured doppler speed
f = dm.frequency('lsrk','1410MHz')    # a measured frequency
dm.torestfrequency(f, dp)        # the corresponding rest frequency

to_uvw(v)¶

Calculates a uvw measure from a baseline. The baseline can consist of a vector of actual baseline positions. Note that the baseline does not have to be a proper baseline, but can be a series of positions (to call positions baselines see asbaseline() ) for speed reasons: operations are linear and can be done on positions, which are converted to baseline values at the end (with expand() ).

Whatever the reference code of the baseline, the returned uvw will be given in J2000. If the dot argument is given, that variable will be filled with a quantity array consisting of the time derivative of the uvw (note that only the sidereal rate is taken into account; not precession, earth tides and similar variations, which are much smaller). If the xyz variable is given, it will be filled with the quantity values of the uvw measure.

The values of the input baselines can be given as a quantity vector per x, y or z value.

uvw coordinates are calculated for a certain direction in the sky; hence the frame has to contain the direction for the calculation to work. Since the baseline and the sky rotate with respect of each other, the time should be specified as well.

Example:

>>> dm.do_frame(dm.observatory('atca'))
>>> dm.do_frame(dm.source('1934-638'))
>>> dm.do_frame(dm.epoch('utc', 'today'))
>>> b = dm.baseline('itrf', '10m', '20m', '30m')

uvw(rf='', v0='0..', v1='', v2='', off=None)¶

Defines a uvw measure. It has to specify a reference code, uvw quantity values (see introduction for the action on a scalar quantity with either a vector or scalar value, and when a vector of quantities is given), and optionally it can specify an offset, which in itself has to be a uvw.

Parameters:	rf – reference code string; Allowable reference codes are: ITRF and direction() codes Note that additional ones may become available. Check with: dm.listcodes(dm.uvw()) v0 – longitude or x as quantity or string v1 – latitude or y as quantity or string v2 – height or z as quantity or string off – an optional offset measure of same type