cf.Field.cell_area

Field.cell_area(radius='earth', great_circle=False, cell_measures=True, coordinates=True, methods=False, return_cell_measure=False, insert=False, force=False)

Return the horizontal cell areas.

New in version 1.0.

See also

bin, collapse, radius, weights

Parameters

radius: optional

Specify the radius used for calculating the areas of cells defined in spherical polar coordinates. The radius is that which would be returned by this call of the field construct’s radius method: f.radius(radius). See cf.Field.radius for details.

By default radius is 'earth' which means that if and only if the radius can not found from the datums of any coordinate reference constructs, then the default radius taken as 6371229 metres.

great_circle: bool, optional

If True then allow, if required, the derivation of i) area weights from polygon geometry cells by assuming that each cell part is a spherical polygon composed of great circle segments; and ii) and the derivation of line-length weights from line geometry cells by assuming that each line part is composed of great circle segments.

New in version 3.2.0.

cell_measures: bool, optional

If True, the default, then area cell measure constructs are considered for cell area creation. Otherwise they are ignored.

New in version 3.16.1.

coordinates: bool, optional

If True, the default, then coordinate constructs are considered for cell area creation. Otherwise they are ignored.

New in version 3.16.1.

methods: bool, optional

If True, then return a dictionary describing the method used to create the cell areas instead of the default, a field construct.

New in version 3.16.1.

return_cell_measure: bool, optional

If True, then return a cell measure construct instead of the default, a field construct.

New in version 3.16.1.

insert: deprecated at version 3.0.0

force: deprecated at version 3.0.0

Returns

Field, CellMeasure, or dict

A field construct, or cell measure construct containing the horizontal cell areas if return_cell_measure is True, or a dictionary describing the method used to create the cell areas if methods is True.

Examples

>>> f = cf.example_field(0)
>>> print(f)
Field: specific_humidity (ncvar%q)
----------------------------------
Data            : specific_humidity(latitude(5), longitude(8)) 1
Cell methods    : area: mean
Dimension coords: latitude(5) = [-75.0, ..., 75.0] degrees_north
                : longitude(8) = [22.5, ..., 337.5] degrees_east
                : time(1) = [2019-01-01 00:00:00]

>>> a = f.cell_area()
>>> a
<CF Field: cell_area(latitude(5), longitude(8)) m2>
>>> print(a.array)
[[4.27128714e+12 4.27128714e+12 4.27128714e+12 4.27128714e+12
  4.27128714e+12 4.27128714e+12 4.27128714e+12 4.27128714e+12]
 [1.16693735e+13 1.16693735e+13 1.16693735e+13 1.16693735e+13
  1.16693735e+13 1.16693735e+13 1.16693735e+13 1.16693735e+13]
 [3.18813213e+13 3.18813213e+13 3.18813213e+13 3.18813213e+13
  3.18813213e+13 3.18813213e+13 3.18813213e+13 3.18813213e+13]
 [1.16693735e+13 1.16693735e+13 1.16693735e+13 1.16693735e+13
  1.16693735e+13 1.16693735e+13 1.16693735e+13 1.16693735e+13]
 [4.27128714e+12 4.27128714e+12 4.27128714e+12 4.27128714e+12
  4.27128714e+12 4.27128714e+12 4.27128714e+12 4.27128714e+12]]
>>> f.cell_area(methods=True)
{(1,): 'linear longitude', (0,): 'linear sine latitude'}

>>> a = f.cell_area(radius=cf.Data(3389.5, 'km'))

>>> c = f.cell_area(return_cell_measure=True)
>>> c
<CF CellMeasure: measure:area(5, 8) m2>
>>> f.set_construct(c)
'cellmeasure0'
>>> print(f)
Field: specific_humidity (ncvar%q)
----------------------------------
Data            : specific_humidity(latitude(5), longitude(8)) 1
Cell methods    : area: mean
Dimension coords: latitude(5) = [-75.0, ..., 75.0] degrees_north
                : longitude(8) = [22.5, ..., 337.5] degrees_east
                : time(1) = [2019-01-01 00:00:00]
Cell measures   : measure:area(latitude(5), longitude(8)) = [[4271287143027.272, ..., 4271287143027.272]] m2
>>> f.cell_area(methods=True)
{(0, 1): 'area cell measure'}