public class Gaia extends Object
The methods here are not specific to the Gaia mission,
but the parameters of the functions and their units are specified
in a form that is convenient for use with Gaia data,
in particular the gaia_source
catalogue available from
http://gea.esac.esa.int/archive/
and copies or mirrors.
There are currently three main sets of functions here:
Position and velocity vectors
Functions are provided for converting the astrometric parameters contained in the Gaia catalogue to ICRS Cartesian position (XYZ) and velocity (UVW) vectors. Functions are also provided to convert these vectors between ICRS and Galactic or Ecliptic coordinates. The calculations are fairly straightforward, and follow the equations laid out in section 1.5.6 of The Hipparcos and Tycho Catalogues, ESA SP1200 (1997) and also section 3.1.7 of the Gaia DR2 documentation (2018).
These functions will often be combined; for instance to calculate the position and velocity in galactic coordinates from Gaia catalogue values, the following expressions may be useful:
xyz_gal = icrsToGal(astromXYZ(ra,dec,parallax)) uvw_gal = icrsToGal(astromUVW(array(ra,dec,parallax,pmra,pmdec,radial_velocity)))though note that these particular examples simply invert parallax to provide distance estimates, which is not generally valid. Note also that these functions do not attempt to correct for solar motion. Such adjustments should be carried out by hand on the results of these functions if they are required.
Functions for calculating errors on the Cartesian components based on the error and correlation quantities from the Gaia catalogue are not currently provided. They would require fairly complicated invocations. If there is demand they may be implemented in the future.
Distance estimation
Gaia measures parallaxes, but some scientific use cases require the radial distance instead. While distance in parsec is in principle the reciprocal of parallax in arcsec, in the presence of nonnegligable errors on measured parallax, this inversion does not give a good estimate of distance. A thorough discussion of this topic and approaches to estimating distances for Gaialike data can be found in the papers
The functions provided here correspond to calculations from Astraatmadja & BailerJones, "Estimating Distances from Parallaxes. III. Distances of Two Million Stars in the Gaia DR1 Catalogue", ApJ 833, a119 (2016) 2016ApJ...833..119A based on the Exponentially Decreasing Space Density prior defined therein. This implementation was written with reference to the Java implementation by Enrique Utrilla (DPAC).
These functions are parameterised by a length scale L
that defines the exponential decay (the mode of the prior PDF is at
r=2L).
Some value for this length scale, specified in parsec, must be supplied
to the functions as the lpc
parameter.
Note that the values provided by these functions do not match those from the paper BailerJones et al. "Estimating Distances from Parallaxes IV: Distances to 1.33 Billion stars in Gaia Data Release 2", accepted for AJ (2018) arXiv:1804.10121. The calculations of that paper differ from the ones presented here in several ways: it uses a galactic model for the directiondependent length scale not currently available here, it preapplies a parallax correction of 0.029mas, and it uses different uncertainty measures and in some cases (bimodal PDF) a different best distance estimator.
Epoch Propagation
The Gaia source catalogue provides, for at least some sources, the sixparameter astrometric solution (Right Ascension, Declination, Parallax, Proper motion in RA and Dec, and Radial Velocity), along with errors on these values and correlations between these errors. While a crude estimate of the position at an earlier or later epoch than that of the measurement can be made by multiplying the proper motion components by epoch difference and adding to the measured position, a more careful treatment is required for accurate propagation between epochs of the astrometric parameters, and if required their errors and correlations. The expressions for this are set out in section 1.5.5 (Volume 1) of The Hipparcos and Tycho Catalogues, ESA SP1200 (1997) (but see below), and the code is based on an implementation by Alexey Butkevich and Daniel Michalik (DPAC). A correction is applied to the SP1200 treatment of radial velocity uncertainty following Michalik et al. 2014 2014A&A...571A..85M because of their better handling of small radial velocities or parallaxes.
The calculations give the same results, though not exactly in the same form, as the epoch propagation functions available in the Gaia archive service.
Modifier and Type  Field and Description 

static double 
AU_YRKMS
This quantity is A_v, the Astronomical Unit expressed in km.yr/sec.

static double 
C_KMS
The speed of light in km/s (exact).

static double 
PC_AU
Parsec in Astronomical Units, equal to 648000/PI.

static double 
PC_YRKMS
Parsec in units of km.yr/sec.

Modifier and Type  Method and Description 

static double[] 
astromUVW(double[] astrom6)
Calculates Cartesian components of velocity from quantities available
in the Gaia source catalogue.

static double[] 
astromUVW(double ra,
double dec,
double pmra,
double pmdec,
double radial_velocity,
double r_parsec,
boolean useDoppler)
Calculates Cartesian components of velocity from the observed
position and proper motion, radial velocity and radial distance,
with optional lighttime correction.

static double[] 
astromXYZ(double ra,
double dec,
double parallax)
Calculates Cartesian components of position from RA, Declination and
parallax.

static double[] 
distanceBoundsEdsd(double plxMas,
double plxErrorMas,
double lPc)
Calculates the 5th and 95th percentile confidence intervals
on the distance estimate using the Exponentially Decreasing
Space Density prior.

static double 
distanceEstimateEdsd(double plxMas,
double plxErrorMas,
double lPc)
Best estimate of distance using the Exponentially Decreasing
Space Density prior.

static double[] 
distanceQuantilesEdsd(double plxMas,
double plxErrorMas,
double lPc,
double... qpoints)
Calculates arbitrary quantiles for the distance estimate
using the Exponentially Decreasing Space Density prior.

static double 
distanceToModulus(double distPc)
Converts a distance in parsec to a distance modulus.

static double[] 
eclToIcrs(double[] xyz)
Converts a 3element vector representing ecliptic coordinates to
ICRS (equatorial) coordinates.

static double[] 
epochProp(double tYr,
double[] astrom6)
Propagates the astrometry parameters, supplied as a 6element array,
to a different epoch.

static double[] 
epochPropErr(double tYr,
double[] astrom22)
Propagates the astrometry parameters and their associated errors
and correlations, supplied as a 22element array,
to a different epoch.

static double[] 
galToIcrs(double[] xyz)
Converts a 3element vector representing galactic coordinates to
ICRS (equatorial) coordinates.

static double[] 
icrsToEcl(double[] xyz)
Converts a 3element vector representing ICRS (equatorial) coordinates
to ecliptic coordinates.

static double[] 
icrsToGal(double[] xyz)
Converts a 3element vector representing ICRS (equatorial) coordinates
to galactic coordinates.

static double 
modulusToDistance(double distmod)
Converts a distance modulus to a distance in parsec.

static double[] 
polarXYZ(double phi,
double theta,
double r)
Converts from spherical polar to Cartesian coordinates.

static double 
rvKmsToMasyr(double rvKms,
double plxMas)
Converts from unnormalised radial velocity in km/s to
normalised radial velocity in mas/year.

static double 
rvMasyrToKms(double rvMasyr,
double plxMas)
Converts from normalised radial velocity in mas/year to
unnormalised radial velocity in km/s.

public static final double AU_YRKMS
public static final double PC_AU
public static final double PC_YRKMS
public static final double C_KMS
public static double[] polarXYZ(double phi, double theta, double r)
phi
 longitude in degreestheta
 latitude in degreesr
 radial distancepublic static double[] astromXYZ(double ra, double dec, double parallax)
polarXYZ(ra, dec, 1000./parallax)
Note that this performs distance scaling using a simple inversion of parallax, which is not in general reliable for parallaxes with nonnegligable errors. Use at your own risk.
ra
 Right Ascension in degreesdec
 Declination in degreesparallax
 parallax in maspublic static double[] icrsToGal(double[] xyz)
The input vector is multiplied by the matrix A_{G}', given in Eq. 3.61 of the Gaia DR2 documentation, following Eq. 1.5.13 of the Hipparcos catalogue.
The output coordinate system is righthanded, with the three components positive in the directions of the Galactic center, Galactic rotation, and the North Galactic Pole respectively.
xyz
 3element vector giving ICRS Cartesian componentspublic static double[] galToIcrs(double[] xyz)
The input vector is multiplied by the matrix A_{G}, given in Eq. 3.61 of the Gaia DR2 documentation, following Eq. 1.5.13 of the Hipparcos catalogue.
The input coordinate system is righthanded, with the three components positive in the directions of the Galactic center, Galactic rotation, and the North Galactic Pole respectively.
xyz
 3element vector giving Galactic Cartesian componentspublic static double[] icrsToEcl(double[] xyz)
The transformation corresponds to that between the coordinates
(ra,dec)
and (ecl_lon,ecl_lat)
in the
Gaia source catalogue (DR2).
xyz
 3element vector giving ICRS Cartesian componentspublic static double[] eclToIcrs(double[] xyz)
The transformation corresponds to that between the coordinates
(ecl_lon,ecl_lat)
and (ra,dec)
in the
Gaia source catalogue (DR2).
xyz
 3element vector giving ecliptic Cartesian coordinatespublic static double[] astromUVW(double[] astrom6)
The input astrometry parameters are represented by a 6element array, with the following elements:
index gaia_source name unit description     0: ra deg right ascension 1: dec deg declination 2: parallax mas parallax 3: pmra mas/yr proper motion in ra * cos(dec) 4: pmdec mas/yr proper motion in dec 5: radial_velocity km/s barycentric radial velocityThe units used by this function are the units used in the
gaia_source
table.
This convenience function just invokes the 7argument
astromUVW
function
using the inverted parallax for the radial distance,
and without invoking the Doppler correction.
It is exactly equivalent to:
astromUVW(a[0], a[1], a[3], a[4], a[5], 1000./a[2], false)Note this naive inversion of parallax to estimate distance is not in general reliable for parallaxes with nonnegligable errors.
astrom6
 vector of 6 astrometric parameters
as provided by the Gaia source cataloguepublic static double[] astromUVW(double ra, double dec, double pmra, double pmdec, double radial_velocity, double r_parsec, boolean useDoppler)
The radial distance must be supplied using the r_parsec
parameter. A naive estimate from quantities in the Gaia
source catalogue may be made with the expression
1000./parallax
,
though note that this simple inversion of parallax
is not in general reliable for parallaxes with nonnegligable errors.
The calculations are fairly straightforward,
following Eq. 1.5.74 from the Hipparcos catalogue.
A (usually small) Doppler factor accounting for lighttime effects
can also optionally be applied. The effect of this is to multiply
the returned vector by a factor of 1/(1radial_velocity/c)
,
as discussed in Eq. 1.2.21 of the Hipparcos catalogue.
Note that no attempt is made to adjust for solar motion.
ra
 Right Ascension in degreesdec
 Declination in degreespmra
 proper motion in RA * cos(dec) in mas/yrpmdec
 proper motion in declination in mas/yrradial_velocity
 radial velocity in km/sr_parsec
 radial distance in parsecuseDoppler
 whether to apply the Doppler factor to account
for lighttime effectspublic static double[] epochProp(double tYr, double[] astrom6)
The input and output astrometry parameters are each represented by a 6element array, with the following elements:
index gaia_source name unit description     0: ra deg right ascension 1: dec deg declination 2: parallax mas parallax 3: pmra mas/yr proper motion in ra * cos(dec) 4: pmdec mas/yr proper motion in dec 5: radial_velocity km/s barycentric radial velocityThe units used by this function are the units used in the
gaia_source
table.tYr
 epoch difference in yearsastrom6
 astrometry at time t0,
represented by a 6element array as above
(a 5element array is also permitted where
radial velocity is zero or unknown)t0+tYr
,
represented by a 6element array as abovepublic static double[] epochPropErr(double tYr, double[] astrom22)
The input and output astrometry parameters with associated error and correlation information are each represented by a 22element array, with the following elements:
index gaia_source name unit description     0: ra deg right ascension 1: dec deg declination 2: parallax mas parallax 3: pmra mas/yr proper motion in RA * cos(dec) 4: pmdec mas/yr proper motion in Declination 5: radial_velocity km/s barycentric radial velocity 6: ra_error mas error in right ascension 7: dec_error mas error in declination 8: parallax_error mas error in parallax 9: pmra_error mas/yr error in RA proper motion * cos(dec) 10: pmdec_error mas/yr error in Declination proper motion 11: radial_velocity_error km/s error in barycentric radial velocity 12: ra_dec_corr correlation between ra and dec 13: ra_parallax_corr correlation between ra and parallax 14: ra_pmra_corr correlation between ra and pmra 15: ra_pmdec_corr correlation between ra and pmdec 16: dec_parallax_corr correlation between dec and parallax 17: dec_pmra_corr correlation between dec and pmra 18: dec_pmdec_corr correlation between dec and pmdec 19: parallax_pmra_corr correlation between parallax and pmra 20: parallax_pmdec_corr correlation between parallax and pmdec 21: pmra_pmdec_corr correlation between pmra and pmdecNote the correlation coefficients, always in the range 1..1, are dimensionless.
This is clearly an unwieldy function to invoke, but if you are using it with the gaia_source catalogue itself, or other similar catalogues with the same column names and units, you can invoke it by just copying and pasting the example shown in this documentation.
This transformation is only applicable for radial velocities determined independently of the astrometry, such as those obtained with a spectrometer. It is not applicable for the backtransformation of data already propagated to another epoch.
tYr
 epoch difference in yearsastrom22
 astrometry at time t0,
represented by a 22element array as abovepublic static double rvMasyrToKms(double rvMasyr, double plxMas)
The output is calculated as
AU_YRKMS * rvMasyr / plxMas
,
where AU_YRKMS=4.740470446
is one Astronomical Unit in km.yr/sec.
rvMasyr
 normalised radial velocity, in mas/yearplxMas
 parallax in maspublic static double rvKmsToMasyr(double rvKms, double plxMas)
The output is calculated as
rvKms * plxMas / AU_YRKMS
,
where AU_YRKMS=4.740470446
is one Astronomical Unit in km.yr/sec.
rvKms
 unnormalised radial velocity, in mas/yearplxMas
 parallax in maspublic static double distanceEstimateEdsd(double plxMas, double plxErrorMas, double lPc)
plxMas
 parallax in masplxErrorMas
 parallax error in maslPc
 length scale in parsecpublic static double[] distanceBoundsEdsd(double plxMas, double plxErrorMas, double lPc)
Note this function has to numerically integrate the PDF to determine quantile values, so it is relatively slow.
plxMas
 parallax in masplxErrorMas
 parallax error in maslPc
 length scale in parsecpublic static double[] distanceQuantilesEdsd(double plxMas, double plxErrorMas, double lPc, double... qpoints)
Note this function has to numerically integrate the PDF to determine quantile values, so it is relatively slow.
plxMas
 parallax in masplxErrorMas
 parallax error in maslPc
 length scale in parsecqpoints
 one or more required quantile cut points,
each in the range 0..1qpoints
giving the corresponding distance in parsecpublic static double distanceToModulus(double distPc)
5*log10(distPc)5
.distPc
 distance in parsecpublic static double modulusToDistance(double distmod)
10^(1+distmod/5)
.distmod
 distance modulus in magnitudesCopyright © 2024 Central Laboratory of the Research Councils. All Rights Reserved.