The following functions can be used anywhere that you can write an
algebraic expression in TOPCAT. They will typically be used for
defining new synthetic columns or algebraically-defined row subsets.
-
Times
-
Functions for conversion of time values between various forms.
The forms used are
-
Modified Julian Date (MJD)
- A continuous measure in days since midnight at the start of
17 November 1858. Based on UTC.
-
ISO 8601
- A string representation of the form
yyyy-mm-ddThh:mm:ss.s
, where the T
is a literal character (a space character may be used instead).
Based on UTC.
-
Julian Epoch
- A continuous measure based on a Julian year of exactly 365.25 days.
For approximate purposes this resembles the fractional number
of years AD represented by the date. Sometimes (but not here)
represented by prefixing a 'J'; J2000.0 is defined as
2000 January 1.5 in the TT timescale.
-
Besselian Epoch
- A continuous measure based on a tropical year of about 365.2422 days.
For approximate purposes this resembles the fractional number of
years AD represented by the date. Sometimes (but not here)
represented by prefixing a 'B'.
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
- 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
", and
"2112-05-25 16:45Z
".
-
dateToMjd( year, month, day, hour, min, sec )
- Converts a calendar date and time to Modified Julian Date.
-
dateToMjd( year, month, day )
- Converts a calendar date to Modified Julian Date.
-
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
.
-
mjdToDate( mjd )
- Converts a Modified Julian Date value to an ISO 8601-format date
string. The output format is
yyyy-mm-dd
.
-
mjdToTime( mjd )
- Converts a Modified Julian Date value to an ISO 8601-format time-only
string. The output format is
hh:mm:ss
.
-
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
"
-
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.
-
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.
-
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.
-
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.
-
Strings
-
String manipulation and query functions.
-
concat( s1, s2 )
- Concatenates two strings.
In most cases the same effect can be achieved by
writing
s1+s2
, but blank values can sometimes appear as
the string "null
" if you do it like that.
-
concat( s1, s2, s3 )
- Concatenates three strings.
In most cases the same effect can be achieved by
writing
s1+s2+s3
, but blank values can sometimes appear as
the string "null
" if you do it like that.
-
concat( s1, s2, s3, s4 )
- Concatenates four strings.
In most cases the same effect can be achieved by
writing
s1+s2+s3+s4
,
but blank values can sometimes appear as
the string "null
" if you do it like that.
-
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.
-
equalsIgnoreCase( s1, s2 )
- Determines whether two strings are equal apart from possible
upper/lower case distinctions.
-
startsWith( whole, start )
- Determines whether a string starts with a certain substring.
-
endsWith( whole, end )
- Determines whether a string ends with a certain substring.
-
contains( whole, sub )
- Determines whether a string contains a given substring.
-
length( str )
- Returns the length of a string in characters.
-
matches( str, regex )
- Tests whether a string matches a given regular expression.
-
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.
-
replaceFirst( str, regex, replacement )
- Replaces the first occurrence of a regular expression in a string with
a different substring value.
-
replaceAll( str, regex, replacement )
- Replaces all occurrences of a regular expression in a string with
a different substring value.
-
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.
-
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
.
-
toUpperCase( str )
- Returns an uppercased version of a string.
-
toLowerCase( str )
- Returns an uppercased version of a string.
-
trim( str )
- Trims whitespace from both ends of a string.
-
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.
-
Maths
-
Standard mathematical and trigonometric functions.
-
E
- Euler's number e, the base of natural logarithms.
-
PI
-
Pi, the ratio of the circumference of a circle to its diameter.
-
RANDOM
- Evaluates to a random number in the range 0<=x<1.
This is different for each cell of the table.
The quality of the randomness may not be particularly good.
-
sin( theta )
- Sine of an angle.
-
cos( theta )
- Cosine of an angle.
-
tan( theta )
- Tangent of an angle.
-
asin( x )
- Arc sine of an angle.
The result is in the range of -pi/2 through
pi/2.
-
acos( x )
- Arc cosine of an angle.
The result is in the range of 0.0 through pi.
-
atan( x )
- Arc tangent of an angle.
The result is in the range of -pi/2 through pi/2.
-
exp( x )
- Euler's number e raised to a power.
-
log10( x )
- Logarithm to base 10.
-
ln( x )
- Natural logarithm.
-
sqrt( x )
- Square root.
The result is correctly rounded and positive.
-
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.
-
pow( a, b )
- Exponentiation.
The result is the value of the first argument raised to
the power of the second argument.
-
Formats
-
Functions for formatting numeric values.
-
formatDecimal( value, dp )
- Turns a floating point value into a string with a given number of
decimal places.
-
formatDecimal( value, format )
- Turns a floating point value into a formatted string.
The
format
string is as defined by Java's
java.text.DecimalFormat
class.
-
Coords
-
Functions for angle transformations and manipulations.
In particular, methods for translating between radians and HH:MM:SS.S
or DDD:MM:SS.S type sexagesimal representations are provided.
-
DEGREE
- The size of one degree in radians.
-
HOUR
- The size of one hour of right ascension in radians.
-
ARC_MINUTE
- The size of one arcminute in radians.
-
ARC_SECOND
- The size of one arcsecond in radians.
-
radiansToDms( rad )
- Converts an angle in radians to a formatted degrees:minutes:seconds
string. No fractional part of the seconds field is given.
-
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.
-
radiansToHms( rad )
- Converts an angle in radians to a formatted hours:minutes:seconds
string. No fractional part of the seconds field is given.
-
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.
-
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.
-
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.
-
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.
-
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).
-
skyDistance( ra1, dec1, ra2, dec2 )
- Calculates the separation (distance around a great circle) of
two points on the sky.
-
skyDistanceDegrees( ra1, dec1, ra2, dec2 )
- Calculates the separation (distance around a great circle) of
two points on the sky in degrees.
-
hoursToRadians( hours )
- Converts hours to radians.
-
degreesToRadians( deg )
- Converts degrees to radians.
-
radiansToDegrees( rad )
- Converts radians to degrees.
-
raFK4toFK5( 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.
-
decFK4toFK5( 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.
-
raFK5toFK4( 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.
-
decFK5toFK4( 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.
-
raFK4toFK5( 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.
-
decFK4toFK5( 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.
-
raFK5toFK4( 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.
-
decFK5toFK4( 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.
-
Conversions
-
Functions for coverting between strings and numeric values.
-
toString( value )
- Turns a numeric value into a string.
-
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.
-
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.
-
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.
-
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.
-
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.
-
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.
-
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.
-
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.
-
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.
-
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.
-
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.
-
toDouble( value )
- Converts the numeric argument to a
double (64-bit signed integer) result.
-
Arithmetic
-
Standard arithmetic functions including things like rounding,
sign manipulation, and maximum/minimum functions.
-
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.
-
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.
-
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.
-
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.
-
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.
-
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.
-
max( a, b )
- Returns the greater of two integer values.
If the arguments have the same value, the result is that same value.
-
max( 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.
-
min( a, b )
- Returns the smaller of two integer values.
If the arguments have the same value, the result is that same value.
-
min( 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.
More detail on these functions is available from within TOPCAT in the
Available Functions window.