cf.Field.healpix_increase_refinement_level

Field.healpix_increase_refinement_level(refinement_level, quantity)

Increase the refinement level of a HEALPix grid.

Increasing the HEALPix refinement level increases the resolution of the HEALPix grid by broadcasting the Field data from each original cell to all of the new smaller cells at the new higher refinement level that lie inside it.

It must be specified whether the field data contains an extensive or intensive quantity. An intensive quantity does not depend on the size of the cells (such as “sea_ice_amount” with units of kg m-2, or “air_temperature” with units of K), and an extensive quantity does depend on the size of the cells (such as “sea_ice_mass” with units of kg, or “cell_area” with units of m2). For an extensive quantity only, the broadcast values are reduced to be consistent with the new smaller cell areas (by dividing them by the number of new cells per original cell).

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

Performance

High refinement levels may require the setting of a very large Dask chunksize, to prevent a possible run-time failure resulting from an attempt to create an excessive amount of chunks for the healpix_index coordinates. For instance, with the default Dask chunksize of 128 MiB, healpix_index coordinates at refinement level 29 would need ~206 billion Dask chunks, which is almost certainly more than enough to cause a crash. In this case, a Dask chunksize of 1 pebibyte results in only 24576 Dask chunks, a much more manageable amount:

>>> cf.chunksize()
<CF Constant: 134217728>
>>> f = cf.example_field(12)
>>> g = f.healpix_increase_refinement_level(10, 'intensive')
>>> assert g.coord('healpix_index').data.npartitions == 1
>>> g = f.healpix_increase_refinement_level(15, 'intensive')
>>> assert g.coord('healpix_index').data.npartitions == 816
>>> with cf.chunksize('1 PiB'):
...     g = f.healpix_increase_refinement_level(29, 'intensive')
...     assert g.coord('healpix_index').data.npartitions == 24576

Added in version 3.20.0.

See also

healpix_decrease_refinement_level, healpix_info, healpix_change_indexing_scheme, healpix_to_ugrid

Parameters:

refinement_level: int or None

Specify the new higher refinement level as an integer greater than or equal to the current refinement level, or if None then the refinement level is not changed.

quantity: str

Whether the Field data represent intensive or extensive quantities, specified with 'intensive' and 'extensive' respectively.

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
>>> g = f.healpix_increase_refinement_level(3, 'intensive')
>>> g
<CF Field: air_temperature(time(2), healpix_index(768)) K>
>>> g.healpix_info()['refinement_level']
3
>>> g = f.healpix_increase_refinement_level(10, 'intensive')
>>> g
<CF Field: air_temperature(time(2), healpix_index(12582912)) K>

Set the refinement level to 2, showing that, for an intensive quantity, every 4 cells at the higher refinement level (i.e. the number of cells at the higher refinement level that lie in one cell of the original refinement level) have the same value as a single cell at the original refinement level:

>>> g = f.healpix_increase_refinement_level(2, 'intensive')
>>> g
<CF Field: air_temperature(time(2), healpix_index(192)) K>
>>> g.healpix_info()['refinement_level']
2
>>> print(f[0, :2] .array)
[[291.5 293.5]]
>>> print(g[0, :8] .array)
[[291.5 291.5 291.5 291.5 293.5 293.5 293.5 293.5]]

For an extensive quantity (which the f in this example is not, but we can assume that it is for demonstration purposes), each output cell has the value of the original cell in which it lies, divided by the ratio of the cells’ areas (4 in this case):

>>> g = f.healpix_increase_refinement_level(2, 'extensive')
>>> print(f[0, :2] .array)
[[291.5 293.5]]
>>> print(g[0, :8] .array)
[[72.875 72.875 72.875 72.875 73.375 73.375 73.375 73.375]]