cf.Data.datum

Data.datum(*index)[source]

Return an element of the data array as a standard Python scalar.

The first and last elements are always returned with d.datum(0) and d.datum(-1) respectively, even if the data array is a scalar array or has two or more dimensions.

The returned object is of the same type as is stored internally.

See also

array, datetime_array

Parameters
index: optional

Specify which element to return. When no positional arguments are provided, the method only works for data arrays with one element (but any number of dimensions), and the single element is returned. If positional arguments are given then they must be one of the fdlowing:

  • An integer. This argument is interpreted as a flat index into the array, specifying which element to copy and return.

    Parameter example:

    If the data array shape is (2, 3, 6) then: * d.datum(0) is equivalent to d.datum(0, 0, 0). * d.datum(-1) is equivalent to d.datum(1, 2, 5). * d.datum(16) is equivalent to d.datum(0, 2, 4).

    If index is 0 or -1 then the first or last data array element respectively will be returned, even if the data array is a scalar array.

  • Two or more integers. These arguments are interpreted as a multidimensional index to the array. There must be the same number of integers as data array dimensions.

  • A tuple of integers. This argument is interpreted as a multidimensional index to the array. There must be the same number of integers as data array dimensions.

    Parameter example:

    d.datum((0, 2, 4)) is equivalent to d.datum(0, 2, 4); and d.datum(()) is equivalent to d.datum().

Returns

A copy of the specified element of the array as a suitable Python scalar.

Examples

>>> d = cf.Data(2)
>>> d.datum()
2
>>> 2 == d.datum(0) == d.datum(-1) == d.datum(())
True

>>> d = cf.Data([[2]])
>>> 2 == d.datum() == d.datum(0) == d.datum(-1)
True
>>> 2 == d.datum(0, 0) == d.datum((-1, -1)) == d.datum(-1, 0)
True

>>> d = cf.Data([[4, 5, 6], [1, 2, 3]], 'metre')
>>> d[0, 1] = cf.masked
>>> print(d)
[[4 -- 6]
 [1  2 3]]
>>> d.datum(0)
4
>>> d.datum(-1)
3
>>> d.datum(1)
masked
>>> d.datum(4)
2
>>> d.datum(-2)
2
>>> d.datum(0, 0)
4
>>> d.datum(-2, -1)
6
>>> d.datum(1, 2)
3
>>> d.datum((0, 2))
6