This is a python bindings to casacore measures
A measure is a quantity with a specified reference frame (e.g. UTC, J2000, mars). The measures module provides an interface to the handling of measures. The basic functionality provided is:
- Conversion of measures, especially between different frames (e.g. UTC to LAST)
- Calculation of e.g. a rest frequency from a velocity and a frequency.
To access the measures do the following. We will use dm as the measures instance through all examples:
>>> from pyrap.measures import measures
>>> dm = measures()
Measures are e.g. an epoch or coordinates which have in addition to values - pyrap.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:
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 pyrap.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 pyrap.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
Return if this is a true measures dictionary
| Parameter: | v – The object to check |
|---|
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:
Typical usage:
from pyrap.measures import measures
dm = measures() # create measures server instance
dirmeas = dm.direction()
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.
| Parameter: | pos – a position measure |
|---|---|
| Returns: | a baseline measure |
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: |
|
|---|
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: |
|
|---|
Example:
>>> dm.direction('j2000','30deg','40deg')
>>> dm.direction('mars')
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
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: |
|
|---|
Example:
>>> from pyrap import quanta
>>> dm.doppler('radio', 0.4)
>>> dm.doppler('radio', '0.4')
>>> dm.doppler('RADIO', quanta.constants['c']*0.4))
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: |
|
|---|
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: |
|
|---|
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 pyrap.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
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: |
|
|---|
Return a list of known spectral line names, which can be used as input to line().
| Return type: | list of strings |
|---|
Return a list of known observatory names, which can be used as input to observatory().
| Return type: | list of strings |
|---|
Get the offset measure.
| Parameter: | m – a measure (dictionary) |
|---|---|
| Return type: | a measure |
Get the reference frame of the measure.
| Parameter: | m – a measure (dictionary) |
|---|---|
| Return type: | string |
Return a list of known sources names, which can be used as input to source().
| Return type: | list of strings |
|---|
Get the type of the measure.
| Parameter: | m – a measure (dictionary) |
|---|---|
| Return type: | string |
Return a list of quantities making up the measures’ value.
| Parameter: | v – a measure |
|---|
Get a (frequency) measure for the given spectral line name.
| Parameter: | 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 |
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).
| Parameter: | m – the measures with the type to get codes for |
|---|
Create/convert a measure using the frame state set on the measures server instance (via do_frame())
| Parameters: |
|
|---|
Get a (position) measure for the given obervatory.
| Parameter: | 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 |
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: |
|
|---|
Example:
>>> a = dm.direction('j2000','0deg','70deg')
>>> b = dm.direction('j2000','0deg','80deg')
>>> print dm.posangle(a,b)
-0.0 deg
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: |
|
|---|
Example:
dm.position('wgs84','30deg','40deg','10m')
dm.observatory('ATCA')
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: |
|
|---|
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: |
|
|---|---|
| Returns: | dict with rise and set sidereal time quantities or a 2 strings “below” or “above” |
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: |
|
|---|---|
| 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. |
This method will give the separation of a direction from another as an angle.
| Parameters: |
|
|---|
Example:
>>> a = dm.direction('j2000','0deg','70deg')
>>> b = dm.direction('j2000','0deg','80deg')
>>> print dm.separation(a,b)
10.0 deg
Set the location of the measures data directory.
| Parameter: | pth – The absolute path to the measures data directory. |
|---|
Get a (direction) measure for the given atsronomical source.
| Parameter: | 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'}
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: |
|
|---|
Example:
f = dm.frequency('lsrk','1410MHz') # specify a frequency
dm.todoppler('radio', f, dm.constants('HI')) # give doppler, using HI rest
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: |
|
|---|
Example:
dop = dm.doppler('radio',0.4)
freq = dm.tofrequency('lsrk', dop, dm.constants('HI'))
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: |
|
|---|
Example:
a = dm.doppler('radio',0.4)
dm.toradialvelocity('topo',a)
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: |
|
|---|
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
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')
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: |
|
|---|