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, moving_window, sum

Parameters

axis:

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. .. note:: Sums produced entirely from masked elements will

always result in masked values in the output data, regardless of the setting of masked_as_zero.

coordinate: str, optional

Set how the cell coordinate values for the summed axis are defined, relative to the new cell bounds. By default they are unchanged from the original field construct. The coordinate parameter may be one of:

coordinate	Description
None	This is the default. Output coordinates are unchanged.
'mid_range'	An output coordinate is the average of its output coordinate bounds.
'minimum'	An output coordinate is the minimum of its output coordinate bounds.
'maximum'	An output coordinate is the maximum of its output coordinate bounds.

Parameter Example:

coordinate='maximum'

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 axis, 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)