Measures (reference frames)

measinfo(t, col) -> Union{Nothing,MeasInfo}

Parse the MEASINFO keyword of column col. nothing if the column carries no measure information.

MeasInfo

The parsed MEASINFO (+ QuantumUnits) of a measure-valued column. fixedref xor varrefcol is set.

measure(t, col, row; epoch=nothing) -> Measure | Vector{Measure}
measure(t, col)                      -> Vector

Read column col of t as a physical measure, taking its reference frame from the MEASINFO keyword (a fixed Ref, or a per-row VarRefCol code). An epoch column yields MEpoch (MJD days), a direction column MDirection (radians), a position column MPosition (metres), a frequency column MFrequency (Hz) – an array-valued frequency/direction cell yields a Vector of them.

Passing epoch (an MEpoch) to a direction cell of a FIELD subtable evaluates a moving target: if that field row is a comet / planet (field_ephemeris finds one), the returned direction is the ephemeris position at epoch (in the ephemeris table's own posrefsys frame), shifted by the stored PHASE_DIR offset.

measconvert(m::Measure, R::Type{<:RefFrame}; frame=MeasFrame()) -> Measure

Convert measure m to reference frame R. Needs SOFA.jl loaded (import SOFA); import EarthOrientation as well for full ΔUT1 / polar-motion accuracy (otherwise ~1 arcsecond, with a one-time warning). frame supplies whatever auxiliary epoch / position / source direction the target frame requires – see MeasFrame.

measconvert(d::MDoppler{C}, C2::Type{<:DopplerType}) -> MDoppler{C2}

Re-express a Doppler shift in another convention.

observatory(name) -> MPosition{ITRF} | nothing

The ITRF position of a known telescope ("VLA", "ALMA", "ATCA", "GBT", "WSRT", "GMRT", …), matched case-insensitively. nothing if the name is not in the bundled table.

MeasFrame(; epoch, position, direction)

The auxiliary information a reference-frame conversion needs: an MEpoch (for APP, AZEL, any velocity frame), an MPosition (for AZEL/HADEC, TOPO), and an MDirection source direction (for every frequency / radial-velocity conversion). Fields are set as needed and may be left nothing.

MEpoch{R}(mjd)

An instant of time as a Modified Julian Date (days) in time scale R (UTC/TAI/TT/TDB/UT1).

MDirection{R}(lon, lat)

A direction on the sky, longitude/latitude in radians, in frame R (J2000/ICRS/B1950/APP/GALACTIC/ECLIPTIC/AZEL/AZELGEO/HADEC).

MPosition{R}(x, y, z)

A location, geocentric Cartesian metres, in frame R (ITRF/WGS84).

Note this differs from real casacore's own MPosition::WGS84, which represents a geodetic (longitude, latitude, height) position — here WGS84 is only a frame label, and measconvert between ITRF/WGS84 is an identity on (x,y,z) (no real MS POSITION column ever uses MEASINFO Ref="WGS84"). For the real geodetic ↔ Cartesian ellipsoidal transform, use _geodetic_to_itrf/_itrf_to_geodetic (internal — exposed to TaQL-lite as meas.wgs()/meas.itrfxyz()).

MFrequency{R}(hz)

A frequency in hertz, referenced to velocity frame R (TOPO/GEO/BARY/LSRK/LSRD/GALACTO/REST).

MRadialVelocity{R}(mps)

A radial velocity in m/s, referenced to velocity frame R (LSRK/LSRD/BARY/GEO/TOPO/GALACTO). measconvert converts between these frames (needs import SOFA and frame.direction).

MDoppler{C}(d)

A Doppler shift as a dimensionless value in convention C (RADIO / OPTICAL / RATIO / BETA / GAMMA). measconvert(d, C2) changes convention; doppler / frequency / radialvelocity / restfrequency bridge to the other spectral measures (a rest frequency is needed where one is).

MBaseline{R}(x, y, z)

A baseline vector (antenna → antenna) in metres, in direction frame R (ITRF / J2000 / APP / AZEL / HADEC / GALACTIC / …). measconvert rotates it between frames (needs import SOFA), preserving its length — equivalent to converting the unit direction and rescaling.

MuvW{R}(u, v, w)

A uvw baseline coordinate in metres, in direction frame R — the UVW column of an MS. Differs from an MBaseline by the rotation onto the frame whose w-axis points at the phase centre, so measconvert also needs frame.direction (the phase centre).

MEarthMagnetic{R}(x, y, z)

The Earth's magnetic field as a 3-vector in nano-tesla, in direction frame R. MEarthMagnetic{IGRF} is a model frame: measconvert(MEarthMagnetic{IGRF}(...), R; frame) evaluates the IGRF-14 field at frame.position / frame.epoch and rotates it to R. See earthfield.

earthfield(pos::MPosition, epoch::MEpoch) -> MEarthMagnetic{ITRF}

The IGRF-14 geomagnetic field vector (nano-tesla, ITRF Cartesian) at pos and epoch. Model accuracy is ~arcminute-of-arc in direction / ~150 nT; the epoch is used as given (the ~1 minute UTC/TDB difference is negligible for the 5-year-interpolated model).

EarthMagneticMachine(height, pos::MPosition, epoch::MEpoch)

A reusable emm_lineofsight evaluator for one shell height, observer and epoch — call it on a direction: machine(dir).

emm_lineofsight(dir::MDirection, height, pos::MPosition, epoch::MEpoch)
    -> (; losfield, field, subpoint, sublon, sublat)

The geomagnetic field along the line of sight to dir, sampled where the ray from pos crosses a sphere height metres above the observer's geocentric radius (e.g. height = 350e3 for the ionospheric F-layer):

• losfield — the field component parallel to the line of sight (nT); multiply by the slant TEC and 2.63e-13 for the RM.
• field — the full field vector at the pierce point, MEarthMagnetic{ITRF}.
• subpoint — the pierce point, MPosition{ITRF}.
• sublon / sublat — its geocentric longitude / latitude (rad).

dir may be in any direction frame; it is rotated to ITRF using epoch + pos. Needs import SOFA.

rotation_measure(dir, epoch, pos; stec, height=350e3) -> Float64
rotation_measure(m::EarthMagneticMachine, dir; stec)  -> Float64

The ionospheric rotation measure (rad/m²) toward dir, in the thin-shell approximation: RM_IONOSPHERE · stec · B∥, with B∥ the geomagnetic field component along the direction of propagation (source → observer) where the line of sight pierces a shell height m up (emm_lineofsight), and stec the slant total electron content in TECU (10¹⁶ e⁻/m²). Positive RM ⇔ the field points toward the observer. Needs import SOFA.

faraday_rotation(rm, freq) -> Δχ   (rad)

The polarization-angle rotation RM · λ² at frequency freq (Hz — a number or MFrequency). λ = c / freq.

derotate_angle(χ, rm, freq) -> χ − RM·λ²

Remove the Faraday rotation from an observed polarization angle χ (rad).

Ionospheric rotation-measure constant (SI collapsed to practical units): RM [rad/m²] = RM_IONOSPHERE · STEC[TECU] · B∥[nT], where RM_IONOSPHERE = e³/(8π²ε₀mₑ²c³) · 10¹⁶ · 10⁻⁹ ≈ 2.631e-6.

Ephemeris

An opened solar-system ephemeris table (casacore MeasComet format). Construct with open_ephemeris or get one for a moving-target field with field_ephemeris; evaluate with ephemeris_direction / ephemeris_radvel / ephemeris_distance.

open_ephemeris(path) -> Ephemeris

Open a casacore ephemeris (MeasComet) table at path.

field_ephemeris(fld::Table, field_id) -> Ephemeris | nothing

If FIELD row field_id (0-based) is a moving target — a non-negative EPHEMERIS_ID with a matching EPHEM<id>_*.tab in the FIELD subtable directory — return its opened Ephemeris, else nothing.

ephemeris_direction(e::Ephemeris, mjd) -> MDirection

The target direction at mjd (MJD, ideally TDB — a coarsely sampled table makes the UTC↔TDB difference negligible), in the table's own posrefsys frame. Linearly interpolates the Cartesian (ρ, RA, Dec) vector between the two bracketing rows.

ephemeris_radvel(e::Ephemeris, mjd) -> Float64

The target radial velocity at mjd, m/s (linear interpolation of the RadVel column, AU/d → m/s).

ephemeris_distance(e::Ephemeris, mjd) -> Float64

The geocentric distance to the target at mjd, metres.

ephemeris_diskpos(e::Ephemeris, mjd) -> (lon, lat)

The sub-observer point on the target body's surface at mjd — the DiskLong / DiskLat ephemeris columns (rad), great-circle interpolated between the bracketing rows (casacore MeasComet::getDisk). Errors if the table has no DiskLong / DiskLat columns.

doppler(f::MFrequency, restfreq) -> MDoppler{BETA}
doppler(v::MRadialVelocity)      -> MDoppler{BETA}

The Doppler shift of f relative to restfreq (a frequency in Hz or an MFrequency), or of a radial velocity (β = v/c). Result in the BETA (true v/c) convention – measconvert it to RADIO / OPTICAL / etc. as needed.

frequency(d::MDoppler, restfreq)         -> MFrequency{LSRK}
frequency(v::MRadialVelocity, restfreq)  -> MFrequency{LSRK}

The frequency √((1−β)/(1+β)) · ν₀ implied by a Doppler shift (casacore fromDoppler) or a radial velocity v and a line rest frequency restfreq. The result frame defaults to LSRK.

radialvelocity(d::MDoppler)              -> MRadialVelocity{LSRK}
radialvelocity(f::MFrequency, restfreq)  -> MRadialVelocity{LSRK}

The true radial velocity of a Doppler shift (c·β, casacore fromDoppler), or of a frequency f relative to restfreq (= radialvelocity(doppler(f, restfreq))). The two-argument form broadcasts — radialvelocity.(measure(spw, "CHAN_FREQ"), ν₀) is a velocity axis. The result frame defaults to LSRK.

restfrequency(f::MFrequency, d::MDoppler) -> MFrequency{REST}

The rest frequency ν / √((1−β)/(1+β)) given an observed frequency and its Doppler shift (casacore toRest).

shiftfreq(d::MDoppler, ν) -> same shape as ν

Multiply frequency(ies) ν by the Doppler factor √((1−β)/(1+β)) (β from d in the BETA convention) — the vectorised form of casacore MDoppler::shiftFrequency. ν is a frequency in Hz, an MFrequency (the frame label is kept), or a vector of either (the factor is computed once).

Unlike casacore, a non-BETA d is converted to BETA first.

reftype(m::Measure) -> Type{<:RefFrame}

The reference-frame type parameter of a measure value (reftype(MEpoch{UTC}(0)) === UTC).

RefFrame

Abstract supertype of every measure reference frame. Concrete singleton subtypes, used as the type parameter of a measure value (MEpoch{UTC}, MDirection{J2000}) and as the target of measconvert:

An unrecognised casacore frame name is carried as OtherRef{:Name} (parsed, not convertible).

A Doppler-shift convention (RADIO / OPTICAL / RATIO / BETA / GAMMA).

Coordinated Universal Time (epoch scale).

International Atomic Time (epoch scale).

Terrestrial Time (epoch scale).

Barycentric Dynamical Time (epoch scale).

Universal Time UT1 (epoch scale; needs ΔUT1).

Mean equator and equinox of J2000.0 (direction; treated as ICRS).

International Celestial Reference System (direction).

FK4 B1950.0 (direction).

Geocentric apparent place, equinox of date (direction).

Galactic coordinates (direction).

Supergalactic coordinates (direction; a fixed rotation of GALACTIC).

J2000 ecliptic coordinates (direction).

Topocentric hour angle / declination (direction).

Azimuth / elevation about the geocentric vertical, N=0 E=90 (direction).

Azimuth / elevation about the geodetic vertical (direction).

Azimuth / elevation about the geocentric vertical, S=0 W=90 – azimuth = AZEL's azimuth + 180° (direction).

Azimuth / elevation about the geodetic vertical, S=0 W=90 – azimuth = AZELGEO's azimuth + 180° (direction).

International Terrestrial Reference Frame (position / direction).

WGS84 geodetic datum (position).

Topocentric (frequency / direction).

Source rest frame (frequency).

Kinematic Local Standard of Rest (frequency / radial velocity).

Dynamical Local Standard of Rest (frequency / radial velocity).

Solar-system barycentre (frequency / radial velocity).

Geocentric (frequency / radial velocity).

Galactocentric (frequency / radial velocity).

Local Group barycentre, ~308 km/s (frequency / radial velocity).

Cosmic microwave background rest frame, ~369.5 km/s (frequency / radial velocity).

The planet Mercury as a direction (geocentric apparent place).

The planet Venus as a direction (geocentric apparent place).

The planet Mars as a direction (geocentric apparent place).

The planet Jupiter as a direction (geocentric apparent place).

The planet Saturn as a direction (geocentric apparent place).

The planet Uranus as a direction (geocentric apparent place).

The planet Neptune as a direction (geocentric apparent place).

The Sun as a direction (geocentric apparent place).

The Moon as a direction (geocentric apparent place; topocentric when frame.position is set).

IGRF-14 geomagnetic field model as an MEarthMagnetic source frame — measconvert(MEarthMagnetic{IGRF}(...), ITRF; frame) evaluates the field at frame.position and frame.epoch.

Radio velocity cΔν/ν₀ (D = 1 − ν/ν₀).

Optical velocity / redshift z = cΔλ/λ₀ (D = ν₀/ν − 1).

The frequency ratio ν/ν₀ itself.

True relativistic velocity v/c (D = (1−F²)/(1+F²), F = ν/ν₀).

The Lorentz factor γ (D = (1+F²)/(2F)).

Alias for OPTICAL — casacore's Z (redshift) spelling.

Alias for BETA — casacore's RELATIVISTIC spelling.