cf.Field.healpix_change_indexing_scheme

Field.healpix_change_indexing_scheme(new_indexing_scheme, sort=False, moc_refinement_level=None)

Change the indexing scheme of HEALPix indices.

Note that the Field data values are not changed, nor is the Field Data array reordered. Only the “healpix_index” coordinate values are changed, along with the corresponding “healpix” grid mapping Coordinate Reference.

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

Added in version 3.20.0.

See also

healpix_info, healpix_to_ugrid

Parameters:

new_indexing_scheme: str or None

The new HEALPix indexing scheme. One of 'nested', 'ring', 'nuniq', 'zuniq', or None. If None then the indexing scheme is unchanged.

The nested scheme indexes with consecutive indices the pixels inside a single coarser refinement level cell. When the indices are sorted monotonically, the scheme is optimised for data retrievals within a geographical range.

The ring scheme indexes with consecutive indices the pixels moving down from the north to the south pole along each isolatitude ring. When the indices are sorted monotonically, the scheme is optimised for data retrievals along latitude bands, such as required for spherical harmonics.

When the HEALPix axis is ordered with monotonically increasing indices, each type of indexing scheme is optimised for different types of operation. For instance, the ring scheme is optimised for Fourier transforms with spherical harmonics; and the nested scheme is optimised for geographical nearest-neighbour operations such as decreasing the refinement level.

A Multi-Order Coverage (MOC) has pixels with different refinement levels stored in the same array. An indexing scheme for an MOC has a unique index for each cell at each refinement level.

The nuniq scheme defines MOC indices such that all cells within a particular refinement level form a set of consecutive integers. E.g. for refinement level 0 the indices are 4, …, 15, for refinement level 1 the indices are 16, …, 63, for refinement level 2 the indices are 64, …, 255, etc. When the indices are sorted monotonically, the scheme is optimised for data retrievals within a refinement level and within a geographical range.

The zuniq scheme defines MOC indices such that, for adjacent refinement levels, cells in the proximity of a particular geographical location have similar index values. This means that the indices for a particular refinement level do not form a set of consecutive integers. In fact the difference between the smallest and largest indices within any given refinement level is \(O(10^19)\). When the indices are sorted monotonically, the scheme is optimised for data retrievals across refinement levels.

sort: bool, optional

If True then re-order the HEALPix axis of the output so that its HEALPix indices are monotonically increasing, including when the indexing scheme is unchanged. If False (the default) then don’t do this.

moc_refinement_level: int or None, optional

By default, or if moc_refinement_level is None, changing from an nuniq or zuniq MOC indexing scheme to a ring or nested indexing scheme is not allowed. However, if it is known that the nuniq or zuniq indices represent a single refinement level, then this integer level may be provided with the moc_refinement_level parameter, and then changing to nested or ring will be allowed. When the new indices are actually computed, an exception is raised if the original MOC indices do in fact include a refinement level other than moc_refinement_level.

Returns:

Field

The Field with the HEALPix indices redefined for the new 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()['indexing_scheme']
'nested'
>>> print(f.coordinate('healpix_index').array)
[ 0  1  2  3  4  5  6  7  8  9 10 11 12 13 14 15 16 17 18 19 20 21 22 23
 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47]

>>> g = f.healpix_change_indexing_scheme('nuniq')
>>> g.healpix_info()['indexing_scheme']
'nuniq'
>>> print(g.coordinate('healpix_index').array)
[16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39
 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63]

>>> g = f.healpix_change_indexing_scheme('ring')
>>> g.healpix_info()['indexing_scheme']
'ring'
>>> print(g.coordinate('healpix_index').array)
[13  5  4  0 15  7  6  1 17  9  8  2 19 11 10  3 28 20 27 12 30 22 21 14
 32 24 23 16 34 26 25 18 44 37 36 29 45 39 38 31 46 41 40 33 47 43 42 35]

>>> g = f.healpix_change_indexing_scheme('ring', sort=True)
>>> print(g.coordinate('healpix_index').array)
[ 0  1  2  3  4  5  6  7  8  9 10 11 12 13 14 15 16 17 18 19 20 21 22 23
 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47]
>>> h = g.healpix_change_indexing_scheme('nested')
>>> print(h.coordinate('healpix_index').array)
[ 3  7 11 15  2  1  6  5 10  9 14 13 19  0 23  4 27  8 31 12 17 22 21 26
 25 30 29 18 16 35 20 39 24 43 28 47 34 33 38 37 42 41 46 45 32 36 40 44]
>>> h = g.healpix_change_indexing_scheme(None, sort=True)
>>> print(h.coordinate('healpix_index').array)
[ 0  1  2  3  4  5  6  7  8  9 10 11 12 13 14 15 16 17 18 19 20 21 22 23
 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47]