cf.Field.cumsum

Field.cumsum(axis, masked_as_zero=False, coordinate=None, inplace=False)

Return the field cumulatively summed along the given axis.

The cell bounds of the axis are updated to describe the range over which the sums apply, and a new “sum” cell method construct is added to the resulting field construct.

New in version 3.0.0.

See also

collapse, convolution_filter, sum

Parameters

axis:g

Select the domain axis over which the cumulative sums are to be calculated, defined by that which would be selected by passing the given axis description to a call of the field construct’s domain_axis method. For example, for a value of 'X', the domain axis construct returned by f.domain_axis('X')) is selected.

masked_as_zero: bool, optional

If True then set missing data values to zero before calculating the cumulative sum. By default the output data will be masked at the same locations as the original data.

coordinate: str, optional

Set how the cell coordinate values for the summed axis are defined. By default they are unchanged from the original field construct, but if coordinate is set to 'mid_range' then the each coordinate value is replaced by the mid_range of the updated cell bounds.

inplace: bool, optional

If True then do the operation in-place and return None.

Returns

Field or None

The field construct with the cumulatively summed dimension, or None if the operation was in-place.

Examples:

>>> f = cf.example_field(2)
>>> print(f)
Field: air_potential_temperature (ncvar%air_potential_temperature)
------------------------------------------------------------------
Data            : air_potential_temperature(time(36), latitude(5), longitude(8)) K
Cell methods    : area: mean
Dimension coords: time(36) = [1959-12-16 12:00:00, ..., 1962-11-16 00:00:00]
                : latitude(5) = [-75.0, ..., 75.0] degrees_north
                : longitude(8) = [22.5, ..., 337.5] degrees_east
                : air_pressure(1) = [850.0] hPa
>>> print(f.dimension_coordinate('T').bounds[[0, -1]].datetime_array)
[[cftime.DatetimeGregorian(1959-12-01 00:00:00)
  cftime.DatetimeGregorian(1960-01-01 00:00:00)]
 [cftime.DatetimeGregorian(1962-11-01 00:00:00)
  cftime.DatetimeGregorian(1962-12-01 00:00:00)]]
>>> print(f.array[:, 0, 0])
[210.7 305.3 249.4 288.9 231.1 200.  234.4 289.2 204.3 203.6 261.8 256.2
 212.3 231.7 255.1 213.9 255.8 301.2 213.3 200.1 204.6 203.2 244.6 238.4
 304.5 269.8 267.9 282.4 215.  288.7 217.3 307.1 299.3 215.9 290.2 239.9]

>>> g = f.cumsum('T')
>>> print(g)
Field: air_potential_temperature (ncvar%air_potential_temperature)
------------------------------------------------------------------
Data            : air_potential_temperature(time(36), latitude(5), longitude(8)) K
Cell methods    : area: mean time(36): sum
Dimension coords: time(36) = [1959-12-16 12:00:00, ..., 1962-11-16 00:00:00]
                : latitude(5) = [-75.0, ..., 75.0] degrees_north
                : longitude(8) = [22.5, ..., 337.5] degrees_east
                : air_pressure(1) = [850.0] hPa
>>>  print(g.dimension_coordinate('T').bounds[[0, -1]].datetime_array)
[[cftime.DatetimeGregorian(1959-12-01 00:00:00)
  cftime.DatetimeGregorian(1960-01-01 00:00:00)]
 [cftime.DatetimeGregorian(1959-12-01 00:00:00)
  cftime.DatetimeGregorian(1962-12-01 00:00:00)]]
>>> print(g.array[:, 0, 0])
[ 210.7  516.   765.4 1054.3 1285.4 1485.4 1719.8 2009.  2213.3 2416.9
 2678.7 2934.9 3147.2 3378.9 3634.  3847.9 4103.7 4404.9 4618.2 4818.3
 5022.9 5226.1 5470.7 5709.1 6013.6 6283.4 6551.3 6833.7 7048.7 7337.4
 7554.7 7861.8 8161.1 8377.  8667.2 8907.1]

>>> g = f.cumsum('latitude', masked_as_zero=True)

>>> g = f.cumsum('latitude', coordinate='mid_range')

>>> f.cumsum('latitude', inplace=True)