Coverage for /wheeldirectory/casa-6.7.0-12-py3.10.el8/lib/py/lib/python3.10/site-packages/casatools/measures.py: 59%
109 statements
« prev ^ index » next coverage.py v7.6.4, created at 2024-10-31 18:48 +0000
1##################### generated by xml-casa (v2) from measures.xml ##################
2##################### 10d0ffd28eb07533e776e745f7d49a27 ##############################
3from __future__ import absolute_import
4from .__casac__.measures import measures as _measures
6from .errors import create_error_string
7from .typecheck import CasaValidator as _validator
8_pc = _validator( )
9from .coercetype import coerce as _coerce
12class measures:
13 _info_group_ = """measures"""
14 _info_desc_ = """measures tool"""
15 ### self
16 def __init__(self, *args, **kwargs):
17 """Create a measures tool on the specified host (or by default the
18 host you are running on).
19 """
20 self._swigobj = kwargs.get('swig_object',None)
21 if self._swigobj is None:
22 self._swigobj = _measures()
24 def dirshow(self, v):
25 """dirshow will convert a direction measure to a string
26 """
27 return self._swigobj.dirshow(v)
29 def show(self, v, refcode=True):
30 """show will convert a measure to a string.
32 All measures are catered for (at this moment {em direction, position, epoch,
33 radialvelocity, frequency, doppler, baseline, uvw, earthmagnetic} ).
34 """
35 return self._swigobj.show(v, refcode)
37 def epoch(self, rf='UTC', v0=[ ], off={ }):
38 """epoch defines an epoch measure from the CLI. It has to specify a
39 reference code, an epoch quantity value (see introduction for the
40 action on a scalar quantity with either a vector or scalar value),
42 and optionally it can specify an offset, which in itself has to be an
43 epoch. Allowable reference codes are:
44 {em UTC TAI LAST LMST GMST1 GAST UT1 UT2 TDT TCG TDB TCB}.
45 Note that additional ones may become available. Check in casa with:
47 begin{verbatim}
48 print "t----t epoch Ex 1 t----"
49 print me.listcodes(me.epoch())
50 #{'normal': ['LAST', 'LMST', 'GMST1', 'GAST', 'UT1', 'UT2', 'UTC', 'TAI',
51 # 'TDT', 'TCG', 'TDB', 'TCB', 'IAT', 'GMST', 'TT', 'ET', 'UT'], 'extra': []}
52 #
53 end{verbatim}
55 See quantity for possible time formats.
56 """
57 return self._swigobj.epoch(rf, v0, off)
59 def direction(self, rf='J2000', v0=[ ], v1=[ ], off={ }):
60 """direction defines a direction measure from the CLI. It has to specify a
61 reference code, direction quantity values (see introduction for the action on a
62 scalar quantity with either a vector or scalar value),
64 and optionally it can specify an
65 offset, which in itself has to be a direction. Allowable reference codes are:
66 {em J2000 JMEAN JTRUE APP B1950 BMEAN BTRUE GALACTIC HADEC AZEL
67 SUPERGAL ECLIPTIC MECLIPTIC TECLIPTIC MERCURY
68 VENUS MARS JUPITER SATURN URANUS NEPTUNE PLUTO MOON SUN COMET}.
69 Note that additional ones may become available. Check in casa with:
71 begin{verbatim}
72 print "t----t direction Ex 1 t----"
73 print me.listcodes(me.direction())
74 #{'normal': ['J2000', 'JMEAN', 'JTRUE', 'APP', 'B1950', 'BMEAN',
75 #'BTRUE', 'GALACTIC', 'HADEC', 'AZEL', 'AZELSW', 'AZELNE', 'AZELGEO',
76 #'AZELSWGEO', 'AZELNEGEO', 'JNAT', 'ECLIPTIC', 'MECLIPTIC',
77 #'TECLIPTIC', 'SUPERGAL', 'ITRF', 'TOPO', 'ICRS'], 'extra': ['MERCURY',
78 #'VENUS', 'MARS', 'JUPITER', 'SATURN', 'URANUS', 'NEPTUNE', 'PLUTO',
79 #'SUN', 'MOON', 'COMET']}
80 end{verbatim}
82 The direction quantity values should be longitude(angle) and
83 latitude(angle) (none needed for planets: the frame epoch defines coordinates).
84 See quantity for possible angle formats.
85 """
86 return self._swigobj.direction(rf, v0, v1, off)
88 def getvalue(self, v):
89 """getvalue gets the actual implementation value of the measure.
90 """
91 return self._swigobj.getvalue(v)
93 def gettype(self, v):
94 """gettype gets the actual type of the measure.
95 """
96 return self._swigobj.gettype(v)
98 def getref(self, v):
99 """gettype gets the actual reference code of the measure.
100 """
101 return self._swigobj.getref(v)
103 def getoffset(self, v):
104 """getoff gets the actual offset of the measure (as a measure) or F if no offset
105 given.
106 """
107 return self._swigobj.getoffset(v)
109 def cometname(self):
110 """cometname gets the name of the current comet (if any).
111 """
112 return self._swigobj.cometname()
114 def comettype(self):
115 """comettype gets the comet table type (apparent or topocentric)
116 """
117 return self._swigobj.comettype()
119 def cometdist(self):
120 """cometdist returns the distance in AU of the current comet in the current frame,
121 as a quantity. It will return -1 AU on failure!
123 """
124 return self._swigobj.cometdist()
126 def cometangdiam(self):
127 """cometdist returns the angular diameter (as seen from Earth) in AU of the current
128 comet in the current frame, as a quantity. It will return -1 radians on failure!
130 """
131 return self._swigobj.cometangdiam()
133 def comettopo(self):
134 """comettopo gets the comet table's topographic coordinates used.
135 """
136 return self._swigobj.comettopo()
138 def framecomet(self, v=''):
139 """framecomet will put the specified comet table in the frame.
140 """
141 return self._swigobj.framecomet(v)
143 def position(self, rf='WGS84', v0=[ ], v1=[ ], v2=[ ], off={ }):
144 """position defines a position measure from the CLI. It has to specify a
145 reference code, position quantity values (see introduction for the action on a
146 scalar quantity with either a vector or scalar value),
148 and optionally it can specify an
149 offset, which in itself has to be a position. Allowable reference codes are:
150 {em WGS84 ITRF} (World Geodetic System and International Terrestrial
151 Reference Frame).
152 Note that additional ones may become available. Check in casa with:
154 begin{verbatim}
155 print "t----t position Ex 1 t----"
156 print me.listcodes(me.position())
157 #{'normal': ['ITRF', 'WGS84'], 'extra': []}
158 end{verbatim}
160 The position quantity values should be either longitude
161 (angle), latitude(angle) and height(length); or x,y,z (length).
162 See quantity for possible angle formats.
163 """
164 return self._swigobj.position(rf, v0, v1, v2, off)
166 def observatory(self, name='ALMA'):
167 """observatory will give you the position of an observatory as given in the
168 system. At the time of writing the following observatories are recognised
169 (but check e.g. the position GUI for currently known ones, or the
170 me.obslist() tool function)::
172 {'ALMA' 'ARECIBO' 'ATCA' 'BIMA' 'CLRO' 'DRAO' 'DWL' 'GB' 'GBT' 'GMRT'
173 'IRAM PDB' 'IRAM_PDB' 'JCMT' 'MOPRA' 'MOST' 'NRAO12M' 'NRAO_GBT' 'PKS'
174 'SAO SMA' 'SMA' 'VLA' 'VLBA' 'WSRT' 'ATF' 'ATA' 'CARMA' 'ACA' 'OSF'
175 'OVRO_MMA' 'EVLA' 'ASKAP' 'APEX' 'SMT' 'NRO' 'ASTE' 'LOFAR' 'MeerKAT'
176 'KAT-7' 'EVN' 'LWA1' 'PAPER_SA' 'PAPER_GB' 'e-MERLIN' 'MERLIN2'
177 'Effelsberg' 'MWA32T' }.
178 """
179 return self._swigobj.observatory(name)
181 def obslist(self):
182 """obslist will give you an array of strings of the
183 observatories known in the Observatories table.
184 """
185 return self._swigobj.obslist()
187 def linelist(self):
188 """linelist will give you a string with a space separated list of spectral lines
189 known in the Lines table.
191 A number of lines are available now, but tables with many lines are
192 already online, and will be interfaced once a nomenclature can be defined for
193 the tens of thousands of lines.
194 """
195 return self._swigobj.linelist()
197 def spectralline(self, name='HI'):
198 """spectralline will give you the frequency of a spectral line. The known list
199 can be obtained by me.linelist().
200 """
201 return self._swigobj.spectralline(name)
203 def sourcelist(self):
204 """sourcelist will give you a string with the space separated list of sources
205 known in the Sources table.
206 """
207 return self._swigobj.sourcelist()
209 def source(self, name=[ ]):
210 """source will give you the direction of a source. The known list
211 can be obtained by me.sourcelist().
212 """
213 return self._swigobj.source(name)
215 def frequency(self, rf='LSRK', v0=[ ], off={ }):
216 """frequency defines a frequency measure from the CLI. It has to specify a
217 reference code, frequency quantity value (see introduction for the action on a
218 scalar quantity with either a vector or scalar value),
220 and optionally it can specify an
221 offset, which in itself has to be a frequency. Allowable reference codes are:
222 {em REST LSRK LSRD BARY GEO TOPO GALACTO LGROUP CMB}.
223 Note that additional ones may become available. Check in casa with:
224 begin{verbatim}
225 print "t----t frequency Ex 1 t----"
226 print me.listcodes(me.frequency())
227 #{'normal': ['REST', 'LSRK', 'LSRD', 'BARY', 'GEO', 'TOPO',
228 # 'GALACTO', 'LGROUP', 'CMB'], 'extra': []}
229 end{verbatim}
231 The frequency quantity values should be in one of the recognised units
232 (examples all give same frequency):
233 begin{itemize}
234 item value with time units: a period (0.5s)
235 item value as frequency: 2Hz
236 item value in angular frequency: 720deg/s
237 item value as length: 149896km
238 item value as wave number: 4.19169e-8m-1
239 item value as energy (h.nu): 8.27134e-9ueV
240 item value as momentum: 4.42044e-42kg.m
241 end{itemize}
242 """
243 return self._swigobj.frequency(rf, v0, off)
245 def doppler(self, rf='RADIO', v0=[ ], off={ }):
246 """doppler defines a doppler measure from the CLI. It has to specify a
247 reference code, doppler quantity value (see introduction for the action on a
248 scalar quantity with either a vector or scalar value),
250 and optionally it can specify an offset,
251 which in itself has to be a doppler. Allowable reference codes are:
252 {em RADIO Z RATIO BETA GAMMA OPTICAL TRUE RELATIVISTIC}.
253 Note that additional ones may become available. Check in casa with:
255 begin{verbatim}
256 print "t----t doppler Ex 1 t----"
257 print me.listcodes(me.doppler())
258 #{'normal': ['RADIO', 'Z', 'RATIO', 'BETA', 'GAMMA', 'OPTICAL',
259 # 'TRUE', 'RELATIVISTIC'], 'extra': []}
260 end{verbatim}
262 The doppler quantity values should be either non-dimensioned to specify a
263 ratio of the light velocity, or in velocity.
264 """
265 return self._swigobj.doppler(rf, v0, off)
267 def radialvelocity(self, rf='LSRK', v0=[ ], off={ }):
268 """radialvelocity defines a radialvelocity measure from the CLI. It has to
269 specify a reference code, radialvelocity quantity value (see introduction for
270 the action on a
271 scalar quantity with either a vector or scalar value),
273 and optionally it
274 can specify an offset, which in itself has to be a radialvelocity.
275 Allowable reference codes are:
276 {em LSRK LSRD BARY GEO TOPO GALACTO LGROUP CMB}.
277 Note that additional ones may become available. Check in casa with:
279 begin{verbatim}
280 print "t----t radialvelocity Ex 1 t----"
281 print me.listcodes(me.radialvelocity())
282 # Out[17]:
283 #{'extra': [],
284 # 'normal': ['LSRK', 'LSRD', 'BARY', 'GEO', 'TOPO', 'GALACTO',
285 # 'LGROUP', 'CMB']}
286 end{verbatim}
287 The radialvelocity quantity values should be given as velocity.
288 """
289 return self._swigobj.radialvelocity(rf, v0, off)
291 def shift(self, v={ }, offset=[ ], pa=[ ]):
292 """This method calculates the direction measure located at the specified offset angular amount along the specified
293 position angle from the specified direction measure.
295 """
296 return self._swigobj.shift(v, offset, pa)
298 def uvw(self, rf='ITRF', v0=[ ], v1=[ ], v2=[ ], off={ }):
299 """uvw defines a uvw measure from the CLI. It has to specify a
300 reference code, uvw quantity values (see introduction for the action on a
301 scalar quantity with either a vector or scalar value), and optionally it can specify an
302 offset, which in itself has to be a uvw. Allowable reference codes are
303 ITRF and the direction ones.
305 Note that additional ones may become available. Check in casa with::
307 print "t----t uvw Ex 1 t----"
308 print me.listcodes(me.uvw())
310 {
311 'normal': array(['J2000', 'JMEAN', 'JTRUE', 'APP', 'B1950', 'B1950_VLA', 'BMEAN',
312 'BTRUE', 'GALACTIC', 'HADEC', 'AZEL', 'AZELSW', 'AZELNE', 'AZELGEO',
313 'AZELSWGEO', 'AZELNEGEO', 'JNAT', 'ECLIPTIC', 'MECLIPTIC',
314 'TECLIPTIC', 'SUPERGAL', 'ITRF', 'TOPO', 'ICRS'], dtype='|S10'),
315 'extra': array([], dtype='|S1')
316 }
318 The uvw quantity values should be either longitude
319 (angle), latitude(angle) and height(length); or x,y,z (length).
320 See quantity for possible angle formats.
321 """
322 return self._swigobj.uvw(rf, v0, v1, v2, off)
324 def touvw(self, v={ }):
325 """touvw calculates a uvw measure from a baseline. Note that the
326 baseline does not have to be a proper {em baseline}, but can be a
327 series of positions (to call positions baselines see
328 asbaseline ) for speed reasons:
329 operations are linear and can be done on positions, which are
330 converted to baseline values at the end (with
331 expand ).
333 Whatever the reference code of the baseline, the returned {em uvw} will be
334 given in J2000. If the {em dot} argument is given, that variable
335 will be filled with a quantity array consisting of the time
336 derivative of the uvw (note that only the sidereal rate is taken
337 into account; not precession, earth tides and similar variations,
338 which are much smaller). If the {em xyz} variable is given, it will
339 be filled with the quantity values of the uvw measure.
341 The values of the input baselines can be given as a quantity
342 vector per x, y or z value.
344 uvw coordinates are calculated for a certain direction in the sky;
345 hence the frame has to contain the direction for the calculation to
346 work. Since the baseline and the sky rotate with respect of each
347 other, the time should be specified as well.
348 """
349 return self._swigobj.touvw(v)
351 def expand(self, v={ }):
352 """expand calculates the differences between a series of given measure
353 values: it calculates baseline values from position values. The
354 returned value is a measure, but the value of the optional output
355 variable {em xyz} will be set to an array of values.
356 """
357 return self._swigobj.expand(v)
359 def earthmagnetic(self, rf='IGRF', v0=[ ], v1=[ ], v2=[ ], off={ }):
360 """earthmagnetic defines an earthmagnetic measure from the CLI. It needs
361 a reference code, earthmagnetic quantity values
362 (see introduction for the action on a
363 scalar quantity with either a vector or scalar value) if the reference code is not
364 for a model, and optionally it
365 can specify an offset, which in itself has to be a earthmagnetic. In general
366 you specify a model (IGRF is the default and the only one known) and convert
367 it to an explicit field. (See
369 http://fdd.gsfc.nasa.gov/IGRF.html
371 for information on the International Geomagnetic Reference Field). The
372 earthmagnetic quantity values should be either longitude (angle),
373 latitude(angle) and length(field strength); or x,y,z (field).
374 See quantity for possible angle formats.
375 """
376 return self._swigobj.earthmagnetic(rf, v0, v1, v2, off)
378 def baseline(self, rf='ITRF', v0=[ ], v1=[ ], v2=[ ], off={ }):
379 """baseline defines a baseline measure from the CLI. It has to specify a
380 reference code, baseline quantity values (see introduction for the action on a
381 scalar quantity with either a vector or scalar value, and when a vector of
382 quantities is given), and optionally it can specify an
383 offset, which in itself has to be a baseline. Allowable reference codes are
384 ITRF and the direction ones.
386 Note that additional ones may become available. Check in casa with::
388 print "t----t baseline Ex 1 t----"
389 print me.listcodes(me.baseline())
390 # {'normal': array(['J2000', 'JMEAN', 'JTRUE', 'APP', 'B1950', 'B1950_VLA', 'BMEAN',
391 # 'BTRUE', 'GALACTIC', 'HADEC', 'AZEL', 'AZELSW', 'AZELNE', 'AZELGEO',
392 # 'AZELSWGEO', 'AZELNEGEO', 'JNAT', 'ECLIPTIC', 'MECLIPTIC',
393 # 'TECLIPTIC', 'SUPERGAL', 'ITRF', 'TOPO', 'ICRS'],
394 # dtype='|S10'), 'extra': array([],
395 # dtype='|S1')}
397 The baseline quantity values should be either longitude
398 (angle), latitude(angle) and height(length); or x,y,z (length).
399 See quantity for possible angle formats.
400 """
401 return self._swigobj.baseline(rf, v0, v1, v2, off)
403 def asbaseline(self, pos):
404 """asbaseline converts a position measure into a baseline measure. No
405 actual baseline is calculated, since operations can be done on
406 positions, with subtractions to obtain baselines at a later stage.
407 """
408 return self._swigobj.asbaseline(pos)
410 def listcodes(self, ms):
411 """listcodes will produce the known reference codes for a specified measure
412 type. It will return a record with two entries. The first is a string vector
413 of all normal codes; the second a string vector (maybe empty) with all extra
414 codes (like planets).
415 NOTE: Synonyms and different code groups may be present in the code name lists.
416 The indices in these lists therefore do not necessarily correspond to
417 the internal CASA enumeration indices.
418 """
419 return self._swigobj.listcodes(ms)
421 def measure(self, v, rf, off={ }):
422 """measure converts measures (epoch, direction etc.) from one reference to
423 another. It will, for instance, convert a direction from J2000 to AZEL
424 representation.
425 Its arguments are a measure, an output reference code (see the individual
426 measures for the allowable codes (direction,
427 position,
428 epoch,
429 frequency,
430 doppler,
431 radialvelocity,
432 baseline,
433 uvw,
434 earthmagnetic)), and an optional offset of
435 the same type as the main measure. The offset will be subtracted from the
436 result before it is returned.
437 In some cases (see the individual measures for when), more information than
438 just a reference code is necessary. E.g. the above example of a conversion to
439 AZEL, needs to know for when, and where on Earth we want it. This information
440 is stored in a reference frame. Measures are set in the reference frame with
441 the doframe function. The frame is tool
442 wide.
444 {bf IMPORTANT NOTE:}
445 To get an accurate conversion of solar system objects direction to a celestial frame, one should convert to AZEL or HADEC before to get parallax accounted for. Thus if you want to get the moon's position in J2000..one would do it in 2 stages
446 i.e (after setting the appropriate frames)
448 moonazel=me.measure(me.direction('moon'), 'AZELGEO')
449 moonJ2000=me.measure(moonazel, 'J2000')
450 """
451 return self._swigobj.measure(v, rf, off)
453 def doframe(self, v):
454 """doframe will set the measure specified as part of a frame.
456 If conversion from one type to another is necessary, with the
457 measure function,
458 the following frames
459 should be set if one of the reference types involved in the conversion is as
460 in the following lists.
461 {em Epoch}
463 UTC
464 TAI
465 LASTposition
466 LMST position
467 GMST1
468 GAST
469 UT1
470 UT2
471 TDT
472 TCG
473 TDB
474 TCD
476 {em Direction}
478 J2000
479 JMEANepoch
480 JTRUE epoch
481 APP epoch
482 B1950
483 BMEAN epoch
484 BTRUE epoch
485 GALACTIC
486 HADEC epochposition
487 AZELepoch position
488 SUPERGALACTIC
489 ECLIPTIC
490 MECLIPTIC epoch
491 TECLIPTICepoch
492 PLANETepoch [position]
494 {em Position}
496 WGS84
497 ITRF
499 {em Radial Velocity}
501 LSRK direction
502 LSRD direction
503 BARY direction
504 GEO directionepoch
505 TOPO directionepochposition
506 GALACTOdirection
508 {em Doppler}
510 RADIO
511 OPTICAL
512 Z
513 RATIO
514 RELATIVISTIC
515 BETA
516 GAMMA
518 {em Frequency}
520 REST directionradialvelocity
521 LSRK direction
522 LSRD direction
523 BARY direction
524 GEO directionepoch
525 TOPO directionepochposition
526 GALACTO
527 """
528 return self._swigobj.doframe(v)
530 def framenow(self):
531 """framenow will fill the active frame time with the current date and time.
532 The different frame values necessary are described in the
533 doframe function
534 """
535 return self._swigobj.framenow()
537 def showframe(self):
538 """showframe will display the currently active reference frame values on the
539 terminal. The
540 different frame values necessary are described in the
541 doframe function.
542 The frame is
543 displayed on the terminal using the formatting as done for the
544 show function.
545 """
546 return self._swigobj.showframe()
548 def toradialvelocity(self, rf, v0):
549 """toradialvelocity will convert a Doppler type value (e.g. in radio mode) to a
550 real radialvelocity. The type of velocity (e.g. LSRK) should be specified
551 """
552 return self._swigobj.toradialvelocity(rf, v0)
554 def tofrequency(self, rf, v0, rfq):
555 """tofrequency will convert a Doppler type value (e.g. in radio mode) to a
556 frequency. The type of frequency (e.g. LSRK) and a rest frequency (either as a
557 frequency quantity (e.g. qa.constants('HI')) or a frequency measure (e.g.
558 me.frequency('rest','5100MHz')) should be specified
559 """
560 return self._swigobj.tofrequency(rf, v0, rfq)
562 def todoppler(self, rf, v0, rfq=[ ]):
563 """todoppler will convert a radialvelocity measure or a frequency measure to a
564 doppler measure. In the case of a frequency, a rest frequency has to be
565 specified. The type of doppler wanted (e.g. RADIO) has to be specified.
566 """
567 return self._swigobj.todoppler(rf, v0, rfq)
569 def torestfrequency(self, v0, d0):
570 """torestfrequency will convert a frequency measure and a doppler measure
571 (e.g. obtained from another spectral line with a known rest frequency) to a
572 rest frequency.
573 """
574 return self._swigobj.torestfrequency(v0, d0)
576 def rise(self, crd=[ ], ev=[ ]):
577 """rise will give the rise/set hour-angles of a source. It needs the position
578 in the frame, and a time. If the latter is not set, the current time will be
579 used.
580 """
581 return self._swigobj.rise(crd, ev)
583 def riseset(self, crd=[ ], ev=[ ]):
584 """rise will give the rise/set times of a source. It needs the position
585 in the frame, and a time. If the latter is not set, the current time will be
586 used. The returned value is a record with a 'solved' field, which is F if the
587 source is always below or above the horizon. In that case the rise and set
588 fields will all have a string value. The record also returns a rise and set
589 record, with 'last' and 'utc' fields showing the rise and set times as epochs.
590 """
591 return self._swigobj.riseset(crd, ev)
593 def posangle(self, m1, m2):
594 """posangle will give the position angle from a direction to another. I.e. the
595 angle in a direction between the direction to the North pole and the other
596 direction.
597 The posiation angle is calculated in the frame of the first argument. m2 is thus converted to the frame of m1 before calculating the position angle.
598 """
599 return self._swigobj.posangle(m1, m2)
601 def separation(self, m1, m2):
602 """separation will give the separation of a direction from another as an angle.
603 """
604 return self._swigobj.separation(m1, m2)
606 def addxvalue(self, a):
607 """addxvalue will give some additional information about some measures as a vector
608 of quantities. It is used internally to get the rectangular coordinates of
609 measures that are normally given in angles. The casual user will probably in
610 general not interested in this function.
611 """
612 return self._swigobj.addxvalue(a)
614 def type(self):
615 """type will return the tool name.
616 """
617 return self._swigobj.type()
619 def done(self):
620 """In general you will not want to call this method. It removes and then
621 recreates the default measures tool.
622 """
623 return self._swigobj.done()
625 def ismeasure(self, v):
626 """Checks if the operand is a correct measure
627 """
628 return self._swigobj.ismeasure(v)