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:
size
,
count
,
countTrue
,
maximum
,
minimum
,
sum
,
mean
,
median
,
quantile
,
stdev
,
variance
,
join
.
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.
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 )
array
is not a numeric array, null
is returned.
array
(Object): array of numbers
array
mean( array )
array
is not a numeric array, null
is returned.
array
(Object): array of numbers
array
variance( array )
array
is not a numeric array,
null
is returned.
array
(Object): array of numbers
array
stdev( array )
array
is not a numeric array,
null
is returned.
array
(Object): array of numbers
array
minimum( array )
array
is not a numeric array, null
is returned.
array
(Object): array of numbers
array
maximum( array )
array
is not a numeric array, null
is returned.
array
(Object): array of numbers
array
median( array )
array
is not a numeric array, null
is returned.
array
(Object): array of numbers
array
quantile( array, quant )
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.
array
(Object): array of numbers
quant
(floating point): number in the range 0-1 deterining which quantile
to calculate
quant
size( array )
array
is not an array, zero is returned.
array
(Object): array
array
count( array )
array
is not an array, zero is returned.
array
(Object): array (may or may not be numeric)
array
countTrue( array )
array
(array of boolean): array of true/false values
array
join( array, joiner )
array
is not an array, null is returned.
array
(Object): array of numbers or strings
joiner
(String): text string to interpose between adjacent elements
array
elements separated by
joiner
strings
join(array(1.5,2.1,-3.9), "; ") = "1.5; 2.1; -3.9"
add( array1, array2 )
null
is returned.
The types of the arrays do not need to be the same,
so for example it is permitted to add an integer array
to a floating point array.
array1
(Object): first array of numeric values
array2
(Object): second array of numeric values
array1
and array2
,
the same length as the input arrays
add(array(1,2,3), array(0.1,0.2,0.3))
= [1.1, 2.2, 3.3]
add( array, constant )
array
argument is not a numeric array,
null
is returned.
array
(Object): array input
constant
(floating point): value to add to each array element
array
parameter
add(array(1,2,3), 10) = [11,12,13]
subtract( array1, array2 )
null
is returned.
The types of the arrays do not need to be the same,
so for example it is permitted to subtract an integer array
from a floating point array.
array1
(Object): first array of numeric values
array2
(Object): second array of numeric values
array1
and array2
,
the same length as the input arrays
subtract(array(1,2,3), array(0.1,0.2,0.3))
= [0.9, 1.8, 2.7]
multiply( array1, array2 )
null
is returned.
The types of the arrays do not need to be the same,
so for example it is permitted to multiply an integer array
by a floating point array.
array1
(Object): first array of numeric values
array2
(Object): second array of numeric values
array1
and array2
,
the same length as the input arrays
multiply(array(1,2,3), array(2,4,6)) = [2, 8, 18]
multiply( array, constant )
array
argument is not a numeric array,
null
is returned.
array
(Object): array input
constant
(floating point): value by which to multiply each array element
array
parameter
multiply(array(1,2,3), 2) = [2, 4, 6]
divide( array1, array2 )
null
is returned.
The types of the arrays do not need to be the same,
so for example it is permitted to divide an integer array
by a floating point array.
array1
(Object): array of numerator values (numeric)
array2
(Object): array of denominator values (numeric)
array1[i]/array2[i]
the same length as the input arrays
divide(array(0,9,4), array(1,3,8)) = [0, 3, 0.5]
reciprocal( array )
array
argument is not a numeric array,
null
is returned.
array
(Object): array input
array
parameter
reciprocal(array(1,2,0.25) = [1, 0.5, 4]
condition( flagArray, trueValue, falseValue )
This has the same effect as applying the expression
outArray[i] = flagArray[i] ? trueValue : falseValue
.
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
flagArray
condition([true, false, true], 1, 0) = [1, 0, 1]
slice( array, i0, i1 )
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
).
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)
i0
and i1
slice(array(10,11,12,13), 0, 3) = [10, 11, 12]
slice(array(10,11,12,13), -2, 999) = [12, 13]
pick( array, indices, ... )
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
).
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)
indices
pick(array(10,11,12,13), 0, 3) = [10, 13]
pick(array(10,11,12,13), -1, -2, -3)
= [13, 12, 11]
array( values, ... )
values
(floating point, one or more): one or more array elements
intArray( values, ... )
values
(integer, one or more): one or more array elements
stringArray( values, ... )
values
(String, one or more): one or more array elements