# 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.

`roundUp( x )`

  Rounds a value up to an integer value. Formally, returns the smallest (closest to negative infinity) integer value that is not less than the argument.

  - Parameters:
    - `x` (floating point): a value.
  - Return value
    - (integer): `x` rounded up
`roundDown( x )`

  Rounds a value down to an integer value. Formally, returns the largest (closest to positive infinity) integer value that is not greater than the argument.

  - Parameters:
    - `x` (floating point): a value
  - Return value
    - (integer): `x` rounded down
`round( x )`

  Rounds a value to the nearest integer. Formally, returns the integer that is closest in value to the argument. If two integers are equally close, the result is the even one.

  - Parameters:
    - `x` (floating point): a floating point value.
  - Return value
    - (integer): `x` rounded to the nearest integer
`roundDecimal( x, dp )`

  Rounds a value to a given number of decimal places. The result is a `float` (32-bit floating point value), so this is only suitable for relatively low-precision values. It's intended for truncating the number of apparent significant figures represented by a value which you know has been obtained by combining other values of limited precision. For more control, see the functions in the `Formats` class.

  - Parameters:
    - `x` (floating point): a floating point value
    - `dp` (integer): number of decimal places (digits after the decimal point) to retain
  - Return value
    - (floating point): floating point value close to `x` but with a limited apparent precision
  - Example:
    - `roundDecimal(PI,2) = 3.14f`
`abs( x )`

  Returns the absolute value of an integer value. If the argument is not negative, the argument is returned. If the argument is negative, the negation of the argument is returned.

  - Parameters:
    - `x` (integer): the argument whose absolute value is to be determined
  - Return value
    - (integer): the absolute value of the argument.
`abs( x )`

  Returns the absolute value of a floating point value. If the argument is not negative, the argument is returned. If the argument is negative, the negation of the argument is returned.

  - Parameters:
    - `x` (floating point): the argument whose absolute value is to be determined
  - Return value
    - (floating point): the absolute value of the argument.
`max( a, b )`

  Returns the greater of two integer values. If the arguments have the same value, the result is that same value.

  Multiple-argument maximum functions are also provided in the `Arrays` and `Lists` packages.

  - Parameters:
    - `a` (integer): an argument.
    - `b` (integer): another argument.
  - Return value
    - (integer): the larger of `a` and `b`.
`maxNaN( a, b )`

  Returns the greater of two floating point values. If the arguments have the same value, the result is that same value. If either value is blank, then the result is blank.

  - Parameters:
    - `a` (floating point): an argument.
    - `b` (floating point): another argument.
  - Return value
    - (floating point): the larger of `a` and `b`.
`maxReal( a, b )`

  Returns the greater of two floating point values, ignoring blanks. If the arguments have the same value, the result is that same value. If one argument is blank, the result is the other one. If both arguments are blank, the result is blank.

  Multiple-argument maximum functions are also provided in the `Arrays` and `Lists` packages.

  - Parameters:
    - `a` (floating point): an argument
    - `b` (floating point): another argument
  - Return value
    - (floating point): the larger non-blank value of `a` and `b`
`min( a, b )`

  Returns the smaller of two integer values. If the arguments have the same value, the result is that same value.

  Multiple-argument minimum functions are also provided in the `Arrays` and `Lists` packages.

  - Parameters:
    - `a` (integer): an argument.
    - `b` (integer): another argument.
  - Return value
    - (integer): the smaller of `a` and `b`.
`minNaN( a, b )`

  Returns the smaller of two floating point values. If the arguments have the same value, the result is that same value. If either value is blank, then the result is blank.

  - Parameters:
    - `a` (floating point): an argument.
    - `b` (floating point): another argument.
  - Return value
    - (floating point): the smaller of `a` and `b`.
`minReal( a, b )`

  Returns the smaller of two floating point values, ignoring blanks. If the arguments have the same value, the result is that same value. If one argument is blank, the result is the other one. If both arguments are blank, the result is blank.

  Multiple-argument minimum functions are also provided in the `Arrays` and `Lists` packages.

  - Parameters:
    - `a` (floating point): an argument
    - `b` (floating point): another argument
  - Return value
    - (floating point): the larger non-blank value of `a` and `b`
`mod( a, b )`

  Returns the non-negative remainder of `a/b`. This is a modulo operation, but differs from the expression `a%b` in that the answer is always >=0 (as long as `b` is not zero).

  - Parameters:
    - `a` (floating point): dividend
    - `b` (floating point): divisor
  - Return value
    - (floating point): non-negative remainder when dividing `a` by `b`
  - Examples:
    - `modulo(14, 5) = 4`
    - `modulo(-14, 5) = 1`
    - `modulo(2.75, 0.5) = 0.25`
`phase( t, period )`

  Returns the phase of a value within a period.

  For positive period, the returned value is in the range [0,1).

  - Parameters:
    - `t` (floating point): value
    - `period` (floating point): folding period
  - Return value
    - (floating point): mod(t,period)/period
  - Examples:
    - `phase(7, 4) = 0.75`
    - `phase(-1000.5, 2.5) = 0.8`
    - `phase(-3300, 33) = 0`
`phase( t, period, t0 )`

  Returns the phase of an offset value within a period. The reference value `t0` corresponds to phase zero.

  For positive period, the returned value is in the range [0,1).

  - Parameters:
    - `t` (floating point): value
    - `period` (floating point): folding period
    - `t0` (floating point): reference value, corresponding to phase zero
  - Return value
    - (floating point): phase(t-t0, period)
  - Examples:
    - `phase(5003,100,0) = 0.03`
    - `phase(5003,100,2) = 0.01`
    - `phase(5003,100,4) = 0.99`
`phase( t, period, t0, phase0 )`

  Returns the offset phase of an offset value within a period. The reference value `t0` corresponds to integer phase value, and the phase offset `phase0` determines the starting value for the phase range.

  For positive period, the returned value is in the range [`phase0`,`phase0+1`).

  - Parameters:
    - `t` (floating point): value
    - `period` (floating point): folding period
    - `t0` (floating point): reference value, corresponding to phase zero
    - `phase0` (floating point): offset for phase
  - Return value
    - (floating point): offset phase
  - Examples:
    - `phase(23,10,1,99) = 99.2`
    - `phase(8.6125,0.2,0.0125,-0.3) = 0`
    - `phase(8.6125,0.2,0.1125,-0.7) = -0.5`

# 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.

`sum( array )`

  Returns the sum of all the non-blank elements in the array. If `array` is not a numeric array, `null` is returned.

  - Parameters:
    - `array` (Object): array of numbers
  - Return value
    - (floating point): sum of all the numeric values in `array`
`mean( array )`

  Returns the mean of all the non-blank elements in the array. If `array` is not a numeric array, `null` is returned.

  - Parameters:
    - `array` (Object): array of numbers
  - Return value
    - (floating point): mean of all the numeric values in `array`
`variance( array )`

  Returns the population variance of all the non-blank elements in the array. If `array` is not a numeric array, `null` is returned.

  - Parameters:
    - `array` (Object): array of numbers
  - Return value
    - (floating point): variance of the numeric values in `array`
`stdev( array )`

  Returns the population standard deviation of all the non-blank elements in the array. If `array` is not a numeric array, `null` is returned.

  - Parameters:
    - `array` (Object): array of numbers
  - Return value
    - (floating point): standard deviation of the numeric values in `array`
`minimum( array )`

  Returns the smallest of the non-blank elements in the array. If `array` is not a numeric array, `null` is returned.

  - Parameters:
    - `array` (Object): array of numbers
  - Return value
    - (floating point): minimum of the numeric values in `array`
`maximum( array )`

  Returns the largest of the non-blank elements in the array. If `array` is not a numeric array, `null` is returned.

  - Parameters:
    - `array` (Object): array of numbers
  - Return value
    - (floating point): maximum of the numeric values in `array`
`median( array )`

  Returns the median of the non-blank elements in the array. If `array` is not a numeric array, `null` is returned.

  - Parameters:
    - `array` (Object): array of numbers
  - Return value
    - (floating point): median of the numeric values in `array`
`quantile( array, quant )`

  Returns a quantile value of the non-blank elements in the array. Which quantile is determined by the `quant` value; values of 0, 0.5 and 1 give the minimum, median and maximum respectively. A value of 0.99 would give the 99th percentile.

  - Parameters:
    - `array` (Object): array of numbers
    - `quant` (floating point): number in the range 0-1 deterining which quantile to calculate
  - Return value
    - (floating point): quantile corresponding to `quant`
`size( array )`

  Returns the number of elements in the array. If `array` is not an array, zero is returned.

  - Parameters:
    - `array` (Object): array
  - Return value
    - (integer): size of `array`
`count( array )`

  Returns the number of non-blank elements in the array. If `array` is not an array, zero is returned.

  - Parameters:
    - `array` (Object): array (may or may not be numeric)
  - Return value
    - (integer): number of non-blank elements in `array`
`countTrue( array )`

  Returns the number of true elements in an array of boolean values.

  - Parameters:
    - `array` (array of boolean): array of true/false values
  - Return value
    - (integer): number of true values in `array`
`join( array, joiner )`

  Returns a string composed of concatenating all the elements of an array, separated by a joiner string. If `array` is not an array, null is returned.

  - Parameters:
    - `array` (Object): array of numbers or strings
    - `joiner` (String): text string to interpose between adjacent elements
  - Return value
    - (String): string composed of `array` elements separated by `joiner` strings
  - Example:
    - `join(array(1.5,2.1,-3.9), "; ") = "1.5; 2.1; -3.9"`
`dotProduct( array1, array2 )`

  Returns the dot (scalar) product of two numeric arrays. If either argument is not an array, or if the arrays are not of the same length, a blank value is returned.

  - Parameters:
    - `array1` (Object): first array
    - `array2` (Object): second array
  - Return value
    - (floating point): sum of element-wise products of input arrays
  - Example:
    - `dotProduct(array(3,4,5), array(1,2,3)) = 26`
`add( arrayOrScalar1, arrayOrScalar2 )`

  Returns the element-by-element result of adding either two numeric arrays of the same length, or an array and a scalar considered as if an array of the right length.

  If the arguments are not as expected (e.g. arrays of different lengths, both scalars, not numeric) then null is returned.

  - Parameters:
    - `arrayOrScalar1` (Object): first numeric array/scalar
    - `arrayOrScalar2` (Object): second numeric array/scalar
  - Return value
    - (array of floating point): element-by-element result of `arrayOrScalar1 + arrayOrScalar2`, the same length as the input array(s)
  - Examples:
    - `add(array(1,2,3), array(0.1,0.2,0.3)) = [1.1, 2.2, 3.3]`
    - `add(array(1,2,3), 10) = [11,12,13]`
`subtract( arrayOrScalar1, arrayOrScalar2 )`

  Returns the element-by-element result of subtracting either two numeric arrays of the same length, or an array and a scalar considered as if an array of the right length.

  If the arguments are not as expected (e.g. arrays of different lengths, both scalars, not numeric) then null is returned.

  - Parameters:
    - `arrayOrScalar1` (Object): first numeric array/scalar
    - `arrayOrScalar2` (Object): second numeric array/scalar
  - Return value
    - (array of floating point): element-by-element result of `arrayOrScalar1 - arrayOrScalar2`, the same length as the input array(s)
  - Examples:
    - `subtract(array(1,2,3), array(0.1,0.2,0.3)) = [0.9, 1.8, 2.7]`
    - `subtract(array(1,2,3), 1.0) = [0, 1, 2]`
`multiply( arrayOrScalar1, arrayOrScalar2 )`

  Returns the element-by-element result of multiplying either two numeric arrays of the same length, or an array and a scalar considered as if an array of the right length.

  If the arguments are not as expected (e.g. arrays of different lengths, both scalars, not numeric) then null is returned.

  - Parameters:
    - `arrayOrScalar1` (Object): first numeric array/scalar
    - `arrayOrScalar2` (Object): second numeric array/scalar
  - Return value
    - (array of floating point): element-by-element result of `arrayOrScalar1 * arrayOrScalar2`, the same length as the input array(s)
  - Examples:
    - `multiply(array(1,2,3), array(2,4,6)) = [2, 8, 18]`
    - `multiply(2, array(1,2,3)) = [2, 4, 6]`
`divide( arrayOrScalar1, arrayOrScalar2 )`

  Returns the element-by-element result of dividing either two numeric arrays of the same length, or an array and a scalar considered as if an array of the right length.

  If the arguments are not as expected (e.g. arrays of different lengths, both scalars, not numeric) then null is returned.

  - Parameters:
    - `arrayOrScalar1` (Object): first numeric array/scalar
    - `arrayOrScalar2` (Object): second numeric array/scalar
  - Return value
    - (array of floating point): element-by-element result of `arrayOrScalar1 / arrayOrScalar2`, the same length as the input array(s)
  - Examples:
    - `divide(array(0,9,4), array(1,3,8)) = [0, 3, 0.5]`
    - `divide(array(50,60,70), 10) = [5, 6, 7]`
`reciprocal( array )`

  Returns the result of taking the reciprocal of every element of a numeric array. If the supplied `array` argument is not a numeric array, `null` is returned.

  - Parameters:
    - `array` (Object): array input
  - Return value
    - (array of floating point): array output, the same length as the `array` parameter
  - Example:
    - `reciprocal(array(1,2,0.25) = [1, 0.5, 4]`
`condition( flagArray, trueValue, falseValue )`

  Maps a boolean array to a numeric array by using supplied numeric values to represent true and false values from the input array.

  This has the same effect as applying the expression `outArray[i] = flagArray[i] ? trueValue : falseValue`.

  - Parameters:
    - `flagArray` (array of boolean): array of boolean values
    - `trueValue` (floating point): output value corresponding to an input true value
    - `falseValue` (floating point): output value corresponding to an input false value
  - Return value
    - (array of floating point): output numeric array, same length as `flagArray`
  - Example:
    - `condition([true, false, true], 1, 0) = [1, 0, 1]`
`constant( n, value )`

  Returns a fixed-size array filled with a given constant value.

  Note: This documents the double-precision version of the routine. Corresponding routines exist for other data types (`float`, `long`, `int`, `short`, `byte`).

  - Parameters:
    - `n` (integer): size of output array
    - `value` (floating point): value of every element in the output array
  - Return value
    - (array of floating point): `n`-element array with every element set to `value`
  - Example:
    - `constant(5, 23.5) = [23.5, 23.5, 23.5, 23.5, 23.5]`
`slice( array, i0, i1 )`

  Returns a sub-sequence of values from a given array.

  The semantics are like python array slicing, though both limits have to be specified: the output array contains the sequence of elements in the input array from `i0` (inclusive) to `i1` (exclusive). If a negative value is given in either case, it is added to the length of the input array, so that -1 indicates the last element of the input array. The indices are capped at 0 and the input array length respectively, so a large positive value may be used to indicate the end of the array. If the end index is less than or equal to the start index, a zero-length array is returned.

  Note: This documents the double-precision version of the routine. Corresponding routines exist for other data types (`float`, `long`, `int`, `short`, `byte`, `String`, `Object`).

  - Parameters:
    - `array` (array of floating point): input array
    - `i0` (integer): index of first element, inclusive (may be negative to count back from the end)
    - `i1` (integer): index of the last element, exclusive (may be negative to count back from the end)
  - Return value
    - (array of floating point): array giving the sequence of elements specified by `i0` and `i1`
  - Examples:
    - `slice(array(10,11,12,13), 0, 3) = [10, 11, 12]`
    - `slice(array(10,11,12,13), -2, 999) = [12, 13]`
`pick( array, indices, ... )`

  Returns a selection of elements from a given array.

  The output array consists of one element selected from the input array for each of the supplied index values. If a negative value is supplied for an index value, it is added to the input array length, so that -1 indicates the last element of the input array. If the input array is null, null is returned. If any of the index values is out of the range of the extent of the input array, an error results.

  Note: This documents the double-precision version of the routine. Corresponding routines exist for other data types (`float`, `long`, `int`, `short`, `byte`, `String`, `Object`).

  - Parameters:
    - `array` (array of floating point): input array
    - `indices` (integer, one or more): one or more index into the input array (may be negative to count back from the end)
  - Return value
    - (array of floating point): array giving the elements specified by `indices`
  - Examples:
    - `pick(array(10,11,12,13), 0, 3) = [10, 13]`
    - `pick(array(10,11,12,13), -1, -2, -3) = [13, 12, 11]`
`arrayFunc( expr, inArray )`

  Returns a floating-point array resulting from applying a given function expression element-by-element to an input array. The output array is the same length as the input array.

  The supplied expression can use the variable "`x`" to refer to the corresponding element of the input array, and "`i`" to refer to its (zero-based) index. The various functions and operators from the expression language can all be used, but it is currently not possible to reference other table column values.

  If there is an error in the expression, a blank value (not an array) will be returned.

  - Parameters:
    - `expr` (String): expression mapping input to output array values
    - `inArray` (Object): input array
  - Return value
    - (array of floating point): floating point array with the same number of elements as `inArray`, or null for a bad `expr`
  - Examples:
    - `arrayFunc("3*x",array(0,1,2,3,NaN)) = [0, 3, 6, 9, NaN]`
    - `arrayFunc("pow(2,i)+x", array(0.5,0.5,0.5,0.5)) = [1.5, 2.5, 4.5, 8.5]`
`intArrayFunc( expr, inArray )`

  Returns an integer array resulting from applying a given function expression element-by-element to an input array. The output array is the same length as the input array.

  The supplied expression can use the variable "`x`" to refer to the corresponding element of the input array, and "`i`" to refer to its (zero-based) index. The various functions and operators from the expression language can all be used, but it is currently not possible to reference other table column values.

  If there is an error in the expression, a blank value (not an array) will be returned.

  - Parameters:
    - `expr` (String): expression mapping input to output array values
    - `inArray` (Object): input array
  - Return value
    - (array of integer): floating point array with the same number of elements as `inArray`, or null for a bad `expr`
  - Example:
    - `intArrayFunc("-x",sequence(5)) = [0, -1, -2, -3, -4]`
`indexOf( array, item )`

  Returns the position in a supplied array at which a given item appears. The result is zero-based, so if the supplied `item` is the first entry in the `array`, the return value will be zero.

  If the item does not appear in the array, -1 is returned. If it appears multiple times, the index of its first appearance is returned.

  If `indexOf(array, item)==n`, then `array[n]` is equal to `item`.

  Note: This documents the `Object` version of the routine. Corresponding routines exist for other data types (`double`, `float`, `long`, `int`, `short`).

  - Parameters:
    - `array` (array of Object): array which may contain the supplied item
    - `item` (Object): entry to look for in the array
  - Return value
    - (integer): the index of `item` in `array`, or -1
  - Examples:
    - `indexOf(stringArray("QSO", "BCG", "SNR"), "BCG") = 1`
    - `indexOf(stringArray("QSO", "BCG", "SNR"), "TLA") = -1`
`sequence( n )`

  Returns an integer array of a given length with the values 0, 1, 2, ....

  See also the `loop` functions, which provide similar functionality.

  - Parameters:
    - `n` (integer): length of array
  - Return value
    - (array of integer): `n`-element array, (0, 1, 2, ... `n`-1)
  - Example:
    - `sequence(4) = (0, 1, 2, 3)`
`sequence( n, start, step )`

  Returns a floating point array of a given length with values starting at a given value and increasing with a given increment.

  See also the `loop` functions, which provide similar functionality.

  - Parameters:
    - `n` (integer): length of array
    - `start` (floating point): value of first element
    - `step` (floating point): increment to apply to each element
  - Return value
    - (array of floating point): `n`-element array, (start, start+step, start+2*step, ... start+(n-1)*step)
  - Example:
    - `sequence(4, 100, 0.1) = (100.0, 100.1, 100.2, 100.3)`
`loop( start, end )`

  Returns an integer array like the values taken in a for-loop with given start and end elements and a step of 1. The notional loop corresponds to: for (int x = start; x < end; x++)

  If you want a floating point array, or one with a non-unit step, you can use the three-parameter version of the `loop` function. See also the `sequence` functions.

  - Parameters:
    - `start` (integer): value for first element of output array
    - `end` (integer): value one greater than last element of output array
  - Return value
    - (array of integer): array with `end-start` (or 0) elements `(start, start+1, start+2, ..., end-1)`
  - Examples:
    - `loop(0, 5) = (0, 1, 2, 3, 4)`
    - `loop(5, 0) = ()`
`loop( start, end, step )`

  Returns a floating point array like the values taken in a for-loop with given start, end, and step arguments. For a positive step, the notional loop corresponds to: for (double x = start; x < end; x += step)

  Note that numerical precision issues may result in the output array differing from its expected length by 1 (it is generally risky to rely on exact comparison of floating point values). If you want to be sure of the number of elements you can use the `sequence` function instead.

  - Parameters:
    - `start` (floating point): value for first element of output array
    - `end` (floating point): first value beyond last element of output array
    - `step` (floating point): increment between output array values; may not be zero
  - Return value
    - (array of floating point): array with approximately `(end-start)/step` (or 0) elements
  - Examples:
    - `loop(10, 12, 0.5) = (10.0, 10.5, 11.0, 11.5)`
    - `loop(0, 10, 3) = (0., 3., 6., 9.)`
    - `loop(5, 0, -1) = (5., 4., 3., 2., 1.)`
`array( values, ... )`

  Returns a floating point numeric array built from the given arguments.

  - Parameters:
    - `values` (floating point, one or more): one or more array elements
  - Return value
    - (array of floating point): array
`intArray( values, ... )`

  Returns an integer numeric array built from the given arguments.

  - Parameters:
    - `values` (integer, one or more): one or more array elements
  - Return value
    - (array of integer): array
`stringArray( values, ... )`

  Returns a String array built from the given arguments.

  - Parameters:
    - `values` (String, one or more): one or more array elements
  - Return value
    - (array of String): array

# Bits

Bit manipulation functions.

Note that for bitwise AND, OR, XOR of integer values etc you can use the java bitwise operators "`&`", "`|`", "`^`".

`hasBit( value, bitIndex )`

  Determines whether a given integer has a certain bit set to 1.

  - Parameters:
    - `value` (long integer): integer whose bits are to be tested
    - `bitIndex` (integer): index of bit to be tested in range 0..63, where 0 is the least significant bit
  - Return value
    - (boolean): true if bit is set; more or less equivalent to `(value & 1L<<bitIndex) != 0`
  - Examples:
    - `hasBit(64, 6) = true`
    - `hasBit(63, 6) = false`
`bitCount( i )`

  Returns the number of set bits in the 64-bit two's complement representation of the integer argument.

  - Parameters:
    - `i` (long integer): integer value
  - Return value
    - (integer): number of "1" bits in the binary representation of `i`
  - Examples:
    - `bitCount(64) = 1`
    - `bitCount(3) = 2`
`toBinary( value )`

  Converts the integer argument to a binary string consisting only of 1s and 0s.

  - Parameters:
    - `value` (long integer): integer value
  - Return value
    - (String): binary representation of `value`
  - Examples:
    - `toBinary(42) = "101010"`
    - `toBinary(255^7) = "11111000"`
`fromBinary( binVal )`

  Converts a string representing a binary number to its integer value.

  - Parameters:
    - `binVal` (String): binary representation of value
  - Return value
    - (integer): integer value represented by binary string `binVal`
  - Example:
    - `fromBinary("101010") = 42`

# Conversions

Functions for converting between strings and numeric values.

`toString( fpVal )`

  Turns a numeric value into a string.

  - Parameters:
    - `fpVal` (floating point): floating point numeric value
  - Return value
    - (String): a string representation of `fpVal`
`toString( intVal )`

  Turns an integer numeric value into a string.

  - Parameters:
    - `intVal` (long integer): integer numeric value
  - Return value
    - (String): a string representation of `intVal`
`toString( charVal )`

  Turns a single character value into a string.

  - Parameters:
    - `charVal` (char): character numeric value
  - Return value
    - (String): a string representation of `charVal`
`toString( byteVal )`

  Turns a byte value into a string.

  - Parameters:
    - `byteVal` (byte): byte numeric value
  - Return value
    - (String): a string representation of `byteVal`
`toString( booleanVal )`

  Turns a boolean value into a string.

  - Parameters:
    - `booleanVal` (boolean): boolean value (true or false)
  - Return value
    - (String): a string representation of `booleanVal` ("`true`" or "`false`")
`toString( objVal )`

  Turns any object value into a string. As applied to existing string values this isn't really useful, but it means that you can apply `toString` to any object value without knowing its type and get a useful return from it.

  - Parameters:
    - `objVal` (Object): non-primitive value
  - Return value
    - (String): a string representation of `objVal`
`parseByte( str )`

  Attempts to interpret a string as a byte (8-bit signed integer) value. If the input string can't be interpreted in this way, a blank value will result.

  - Parameters:
    - `str` (String): string containing numeric representation
  - Return value
    - (byte): byte value of `str`
`parseShort( str )`

  Attempts to interpret a string as a short (16-bit signed integer) value. If the input string can't be interpreted in this way, a blank value will result.

  - Parameters:
    - `str` (String): string containing numeric representation
  - Return value
    - (short integer): byte value of `str`
`parseInt( str )`

  Attempts to interpret a string as an int (32-bit signed integer) value. If the input string can't be interpreted in this way, a blank value will result.

  - Parameters:
    - `str` (String): string containing numeric representation
  - Return value
    - (integer): byte value of `str`
`parseLong( str )`

  Attempts to interpret a string as a long (64-bit signed integer) value. If the input string can't be interpreted in this way, a blank value will result.

  - Parameters:
    - `str` (String): string containing numeric representation
  - Return value
    - (long integer): byte value of `str`
`parseFloat( str )`

  Attempts to interpret a string as a float (32-bit floating point) value. If the input string can't be interpreted in this way, a blank value will result.

  - Parameters:
    - `str` (String): string containing numeric representation
  - Return value
    - (floating point): byte value of `str`
`parseDouble( str )`

  Attempts to interpret a string as a double (64-bit signed integer) value. If the input string can't be interpreted in this way, a blank value will result.

  - Parameters:
    - `str` (String): string containing numeric representation
  - Return value
    - (floating point): byte value of `str`
`parseBigInteger( str )`

  Attempts to interpret a string as a "BigInteger" value. This can be used for working with string representations of integers that can't be stored as an unsigned 64-bit value.

  The result is a `BigInteger` object, which can't be used in normal numeric expressions, but has a number of methods defined on it for comparison, arithmetic, bit manipulation etc. See the java.math.BigInteger javadocs for details.

  - Parameters:
    - `str` (String): string containing numeric representation
  - Return value
    - (BigInteger): BigInteger value of `str`
  - Examples:
    - `parseBigInteger("-20000000000000000023").doubleValue() = -2e19`
    - `parseBigInteger("18446744073709551616").testBit(64) = true`
`parseBigDecimal( str )`

  Attempts to interpret a string as a "BigDecimal" value. This can be used for working with string representations of non-integer values that require more precision or range than is possible in a 64-bit IEEE-754 double precision variable.

  The result is a `BigDecimal` object, which can't be used in normal numeric expressions, but has a number of methods defined on it for comparison, arithmetic, bit manipulation etc. See the java.math.BigDecimal javadocs for details.

  - Parameters:
    - `str` (String): string contining numeric representation
  - Return value
    - (BigDecimal): BigDecimal value of `str`
  - Example:
    - `parseBigDecimal("101").compareTo(parseBigDecimal("102")) = -1`
`parseInts( str )`

  Attempts to interpret a string as an array of integer values. An ad-hoc algorithm is used that tries to extract a list of integers from a string; a comma- or space-separated list of integer values will work, and other formats may or may not.

  The details of this function's behaviour may change in future releases.

  - Parameters:
    - `str` (String): string containing a list of integer values
  - Return value
    - (array of integer): array of integer values
  - Examples:
    - `parseInts("9 8 -23") = [9, 8, -23]`
    - `parseInts("tiddly-pom") = []`
`parseDoubles( str )`

  Attempts to interpret a string as an array of floating point values. An ad-hoc algorithm is used that tries to extract a list of numeric values from a string; a comma- or space-separated list of floating point values will work, and other formats may or may not.

  This function can be used as a hacky way to extract the numeric values from an STC-S (for instance ObsCore/EPNcore `s_region`) string.

  The details of this function's behaviour may change in future releases.

  - Parameters:
    - `str` (String): string containing a list of floating point values
  - Return value
    - (array of floating point): array of floating point values
  - Examples:
    - `parseDoubles("1.3, 99e1, NaN, -23") = [1.3, 990.0, NaN, -23.0]`
    - `parseDoubles("Polygon ICRS 0.8 2.1 9.0 2.1 6.2 8.6") = [0.8, 2.1, 9.0, 2.1, 6.2, 8.6]`
    - `parseDoubles("La la la") = []`
`toByte( value )`

  Attempts to convert the numeric argument to a byte (8-bit signed integer) result. If it is out of range, a blank value will result.

  - Parameters:
    - `value` (floating point): numeric value for conversion
  - Return value
    - (byte): `value` converted to type byte
`toShort( value )`

  Attempts to convert the numeric argument to a short (16-bit signed integer) result. If it is out of range, a blank value will result.

  - Parameters:
    - `value` (floating point): numeric value for conversion
  - Return value
    - (short integer): `value` converted to type short
`toInteger( value )`

  Attempts to convert the numeric argument to an int (32-bit signed integer) result. If it is out of range, a blank value will result.

  - Parameters:
    - `value` (floating point): numeric value for conversion
  - Return value
    - (integer): `value` converted to type int
`toLong( value )`

  Attempts to convert the numeric argument to a long (64-bit signed integer) result. If it is out of range, a blank value will result.

  - Parameters:
    - `value` (floating point): numeric value for conversion
  - Return value
    - (long integer): `value` converted to type long
`toFloat( value )`

  Attempts to convert the numeric argument to a float (32-bit floating point) result. If it is out of range, a blank value will result.

  - Parameters:
    - `value` (floating point): numeric value for conversion
  - Return value
    - (floating point): `value` converted to type float
`toDouble( value )`

  Converts the numeric argument to a double (64-bit signed integer) result.

  - Parameters:
    - `value` (floating point): numeric value for conversion
  - Return value
    - (floating point): `value` converted to type double
`toHex( value )`

  Converts the integer argument to hexadecimal form.

  - Parameters:
    - `value` (long integer): integer value
  - Return value
    - (String): hexadecimal representation of `value`
  - Example:
    - `toHex(42) = "2a"`
`fromHex( hexVal )`

  Converts a string representing a hexadecimal number to its integer value.

  - Parameters:
    - `hexVal` (String): hexadecimal representation of value
  - Return value
    - (integer): integer value represented by `hexVal`
  - Example:
    - `fromHex("2a") = 42`

# 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.

`degreesToDms( deg )`

  Converts an angle in degrees to a formatted degrees:minutes:seconds string. No fractional part of the seconds field is given.

  - Parameters:
    - `deg` (floating point): angle in degrees
  - Return value
    - (String): DMS-format string representing `deg`
`degreesToDms( deg, secFig )`

  Converts an angle in degrees to a formatted degrees:minutes:seconds string with a given number of decimal places in the seconds field.

  - Parameters:
    - `deg` (floating point): angle in degrees
    - `secFig` (integer): number of decimal places in the seconds field
  - Return value
    - (String): DMS-format string representing `deg`
`degreesToHms( deg )`

  Converts an angle in degrees to a formatted hours:minutes:seconds string. No fractional part of the seconds field is given.

  - Parameters:
    - `deg` (floating point): angle in degrees
  - Return value
    - (String): HMS-format string representing `deg`
`degreesToHms( deg, secFig )`

  Converts an angle in degrees to a formatted hours:minutes:seconds string with a given number of decimal places in the seconds field.

  - Parameters:
    - `deg` (floating point): angle in degrees
    - `secFig` (integer): number of decimal places in the seconds field
  - Return value
    - (String): HMS-format string representing `deg`
`dmsToDegrees( dms )`

  Converts a formatted degrees:minutes:seconds string to an angle in degrees. Delimiters may be colon, space, characters `dm[s]`, or some others. Additional spaces and leading +/- are permitted. The :seconds part is optional.

  - Parameters:
    - `dms` (String): formatted DMS string
  - Return value
    - (floating point): angle in degrees specified by `dms`
`hmsToDegrees( hms )`

  Converts a formatted hours:minutes:seconds string to an angle in degrees. Delimiters may be colon, space, characters `hm[s]`, or some others. Additional spaces and leading +/- are permitted. The :seconds part is optional.

  - Parameters:
    - `hms` (String): formatted HMS string
  - Return value
    - (floating point): angle in degrees specified by `hms`
`dmsToDegrees( deg, min, sec )`

  Converts degrees, minutes, seconds to an angle in degrees.

  In conversions of this type, one has to be careful to get the sign right in converting angles which are between 0 and -1 degrees. This routine uses the sign bit of the `deg` argument, taking care to distinguish between +0 and -0 (their internal representations are different for floating point values). It is illegal for the `min` or `sec` arguments to be negative.

  - Parameters:
    - `deg` (floating point): degrees part of angle
    - `min` (floating point): minutes part of angle
    - `sec` (floating point): seconds part of angle
  - Return value
    - (floating point): specified angle in degrees
`hmsToDegrees( hour, min, sec )`

  Converts hours, minutes, seconds to an angle in degrees.

  In conversions of this type, one has to be careful to get the sign right in converting angles which are between 0 and -1 hours. This routine uses the sign bit of the `hour` argument, taking care to distinguish between +0 and -0 (their internal representations are different for floating point values).

  - Parameters:
    - `hour` (floating point): degrees part of angle
    - `min` (floating point): minutes part of angle
    - `sec` (floating point): seconds part of angle
  - Return value
    - (floating point): specified angle in degrees
`skyDistanceDegrees( ra1, dec1, ra2, dec2 )`

  Calculates the separation (distance around a great circle) of two points on the sky in degrees.

  - Parameters:
    - `ra1` (floating point): right ascension of point 1 in degrees
    - `dec1` (floating point): declination of point 1 in degrees
    - `ra2` (floating point): right ascension of point 2 in degrees
    - `dec2` (floating point): declination of point 2 in degrees
  - Return value
    - (floating point): angular distance between point 1 and point 2 in degrees
`posAngDegrees( ra1, dec1, ra2, dec2 )`

  Calculates the position angle between two points on the sky in degrees. The result is in the range +/-180. If point 2 is due east of point 1, the result is +90. Zero is returned if the points are coincident.

  - Parameters:
    - `ra1` (floating point): right ascension of point 1 in degrees
    - `dec1` (floating point): declination of point 1 in degrees
    - `ra2` (floating point): right ascension of point 2 in degrees
    - `dec2` (floating point): declination of point 2 in degrees
  - Return value
    - (floating point): bearing in degrees of point 2 from point 1.
`polarDistanceDegrees( ra1, dec1, radius1, ra2, dec2, radius2 )`

  Calculates the distance in three dimensional space between two points specified in spherical polar coordinates.

  - Parameters:
    - `ra1` (floating point): right ascension of point 1 in degrees
    - `dec1` (floating point): declination of point1 in degrees
    - `radius1` (floating point): distance from origin of point1
    - `ra2` (floating point): right ascension of point 2 in degrees
    - `dec2` (floating point): declination of point2 in degrees
    - `radius2` (floating point): distance from origin of point2
  - Return value
    - (floating point): the linear distance between point1 and point2; units are as for `radius1` and `radius2`

# 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.

`radiansToDms( rad )`

  Converts an angle in radians to a formatted degrees:minutes:seconds string. No fractional part of the seconds field is given.

  - Parameters:
    - `rad` (floating point): angle in radians
  - Return value
    - (String): DMS-format string representing `rad`
`radiansToDms( rad, secFig )`

  Converts an angle in radians to a formatted degrees:minutes:seconds string with a given number of decimal places in the seconds field.

  - Parameters:
    - `rad` (floating point): angle in radians
    - `secFig` (integer): number of decimal places in the seconds field
  - Return value
    - (String): DMS-format string representing `rad`
`radiansToHms( rad )`

  Converts an angle in radians to a formatted hours:minutes:seconds string. No fractional part of the seconds field is given.

  - Parameters:
    - `rad` (floating point): angle in radians
  - Return value
    - (String): HMS-format string representing `rad`
`radiansToHms( rad, secFig )`

  Converts an angle in radians to a formatted hours:minutes:seconds string with a given number of decimal places in the seconds field.

  - Parameters:
    - `rad` (floating point): angle in radians
    - `secFig` (integer): number of decimal places in the seconds field
  - Return value
    - (String): HMS-format string representing `rad`
`dmsToRadians( dms )`

  Converts a formatted degrees:minutes:seconds string to an angle in radians. Delimiters may be colon, space, characters `dm[s]`, or some others. Additional spaces and leading +/- are permitted. The :seconds part is optional.

  - Parameters:
    - `dms` (String): formatted DMS string
  - Return value
    - (floating point): angle in radians specified by `dms`
`hmsToRadians( hms )`

  Converts a formatted hours:minutes:seconds string to an angle in radians. Delimiters may be colon, space, characters `hm[s]`, or some others. Additional spaces and leading +/- are permitted. The :seconds part is optional.

  - Parameters:
    - `hms` (String): formatted HMS string
  - Return value
    - (floating point): angle in radians specified by `hms`
`dmsToRadians( deg, min, sec )`

  Converts degrees, minutes, seconds to an angle in radians.

  In conversions of this type, one has to be careful to get the sign right in converting angles which are between 0 and -1 degrees. This routine uses the sign bit of the `deg` argument, taking care to distinguish between +0 and -0 (their internal representations are different for floating point values). It is illegal for the `min` or `sec` arguments to be negative.

  - Parameters:
    - `deg` (floating point): degrees part of angle
    - `min` (floating point): minutes part of angle
    - `sec` (floating point): seconds part of angle
  - Return value
    - (floating point): specified angle in radians
`hmsToRadians( hour, min, sec )`

  Converts hours, minutes, seconds to an angle in radians.

  In conversions of this type, one has to be careful to get the sign right in converting angles which are between 0 and -1 hours. This routine uses the sign bit of the `hour` argument, taking care to distinguish between +0 and -0 (their internal representations are different for floating point values).

  - Parameters:
    - `hour` (floating point): degrees part of angle
    - `min` (floating point): minutes part of angle
    - `sec` (floating point): seconds part of angle
  - Return value
    - (floating point): specified angle in radians
`skyDistanceRadians( ra1, dec1, ra2, dec2 )`

  Calculates the separation (distance around a great circle) of two points on the sky in radians.

  - Parameters:
    - `ra1` (floating point): right ascension of point 1 in radians
    - `dec1` (floating point): declination of point 1 in radians
    - `ra2` (floating point): right ascension of point 2 in radians
    - `dec2` (floating point): declination of point 2 in radians
  - Return value
    - (floating point): angular distance between point 1 and point 2 in radians
`posAngRadians( ra1, dec1, ra2, dec2 )`

  Calculates the position angle between two points on the sky in radians. The result is in the range +/-pi. If point 2 is due east of point 1, the result is +pi/2. Zero is returned if the points are coincident.

  - Parameters:
    - `ra1` (floating point): right ascension of point 1 in radians
    - `dec1` (floating point): declination of point 1 in radians
    - `ra2` (floating point): right ascension of point 2 in radians
    - `dec2` (floating point): declination of point 2 in radians
  - Return value
    - (floating point): bearing in radians of point 2 from point 1
`polarDistanceRadians( ra1, dec1, radius1, ra2, dec2, radius2 )`

  Calculates the distance in three dimensional space between two points specified in spherical polar coordinates.

  - Parameters:
    - `ra1` (floating point): right ascension of point 1 in radians
    - `dec1` (floating point): declination of point1 in radians
    - `radius1` (floating point): distance from origin of point1
    - `ra2` (floating point): right ascension of point 2 in radians
    - `dec2` (floating point): declination of point2 in radians
    - `radius2` (floating point): distance from origin of point2
  - Return value
    - (floating point): the linear distance between point1 and point2; units are as for `radius1` and `radius2`
`hoursToRadians( hours )`

  Converts hours to radians.

  - Parameters:
    - `hours` (floating point): angle in hours
  - Return value
    - (floating point): angle in radians
`degreesToRadians( deg )`

  Converts degrees to radians.

  - Parameters:
    - `deg` (floating point): angle in degrees
  - Return value
    - (floating point): angle in radians
`radiansToDegrees( rad )`

  Converts radians to degrees.

  - Parameters:
    - `rad` (floating point): angle in radians
  - Return value
    - (floating point): angle in degrees
`raFK4toFK5radians( raFK4, decFK4 )`

  Converts a B1950.0 FK4 position to J2000.0 FK5 at an epoch of B1950.0 yielding Right Ascension. This assumes zero proper motion in the FK5 frame.

  - Parameters:
    - `raFK4` (floating point): right ascension in B1950.0 FK4 system (radians)
    - `decFK4` (floating point): declination in B1950.0 FK4 system (radians)
  - Return value
    - (floating point): right ascension in J2000.0 FK5 system (radians)
`decFK4toFK5radians( raFK4, decFK4 )`

  Converts a B1950.0 FK4 position to J2000.0 FK5 at an epoch of B1950.0 yielding Declination This assumes zero proper motion in the FK5 frame.

  - Parameters:
    - `raFK4` (floating point): right ascension in B1950.0 FK4 system (radians)
    - `decFK4` (floating point): declination in B1950.0 FK4 system (radians)
  - Return value
    - (floating point): declination in J2000.0 FK5 system (radians)
`raFK5toFK4radians( raFK5, decFK5 )`

  Converts a J2000.0 FK5 position to B1950.0 FK4 at an epoch of B1950.0 yielding Declination. This assumes zero proper motion, parallax and radial velocity in the FK5 frame.

  - Parameters:
    - `raFK5` (floating point): right ascension in J2000.0 FK5 system (radians)
    - `decFK5` (floating point): declination in J2000.0 FK5 system (radians)
  - Return value
    - (floating point): right ascension in the FK4 system (radians)
`decFK5toFK4radians( raFK5, decFK5 )`

  Converts a J2000.0 FK5 position to B1950.0 FK4 at an epoch of B1950.0 yielding Declination. This assumes zero proper motion, parallax and radial velocity in the FK5 frame.

  - Parameters:
    - `raFK5` (floating point): right ascension in J2000.0 FK5 system (radians)
    - `decFK5` (floating point): declination in J2000.0 FK5 system (radians)
  - Return value
    - (floating point): right ascension in the FK4 system (radians)
`raFK4toFK5Radians( raFK4, decFK4, bepoch )`

  Converts a B1950.0 FK4 position to J2000.0 FK5 yielding Right Ascension. This assumes zero proper motion in the FK5 frame. The `bepoch` parameter is the epoch at which the position in the FK4 frame was determined.

  - Parameters:
    - `raFK4` (floating point): right ascension in B1950.0 FK4 system (radians)
    - `decFK4` (floating point): declination in B1950.0 FK4 system (radians)
    - `bepoch` (floating point): Besselian epoch
  - Return value
    - (floating point): right ascension in J2000.0 FK5 system (radians)
`decFK4toFK5Radians( raFK4, decFK4, bepoch )`

  Converts a B1950.0 FK4 position to J2000.0 FK5 yielding Declination. This assumes zero proper motion in the FK5 frame. The `bepoch` parameter is the epoch at which the position in the FK4 frame was determined.

  - Parameters:
    - `raFK4` (floating point): right ascension in B1950.0 FK4 system (radians)
    - `decFK4` (floating point): declination in B1950.0 FK4 system (radians)
    - `bepoch` (floating point): Besselian epoch
  - Return value
    - (floating point): declination in J2000.0 FK5 system (radians)
`raFK5toFK4Radians( raFK5, decFK5, bepoch )`

  Converts a J2000.0 FK5 position to B1950.0 FK4 yielding Declination. This assumes zero proper motion, parallax and radial velocity in the FK5 frame.

  - Parameters:
    - `raFK5` (floating point): right ascension in J2000.0 FK5 system (radians)
    - `decFK5` (floating point): declination in J2000.0 FK5 system (radians)
    - `bepoch` (floating point): Besselian epoch
  - Return value
    - (floating point): right ascension in the FK4 system (radians)
`decFK5toFK4Radians( raFK5, decFK5, bepoch )`

  Converts a J2000.0 FK5 position to B1950.0 FK4 yielding Declination. This assumes zero proper motion, parallax and radial velocity in the FK5 frame.

  - Parameters:
    - `raFK5` (floating point): right ascension in J2000.0 FK5 system (radians)
    - `decFK5` (floating point): declination in J2000.0 FK5 system (radians)
    - `bepoch` (floating point): Besselian epoch
  - Return value
    - (floating point): right ascension in the FK4 system (radians)
`DEGREE_RADIANS`

  The size of one degree in radians.

`HOUR_RADIANS`

  The size of one hour of right ascension in radians.

`ARC_MINUTE_RADIANS`

  The size of one arcminute in radians.

`ARC_SECOND_RADIANS`

  The size of one arcsecond in radians.

# 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.

MOCs may be specified using a string argument of the functions in one of the following ways:

- The filename of a MOC FITS file
- The URL of a MOC FITS file
- The identifier of a VizieR table, for instance "`V/139/sdss9`" (SDSS DR9)
- An ASCII MOC string, for instance "`1/1 2 4 2/12-14 21 23 25 8/`"

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`").

`inMoc( moc, ra, dec )`

  Indicates whether a given sky position falls strictly within a given MOC (Multi-Order Coverage map). If the given `moc` value does not represent a MOC (for instance no file exists or the file/string is not in MOC format) a warning will be issued the first time it's referenced, and the result will be false.

  - Parameters:
    - `moc` (String): a MOC identifier; a filename, a URL, a VizieR table name, or an ASCII MOC string
    - `ra` (floating point): ICRS right ascension in degrees
    - `dec` (floating point): ICRS declination in degrees
  - Return value
    - (boolean): true iff the given position falls within the given MOC
`nearMoc( moc, ra, dec, distanceDeg )`

  Indicates whether a given sky position either falls within, or is within a certain distance of the edge of, a given MOC (Multi-Order Coverage map). If the given `moc` value does not represent a MOC (for instance no file exists or the file/string is not in MOC format) a warning will be issued the first time it's referenced, and the result will be false.

  - Parameters:
    - `moc` (String): a MOC identifier; a filename, a URL, a VizieR table name, or an ASCII MOC string
    - `ra` (floating point): ICRS right ascension in degrees
    - `dec` (floating point): ICRS declination in degrees
    - `distanceDeg` (floating point): permitted distance from MOC boundary in degrees
  - Return value
    - (boolean): true iff the given position is within `distance` degrees of the given MOC
`mocSkyProportion( moc )`

  Returns the proportion of the sky covered by a given MOC.

  If the given `moc` value does not represent a MOC (for instance no file exists or the file/string is not in MOC format) a warning will be issued the first time it's referenced, and the result will be NaN.

  - Parameters:
    - `moc` (String): a MOC identifier; a filename, a URL, a VizieR table name, or an ASCII MOC string
  - Return value
    - (floating point): a fractional value in the range 0..1
`mocTileCount( moc )`

  Returns the number of unique tiles within a given MOC.

  If the given `moc` value does not represent a MOC (for instance no file exists or the file/string is not in MOC format) a warning will be issued the first time it's referenced, and the result will be 0.

  - Parameters:
    - `moc` (String): a MOC identifier; a filename, a URL, a VizieR table name, or an ASCII MOC string
  - Return value
    - (long integer): number of tiles in the MOC
`mocUniq( order, index )`

  Converts a HEALPix order and and tile index into a UNIQ-encoded integer as used in MOC encoding. The result is `index + 4**(1+order)`.

  If the order or index are out of bounds, behaviour is undefined.

  - Parameters:
    - `order` (integer): HEALPix order, in range 0..29
    - `index` (long integer): tile index within the given level
  - Return value
    - (long integer): uniq-encoded value
`uniqToOrder( uniq )`

  Extracts the HEALPix order from a UNIQ-encoded integer as used in MOC encoding.

  If the supplied value is not a legal UNIQ integer, behaviour is undefined.

  - Parameters:
    - `uniq` (long integer): uniq-encoded value
  - Return value
    - (integer): HEALPix order
`uniqToIndex( uniq )`

  Extracts the HEALPix pixel index from a UNIQ-encoded integer as used in MOC encoding.

  If the supplied value is not a legal UNIQ integer, behaviour is undefined.

  - Parameters:
    - `uniq` (long integer): uniq-encoded value
  - Return value
    - (long integer): pixel index
`SPHERE_STERADIAN`

  The number of steradians on the sphere, 4 PI.

`SPHERE_SQDEG`

  The number of square degrees on the sphere, approx 41253.

# 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).

`MpcToM( distMpc )`

  Converts from MegaParsecs to metres.

  - Parameters:
    - `distMpc` (floating point): distance in Mpc
  - Return value
    - (floating point): distance in m
`mToMpc( distM )`

  Converts from metres to MegaParsecs.

  - Parameters:
    - `distM` (floating point): distance in m
  - Return value
    - (floating point): distance in Mpc
`zToDist( z )`

  Quick and dirty function for converting from redshift to distance.

  Warning: this makes some reasonable assumptions about the cosmology and returns the luminosity distance. It is only intended for approximate use. If you care about the details, use one of the more specific functions here.

  - Parameters:
    - `z` (floating point): redshift
  - Return value
    - (floating point): some distance measure in Mpc
`zToAge( z )`

  Quick and dirty function for converting from redshift to time.

  Warning: this makes some reasonable assumptions about the cosmology. It is only intended for approximate use. If you care about the details use one of the more specific functions here.

  - Parameters:
    - `z` (floating point): redshift
  - Return value
    - (floating point): 'age' of photons from redshift `z` in Gyr
`comovingDistanceL( z, H0, omegaM, omegaLambda )`

  Line-of-sight comoving distance.

  - Parameters:
    - `z` (floating point): redshift
    - `H0` (floating point): Hubble constant in km/sec/Mpc
    - `omegaM` (floating point): density ratio of the universe
    - `omegaLambda` (floating point): normalised cosmological constant
  - Return value
    - (floating point): line-of-sight comoving distance in Mpc
`comovingDistanceT( z, H0, omegaM, omegaLambda )`

  Transverse comoving distance.

  - Parameters:
    - `z` (floating point): redshift
    - `H0` (floating point): Hubble constant in km/sec/Mpc
    - `omegaM` (floating point): density ratio of the universe
    - `omegaLambda` (floating point): normalised cosmological constant
  - Return value
    - (floating point): transverse comoving distance in Mpc
`angularDiameterDistance( z, H0, omegaM, omegaLambda )`

  Angular diameter distance.

  - Parameters:
    - `z` (floating point): redshift
    - `H0` (floating point): Hubble constant in km/sec/Mpc
    - `omegaM` (floating point): density ratio of the universe
    - `omegaLambda` (floating point): normalised cosmological constant
  - Return value
    - (floating point): angular diameter distance in Mpc
`luminosityDistance( z, H0, omegaM, omegaLambda )`

  Luminosity distance.

  - Parameters:
    - `z` (floating point): redshift
    - `H0` (floating point): Hubble constant in km/sec/Mpc
    - `omegaM` (floating point): density ratio of the universe
    - `omegaLambda` (floating point): normalised cosmological constant
  - Return value
    - (floating point): luminosity distance in Mpc
`lookbackTime( z, H0, omegaM, omegaLambda )`

  Lookback time. This returns the difference between the age of the universe at time of observation (now) and the age of the universe at the time when photons of redshift `z` were emitted.

  - Parameters:
    - `z` (floating point): redshift
    - `H0` (floating point): Hubble constant in km/sec/Mpc
    - `omegaM` (floating point): density ratio of the universe
    - `omegaLambda` (floating point): normalised cosmological constant
  - Return value
    - (floating point): lookback time in Gyr
`comovingVolume( z, H0, omegaM, omegaLambda )`

  Comoving volume. This returns the all-sky total comoving volume out to a given redshift `z`.

  - Parameters:
    - `z` (floating point): redshift
    - `H0` (floating point): Hubble constant in km/sec/Mpc
    - `omegaM` (floating point): density ratio of the universe
    - `omegaLambda` (floating point): normalised cosmological constant
  - Return value
    - (floating point): comoving volume in Gpc3
`SPEED_OF_LIGHT`

  Speed of light in m/s.

`METRE_PER_PARSEC`

  Number of metres in a parsec.

`SEC_PER_YEAR`

  Number of seconds in a year.

# 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).

`abToJansky( magAB )`

  Converts AB magnitude to flux in Jansky.

  F/Jy=10(23-(AB+48.6)/2.5)

  - Parameters:
    - `magAB` (floating point): AB magnitude value
  - Return value
    - (floating point): equivalent flux in Jansky
`janskyToAb( fluxJansky )`

  Converts flux in Jansky to AB magnitude.

  AB=2.5*(23-log10(F/Jy))-48.6

  - Parameters:
    - `fluxJansky` (floating point): flux in Jansky
  - Return value
    - (floating point): equivalent AB magnitude
`luminosityToFlux( lumin, dist )`

  Converts luminosity to flux given a luminosity distance.

  F=lumin/(4 x Pi x dist2)

  - Parameters:
    - `lumin` (floating point): luminosity
    - `dist` (floating point): luminosity distance
  - Return value
    - (floating point): equivalent flux
`fluxToLuminosity( flux, dist )`

  Converts flux to luminosity given a luminosity distance.

  lumin=(4 x Pi x dist2) F

  - Parameters:
    - `flux` (floating point): flux
    - `dist` (floating point): luminosity distance
  - Return value
    - (floating point): equivalent luminosity
`JOHNSON_AB_V`

  Approximate offset between Johnson and AB magnitudes in V band. VJ~=VAB+`JOHNSON_AB_V`.

`JOHNSON_AB_B`

  Approximate offset between Johnson and AB magnitudes in B band. BJ~=BAB+`JOHNSON_AB_B`.

`JOHNSON_AB_Bj`

  Approximate offset between Johnson and AB magnitudes in Bj band. BjJ~=BjAB+`JOHNSON_AB_Bj`.

`JOHNSON_AB_R`

  Approximate offset between Johnson and AB magnitudes in R band. RJ~=RAB+`JOHNSON_AB_R`.

`JOHNSON_AB_I`

  Approximate offset between Johnson and AB magnitudes in I band. IJ~=IAB+`JOHNSON_AB_I`.

`JOHNSON_AB_g`

  Approximate offset between Johnson and AB magnitudes in g band. gJ~=gAB+`JOHNSON_AB_g`.

`JOHNSON_AB_r`

  Approximate offset between Johnson and AB magnitudes in r band. rJ~=rAB+`JOHNSON_AB_r`.

`JOHNSON_AB_i`

  Approximate offset between Johnson and AB magnitudes in i band. iJ~=iAB+`JOHNSON_AB_i`.

`JOHNSON_AB_Rc`

  Approximate offset between Johnson and AB magnitudes in Rc band. RcJ~=RcAB+`JOHNSON_AB_Rc`.

`JOHNSON_AB_Ic`

  Approximate offset between Johnson and AB magnitudes in Ic band. IcJ~=IcAB+`JOHNSON_AB_Ic`.

`JOHNSON_AB_uPrime`

  Offset between Johnson and AB magnitudes in u' band (zero). u'J=u'AB+`JOHNSON_AB_uPrime`=u'AB.

`JOHNSON_AB_gPrime`

  Offset between Johnson and AB magnitudes in g' band (zero). g'J=g'AB+`JOHNSON_AB_gPrime`=g'AB.

`JOHNSON_AB_rPrime`

  Offset between Johnson and AB magnitudes in r' band (zero). r'J=r'AB+`JOHNSON_AB_rPrime`=r'AB.

`JOHNSON_AB_iPrime`

  Offset between Johnson and AB magnitudes in i' band (zero). i'J=i'AB+`JOHNSON_AB_iPrime`=i'AB.

`JOHNSON_AB_zPrime`

  Offset between Johnson and AB magnitudes in z' band (zero). z'J=z'AB+`JOHNSON_AB_zPrime`=z'AB.

`VEGA_AB_J`

  Approximate offset between Vega (as in 2MASS) and AB magnitudes in J band. JVega~=JAB+`VEGA_AB_J`.

`VEGA_AB_H`

  Approximate offset between Vega (as in 2MASS) and AB magnitudes in H band. HVega~=HAB+`VEGA_AB_H`.

`VEGA_AB_K`

  Approximate offset between Vega (as in 2MASS) and AB magnitudes in K band. KVega~=KAB+`VEGA_AB_K`.

# Formats

Functions for formatting numeric values.

`formatDecimal( value, dp )`

  Turns a floating point value into a string with a given number of decimal places using standard settings.

  - Parameters:
    - `value` (floating point): value to format
    - `dp` (integer): number of decimal places (digits after the decmal point)
  - Return value
    - (String): formatted string
  - Examples:
    - `formatDecimal(PI,0) = "3."`
    - `formatDecimal(0,10) = ".0000000000"`
    - `formatDecimal(E*10,3) = "27.183"`
`formatDecimalLocal( value, dp )`

  Turns a floating point value into a string using current locale settings. For instance if language is set to French, decimal points will be represented as a comma "," instead of a full stop ".". Otherwise behaves the same as the corresponding `formatDecimal` function.

  - Parameters:
    - `value` (floating point): value to format
    - `dp` (integer): number of decimal places (digits after the decmal point)
  - Return value
    - (String): formatted string
  - Examples:
    - `formatDecimal(PI,0) = "3,"`
    - `formatDecimal(0,10) = ",0000000000"`
    - `formatDecimal(E*10,3) = "27,183"`
`formatDecimal( value, format )`

  Turns a floating point value into a formatted string using standard settings. The `format` string is as defined by Java's `java.text.DecimalFormat` class.

  - Parameters:
    - `value` (floating point): value to format
    - `format` (String): format specifier
  - Return value
    - (String): formatted string
  - Examples:
    - `formatDecimal(99, "#.000") = "99.000"`
    - `formatDecimal(PI, "+0.##;-0.##") = "+3.14"`
`formatDecimalLocal( value, format )`

  Turns a floating point value into a formatted string using current locale settings. For instance if language is set to French, decimal points will be represented as a comma "," instead of a full stop ".". Otherwise behaves the same as the corresponding `formatDecimal` function.

  - Parameters:
    - `value` (floating point): value to format
    - `format` (String): format specifier
  - Return value
    - (String): formatted string
  - Examples:
    - `formatDecimal(99, "#.000") = "99,000"`
    - `formatDecimal(PI, "+0.##;-0.##") = "+3,14"`

# 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.

`polarXYZ( phi, theta, r )`

  Converts from spherical polar to Cartesian coordinates.

  - Parameters:
    - `phi` (floating point): longitude in degrees
    - `theta` (floating point): latitude in degrees
    - `r` (floating point): radial distance
  - Return value
    - (array of floating point): 3-element vector giving Cartesian coordinates
  - Examples:
    - `polarXYZ(ra, dec, distance_estimate)`
    - `polarXYZ(l, b, 3262./parallax)` - calculates vector components in units of light year in the galactic system, on the assumption that distance is the inverse of parallax
`astromXYZ( ra, dec, parallax )`

  Calculates Cartesian components of position from RA, Declination and parallax. This is a convenience function, equivalent to: 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 non-negligable errors. Use at your own risk.

  - Parameters:
    - `ra` (floating point): Right Ascension in degrees
    - `dec` (floating point): Declination in degrees
    - `parallax` (floating point): parallax in mas
  - Return value
    - (array of floating point): 3-element vector giving equatorial space coordinates in parsec
  - Examples:
    - `astromXYZ(ra, dec, parallax)`
    - `icrsToGal(astromXYZ(ra, dec, parallax))`
`icrsToGal( xyz )`

  Converts a 3-element vector representing ICRS (equatorial) coordinates to galactic coordinates. This can be used with position or velocity vectors.

  The input vector is multiplied by the matrix AG', given in Eq. 3.61 of the Gaia DR2 documentation, following Eq. 1.5.13 of the Hipparcos catalogue.

  The output coordinate system is right-handed, with the three components positive in the directions of the Galactic center, Galactic rotation, and the North Galactic Pole respectively.

  - Parameters:
    - `xyz` (array of floating point): 3-element vector giving ICRS Cartesian components
  - Return value
    - (array of floating point): 3-element vector giving Galactic Cartesian components
  - Example:
    - `icrsToGal(polarXYZ(ra, dec, distance))`
`galToIcrs( xyz )`

  Converts a 3-element vector representing galactic coordinates to ICRS (equatorial) coordinates. This can be used with position or velocity vectors.

  The input vector is multiplied by the matrix AG, given in Eq. 3.61 of the Gaia DR2 documentation, following Eq. 1.5.13 of the Hipparcos catalogue.

  The input coordinate system is right-handed, with the three components positive in the directions of the Galactic center, Galactic rotation, and the North Galactic Pole respectively.

  - Parameters:
    - `xyz` (array of floating point): 3-element vector giving Galactic Cartesian components
  - Return value
    - (array of floating point): 3-element vector giving ICRS Cartesian components
  - Example:
    - `galToIcrs(polarXYZ(l, b, distance))`
`icrsToEcl( xyz )`

  Converts a 3-element vector representing ICRS (equatorial) coordinates to ecliptic coordinates. This can be used with position or velocity vectors.

  The transformation corresponds to that between the coordinates `(ra,dec)` and `(ecl_lon,ecl_lat)` in the Gaia source catalogue (DR2).

  - Parameters:
    - `xyz` (array of floating point): 3-element vector giving ICRS Cartesian components
  - Return value
    - (array of floating point): 3-element vector giving ecliptic Cartesian components
  - Example:
    - `icrsToEcl(polarXYZ(ra, dec, distance))`
`eclToIcrs( xyz )`

  Converts a 3-element vector representing ecliptic coordinates to ICRS (equatorial) coordinates. This can be used with position or velocity vectors.

  The transformation corresponds to that between the coordinates `(ecl_lon,ecl_lat)` and `(ra,dec)` in the Gaia source catalogue (DR2).

  - Parameters:
    - `xyz` (array of floating point): 3-element vector giving ecliptic Cartesian coordinates
  - Return value
    - (array of floating point): 3-element vector giving ICRS Cartesian coordinates
  - Example:
    - `eclToIcrs(polarXYZ(ecl_lon, ecl_lat, distance))`
`astromUVW( astrom6 )`

  Calculates Cartesian components of velocity from quantities available in the Gaia source catalogue. The output is in the same coordinate system as the inputs, that is ICRS for the correspondingly-named Gaia quantities.

  The input astrometry parameters are represented by a 6-element 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 velocity The units used by this function are the units used in the `gaia_source` table.

  This convenience function just invokes the 7-argument `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 non-negligable errors.

  - Parameters:
    - `astrom6` (array of floating point): vector of 6 astrometric parameters as provided by the Gaia source catalogue
  - Return value
    - (array of floating point): 3-element vector giving equatorial velocity components in km/s
  - Examples:
    - `astromUVW(array(ra, dec, parallax, pmra, pmdec, radial_velocity))`
    - `icrsToGal(astromUVW(array(ra, dec, parallax, pmra, pmdec, radial_velocity)))`
`astromUVW( ra, dec, pmra, pmdec, radial_velocity, r_parsec, useDoppler )`

  Calculates Cartesian components of velocity from the observed position and proper motion, radial velocity and radial distance, with optional light-time correction. The output is in the same coordinate system as the inputs, that is ICRS for the correspondingly-named Gaia quantities.

  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 non-negligable errors.

  The calculations are fairly straightforward, following Eq. 1.5.74 from the Hipparcos catalogue. A (usually small) Doppler factor accounting for light-time effects can also optionally be applied. The effect of this is to multiply the returned vector by a factor of `1/(1-radial_velocity/c)`, as discussed in Eq. 1.2.21 of the Hipparcos catalogue.

  Note that no attempt is made to adjust for solar motion.

  - Parameters:
    - `ra` (floating point): Right Ascension in degrees
    - `dec` (floating point): Declination in degrees
    - `pmra` (floating point): proper motion in RA * cos(dec) in mas/yr
    - `pmdec` (floating point): proper motion in declination in mas/yr
    - `radial_velocity` (floating point): radial velocity in km/s
    - `r_parsec` (floating point): radial distance in parsec
    - `useDoppler` (boolean): whether to apply the Doppler factor to account for light-time effects
  - Return value
    - (array of floating point): 3-element vector giving equatorial velocity components in km/s
  - Examples:
    - `astromUVW(ra, dec, pmra, pmdec, radial_velocity, dist, true)`
    - `icrsToGal(astromUVW(ra, dec, pmra, pmdec, radial_velocity, 1000./parallax, false))`
`epochProp( tYr, astrom6 )`

  Propagates the astrometry parameters, supplied as a 6-element array, to a different epoch.

  The input and output astrometry parameters are each represented by a 6-element 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 velocity The units used by this function are the units used in the `gaia_source` table.

  Null values for `parallax`, `pmra`, `pmdec` and `radial_velocity` are treated as if zero for the purposes of propagation. The documentation of the equivalent function in the Gaia archive comments "This is a reasonable choice for most stars because those quantities would be either small (parallax and proper motion) or irrelevant (radial velocity). However, this is not true for stars very close to the Sun, where appropriate values need to be taken from the literature (e.g. average velocity field in the solar neighbourhood)."

  The effect is that the output represents the best estimates available for propagated astrometry; proper motions, parallax and RV are applied if present, but if not the output values are calculated or simply copied across as if those quantities were zero.

  - Parameters:
    - `tYr` (floating point): epoch difference in years
    - `astrom6` (array of floating point): astrometry at time t0, represented by a 6-element array as above (a 5-element array is also permitted where radial velocity is zero or unknown)
  - Return value
    - (array of floating point): astrometry at time `t0+tYr`, represented by a 6-element array as above
  - Example:
    - `epochProp(-15.5, array(ra,dec,parallax,pmra,pmdec,radial_velocity))` - calculates the astrometry at 2000.0 of gaia_source values that were observed at 2015.5
`epochPropErr( tYr, astrom22 )`

  Propagates the astrometry parameters and their associated errors and correlations, supplied as a 22-element array, to a different epoch.

  The input and output astrometry parameters with associated error and correlation information are each represented by a 22-element 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 pmdec Note the correlation coefficients, always in the range -1..1, are dimensionless.

  Null values for `parallax`, `pmra`, `pmdec` and `radial_velocity` are treated as if zero for the purposes of propagation. The documentation of the equivalent function in the Gaia archive comments "This is a reasonable choice for most stars because those quantities would be either small (parallax and proper motion) or irrelevant (radial velocity). However, this is not true for stars very close to the Sun, where appropriate values need to be taken from the literature (e.g. average velocity field in the solar neighbourhood)."

  The effect is that the output represents the best estimates available for propagated astrometry; proper motions, parallax and RV are applied if present, but if not the output values are calculated or simply copied across as if those quantities were zero.

  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 back-transformation of data already propagated to another epoch.

  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.

  - Parameters:
    - `tYr` (floating point): epoch difference in years
    - `astrom22` (array of floating point): astrometry at time t0, represented by a 22-element array as above
  - Return value
    - (array of floating point): astrometry at time t0+tYr, represented by a 22-element array as above
  - Example:
    - `epochPropErr(-15.5, array( ra,dec,parallax,pmra,pmdec,radial_velocity, ra_error,dec_error,parallax_error,pmra_error,pmdec_error,radial_velocity_error, ra_dec_corr,ra_parallax_corr,ra_pmra_corr,ra_pmdec_corr, dec_parallax_corr,dec_pmra_corr,dec_pmdec_corr, parallax_pmra_corr,parallax_pmdec_corr, pmra_pmdec_corr))` - calculates the astrometry with all errors and correlations at 2000.0 for gaia_source values that were observed at 2015.5.
`rvMasyrToKms( rvMasyr, plxMas )`

  Converts from normalised radial velocity in mas/year to unnormalised radial velocity in km/s.

  The output is calculated as `AU_YRKMS * rvMasyr / plxMas`, where `AU_YRKMS=4.740470446` is one Astronomical Unit in km.yr/sec.

  - Parameters:
    - `rvMasyr` (floating point): normalised radial velocity, in mas/year
    - `plxMas` (floating point): parallax in mas
  - Return value
    - (floating point): radial velocity in km/s
`rvKmsToMasyr( rvKms, plxMas )`

  Converts from unnormalised radial velocity in km/s to normalised radial velocity in mas/year.

  The output is calculated as `rvKms * plxMas / AU_YRKMS`, where `AU_YRKMS=4.740470446` is one Astronomical Unit in km.yr/sec.

  - Parameters:
    - `rvKms` (floating point): unnormalised radial velocity, in mas/year
    - `plxMas` (floating point): parallax in mas
  - Return value
    - (floating point): radial velocity in mas/year
`distanceEstimateEdsd( plxMas, plxErrorMas, lPc )`

  Best estimate of distance using the Exponentially Decreasing Space Density prior. This estimate is provided by the mode of the PDF.

  - Parameters:
    - `plxMas` (floating point): parallax in mas
    - `plxErrorMas` (floating point): parallax error in mas
    - `lPc` (floating point): length scale in parsec
  - Return value
    - (floating point): best distance estimate in parsec
`distanceBoundsEdsd( plxMas, plxErrorMas, lPc )`

  Calculates the 5th and 95th percentile confidence intervals on the distance estimate using the Exponentially Decreasing Space Density prior.

  Note this function has to numerically integrate the PDF to determine quantile values, so it is relatively slow.

  - Parameters:
    - `plxMas` (floating point): parallax in mas
    - `plxErrorMas` (floating point): parallax error in mas
    - `lPc` (floating point): length scale in parsec
  - Return value
    - (array of floating point): 2-element array giving the 5th and 95th percentiles in parsec of the EDSD distance PDF
`distanceQuantilesEdsd( plxMas, plxErrorMas, lPc, qpoints, ... )`

  Calculates arbitrary quantiles for the distance estimate using the Exponentially Decreasing Space Density prior.

  Note this function has to numerically integrate the PDF to determine quantile values, so it is relatively slow.

  - Parameters:
    - `plxMas` (floating point): parallax in mas
    - `plxErrorMas` (floating point): parallax error in mas
    - `lPc` (floating point): length scale in parsec
    - `qpoints` (floating point, one or more): one or more required quantile cut points, each in the range 0..1
  - Return value
    - (array of floating point): array with one element for each of the supplied `qpoints` giving the corresponding distance in parsec
  - Examples:
    - `distanceQuantilesEdsd(parallax, parallax_error, 1350, 0.5)[0]` calculates the median of the EDSD distance PDF using a length scale of 1.35kpc
    - `distanceQuantilesEdsd(parallax, parallax_error, 3000, 0.01, 0.99)` returns a 2-element array giving the 1st and 99th percentile of the distance estimate using a length scale of 3kpc
`distanceToModulus( distPc )`

  Converts a distance in parsec to a distance modulus. The formula is `5*log10(distPc)-5`.

  - Parameters:
    - `distPc` (floating point): distance in parsec
  - Return value
    - (floating point): distance modulus in magnitudes
`modulusToDistance( distmod )`

  Converts a distance modulus to a distance in parsec. The formula is `10^(1+distmod/5)`.

  - Parameters:
    - `distmod` (floating point): distance modulus in magnitudes
  - Return value
    - (floating point): distance in parsec
`AU_YRKMS`

  This quantity is A_v, the Astronomical Unit expressed in km.yr/sec. See the Hipparcos catalogue (ESA SP-1200) table 1.2.2 and Eq. 1.5.24.

`PC_AU`

  Parsec in Astronomical Units, equal to 648000/PI.

`PC_YRKMS`

  Parsec in units of km.yr/sec.

`C_KMS`

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

# Json

Functions for working with JSON strings.

Usage of this class to manipulate hierarchical JSON objects is a bit different from the way that most of the other functions in the expression language are used. The main function provided by this class is `jsonObject`, which can be applied to a string value containing a JSON object (legal JSON object strings are enclosed in curly brackets), and returns a JSONObject instance. This JSONObject cannot be used on its own in the rest of the application, but various methods can be applied to it to extract information from its structure. These methods are applied by writing `jsonObject.method(arg,arg,...)` rather than `function(jsonObject,arg,arg,...)`.

Methods you can apply to a JSONObject include:

- `getString(key)`
- `getInt(key)`
- `getDouble(key)`
- `getBoolean(key)`
- `getJSONObject(key)`
- `getJSONArray(key)`

where `key` is a string giving the name with which the member of the JSON object is associated. The first four of the above methods give you string, numeric, or boolean values that you can use in the application for plotting etc. `getJSONObject` returns another JSONObject that you can interrogate with further methods. `getJSONArray` gives you a JSONArray.

You can apply a different set of methods to a JSONArray, including:

- `getString(index)`
- `getInt(index)`
- `getDouble(index)`
- `getBoolean(index)`
- `getJSONObject(index)`
- `getJSONArray(index)`

where `index` is an integer giving the (zero-based) index of the element in the array that you want.

Using these methods you can drill down into the hierarchical structure of a JSON string to retrieve the string, numeric or boolean values that you need. If you are not familiar with this syntax, an example is the best way to illustrate it. Consider the following JSON string, which may be the value in a column named `txt`: { "sequence": 23, "temperature": { "value": 278.5, "units": "Kelvin" }, "operational": true, "readings": [12, null, 23.2, 441, 0] } To obtain the sequence value, you can write: jsonObject(txt).getInt("sequence") to obtain the numeric temperature value, you can write: jsonObject(txt).getJSONObject("temperature").getDouble("value") and to obtain the first element of the readings array, you can write: jsonObject(txt).getJSONArray("readings").getDouble(0)

Other methods are available on JSONObject and JSONArray; you can currently find documentation on them at https://stleary.github.io/JSON-java/. Note in particular that each of the JSONObject.`get*(key)` and JSONArray.`get*(index)` methods is accompanied by a corresponding `opt*` method; where the key/index may not exist, this will probably give effectively the same behaviour (generating a blank result) but may be considerably faster.

This class also contains some other utility functions for working with JSONObjects and JSONArrays; see the function documentation below for details.

Note: This class is somewhat experimental, and the functions and methods may change in future. An attempt will be made to retain the functions and methods described in this section, but those described in the external JSON-java javadocs may be subject to change.

`jsonObject( txt )`

  Converts the supplied string to a JSONObject which can be interrogated further. If the input string doesn't have the syntax of a JSON object, an empty JSONObject will be returned.

  The JSON parsing is currently somewhat lenient, for instance allowing a comma before a closing curly bracket.

  - Parameters:
    - `txt` (String): string assumed to contain a JSON object
  - Return value
    - (JSONObject): JSON object value on which further methods can be called
`jsonArray( txt )`

  Converts the supplied string to a JSONArray which can be interrogated further. If the input string doesn't have the syntax of a JSON array, a zero-length JSONArray will be returned.

  The JSON parsing is currently somewhat lenient, for instance allowing a comma before a closing square bracket.

  - Parameters:
    - `txt` (String): string assumed to contain a JSON array
  - Return value
    - (JSONArray): JSON array value on which further methods can be called
`jsonObjectOpt( txt )`

  Converts the supplied string to a JSON object which can be interrogated further. If the input doesn't have the syntax of a JSON object, null will be returned.

  For most purposes this will behave the same as the `jsonObject` function, but it may be slower if there are many invalid or empty JSON strings.

  - Parameters:
    - `txt` (String): JSON object text
  - Return value
    - (JSONObject): JSON object value on which further methods can be called, or null
`jsonArrayOpt( txt )`

  Converts the supplied string to a JSONArray which can be interrogated further. If the input string doesn't have the syntax of a JSON array, null will be returned.

  - Parameters:
    - `txt` (String): JSON object text
  - Return value
    - (JSONArray): JSON array value on which further methods can be called, or null
`jsonToDoubles( jsonArray )`

  Converts a JSONArray to an array of floating point values. The result will be the same length as the supplied JSONArray, and any element in the JSONArray which cannot be interpreted as a floating point value is represented by a NaN.

  - Parameters:
    - `jsonArray` (JSONArray): JSON Array
  - Return value
    - (array of floating point): floating point array the same length as the input array
  - Example:
    - jsonToDoubles(jsonArray("[true, \"two\", 3.0, 4, null"])) = [NaN, NaN, 3.0, 4.0, NaN]
`jsonToStrings( jsonArray )`

  Converts a JSONArray to an array of string values.

  - Parameters:
    - `jsonArray` (JSONArray): JSON Array
  - Return value
    - (array of String): string array the same length as the input array
  - Example:
    - jsonToStrings(jsonArray("[true, \"two\", 3.0, 4, null]")) = ["true", "two", "3.0", "4", null]
`jsonGetKeys( jsonObject )`

  Returns an array giving keys for each key-value pair in a JSON object. The members of a JSON object are not ordered, so no order can be guaranteed in the output array.

  - Parameters:
    - `jsonObject` (JSONObject): JSON object
  - Return value
    - (array of String): string array containing keys of object
  - Example:
    - jsonGetKeys(jsonObject("{\"one\", 1, \"two\", 2, \"three\", 3}")) = ["one", "two", "three"]

# KCorrections

Functions for calculating K-corrections.

`kCorr( filter, redshift, colorType, colorValue )`

  Calculates K-corrections. This allows you to determine K-corrections for a galaxy, given its redshift and a colour. Filters for GALEX, SDSS, UKIDSS, Johnson, Cousins and 2MASS are covered.

  To define the calculation you must choose both a filter, specified as a `KCF_*` constant, and a colour (filter pair) specified as a `KCC_*` constant. For each available filter, only certain colours are available, as described in the documentation of the relevant `KCF_*` constant.

  The algorithm used is described at http://kcor.sai.msu.ru/. This is based on the paper "Analytical Approximations of K-corrections in Optical and Near-Infrared Bands" by I.Chilingarian, A.-L.Melchior and I.Zolotukhin (2010MNRAS.405.1409C), but extended to include GALEX UV bands and with redshift coverage up to 0.5 as described in "Universal UV-optical Colour-Colour-Magnitude Relation of Galaxies" by I.Chilingarian and I.Zolotukhin (2012MNRAS.419.1727C).

  - Parameters:
    - `filter` (KFilter): `KCF_*` constant defining the filter for which you want to calculate the K-correction
    - `redshift` (floating point): galaxy redshift; this should be in the range 0-0.5
    - `colorType` (KColor): `KCC_*` constant defining the filter pair for the calculation; check the `KCF_*` constant documentation to see which ones are permitted for a given filter
    - `colorValue` (floating point): the value of the colour
  - Return value
    - (floating point): K correction
  - Examples:
    - `kCorr(KCF_g, 0.16, KCC_gr, -0.8) = 3.593`
    - `kCorr(KCF_FUV, 0.48, KCC_FUVu, 0.31) = -0.170`
`KCF_FUV`

  GALEX FUV filter (AB). Use with KCC_FUVNUV or KCC_FUVu.

`KCF_NUV`

  GALEX NUV filter (AB). Use with KCC_NUVg or KCC_NUVr.

`KCF_u`

  SDSS u filter (AB). Use with KCC_ur, KCC_ui or KCC_uz.

`KCF_g`

  SDSS g filter (AB). Use with KCC_gr, KCC_gi or KCC_gz.

`KCF_r`

  SDSS r filter (AB). Use with KCC_gr or KCC_ur.

`KCF_i`

  SDSS i filter (AB). Use with KCC_gi or KCC_ui.

`KCF_z`

  SDSS z filter (AB). Use with KCC_rz, KCC_gz or KCC_uz.

`KCF_Y`

  UKIDSS Y filter (AB). Use with KCC_YH or KCC_YK.

`KCF_J`

  UKIDSS J filter (AB). Use with KCC_JK or KCC_JH.

`KCF_H`

  UKIDSS H filter (AB). Use with KCC_HK or KCC_JH.

`KCF_K`

  UKIDSS K filter (AB). Use with KCC_JK or KCC_HK.

`KCF_U`

  Johnson U filter (Vega). Use with KCC_URc.

`KCF_B`

  Johnson B filter (Vega). Use with KCC_BRc or KCC_BIc.

`KCF_V`

  Johnson V filter (Vega). Use with KCC_VIc or KCC_VRc.

`KCF_Rc`

  Cousins Rc filter (Vega). Use with KCC_BRc or KCC_VRc.

`KCF_Ic`

  Cousins Ic filter (Vega). Use with KCC_VIc.

`KCF_J2`

  2MASS J filter (Vega). Use with KCC_J2Ks2 or KCC_J2H2.

`KCF_H2`

  2MASS H filter (Vega). Use with KCC_H2Ks2 or KCC_J2H2.

`KCF_Ks2`

  2MASS Ks filter (Vega). Use with KCC_J2Ks2 or KCC_H2Ks2.

`KCC_BIc`

  Johnson B - Cousins Ic colour.

`KCC_BRc`

  Johnson B - Cousins Rc colour.

`KCC_FUVNUV`

  GALEX FUV - NUV colour.

`KCC_FUVu`

  GALEX FUV - SDSS u colour.

`KCC_gi`

  SDSS g - i colour.

`KCC_gr`

  SDSS g - r colour.

`KCC_gz`

  SDSS g - z colour.

`KCC_H2Ks2`

  2MASS H - Ks colour.

`KCC_HK`

  UKIDSS H - K colour.

`KCC_J2H2`

  2MASS J - H colour.

`KCC_J2Ks2`

  2MASS J - Ks colour.

`KCC_JH`

  UKIDSS J - H colour.

`KCC_JK`

  UKIDSS J - K colour.

`KCC_NUVg`

  GALEX NUV - SDSS g colour.

`KCC_NUVr`

  GALEX NUV - SDSS r colour.

`KCC_rz`

  SDSS r - SDSS z colour.

`KCC_ui`

  SDSS u - SDSS i colour.

`KCC_URc`

  Johnson U - Cousins Rc colour.

`KCC_ur`

  SDSS u - r colour.

`KCC_uz`

  SDSS u - z colour.

`KCC_VIc`

  Johnson V - Cousins Ic colour.

`KCC_VRc`

  Johnson V - Cousins Rc colour.

`KCC_YH`

  UKIDSS Y - H colour.

`KCC_YK`

  UKIDSS Y - K colour.

# 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.

`sum( values, ... )`

  Returns the sum of all the non-blank supplied arguments.

  - Parameters:
    - `values` (floating point, one or more): one or more numeric values
  - Return value
    - (floating point): sum of `values`
  - Examples:
    - `sum(1, 3, 99) = 103`
    - `sum(1, 3, NaN) = 4`
`mean( values, ... )`

  Returns the mean of all the non-blank supplied arguments.

  - Parameters:
    - `values` (floating point, one or more): one or more numeric values
  - Return value
    - (floating point): mean of `values`
  - Examples:
    - `mean(2, 4, 6, 8) = 5`
    - `mean(100.5, 99.5, NaN) = 100`
`variance( values, ... )`

  Returns the population variance of the non-blank supplied arguments.

  - Parameters:
    - `values` (floating point, one or more): one or more numeric values
  - Return value
    - (floating point): population variance of `values`
  - Examples:
    - `variance(0, 3, 4, 3, 0) = 2.8`
    - `variance(0, 3, NaN, 3, NaN) = 2`
`stdev( values, ... )`

  Returns the population standard deviation of the non-blank supplied arguments.

  - Parameters:
    - `values` (floating point, one or more): one or more numeric values
  - Return value
    - (floating point): population standard deviation of `values`
  - Example:
    - `stdev(-3, -2, 0, 0, 1, 2, 3, 4, 5, 6) = 2.8`
`min( values, ... )`

  Returns the minimum of all the non-blank supplied arguments.

  - Parameters:
    - `values` (floating point, one or more): one or more numeric values
  - Return value
    - (floating point): minimum of `values`
  - Example:
    - `min(20, 25, -50, NaN, 101) = -50`
`max( values, ... )`

  Returns the maximum of all the non-blank supplied arguments.

  - Parameters:
    - `values` (floating point, one or more): one or more numeric values
  - Return value
    - (floating point): maximum of `values`
  - Example:
    - `max(20, 25, -50, NaN, 101) = 101`
`median( values, ... )`

  Returns the median of all the non-blank supplied arguments.

  - Parameters:
    - `values` (floating point, one or more): one or more numeric values
  - Return value
    - (floating point): median of `values`
  - Example:
    - `median(-100000, 5, 6, 7, 8) = 6`
`countTrue( values, ... )`

  Returns the number of true values in a list of boolean arguments. Note if any of the values are blank, the result may be blank as well.

  - Parameters:
    - `values` (boolean, one or more): one or more true/false values
  - Return value
    - (integer): number of elements of `values` that are true
  - Example:
    - `countTrue(false, false, true, false, true) = 2`

# Maths

Standard mathematical and trigonometric functions. Trigonometric functions work with angles in radians.

`sin( theta )`

  Sine of an angle.

  - Parameters:
    - `theta` (floating point): an angle, in radians.
  - Return value
    - (floating point): the sine of the argument.
`cos( theta )`

  Cosine of an angle.

  - Parameters:
    - `theta` (floating point): an angle, in radians.
  - Return value
    - (floating point): the cosine of the argument.
`tan( theta )`

  Tangent of an angle.

  - Parameters:
    - `theta` (floating point): an angle, in radians.
  - Return value
    - (floating point): the tangent of the argument.
`asin( x )`

  Arc sine of an angle. The result is in the range of -pi/2 through pi/2.

  - Parameters:
    - `x` (floating point): the value whose arc sine is to be returned.
  - Return value
    - (floating point): the arc sine of the argument (radians)
`acos( x )`

  Arc cosine of an angle. The result is in the range of 0.0 through pi.

  - Parameters:
    - `x` (floating point): the value whose arc cosine is to be returned.
  - Return value
    - (floating point): the arc cosine of the argument (radians)
`atan( x )`

  Arc tangent of an angle. The result is in the range of -pi/2 through pi/2.

  - Parameters:
    - `x` (floating point): the value whose arc tangent is to be returned.
  - Return value
    - (floating point): the arc tangent of the argument (radians)
`ln( x )`

  Natural logarithm.

  - Parameters:
    - `x` (floating point): argument
  - Return value
    - (floating point): loge(x)
`exp( x )`

  Euler's number e raised to a power.

  - Parameters:
    - `x` (floating point): the exponent to raise e to.
  - Return value
    - (floating point): the value ex, where e is the base of the natural logarithms.
`log10( x )`

  Logarithm to base 10.

  - Parameters:
    - `x` (floating point): argument
  - Return value
    - (floating point): log10(x)
`exp10( x )`

  Power of 10. This convenience function is identical to `pow(10,x)`.

  - Parameters:
    - `x` (floating point): argument
  - Return value
    - (floating point): 10x
`sqrt( x )`

  Square root. The result is correctly rounded and positive.

  - Parameters:
    - `x` (floating point): a value.
  - Return value
    - (floating point): the positive square root of `x`. If the argument is NaN or less than zero, the result is NaN.
`square( x )`

  Raise to the power 2.

  - Parameters:
    - `x` (floating point): a value
  - Return value
    - (floating point): x * x
`hypot( xs, ... )`

  Returns the square root of the sum of squares of its arguments. In the 2-argument case, doing it like this may avoid intermediate overflow or underflow.

  - Parameters:
    - `xs` (floating point, one or more): one or more numeric values
  - Return value
    - (floating point): sqare root of sum of squares of arguments
  - Examples:
    - `hypot(3,4) = 5`
    - `hypot(2,2,2,2) = 4`
`atan2( y, x )`

  Converts rectangular coordinates (`x`,`y`) to polar (`r`,`theta`). This method computes the phase `theta` by computing an arc tangent of `y/x` in the range of -pi to pi.

  - Parameters:
    - `y` (floating point): the ordinate coordinate
    - `x` (floating point): the abscissa coordinate
  - Return value
    - (floating point): the `theta` component (radians) of the point (`r`,`theta`) in polar coordinates that corresponds to the point (`x`,`y`) in Cartesian coordinates.
`pow( a, b )`

  Exponentiation. The result is the value of the first argument raised to the power of the second argument.

  - Parameters:
    - `a` (floating point): the base.
    - `b` (floating point): the exponent.
  - Return value
    - (floating point): the value `ab`.
`sinh( x )`

  Hyperbolic sine.

  - Parameters:
    - `x` (floating point): parameter
  - Return value
    - (floating point): result
`cosh( x )`

  Hyperbolic cosine.

  - Parameters:
    - `x` (floating point): parameter
  - Return value
    - (floating point): result
`tanh( x )`

  Hyperbolic tangent.

  - Parameters:
    - `x` (floating point): parameter
  - Return value
    - (floating point): result
`asinh( x )`

  Inverse hyperbolic sine.

  - Parameters:
    - `x` (floating point): parameter
  - Return value
    - (floating point): result
`acosh( x )`

  Inverse hyperbolic cosine.

  - Parameters:
    - `x` (floating point): parameter
  - Return value
    - (floating point): result
`atanh( x )`

  Inverse hyperbolic tangent.

  - Parameters:
    - `x` (floating point): parameter
  - Return value
    - (floating point): result
`symlog( linthresh, linscale, x )`

  Symmetric logarithm mapping function. This function is not generally of much mathematical use, but it is available as one of the scaling options for plot axes. It is linear near the origin (abs(x)<=`linthresh`) and positive/negative logarithmic outside that region.

  The function is: |x| <= linthresh: x * linscale / linthresh |x| >= linthresh: sgn(x) * (linscale + log10(|x|) - log10(linthresh))

  - Parameters:
    - `linthresh` (floating point): linear threshold, below which absolute value the function is linear; must be >0
    - `linscale` (floating point): linear scale, being the ratio of the half-extent of the linear mapped region to the extent of a decade in the logarithmic region; must be >0
    - `x` (floating point): value to map
  - Return value
    - (floating point): mapped value
`E`

  Euler's number e, the base of natural logarithms.

`PI`

  Pi, the ratio of the circumference of a circle to its diameter.

`Infinity`

  Positive infinite floating point value.

`NaN`

  Not-a-Number floating point value. Use with care; arithmetic and logical operations behave in strange ways near NaN (for instance, `NaN!=NaN`). For most purposes this is equivalent to the blank value.

# Randoms

Functions concerned with random number generation.

There are two flavours of functions here: index-based (`random*`) and sequential (`nextRandom*`). Briefly, the index-based ones are safer to use, but provide poorer random statistics, while the sequential ones provide decent randomness but are not suitable for use in some/most contexts. They are documented separately below.

Index-based functions

The functions named `random*` all take an `index` parameter which determines the value of the result; the same index always leads to the same output, but there is not supposed to be any obvious relationship between index and output. An explicit index is required to ensure that a given cell always has the same value, since cell values are in general calculated on demand. The quality of the randomness for these functions may not be that good.

In most cases, the table row index, available as the special token `$0`, is a suitable value for the `index` parameter.

If several different random values are required in the same table row, one way is to supply a different row-based index value for each one, e.g. `random(2*$0)` and `random(2*$0+1)`. However, this tends to introduce a correlation between the random values in the same row, so a better (though in some cases slower) solution is to use one of the array-generating functions, e.g. `randomArray($0,2)[0]` and `randomArray($0,2)[1]`.

The output is deterministic, in the sense that the same invocation will always generate the same "random" number, even across different machines. However, in view of the comments in the implementation note below, the output may be subject to change in the future if some improved algorithm can be found, so this guarantee does not necessarily hold across software versions.

Implementation Note: The requirement for mapping a given input index deterministically to a pseudo-random number constrains the way that the random number generation is done; most well-studied RNGs generate sequences of random numbers, but that approach cannot be used here, since these sequences do not admit of random-access. What we do instead is to scramble the input index somewhat and use that as the seed for an instance of Java's `Random` class, which is then used to produce one or more random numbers per input index. Some thought and experimentation has gone into the current implementation (I bought a copy of Knuth Vol. 2 specially!) and an eyeball check of the results doesn't look all that bad, but it's still probably not very good, and is not likely to pass random number quality tests (though I haven't tried). A more respectable approach might be to use a cryptographic-grade hash function on the supplied index, but that's likely to be much slower. If there is demand, something like that could be added as an alternative option. In the mean time, beware if you use these random numbers for scientifically sensitive output.

Sequential functions

The functions named `nextRandom*` have no arguments, and supply the next value in a global sequence when they are evaluated. These can be used if scanning through a table once (for instance when writing a table using STILTS), but they are not suitable for contexts that should supply a fixed value. For instance if you use them to define the value of a table cell in TOPCAT, that cell may have a different value every time you look at it, which may have disconcerting results. These use the java.util.Random class in a more standard way than the index-based functions and should provide random numbers of reasonable quality.

`random( index )`

  Generates a pseudo-random number sampled from a uniform distribution between 0 and 1.

  Note: The randomness may not be very high quality.

  - Parameters:
    - `index` (long integer): input value, typically row index "`$0`"
  - Return value
    - (floating point): random number between 0 and 1
`randomGaussian( index )`

  Generates a pseudo-random number sampled from a Gaussian distribution with mean of 0.0 and standard deviation of 1.0.

  Note: The randomness may not be very high quality.

  - Parameters:
    - `index` (long integer): input value, typically row index "`$0`"
  - Return value
    - (floating point): random number
`randomArray( index, n )`

  Generates an array of pseudo-random numbers sampled from a uniform distribution between 0 and 1.

  Note: The randomness may not be very high quality.

  - Parameters:
    - `index` (long integer): input value, typically row index "`$0`"
    - `n` (integer): size of output array
  - Return value
    - (array of floating point): `n`-element array of random numbers between 0 and 1
`randomGaussianArray( index, n )`

  Generates an array of pseudo-random numbers sampled from a Gaussian distribution with mean of 0.0 and standard deviation of 1.0.

  Note: The randomness may not be very high quality.

  - Parameters:
    - `index` (long integer): input value, typically row index "`$0`"
    - `n` (integer): size of output array
  - Return value
    - (array of floating point): `n`-element array of random numbers
`nextRandom( )`

  Returns the next value in a random sequence, sampled from a uniform distribution between 0 and 1.

  This function will give a different result every time, hence it is not suitable for use in an expression which should have a fixed value, for instance to define a TOPCAT column.

  - Return value
    - (floating point): random number between 0 and 1
`nextRandomGaussian( )`

  Returns the next value in a random sequence, sampled from a Gaussian distribution with mean of 0.0 and standard deviation of 1.0.

  This function will give a different result every time, hence it is not suitable for use in an expression which should have a fixed value, for instance to define a TOPCAT column.

  - Return value
    - (floating point): random number

# Shapes

Functions useful for working with shapes in the (X, Y) plane.

`polyLine( x, xys, ... )`

  Function of `x` defined by straight line segments between a specified list of vertices. The vertices are specified as a sequence of Xi, Yi pairs, for which the Xi values must be monotonic. The line segment at each end of the specified point sequence is considered to be extended to infinity. If only two points are specified, this is the equation of a straight line between those points. As a special case, if only one point is specified, the line is considered to be a horizontal line (equal to the sole specified Yi coordinate for all `x`).

  By reversing the Xi and Yi values, this function can equally be used to represent a function `X(y)` rather than `Y(x)`.

  If the number of coordinates is odd, or the Xi values are not monotonic, behaviour is undefined.

  - Parameters:
    - `x` (floating point): X value at which function is to be evaluated
    - `xys` (floating point, one or more): 2N arguments (`x1`, `y1`, `x2`, `y2`, ..., `xN`, `yN`) giving vertices of an N-point line with monotonically increasing or decreasing X values
  - Return value
    - (floating point): Y coordinate of poly-line for specified `x`
  - Example:
    - `polyLine(5, 0,0, 2,2) = 5`
`isInside( x, y, xys, ... )`

  Indicates whether a given test point is inside a polygon defined by specified list of vertices. The vertices are specified as a sequence of Xi, Yi pairs.

  If the number of coordinates is odd, the behaviour is not defined.

  - Parameters:
    - `x` (floating point): X coordinate of test point
    - `y` (floating point): Y coordinate of test point
    - `xys` (floating point, one or more): 2N arguments (`x1`, `y1`, `x2`, `y2`, ..., `xN`, `yN`) giving vertices of an N-sided polygon
  - Return value
    - (boolean): true iff test point is inside, or on the border of, the polygon
  - Examples:
    - `isInside(0.5,0.5, 0,0, 0,1, 1,1, 1,0) = true`
    - `isInside(0,0, array(10,20, 20,20, 20,10)) = false`

# Sky

Functions useful for working with shapes on a sphere. All angles are expressed in degrees.

`skyDistance( lon1, lat1, lon2, lat2 )`

  Calculates the separation (distance around a great circle) of two points on the sky in degrees.

  This function is identical to `skyDistanceDegrees` in class `CoordsDegrees`.

  - Parameters:
    - `lon1` (floating point): point 1 longitude in degrees
    - `lat1` (floating point): point 1 latitude in degrees
    - `lon2` (floating point): point 2 longitude in degrees
    - `lat2` (floating point): point 2 latitude in degrees
  - Return value
    - (floating point): angular distance between point 1 and point 2 in degrees
`midLon( lon1, lon2 )`

  Determines the longitude mid-way between two given longitudes. In most cases this is just the mean of the two values, but this function copes correctly with the case where the given values straddle the lon=0 line.

  - Parameters:
    - `lon1` (floating point): first longitude in degrees
    - `lon2` (floating point): second longitude in degrees
  - Return value
    - (floating point): longitude midway between the given values
  - Examples:
    - `midLon(204.0, 203.5) = 203.75`
    - `midLon(2, 359) = 0.5`
`midLat( lat1, lat2 )`

  Determines the latitude midway between two given latitudes. This simply returns the mean of the two values, but is supplied for convenience to use alongside the `midLon` function.

  - Parameters:
    - `lat1` (floating point): first latitude in degrees
    - `lat2` (floating point): second latitude in degrees
  - Return value
    - (floating point): latitude midway between the given values
  - Example:
    - `midLat(23.5, 24.0) = 23.75`
`inSkyEllipse( lon0, lat0, lonCenter, latCenter, rA, rB, posAng )`

  Tests whether a given sky position is inside a given ellipse.

  - Parameters:
    - `lon0` (floating point): test point longitude in degrees
    - `lat0` (floating point): test point latitude in degrees
    - `lonCenter` (floating point): ellipse center longitude in degrees
    - `latCenter` (floating point): ellipse center latitude in degrees
    - `rA` (floating point): ellipse first principal radius in degrees
    - `rB` (floating point): ellipse second principal radius in degrees
    - `posAng` (floating point): position angle in degrees from the North pole to the primary axis of the ellipse in the direction of increasing longitude
  - Return value
    - (boolean): true iff test point is inside, or on the border of, the ellipse
`inSkyPolygon( lon0, lat0, lonLats, ... )`

  Tests whether a given sky position is inside the polygon defined by a given set of vertices. The bounding lines of the polygon are the minor arcs of great circles between adjacent vertices, with an extra line assumed between the first and last supplied vertex. The interior of the polygon is defined to be the smaller of the two regions separated by the boundary. The vertices are specified as a sequence of loni, lati pairs.

  The implementation of this point-in-polygon function is mostly correct, but may not be bulletproof. It ought to work for relatively small regions anywhere on the sky, but for instance it may get the sense wrong for regions that extend to cover both poles.

  - Parameters:
    - `lon0` (floating point): test point longitude in degrees
    - `lat0` (floating point): test point latitude in degrees
    - `lonLats` (floating point, one or more): 2N arguments (`lon1`, `lat1`, `lon2`, `lat2`, ..., `lonN`, `latN`) giving (longitude, latitude) vertices of an N-sided polygon in degrees
  - Return value
    - (boolean): true iff test point is inside, or on the border of, the polygon

# Strings

String manipulation and query functions.

`concat( strings, ... )`

  Concatenates multiple values into a string. In some cases the same effect can be achieved by writing `s1+s2+...`, but this method makes sure that values are converted to strings, with the blank value invisible.

  - Parameters:
    - `strings` (Object, one or more): one or more strings
  - Return value
    - (String): concatenation of input strings, without separators
  - Examples:
    - `concat("blue", "moon") = "bluemoon"`
    - `concat("1", 2, 3, "4") = "1234"`
    - `concat("Astro", null, "Physics") = "AstroPhysics"`
`join( separator, words, ... )`

  Joins multiple values into a string, with a given separator between each pair.

  - Parameters:
    - `separator` (String): string to insert between adjacent words
    - `words` (Object, one or more): one or more values to join
  - Return value
    - (String): input values joined together with `separator`
  - Examples:
    - `join("<->", "alpha", "beta", "gamma") = "alpha<->beta<->gamma"`
    - `join(" ", 1, "brown", "mouse") = "1 brown mouse"`
`equals( s1, s2 )`

  Determines whether two strings are equal. Note you should use this function instead of `s1==s2`, which can (for technical reasons) return false even if the strings are the same.

  - Parameters:
    - `s1` (String): first string
    - `s2` (String): second string
  - Return value
    - (boolean): true if s1 and s2 are both blank, or have the same content
`equalsIgnoreCase( s1, s2 )`

  Determines whether two strings are equal apart from possible upper/lower case distinctions.

  - Parameters:
    - `s1` (String): first string
    - `s2` (String): second string
  - Return value
    - (boolean): true if s1 and s2 are both blank, or have the same content apart from case folding
  - Examples:
    - `equalsIgnoreCase("Cygnus", "CYGNUS") = true`
    - `equalsIgnoreCase("Cygnus", "Andromeda") = false`
`startsWith( whole, start )`

  Determines whether a string starts with a certain substring.

  - Parameters:
    - `whole` (String): the string to test
    - `start` (String): the sequence that may appear at the start of `whole`
  - Return value
    - (boolean): true if the first few characters of `whole` are the same as `start`
  - Example:
    - `startsWith("CYGNUS X-1", "CYG") = true`
`endsWith( whole, end )`

  Determines whether a string ends with a certain substring.

  - Parameters:
    - `whole` (String): the string to test
    - `end` (String): the sequence that may appear at the end of `whole`
  - Return value
    - (boolean): true if the last few characters of `whole` are the same as `end`
  - Example:
    - `endsWith("M32", "32") = true`
`contains( whole, sub )`

  Determines whether a string contains a given substring.

  - Parameters:
    - `whole` (String): the string to test
    - `sub` (String): the sequence that may appear within `whole`
  - Return value
    - (boolean): true if the sequence `sub` appears within `whole`
  - Example:
    - `contains("Vizier", "izi") = true`
`length( str )`

  Returns the length of a string in characters.

  - Parameters:
    - `str` (String): string
  - Return value
    - (integer): number of characters in `str`
  - Example:
    - `length("M34") = 3`
`split( words )`

  Splits a string into an array of space-separated words. One or more spaces separates each word from the next. Leading and trailing spaces are ignored.

  The result is an array of strings, and if you want to use the individual elements you need to use square-bracket indexing, with `[0]` representing the first object

  - Parameters:
    - `words` (String): string with embedded spaces delimiting the words
  - Return value
    - (array of String): array of the separate words; you can extract the individual words from the result using square bracket indexing
  - Examples:
    - `split("211:54:01 +29:33:41")` gives a 2-element array, first element is `"211:54:01"` and second element is `"+29:33:41"`.
    - `split(" cat dog cow ")[1] = "dog"`
`split( words, regex )`

  Splits a string into an array of words separated by a given regular expression.

  The result is an array of strings, and if you want to use the individual elements you need to use square-bracket indexing, with `[0]` representing the first object

  - Parameters:
    - `words` (String): string with multiple parts
    - `regex` (String): regular expression delimiting the different words in the `words` parameter
  - Return value
    - (array of String): array of the separate words; you can extract the individual words from the result using square bracket indexing
  - Examples:
    - `split("cat, dog, cow", ", *")` gives a 3-element string array.
    - `split("23.0, 45.92", ", ")[0] = "23.0"`
    - `parseDouble(split("23.0, 45.92", ", ")[0]) = 23`
`matches( str, regex )`

  Tests whether a string matches a given regular expression.

  - Parameters:
    - `str` (String): string to test
    - `regex` (String): regular expression string
  - Return value
    - (boolean): true if `regex` matches `str` anywhere
  - Example:
    - `matches("Hubble", "ub") = true`
`matchGroup( str, regex )`

  Returns the first grouped expression matched in a string defined by a regular expression. A grouped expression is one enclosed in parentheses.

  - Parameters:
    - `str` (String): string to match against
    - `regex` (String): regular expression containing a grouped section
  - Return value
    - (String): contents of the matched group (or null, if `regex` didn't match `str`)
  - Example:
    - `matchGroup("NGC28948b","NGC([0-9]*)") = "28948"`
`replaceFirst( str, regex, replacement )`

  Replaces the first occurrence of a regular expression in a string with a different substring value.

  - Parameters:
    - `str` (String): string to manipulate
    - `regex` (String): regular expression to match in `str`
    - `replacement` (String): replacement string
  - Return value
    - (String): same as `str`, but with the first match (if any) of `regex` replaced by `replacement`
  - Example:
    - `replaceFirst("Messier 61", "Messier ", "M-") = "M-61"`
`replaceAll( str, regex, replacement )`

  Replaces all occurrences of a regular expression in a string with a different substring value.

  - Parameters:
    - `str` (String): string to manipulate
    - `regex` (String): regular expression to match in `str`
    - `replacement` (String): replacement string
  - Return value
    - (String): same as `str`, but with all matches of `regex` replaced by `replacement`
  - Example:
    - `replaceAll("1-2--3---4","--*","x") = "1x2x3x4"`
`substring( str, startIndex )`

  Returns the last part of a given string. The substring begins with the character at the specified index and extends to the end of this string.

  - Parameters:
    - `str` (String): the input string
    - `startIndex` (integer): the beginning index, inclusive
  - Return value
    - (String): last part of `str`, omitting the first `startIndex` characters
  - Example:
    - `substring("Galaxy", 2) = "laxy"`
`substring( str, startIndex, endIndex )`

  Returns a substring of a given string. The substring begins with the character at `startIndex` and continues to the character at index `endIndex-1` Thus the length of the substring is `endIndex-startIndex`.

  - Parameters:
    - `str` (String): the input string
    - `startIndex` (integer): the beginning index, inclusive
    - `endIndex` (integer): the end index, inclusive
  - Return value
    - (String): substring of `str`
  - Example:
    - `substring("Galaxy", 2, 5) = "lax"`
`toUpperCase( str )`

  Returns an uppercased version of a string.

  - Parameters:
    - `str` (String): input string
  - Return value
    - (String): uppercased version of `str`
  - Example:
    - `toUpperCase("Universe") = "UNIVERSE"`
`toLowerCase( str )`

  Returns an lowercased version of a string.

  - Parameters:
    - `str` (String): input string
  - Return value
    - (String): lowercased version of `str`
  - Example:
    - `toLowerCase("Universe") = "universe"`
`trim( str )`

  Trims whitespace from both ends of a string.

  - Parameters:
    - `str` (String): input string
  - Return value
    - (String): str with any spaces trimmed from start and finish
  - Examples:
    - `trim(" some text ") = "some text"`
    - `trim("some text") = "some text"`
`padWithZeros( value, ndigit )`

  Takes an integer argument and returns a string representing the same numeric value but padded with leading zeros to a specified length.

  - Parameters:
    - `value` (long integer): numeric value to pad
    - `ndigit` (integer): the number of digits in the resulting string
  - Return value
    - (String): a string evaluating to the same as `value` with at least `ndigit` characters
  - Example:
    - `padWithZeros(23,5) = "00023"`
`desigToRa( designation )`

  Attempts to determine the ICRS Right Ascension from an IAU-style designation such as "`2MASS J04355524+1630331`" following the specifications in the document https://cdsweb.u-strasbg.fr/Dic/iau-spec.html.

  Note: this function should be used with considerable care. Such designators are intended for object identification and not for communicating sky positions, so that the resulting positions are likely to lack precision, and may be inaccurate. If positional information is available from other sources, it should almost certainly be used instead. But if there's no other choice, this may be used as a fallback.

  Note also that a designator with no coordsystem-specific flag character (a leading "`J`", "`B`" or "`G`") is considered to be B1950, not J2000.

  - Parameters:
    - `designation` (String): designation string in IAU format
  - Return value
    - (floating point): ICRS right ascension in degreees, or blank if no position can be decoded
  - Examples:
    - `desigToRa("2MASS J04355524+1630331") = 60.98016`
    - `desigToRa("PSR J120000.0+450000.0") = 180`
    - `desigToDec("PSR B120000.0+450000.0") = 180.639096`
    - `desigToRa("PN G001.2-00.3") = 267.403`
    - `desigToRa("NGC 4993") = NaN`
`desigToDec( designation )`

  Attempts to determine the ICRS Declination from an IAU-style designation such as "`2MASS J04355524+1630331`" following the specifications in the document https://cdsweb.u-strasbg.fr/Dic/iau-spec.html.

  Note: this function should be used with considerable care. Such designators are intended for object identification and not for communicating sky positions, so that the resulting positions are likely to lack precision, and may be inaccurate. If positional information is available from other sources, it should almost certainly be used instead. But if there's no other choice, this may be used as a fallback.

  Note also that a designator with no coordsystem-specific flag character (a leading "`J`", "`B`" or "`G`") is considered to be B1950, not J2000.

  - Parameters:
    - `designation` (String): designation string in IAU format
  - Return value
    - (floating point): ICRS declination in degrees, or blank if no position can be decoded
  - Examples:
    - `desigToDec("2MASS J04355524+1630331") = 16.50919`
    - `desigToDec("PSR J120000.0+450000.0") = 45`
    - `desigToDec("PSR B120000.0+450000.0") = 44.72167`
    - `desigToDec("PN G001.2-00.3") = -28.06457`
    - `desigToDec("NGC 4993") = NaN`
`desigToIcrs( designation )`

  Attempts to decode an IAU-style designation such as "`2MASS J04355524+1630331`" to determine its sky position, following the specifications in the document https://cdsweb.u-strasbg.fr/Dic/iau-spec.html.

  Obviously, this only works where the sequence part of the designation takes one of the family of coordinate-based forms.

  Note: this function should be used with considerable care. Such designators are intended for object identification and not for communicating sky positions, so that the resulting positions are likely to lack precision, and may be inaccurate. If positional information is available from other sources, it should almost certainly be used instead. But if there's no other choice, this may be used as a fallback.

  Note also that a designator with no coordsystem-specific flag character (a leading "`J`", "`B`" or "`G`") is considered to be B1950, not J2000.

  - Parameters:
    - `designation` (String): designation string in IAU format
  - Return value
    - (array of floating point): 2-element array giving ICRS (RA,Dec) in degrees, or `null` if no position can be decoded

# 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.

`healpixNestIndex( k, lon, lat )`

  Gives the pixel index for a given sky position in the HEALPix NEST scheme.

  - Parameters:
    - `k` (integer): HEALPix order (0..29)
    - `lon` (floating point): longitude in degrees
    - `lat` (floating point): latitude in degrees
  - Return value
    - (long integer): pixel index
  - See Also:
    - HEALPix web site
`healpixRingIndex( k, lon, lat )`

  Gives the pixel index for a given sky position in the HEALPix RING scheme.

  - Parameters:
    - `k` (integer): HEALPix order (0..29)
    - `lon` (floating point): longitude in degrees
    - `lat` (floating point): latitude in degrees
  - Return value
    - (long integer): pixel index
  - See Also:
    - HEALPix web site
`healpixNestLon( k, index )`

  Returns the longitude of the approximate center of the tile with a given index in the HEALPix NEST scheme.

  Note: the `index` parameter is 0-based, unlike the table row index special token `$index` (a.k.a. `$0`), which is 1-based. So if the HEALpix index is implicitly determined by the table row, the value `$index-1` should be used.

  - Parameters:
    - `k` (integer): HEALPix order (0..29)
    - `index` (long integer): healpix index
  - Return value
    - (floating point): longitude in degrees
  - See Also:
    - HEALPix web site
`healpixNestLat( k, index )`

  Returns the latitude of the approximate center of the tile with a given index in the HEALPix NEST scheme.

  Note: the `index` parameter is 0-based, unlike the table row index special token `$index` (a.k.a. `$0`), which is 1-based. So if the HEALpix index is implicitly determined by the table row, the value `$index-1` should be used.

  - Parameters:
    - `k` (integer): HEALPix order (0..29)
    - `index` (long integer): healpix index
  - Return value
    - (floating point): latitude in degrees
  - See Also:
    - HEALPix web site
`healpixRingLon( k, index )`

  Returns the longitude of the approximate center of the tile with a given index in the HEALPix RING scheme.

  Note: the `index` parameter is 0-based, unlike the table row index special token `$index` (a.k.a. `$0`), which is 1-based. So if the HEALpix index is implicitly determined by the table row, the value `$index-1` should be used.

  - Parameters:
    - `k` (integer): HEALPix order (0..29)
    - `index` (long integer): healpix index
  - Return value
    - (floating point): longitude in degrees
  - See Also:
    - HEALPix web site
`healpixRingLat( k, index )`

  Returns the latitude of the approximate center of the tile with a given index in the HEALPix RING scheme.

  Note: the `index` parameter is 0-based, unlike the table row index special token `$index` (a.k.a. `$0`), which is 1-based. So if the HEALpix index is implicitly determined by the table row, the value `$index-1` should be used.

  - Parameters:
    - `k` (integer): HEALPix order (0..29)
    - `index` (long integer): healpix index
  - Return value
    - (floating point): latitude in degrees
  - See Also:
    - HEALPix web site
`healpixNestToRing( k, nestIndex )`

  Converts a healpix tile index from the NEST to the RING scheme at a given order.

  Note: the `nestIndex` parameter is 0-based, unlike the table row index special token `$index` (a.k.a. `$0`), which is 1-based. So if the HEALpix index is implicitly determined by the table row, the value `$index-1` should be used.

  - Parameters:
    - `k` (integer): HEALPix order (0..29)
    - `nestIndex` (long integer): pixel index in NEST scheme
  - Return value
    - (long integer): pixel index in RING scheme
  - See Also:
    - HEALPix web site
`healpixRingToNest( k, ringIndex )`

  Converts a healpix tile index from the RING to the NEST scheme at a given order.

  Note: the `ringIndex` parameter is 0-based, unlike the table row index special token `$index` (a.k.a. `$0`), which is 1-based. So if the HEALpix index is implicitly determined by the table row, the value `$index-1` should be used.

  - Parameters:
    - `k` (integer): HEALPix order (0..29)
    - `ringIndex` (long integer): pixel index in RING scheme
  - Return value
    - (long integer): pixel index in NEST scheme
  - See Also:
    - HEALPix web site
`healpixK( pixelsize )`

  Gives the HEALPix resolution parameter suitable for a given pixel size. This `k` value (also variously known as order, level, depth) is the logarithm to base 2 of the Nside parameter.

  - Parameters:
    - `pixelsize` (floating point): pixel size in degrees
  - Return value
    - (integer): HEALPix order `k`
  - See Also:
    - HEALPix web site
`healpixResolution( k )`

  Gives the approximate resolution in degrees for a given HEALPix resolution parameter `k` This `k` value is the logarithm to base 2 of the Nside parameter.

  - Parameters:
    - `k` (integer): HEALPix order (0..29)
  - Return value
    - (floating point): approximate angular resolution in degrees
`healpixSteradians( k )`

  Returns the solid angle in steradians of each HEALPix pixel at a given order.

  - Parameters:
    - `k` (integer): HEALPix order (0..29)
  - Return value
    - (floating point): pixel size in steradians
  - Examples:
    - `healpixSteradians(5) = 0.0010226538585904274`
    - `4*PI/healpixSteradians(0) = 12.0`
`healpixSqdeg( k )`

  Returns the solid angle in square degrees of each HEALPix pixel at a given order.

  - Parameters:
    - `k` (integer): HEALPix order (0..29)
  - Return value
    - (floating point): pixel size in steradians
  - Examples:
    - `healpixSqdeg(5) = 3.357174580844667`
    - `round(12 * healpixSqdeg(0)) = 41253`
`steradiansToSqdeg( sr )`

  Converts a solid angle from steradians to square degrees.

  The unit sphere is 4*PI steradians = 360*360/PI square degrees.

  - Parameters:
    - `sr` (floating point): quantity in steradians
  - Return value
    - (floating point): quantity in sqare degrees
  - Example:
    - `round(steradiansToSqdeg(4*PI)) = 41253`
`sqdegToSteradians( sqdeg )`

  Converts a solid angle from square degrees to steradians.

  The unit sphere is 4*PI steradians = 360*360/PI square degrees.

  - Parameters:
    - `sqdeg` (floating point): quantity in square degrees
  - Return value
    - (floating point): quantity in steradians
  - Example:
    - `round(sqdegToSteradians(41253)/PI) = 4`
`htmLevel( pixelsize )`

  Gives the HTM `level` parameter suitable for a given pixel size.

  - Parameters:
    - `pixelsize` (floating point): required resolution in degrees
  - Return value
    - (integer): HTM level parameter
`htmResolution( level )`

  Gives the approximate resolution in degrees for a given HTM depth level.

  - Parameters:
    - `level` (integer): HTM depth
  - Return value
    - (floating point): approximate angular resolution in degrees
`SQDEG`

  Solid angle in steradians corresponding to 1 square degree.

# 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.

Julian Day (JD)

  MJD plus a fixed offset of 2400000.5. The number of days since the notional creation of the universe, midday on 1 Jan 4713 BC.

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.

`isoToMjd( isoDate )`

  Converts an ISO8601 date string to Modified Julian Date. The basic format of the `isoDate` argument is `yyyy-mm-ddThh:mm:ss.s`, though some deviations from this form are permitted:

  - The '`T`' which separates date from time can be replaced by a space
  - The seconds, minutes and/or hours can be omitted
  - The decimal part of the seconds can be any length, and is optional
  - The '`mm-dd`' part may be replaced by a 3-digit day of year '`ddd`'
  - A '`Z`' (which indicates UTC) may be appended to the time
  Some legal examples are therefore: "`1994-12-21T14:18:23.2`", "`1968-01-14`", "`2112-05-25 16:45Z`", and "`1987-172T22:12`".

  - Parameters:
    - `isoDate` (String): date in ISO 8601 format
  - Return value
    - (floating point): modified Julian date corresponding to `isoDate`
  - Examples:
    - `isoToMjd("2004-10-25T18:00:00") = 53303.75`
    - `isoToMjd("1970-01-01") = 40587.0`
`dateToMjd( year, month, day, hour, min, sec )`

  Converts a calendar date and time to Modified Julian Date.

  - Parameters:
    - `year` (integer): year AD
    - `month` (integer): index of month; January is 1, December is 12
    - `day` (integer): day of month (the first day is 1)
    - `hour` (integer): hour (0-23)
    - `min` (integer): minute (0-59)
    - `sec` (floating point): second (0<=sec<60)
  - Return value
    - (floating point): modified Julian date corresponding to arguments
  - Example:
    - `dateToMjd(1999, 12, 31, 23, 59, 59.) = 51543.99998`
`dateToMjd( year, month, day )`

  Converts a calendar date to Modified Julian Date.

  - Parameters:
    - `year` (integer): year AD
    - `month` (integer): index of month; January is 1, December is 12
    - `day` (integer): day of month (the first day is 1)
  - Return value
    - (floating point): modified Julian date corresponding to 00:00:00 of the date specified by the arguments
  - Example:
    - `dateToMjd(1999, 12, 31) = 51543.0`
`decYearToMjd( decYear )`

  Converts a Decimal Year to a Modified Julian Date.

  - Parameters:
    - `decYear` (floating point): decimal year
  - Return value
    - (floating point): modified Julian Date
  - Example:
    - `decYearToMjd(2000.0) = 51544.0`
`isoToUnixSec( isoDate )`

  Converts an ISO8601 date string to seconds since 1970-01-01. The basic format of the `isoDate` argument is `yyyy-mm-ddThh:mm:ss.s`, though some deviations from this form are permitted:

  - The '`T`' which separates date from time can be replaced by a space
  - The seconds, minutes and/or hours can be omitted
  - The decimal part of the seconds can be any length, and is optional
  - The '`mm-dd`' part may be replaced by a 3-digit day of year '`ddd`'
  - A '`Z`' (which indicates UTC) may be appended to the time
  Some legal examples are therefore: "`1994-12-21T14:18:23.2`", "`1968-01-14`", "`2112-05-25 16:45Z` and "`1987-172T22:12`".

  - Parameters:
    - `isoDate` (String): date in ISO 8601 format
  - Return value
    - (floating point): seconds since the Unix epoch
  - Examples:
    - `isoToUnixSec("2004-10-25T18:00:00") = 1098727200`
    - `isoToUnixSec("1970-01-01") = 0`
`decYearToUnixSec( decYear )`

  Converts a Decimal Year to seconds since 1970-01-01.

  - Parameters:
    - `decYear` (floating point): decimal year
  - Return value
    - (floating point): seconds since the Unix epoch
  - Examples:
    - `decYearToUnixSec(2000.0) = 946684800`
    - `decYearToUnixSec(1970) = 0`
`mjdToUnixSec( mjd )`

  Converts a Modified Julian Date to seconds since 1970-01-01.

  - Parameters:
    - `mjd` (floating point): modified Julian date
  - Return value
    - (floating point): seconds since the Unix epoch
`jdToUnixSec( jd )`

  Converts a Julian day to seconds since 1970-01-01.

  - Parameters:
    - `jd` (floating point): Julian day
  - Return value
    - (floating point): seconds since the Unix epoch
`mjdToIso( mjd )`

  Converts a Modified Julian Date value to an ISO 8601-format date-time string. The output format is `yyyy-mm-ddThh:mm:ss`. If the result predates the Common Era, the string "(BCE)" is prepended.

  - Parameters:
    - `mjd` (floating point): modified Julian date
  - Return value
    - (String): ISO 8601 format date corresponding to `mjd`
  - Example:
    - `mjdToIso(53551.72917) = "2005-06-30T17:30:00"`
`mjdToDate( mjd )`

  Converts a Modified Julian Date value to an ISO 8601-format date string. The output format is `yyyy-mm-dd`. If the result predates the Common Era, the string "(BCE)" is prepended.

  - Parameters:
    - `mjd` (floating point): modified Julian date
  - Return value
    - (String): ISO 8601 format date corresponding to `mjd`
  - Example:
    - `mjdToDate(53551.72917) = "2005-06-30"`
`mjdToTime( mjd )`

  Converts a Modified Julian Date value to an ISO 8601-format time-only string. The output format is `hh:mm:ss`.

  - Parameters:
    - `mjd` (floating point): modified Julian date
  - Return value
    - (String): ISO 8601 format time corresponding to `mjd`
  - Example:
    - `mjdToTime(53551.72917) = "17:30:00"`
`mjdToDecYear( mjd )`

  Converts a Modified Julian Date to Decimal Year.

  - Parameters:
    - `mjd` (floating point): modified Julian Date
  - Return value
    - (floating point): decimal year
  - Example:
    - `mjdToDecYear(0.0) = 1858.87671`
`formatMjd( mjd, format )`

  Converts a Modified Julian Date value to a date using a customisable date format. The format is as defined by the `java.text.SimpleDateFormat` class. The default output corresponds to the string "`yyyy-MM-dd'T'HH:mm:ss`"

  Note that the output from certain formatting characters (such as `MMM` for month, `EEE` for day of week) is dependent on your locale (system language settings). The output time zone however always corresponds to UTC.

  - Parameters:
    - `mjd` (floating point): modified Julian date
    - `format` (String): formatting patttern
  - Return value
    - (String): custom formatted time corresponding to `mjd`
  - Examples:
    - `formatMjd(50000.3, "EEE dd, MMM, yy") = "Tue 10 Oct, 95"`
    - `formatMjd(50000.1234, "'time 'H:mm:ss.SSS") = "time 2:57:41.760"`
`jdToMjd( jd )`

  Converts a Julian Day to Modified Julian Date. The calculation is simply `jd-2400000.5`.

  - Parameters:
    - `jd` (floating point): Julian day number
  - Return value
    - (floating point): MJD value
`mjdToJd( mjd )`

  Converts a Modified Julian Date to Julian Day. The calculation is simply `jd+2400000.5`.

  - Parameters:
    - `mjd` (floating point): MJD value
  - Return value
    - (floating point): Julian day number
`mjdToJulian( mjd )`

  Converts a Modified Julian Date to Julian Epoch. For approximate purposes, the result of this routine consists of an integral part which gives the year AD and a fractional part which represents the distance through that year, so that for instance 2000.5 is approximately 1 July 2000.

  - Parameters:
    - `mjd` (floating point): modified Julian date
  - Return value
    - (floating point): Julian epoch
  - Example:
    - `mjdToJulian(0.0) = 1858.87885`
`julianToMjd( julianEpoch )`

  Converts a Julian Epoch to Modified Julian Date. For approximate purposes, the argument of this routine consists of an integral part which gives the year AD and a fractional part which represents the distance through that year, so that for instance 2000.5 is approximately 1 July 2000.

  - Parameters:
    - `julianEpoch` (floating point): Julian epoch
  - Return value
    - (floating point): modified Julian date
  - Example:
    - `julianToMjd(2000.0) = 51544.5`
`mjdToBesselian( mjd )`

  Converts Modified Julian Date to Besselian Epoch. For approximate purposes, the result of this routine consists of an integral part which gives the year AD and a fractional part which represents the distance through that year, so that for instance 1950.5 is approximately 1 July 1950.

  - Parameters:
    - `mjd` (floating point): modified Julian date
  - Return value
    - (floating point): Besselian epoch
  - Example:
    - `mjdToBesselian(0.0) = 1858.87711`
`besselianToMjd( besselianEpoch )`

  Converts Besselian Epoch to Modified Julian Date. For approximate purposes, the argument of this routine consists of an integral part which gives the year AD and a fractional part which represents the distance through that year, so that for instance 1950.5 is approximately 1 July 1950.

  - Parameters:
    - `besselianEpoch` (floating point): Besselian epoch
  - Return value
    - (floating point): modified Julian date
  - Example:
    - `besselianToMjd(1950.0) = 33281.92346`
`unixMillisToMjd( unixMillis )`

  Converts from milliseconds since the Unix epoch (1970-01-01T00:00:00) to a modified Julian date value

  - Parameters:
    - `unixMillis` (long integer): milliseconds since the Unix epoch
  - Return value
    - (floating point): modified Julian date
`mjdToUnixMillis( mjd )`

  Converts from modified Julian date to milliseconds since the Unix epoch (1970-01-01T00:00:00).

  - Parameters:
    - `mjd` (floating point): modified Julian date
  - Return value
    - (long integer): milliseconds since the Unix epoch
`MJD_OFFSET`

  JD value for MJD = 0 (=2400000.5).

# TrigDegrees

Standard trigonometric functions with angles in degrees.

`sinDeg( theta )`

  Sine of an angle.

  - Parameters:
    - `theta` (floating point): an angle, in degrees
  - Return value
    - (floating point): the sine of the argument
`cosDeg( theta )`

  Cosine of an angle.

  - Parameters:
    - `theta` (floating point): an angle, in degrees
  - Return value
    - (floating point): the cosine of the argument
`tanDeg( theta )`

  Tangent of an angle.

  - Parameters:
    - `theta` (floating point): an angle, in degrees
  - Return value
    - (floating point): the tangent of the argument.
`asinDeg( x )`

  Arc sine. The result is in the range of -90 through 90.

  - Parameters:
    - `x` (floating point): the value whose arc sine is to be returned.
  - Return value
    - (floating point): the arc sine of the argument in degrees
`acosDeg( x )`

  Arc cosine. The result is in the range of 0.0 through 180.

  - Parameters:
    - `x` (floating point): the value whose arc cosine is to be returned.
  - Return value
    - (floating point): the arc cosine of the argument in degrees
`atanDeg( x )`

  Arc tangent. The result is in the range of -90 through 90.

  - Parameters:
    - `x` (floating point): the value whose arc tangent is to be returned.
  - Return value
    - (floating point): the arc tangent of the argument in degrees
`atan2Deg( y, x )`

  Converts rectangular coordinates (`x`,`y`) to polar (`r`,`theta`). This method computes the phase `theta` by computing an arc tangent of `y/x` in the range of -180 to 180.

  - Parameters:
    - `y` (floating point): the ordinate coordinate
    - `x` (floating point): the abscissa coordinate
  - Return value
    - (floating point): the `theta` component in degrees of the point (`r`,`theta`) in polar coordinates that corresponds to the point (`x`,`y`) in Cartesian coordinates.

# 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.

`urlEncode( txt )`

  Performs necessary quoting of a string for it to be included safely in the data part of a URL. Alphanumeric characters and the characters underscore ("`_`"), minus sign ("`-`"), period ("`.`") and tilde ("`~`") are passed through unchanged, and any other 7-bit ASCII character is represented by a percent sign ("`%`") followed by its 2-digit hexadecimal code. Characters with values of 128 or greater are simply dropped.

  - Parameters:
    - `txt` (String): input (unencoded) string
  - Return value
    - (String): output (encoded) string
  - Example:
    - `urlEncode("RR Lyr") = "RR%20Lyr"`
  - See Also:
    - RFC 3986
`urlDecode( txt )`

  Reverses the quoting performed by `urlEncode`. Percent-encoded sequences (`%xx`) are replaced by the ASCII character with the hexadecimal code `xx`.

  - Parameters:
    - `txt` (String): input (encoded) string
  - Return value
    - (String): output (unencoded) string
  - Example:
    - `urlDecode("RR%20Lyr") = "RR Lyr"`
  - See Also:
    - RFC 3986
`paramsUrl( baseUrl, nameValuePairs, ... )`

  Builds a query-type URL string given a base URL and a list of name, value pairs.

  The parameters are encoded on the command line according to the "`application/x-www-form-urlencoded`" convention, which appends a "?" to the base URL, and then adds name=value pairs separated by "&" characters, with percent-encoding of non-URL-friendly characters. This format is used by many services that require a list of parameters to be conveyed on the URL.

  - Parameters:
    - `baseUrl` (String): basic URL (may or may not already contain a "?")
    - `nameValuePairs` (String, one or more): an even number of arguments (or an even-length string array) giving parameter name1,value1,name2,value2,...nameN,valueN
  - Return value
    - (String): form-encoded URL
  - Example:
    - `paramsUrl("http://x.org/", "a", "1", "b", "two", "c", "3&4") = "http://x.org/?a=1&b=two&c=3%264"`
`bibcodeUrl( bibcode )`

  Maps a bibcode to the URL that will display the relevant entry in ADS. If the supplied string does not appear to be a bibcode, null will be returned.

  If the supplied string appears to be a bibcode, it just prepends the string "`https://ui.adsabs.harvard.edu/abs/`" and performs any character escaping that is required.

  - Parameters:
    - `bibcode` (String): ADS-style bibcode string
  - Return value
    - (String): display URL pointing at bibcode record, or null if it doesn't look like a bibcode
  - Example:
    - `bibcodeUrl("2018A&A...616A...2L") = "https://ui.adsabs.harvard.edu/abs/2018A%26A...616A...2L"`
  - See Also:
    - http://adsabs.harvard.edu/abs_doc/help_pages/data.html
`doiUrl( doi )`

  Maps a DOI (Digital Object Identifier) to its display URL. If the supplied string does not appear to be a DOI, null will be returned.

  If the supplied string appears to be a DOI, it strips any "`doi:`" prefix if present, prepends the string "`https://doi.org/`", and performs any character escaping that is required.

  - Parameters:
    - `doi` (String): DOI string, with or without "doi:" prefix
  - Return value
    - (String): display URL pointing at DOI content, or null if it doesn't look like a DOI
  - Example:
    - `doiUrl("10.3390/informatics4030018") = "https://doi.org/10.3390/informatics4030018"`
  - See Also:
    - https://www.doi.org/
`arxivUrl( arxivId )`

  Maps an arXiv identifier to the URL that will display its arXiv web page. If the supplied string does not appear to be an arXiv identifier, null will be returned.

  If the supplied string appears to be an arXiv identifier, it strips any "`arXiv:` prefix and prepends the string "`https://arxiv.org/abs/`".

  - Parameters:
    - `arxivId` (String): arXiv identifier, with or without "arXiv:" prefix
  - Return value
    - (String): display URL pointing at bibcode record, or null if it doesn't look like a bibcode
  - Example:
    - `arxivUrl("arXiv:1804.09379") = "https://arxiv.org/abs/1804.09381"`
  - See Also:
    - https://arxiv.org/help/arxiv_identifier
`simbadUrl( sourceId )`

  Maps a source identifier to the URL of its SIMBAD web page. SIMBAD is the astronomical source information service run by the Centre de Données astronomiques de Strasbourg.

  The string "`http://simbad.u-strasbg.fr/simbad/sim-id?Ident=`" is prepended to the given id string, and any necessary character escaping is applied. No attempt is made to validate whether the supplied string is a real source identifier, so there is no guarantee that the returned URL will contain actual results.

  - Parameters:
    - `sourceId` (String): free text assumed to represent a source identifier known by SIMBAD
  - Return value
    - (String): URL of the Simbad web page describing the identified source
  - Example:
    - `simbadUrl("Beta Pictoris") = "http://simbad.u-strasbg.fr/simbad/sim-id?Ident=Beta%20Pictoris"`
`nedUrl( sourceId )`

  Maps a source identifier to the URL of its NED web page. NED is the NASA/IPAC Extragalactic Database.

  The string "`http://ned.ipac.caltech.edu/byname?objname=`" is prepended to the given id string, and any necessary character escaping is applied. No attempt is made to validate whether the supplied string is a real source identifier, so there is no guarantee that the returned URL will contain actual results.

  - Parameters:
    - `sourceId` (String): free text assumed to represent a source identifier known by NED
  - Return value
    - (String): URL of the NED web page describing the identified source
  - Example:
    - `nedUrl("NGC 3952") = "http://ned.ipac.caltech.edu/byname?objname=NGC%203952"`
`hips2fitsUrl( hipsId, fmt, raDeg, decDeg, fovDeg, npix )`

  Returns the URL of a cutout from the Hips2Fits service operated by CDS. The result will be the URL of a FITS or image file resampled to order from one of the HiPS surveys available at CDS.

  This function requests a square cutout using the SIN projection, which is suitable for small cutouts. If the details of this function don't suit your purposes, you can construct the URL yourself.

  - Parameters:
    - `hipsId` (String): identifier or partial identifier for the HiPS survey
    - `fmt` (String): required output format, for instance "`fits`", "`png`", "`jpg`"
    - `raDeg` (floating point): central Right Ascension (longitude) in degrees
    - `decDeg` (floating point): central Declination (latitude) in degrees
    - `fovDeg` (floating point): field of view; extent of the cutout in degrees
    - `npix` (integer): extent of the cutout in pixels (width=height=npix)
  - Return value
    - (String): URL of the required cutout
  - See Also:
    - http://alasky.u-strasbg.fr/hips-image-services/hips2fits

# VO

Virtual Observatory-specific functions. Some of these are for rather technical purposes.

The UCD parsing functions are based on Grégory Mantelet's library Ucidy corresponding to UCD1+ 1.5, and the VOUnit parsing functions are based on Norman Gray's library Unity corresponding to VOUnits 1.0.

TFCat refers to the Time-Frequency Radio Catalogues format, TFCat 1.0.

`ucdStatus( ucd )`

  Returns a token string giving the category of UCD compliance. UCD1+, UCD1 and SIAv1 ("VOX:")-style UCDs are recognised.

  Possible return values are currently:

  - "OK": conforms to UCD1+ standard
  - "UCD1": looks like a UCD1
  - "VOX": is in VOX: namespace introduced by SIAv1
  - "BAD_SYNTAX": not a UCD1 and cannot be parsed according to UCD1+
  - "BAD_SEQUENCE": UCD words violate UCD1+ sequence rules
  - "UNKNOWN_WORD": follows UCD1+ syntax rules but contains non-UCD1+ atom
  - "NAMESPACE": follows UCD1+ syntax but contains atoms in non-standard namespace
  - "DEPRECATED": contains deprecated UCD1+ words

  In the case of non-compliant values, more information can be found using the `ucdMessage` function.

  - Parameters:
    - `ucd` (String): UCD string
  - Return value
    - (String): "OK" for conformant UCD1+, otherwise some other value
`ucdMessage( ucd )`

  Returns a human-readable message associated with the parsing of a UCD. This is expected to be empty for a fully compliant UCD, and may contain error messages or advice otherwise.

  - Parameters:
    - `ucd` (String): UCD value
  - Return value
    - (String): message text
`vounitStatus( unit )`

  Returns a token string giving the category of VOUnits compliance.

  Possible return values are currently:

  - "OK": conforms to VOUnits syntax
  - "UNKNOWN_UNIT": parsed as VOUnit but contains unknown base unit(s)
  - "GUESSED_UNIT": parsed as VOUnit but contains unknown, though guessable, base unit(s)
  - "BAD_SYNTAX": cannot be parsed as VOUnit syntax
  - "PARSE_ERROR": unexpected error during parsing
  - "USAGE": violates VOUnit usage constraints
  - "WHITESPACE": legal VOUnit except that it contains whitespace, which is not allowed by VOUnits

  In the case of non-compliant values, more information can be found using the `vounitMessage` function.

  - Parameters:
    - `unit` (String): unit string
  - Return value
    - (String): "OK" for conformant VOUnits, otherwise some other value
`vounitMessage( unit )`

  Returns a human-readable message associated with the parsing of a unit string. This is expected to be empty for a string fully compliant with VOUnits, and may contain error messages or additional information otherwise.

  - Parameters:
    - `unit` (String): unit string
  - Return value
    - (String): message text
`tfcatStatus( tfcat )`

  Returns a token string giving the category of TFCat compliance.

  Possible return values are currently:

  - "OK": conforms to TFCat syntax
  - "ERROR": parsed as TFCat, but with one or more errors
  - "FAIL": could not be parsed as a TFCat object

  For non-OK values, more information can be found using the `tfcatMessage` function.

  - Parameters:
    - `tfcat` (String): JSON string giving TFCat text
  - Return value
    - (String): "OK" for conformant TFCat, otherwise some other value
`tfcatMessage( tfcat )`

  Returns a human-readable message associated with the parsing of a TFCat text. This will be empty for a string fully compliant with the TFCat standard, but will contain error messages otherwise.

  - Parameters:
    - `tfcat` (String): JSON string giving TFCat text
  - Return value
    - (String): message text