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

### 7.6 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:

Tilings
  Pixel tiling functions for the celestial sphere.
Arithmetic
  Standard arithmetic functions including things like rounding, sign manipulation, and maximum/minimum functions.
Conversions
  Functions for converting between strings and numeric values.
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).

KCorrections
  Functions for calculating K-corrections.
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.
Maths
  Standard mathematical and trigonometric functions. Trigonometric functions work with angles in radians.
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.

  The functions fall into a number of categories:

  - Aggregating operations, which map an array value to a scalar, including `size`, `count`, `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`.
  - A set of functions named `array` with various numbers of arguments, which let you assemble an array value from a list of scalar numbers. This can be used for instance to get the mean of a set of three magnitudes by using an expression like "`mean(array(jmag, hmag, kmag))`".
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).
Strings
  String manipulation and query functions.
Formats
  Functions for formatting numeric values.
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`").

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.

A listing of the functions in these classes is given in Appendix B.1, and complete documentation on them is available within TOPCAT from the Available Functions Window.

- 7.6.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@bristol.ac.uk