Next Previous Up Contents
Next: Technical Note
Up: Algebraic Expression Syntax
Previous: Operators

### 7.7 Functions

Many functions are available for use within your expressions, covering standard mathematical and trigonometric functions, arithmetic utility functions, type conversions, and some more specialised astronomical ones. You can use them in just the way you'd expect, by using the function name (unlike column names, this is case-sensitive) followed by comma-separated arguments in brackets, so

        max(IMAG,JMAG)

will give you the larger of the values in the columns IMAG and JMAG, and so on.

The functions are grouped into the following classes:

Arithmetic
  Standard arithmetic functions including things like rounding, sign manipulation, and maximum/minimum functions. Phase folding operations, and a convenient form of the modulus operation on which they are based, are also provided.
Arrays
  Functions which operate on array-valued cells. The array parameters of these functions can only be used on values which are already arrays (usually, numeric arrays). In most cases that means on values in table columns which are declared as array-valued. FITS and VOTable tables can have columns which contain array values, but other formats such as CSV cannot.

  If you want to calculate aggregating functions like sum, min, max etc on multiple values which are not part of an array, it's easier to use the functions from the `Lists` class.

  Note that none of these functions will calculate statistical functions over a whole column of a table.

  The functions fall into a number of categories:

  - Aggregating operations, which map an array value to a scalar, including `size`, `count`, `countTrue`, `maximum`, `minimum`, `sum`, `mean`, `median`, `quantile`, `stdev`, `variance`, `join`.
  - Operations on one or more arrays which produce array results, including `add`, `subtract`, `multiply`, `divide`, `reciprocal`, `condition`, `slice`, `pick`. Mostly these work on any numeric array type and return floating point (double precision) values, but some of them (`slice`, `pick`) have variants for different array types.
  - The function `array`, which lets you assemble a floating point array value from a list of scalar numbers. There are variants (`intArray`, `stringArray`) for some different array types.
Conversions
  Functions for converting between strings and numeric values.
CoordsDegrees
  Functions for angle transformations and manipulations, with angles generally in degrees. In particular, methods for translating between degrees and HH:MM:SS.S or DDD:MM:SS.S type sexagesimal representations are provided.
CoordsRadians
  Functions for angle transformations and manipulations, based on radians rather than degrees. In particular, methods for translating between radians and HH:MM:SS.S or DDD:MM:SS.S type sexagesimal representations are provided.
Coverage
  Functions related to coverage and footprints.

  One coverage standard is Multi-Order Coverage maps, described at http://www.ivoa.net/Documents/MOC/. MOC positions are always defined in ICRS equatorial coordinates.

  MOC locations may be given as either the filename or the URL of a MOC FITS file. Alternatively, they may be the identifier of a VizieR table, for instance "`V/139/sdss9`" (SDSS DR9). A list of all the MOCs available from VizieR can currently be found at http://alasky.u-strasbg.fr/footprints/tables/vizier/. You can search for VizieR table identifiers from the VizieR web page (http://vizier.u-strasbg.fr/); note you must use the table identifier (like "`V/139/sdss9`") and not the catalogue identifier (like "`V/139`").

Distances
  Functions for converting between different measures of cosmological distance.

  The following parameters are used:

  - z: redshift
  - H0: Hubble constant in km/sec/Mpc (example value ~70)
  - omegaM: Density ratio of the universe (example value 0.3)
  - omegaLambda: Normalised cosmological constant (example value 0.7)

  For a flat universe, `omegaM`+`omegaLambda`=1

  The terms and formulae used here are taken from the paper by D.W.Hogg, Distance measures in cosmology, astro-ph/9905116 v4 (2000).

Fluxes
  Functions for conversion between flux and magnitude values. Functions are provided for conversion between flux in Janskys and AB magnitudes.

  Some constants for approximate conversions between different magnitude scales are also provided:

  - Constants `JOHNSON_AB_*`, for Johnson <-> AB magnitude conversions, from Frei and Gunn, Astronomical Journal 108, 1476 (1994), Table 2 (1994AJ....108.1476F).
  - Constants `VEGA_AB_*`, for Vega <-> AB magnitude conversions, from Blanton et al., Astronomical Journal 129, 2562 (2005), Eqs. (5) (2005AJ....129.2562B).
Formats
  Functions for formatting numeric values.
Gaia
  Functions related to astrometry suitable for use with data from the Gaia astrometry mission.

  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 vector calculation and manipulation
  - distance estimation from parallaxes
  - astrometry propagation to different epochs

  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 SP-1200 (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 non-negligable 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 Gaia-like data can be found in the papers

  - C.A.L.Bailer-Jones, "Estimating distances from parallaxes", PASP 127, p994 (2015) 2015PASP..127..994B
  - T.L.Astraatmadja and C.A.L.Bailer-Jones, "Estimating Distances from Parallaxes. II. Performance of Bayesian Distance Estimators on a Gaia-like Catalogue", ApJ 832, a137 (2016) 2016ApJ...832..137A
  - X.Luri et al., "Gaia Data Release 2: Using Gaia Parallaxes", A&A in press (2018) arXiv:1804.09376

  The functions provided here correspond to calculations from Astraatmadja & Bailer-Jones, "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 Bailer-Jones 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 direction-dependent length scale not currently available here, it pre-applies 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 six-parameter 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 SP-1200 (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 SP-1200 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.

KCorrections
  Functions for calculating K-corrections.
Lists
  Functions which operate on lists of values.

  Some of these resemble similar functions in the `Arrays` class, and in some cases are interchangeable, but these are easier to use on non-array values because you don't have to explicitly wrap up lists of arguments as an array. However, for implementation reasons, most of the functions defined here can be used on values which are already `double[]` arrays (for instance array-valued columns) rather than as comma-separated lists of floating point values.

Maths
  Standard mathematical and trigonometric functions. Trigonometric functions work with angles in radians.
Shapes
  Functions useful for working with shapes in the (X, Y) plane.
Sky
  Functions useful for working with shapes on a sphere. All angles are expressed in degrees.
Strings
  String manipulation and query functions.
Tilings
  Pixel tiling functions for the celestial sphere.

  The `k` parameter for the HEALPix functions is the HEALPix order, which can be in the range 0<=k<=29. This is the logarithm to base 2 of the HEALPix NSIDE parameter. At order `k`, there are 12*4^k pixels on the sphere.

Times
  Functions for conversion of time values between various forms. The forms used are
  Modified Julian Date (MJD)
    A continuous measure in days since midnight at the start of 17 November 1858. Based on UTC.
  ISO 8601
    A string representation of the form `yyyy-mm-ddThh:mm:ss.s`, where the `T` is a literal character (a space character may be used instead). Based on UTC.
  Julian Epoch
    A continuous measure based on a Julian year of exactly 365.25 days. For approximate purposes this resembles the fractional number of years AD represented by the date. Sometimes (but not here) represented by prefixing a 'J'; J2000.0 is defined as 2000 January 1.5 in the TT timescale.
  Besselian Epoch
    A continuous measure based on a tropical year of about 365.2422 days. For approximate purposes this resembles the fractional number of years AD represented by the date. Sometimes (but not here) represented by prefixing a 'B'.
  Decimal Year
    Fractional number of years AD represented by the date. 2000.0, or equivalently 1999.99recurring, is midnight at the start of the first of January 2000. Because of leap years, the size of a unit depends on what year it is in.

  Therefore midday on the 25th of October 2004 is `2004-10-25T12:00:00` in ISO 8601 format, 53303.5 as an MJD value, 2004.81588 as a Julian Epoch and 2004.81726 as a Besselian Epoch.

  Currently this implementation cannot be relied upon to better than a millisecond.

TrigDegrees
  Standard trigonometric functions with angles in degrees.
URLs
  Functions that construct URLs for external services. Most of the functions here just do string manipulation to build up URL strings, using knowledge of the parameters required for various services.

Full documentation of the functions in these classes is given in Appendix B.1, and is also available within TOPCAT from the Available Functions Window.

- 7.7.1 Technical Note

Next Previous Up Contents
Next: Technical Note
Up: Algebraic Expression Syntax
Previous: Operators

TOPCAT - Tool for OPerations on Catalogues And Tables
Starlink User Note253
TOPCAT web page: http://www.starlink.ac.uk/topcat/
Author email: m.b.taylor@bristol.ac.uk
Mailing list: topcat-user@jiscmail.ac.uk