cf.Field.healpix_decrease_refinement_level¶

Field.healpix_decrease_refinement_level(refinement_level, method, reduction=None, conform=True, check_healpix_index=True)[source]¶

Decrease the refinement level of a HEALPix grid.

Decreasing the HEALPix refinement level reduces the resolution of the HEALPix grid by combining, using the given method, the Field data from the original cells that lie inside each larger cell at the new lower refinement level.

A new cell method is added, when appropriate, to describe the reduction.

The operation requires that a new larger cell at the lower refinement level either:

contains no original cells, in which case that larger cell is not included in the output;

or

is completely covered by original cells.

It is not allowed for a larger cell to be only partially covered by original cells. For instance, if the original refinement level is 10 and the new refinement level is 8, then each output cell will be the combination of \(16\equiv 4^2\equiv 4^{(10-8)}\) original cells, and if a larger cell contains at least one but fewer than 16 original cells then an exception is raised (assuming that check_healpix_index is True).

See CF Appendix F: Grid Mappings. https://doi.org/10.5281/zenodo.14274886

Added in version 3.20.0.

Parameters:

refinement_level: int or None

Specify the new lower refinement level as a non-negative integer less than or equal to the current refinement level, or if None then the refinement level is not changed.

method: str

The method used to calculate the values in the new larger cells, from the data on the original cells. Must be one of these CF standardised cell method names: 'maximum', 'maximum_absolute_value', 'mean', 'mean_absolute_value', 'mean_of_upper_decile', 'median', 'mid_range', 'minimum', 'minimum_absolute_value', 'mode', 'range', 'root_mean_square', 'standard_deviation', 'sum', 'sum_of_squares', 'variance'.

Note

The method should be appropriate to nature of the Field quantity, which is either intensive (i.e. that does not depend on the size of the cells, such as “sea_ice_amount” with units of kg m-2), or extensive (i.e. that depends on the size of the cells, such as “sea_ice_mass” with units of kg).

reduction: function or None, optional

The function used to calculate the values in the new larger cells, from the data on the original cells. The function must:

calculate the quantity defined by the method parameter,
take an array of values as its first argument,
have an axis keyword that specifies which of the array axes is the HEALPix axis.

For some methods there are default reduction functions, which are only used when reduction is None (the default):

method	Default reduction
`'maximum'`	`np.max`
`'mean'`	`np.mean`
`'median'`	`np.median`
`'minimum'`	`np.min`
`'standard_deviation'`	`np.std`
`'sum'`	`np.sum`
`'variance'`	`np.var`

Note that these methods may be also calculated by another function provided by the reduction parameter.

conform: bool, optional

If True (the default) then the HEALPix grid is automatically converted to a form suitable for having its refinement level changed, i.e. the indexing scheme is changed to nested and the HEALPix axis is sorted so that the nested HEALPix indices are monotonically increasing. If False then an exception is raised if the HEALPix indexing scheme is not already nested and the HEALPix axis is not sorted.

Note

Setting to False will speed up the operation when the HEALPix indexing scheme is already nested and the HEALPix axis is already sorted monotonically.

check_healpix_index: bool, optional

If True (the default) then the following conditions will be checked before the creation of the new Field (but after the HEALPix grid has been conformed, when conform is True):

The nested HEALPix indices are strictly monotonically increasing.
Every cell at the new lower refinement level contains zero or the maximum possible number of cells at the original refinement level.

If False then these checks are not carried out.

Warning

Only set to False, which will speed up the operation, when it is known in advance that these conditions are satisfied. If set to False and any of the conditions are not met then either an exception will be raised or, much worse, the operation could complete and return incorrect data values.

Returns:

Field: A new Field with the new HEALPix grid. The HEALPix indices of this field will follow the nested indexing scheme.

Examples

>>> f = cf.example_field(12)
>>> print(f)
Field: air_temperature (ncvar%tas)
----------------------------------
Data            : air_temperature(time(2), healpix_index(48)) K
Cell methods    : time(2): mean area: mean
Dimension coords: time(2) = [2025-06-16 00:00:00, 2025-07-16 12:00:00] proleptic_gregorian
                : healpix_index(48) = [0, ..., 47]
                : height(1) = [1.5] m
Coord references: grid_mapping_name:healpix
>>> f.healpix_info()['refinement_level']
1

Set the refinement level to 0, showing that every 4 cells (i.e. the number of cells at the original refinement level that lie in one cell of the lower refinement level) in the original field correspond to one cell at the lower level:

>>> g = f.healpix_decrease_refinement_level(0, 'maximum')
>>> print(g)
Field: air_temperature (ncvar%tas)
----------------------------------
Data            : air_temperature(time(2), healpix_index(12)) K
Cell methods    : time(2): mean area: mean area: maximum
Dimension coords: time(2) = [2025-06-16 00:00:00, 2025-07-16 12:00:00] proleptic_gregorian
                : healpix_index(12) = [0, ..., 11]
                : height(1) = [1.5] m
Coord references: grid_mapping_name:healpix
>>> g.healpix_info()['refinement_level']
0
>>> print(f[0, :4].array)
[[291.5 293.5 285.3 286.3]]
>>> print(g[0, 0].array)
[[293.5]]

Set the refinement level to 0 using the 'range' method, which requires a reduction function to be defined:

>>> import numpy as np
>>> def range_func(a, axis=None):
...     return np.max(a, axis=axis) - np.min(a, axis=axis)
...
>>> g = f.healpix_decrease_refinement_level(0, 'range', range_func)
>>> print(g)
Field: air_temperature (ncvar%tas)
----------------------------------
Data            : air_temperature(time(2), healpix_index(12)) K
Cell methods    : time(2): mean area: mean area: range
Dimension coords: time(2) = [2025-06-16 00:00:00, 2025-07-16 12:00:00] proleptic_gregorian
                : healpix_index(12) = [0, ..., 11]
                : height(1) = [1.5] m
Coord references: grid_mapping_name:healpix
>>> print(g[0, 0].array)
[[8.2]]

cf 3.21.0

Related Topics

cf.Field.healpix_decrease_refinement_level¶