Working with HEALPix Data

In this notebook, we showcase how UXarray can be used with HEALPix data.

• A brief overview into HEALPix

• Representing a HEALPix grid in the UGRID conventions

• Loading data that resides on HEALPix Grids

import cartopy.crs as ccrs

import uxarray as ux

What is HEALPix?

The Hierarchical Equal Area isoLatitude Pixelisation (HEALPix) algorithm is a method for the pixelisation of the 2-sphere. It has three defining qualities.

• The sphere is hierarchically tessellated into curvilinear quadrilaterals

• Areas of all pixels at a given resolution are identical

• Pixels are distributed on lines of constant latitude

Note

For more information on HEALPix, you can refer to this excellent overview in DKRZ’s Easy Gems documentation.

Representing a HEALPix Grid in the UGRID Conventions

Most datasets loaded into UXarray come with a dedicated grid file. However, for HEALPix datasets, the underlying grid structure is inferred from the number of cells.

For a HEALPix grid in a nested layout, the number of cells is defined by:

\[ N_{\text{cells}} = 12 \cdot z^4, \]

where z is the zoom level. A higher zoom level increases the effective resolution of the grid.

The ux.Grid.from_healpix(zoom) classmethod can be used to construct a ux.Grid instance representing a HEALPix grid in the UGRID conventions.

ux.Grid.from_healpix(zoom=3)

<uxarray.Grid>
Original Grid Type: HEALPix
Grid Dimensions:
  * n_face: 768
Grid Coordinates (Spherical):
  * face_lon: (768,)
  * face_lat: (768,)
Grid Coordinates (Cartesian):
Grid Connectivity Variables:
Grid Descriptor Variables:

uxarray.Grid

• Dimensions:
  • n_face: 768
• Spherical Coordinates: (2)
  • face_lon
    (n_face)
    float64
    45.0 50.62 39.38 ... -50.62 -45.0

    standard_name :

    longitude

    long name :

    Longitude of the center of each face

    units :

    degrees_east

    array([  45.        ,   50.625     ,   39.375     ,   45.        ,
             56.25      ,   61.875     ,   50.625     ,   56.25      ,
             33.75      ,   39.375     ,   28.125     ,   33.75      ,
             45.        ,   50.625     ,   39.375     ,   45.        ,
             67.5       ,   73.125     ,   61.875     ,   67.5       ,
             78.75      ,   84.375     ,   73.125     ,   83.57142857,
             56.25      ,   61.875     ,   50.625     ,   57.85714286,
             70.71428571,   82.5       ,   67.5       ,   81.        ,
             22.5       ,   28.125     ,   16.875     ,   22.5       ,
             33.75      ,   39.375     ,   28.125     ,   32.14285714,
             11.25      ,   16.875     ,    5.625     ,    6.42857143,
             19.28571429,   22.5       ,    7.5       ,    9.        ,
             45.        ,   52.5       ,   37.5       ,   45.        ,
             63.        ,   78.75      ,   56.25      ,   75.        ,
             27.        ,   33.75      ,   11.25      ,   15.        ,
             45.        ,   67.5       ,   22.5       ,   45.        ,
            135.        ,  140.625     ,  129.375     ,  135.        ,
            146.25      ,  151.875     ,  140.625     ,  146.25      ,
            123.75      ,  129.375     ,  118.125     ,  123.75      ,
            135.        ,  140.625     ,  129.375     ,  135.        ,
    ...
           -135.        , -129.375     , -140.625     , -135.        ,
           -123.75      , -118.125     , -129.375     , -123.75      ,
           -146.25      , -140.625     , -151.875     , -146.25      ,
           -135.        , -129.375     , -140.625     , -135.        ,
            -45.        ,  -22.5       ,  -67.5       ,  -45.        ,
            -15.        ,  -11.25      ,  -33.75      ,  -27.        ,
            -75.        ,  -56.25      ,  -78.75      ,  -63.        ,
            -45.        ,  -37.5       ,  -52.5       ,  -45.        ,
             -9.        ,   -7.5       ,  -22.5       ,  -19.28571429,
             -6.42857143,   -5.625     ,  -16.875     ,  -11.25      ,
            -32.14285714,  -28.125     ,  -39.375     ,  -33.75      ,
            -22.5       ,  -16.875     ,  -28.125     ,  -22.5       ,
            -81.        ,  -67.5       ,  -82.5       ,  -70.71428571,
            -57.85714286,  -50.625     ,  -61.875     ,  -56.25      ,
            -83.57142857,  -73.125     ,  -84.375     ,  -78.75      ,
            -67.5       ,  -61.875     ,  -73.125     ,  -67.5       ,
            -45.        ,  -39.375     ,  -50.625     ,  -45.        ,
            -33.75      ,  -28.125     ,  -39.375     ,  -33.75      ,
            -56.25      ,  -50.625     ,  -61.875     ,  -56.25      ,
            -45.        ,  -39.375     ,  -50.625     ,  -45.        ])

  • face_lat
    (n_face)
    float64
    4.78 9.594 9.594 ... -9.594 -4.78

    standard_name :

    latitude

    long name :

    Latitude of the center of each face

    units :

    degrees_north

    array([  4.78019185,   9.59406823,   9.59406823,  14.47751219,
            14.47751219,  19.47122063,  19.47122063,  24.62431835,
            14.47751219,  19.47122063,  19.47122063,  24.62431835,
            24.62431835,  30.        ,  30.        ,  35.68533471,
            24.62431835,  30.        ,  30.        ,  35.68533471,
            35.68533471,  41.8103149 ,  41.8103149 ,  48.14120779,
            35.68533471,  41.8103149 ,  41.8103149 ,  48.14120779,
            48.14120779,  54.3409123 ,  54.3409123 ,  60.43443884,
            24.62431835,  30.        ,  30.        ,  35.68533471,
            35.68533471,  41.8103149 ,  41.8103149 ,  48.14120779,
            35.68533471,  41.8103149 ,  41.8103149 ,  48.14120779,
            48.14120779,  54.3409123 ,  54.3409123 ,  60.43443884,
            48.14120779,  54.3409123 ,  54.3409123 ,  60.43443884,
            60.43443884,  66.44353569,  66.44353569,  72.38756093,
            60.43443884,  66.44353569,  66.44353569,  72.38756093,
            72.38756093,  78.28414761,  78.28414761,  84.14973294,
             4.78019185,   9.59406823,   9.59406823,  14.47751219,
            14.47751219,  19.47122063,  19.47122063,  24.62431835,
            14.47751219,  19.47122063,  19.47122063,  24.62431835,
            24.62431835,  30.        ,  30.        ,  35.68533471,
    ...
           -35.68533471, -30.        , -30.        , -24.62431835,
           -24.62431835, -19.47122063, -19.47122063, -14.47751219,
           -24.62431835, -19.47122063, -19.47122063, -14.47751219,
           -14.47751219,  -9.59406823,  -9.59406823,  -4.78019185,
           -84.14973294, -78.28414761, -78.28414761, -72.38756093,
           -72.38756093, -66.44353569, -66.44353569, -60.43443884,
           -72.38756093, -66.44353569, -66.44353569, -60.43443884,
           -60.43443884, -54.3409123 , -54.3409123 , -48.14120779,
           -60.43443884, -54.3409123 , -54.3409123 , -48.14120779,
           -48.14120779, -41.8103149 , -41.8103149 , -35.68533471,
           -48.14120779, -41.8103149 , -41.8103149 , -35.68533471,
           -35.68533471, -30.        , -30.        , -24.62431835,
           -60.43443884, -54.3409123 , -54.3409123 , -48.14120779,
           -48.14120779, -41.8103149 , -41.8103149 , -35.68533471,
           -48.14120779, -41.8103149 , -41.8103149 , -35.68533471,
           -35.68533471, -30.        , -30.        , -24.62431835,
           -35.68533471, -30.        , -30.        , -24.62431835,
           -24.62431835, -19.47122063, -19.47122063, -14.47751219,
           -24.62431835, -19.47122063, -19.47122063, -14.47751219,
           -14.47751219,  -9.59406823,  -9.59406823,  -4.78019185])

• Cartesian Coordinates: (0)
• Connectivity: (0)
• Descriptors: (0)
• Attributes: (5)

  zoom :

  3

  n_side :

  8

  n_pix :

  768

  nest :

  True

  source_grid_spec :

  HEALPix

By default, our Grid will only contain the face coordinate values, which represent the HEALPix pixel locations. We can see this above with only the face_lon and face_lat variables populated.

However, much of UXarray functionality requires the boundaries of each cell to be defined. This is represented using the following variables:

• node_lon: Longitude of the corners of each cell

• node_lat: Latitude of the corners of each cell

• face_node_connectivity: The indices of the nodes that surround each face

An optional parameter, pixels_only, is provided which can be set to True if you require the boundaries to be computed upfront.

ux.Grid.from_healpix(zoom=3, pixels_only=False)

<uxarray.Grid>
Original Grid Type: HEALPix
Grid Dimensions:
  * n_node: 770
  * n_face: 768
  * n_max_face_nodes: 4
Grid Coordinates (Spherical):
  * node_lon: (770,)
  * node_lat: (770,)
  * face_lon: (768,)
  * face_lat: (768,)
Grid Coordinates (Cartesian):
Grid Connectivity Variables:
  * face_node_connectivity: (768, 4)
Grid Descriptor Variables:

uxarray.Grid

• Dimensions:
  • n_face: 768
  • n_node: 770
  • n_max_face_nodes: 4
• Spherical Coordinates: (4)
  • node_lon
    (n_node)
    float64
    135.0 0.0 73.12 ... 11.25 -90.0

    standard_name :

    longitude

    long name :

    Longitude of the corner nodes of each face

    units :

    degrees_east

    array([ 135.        ,    0.        ,   73.125     , -101.25      ,
            -61.875     ,  151.875     ,  163.125     ,   67.5       ,
            150.        ,   78.75      , -146.25      ,  -28.125     ,
            120.        ,   84.375     ,  115.71428571,  -22.5       ,
           -150.        ,    0.        ,  -90.        ,   33.75      ,
           -135.        ,  146.25      ,  112.5       , -126.        ,
           -174.375     , -129.375     ,   73.125     , -123.75      ,
            -50.625     , -165.        ,  -56.25      ,   39.375     ,
           -157.5       , -146.25      ,  174.375     ,  -22.5       ,
            106.875     ,   56.25      ,  -75.        ,   25.71428571,
           -129.375     ,   45.        ,   11.25      ,   56.25      ,
             95.625     , -162.        ,  150.        ,   22.5       ,
            165.        ,  135.        , -120.        , -101.25      ,
            112.5       ,  151.875     ,    5.625     ,  112.5       ,
            135.        ,  163.125     ,  -95.625     ,   -5.625     ,
              0.        ,  135.        , -174.375     ,  123.75      ,
            -78.75      ,  -16.875     ,  174.375     , -118.125     ,
            -56.25      ,  106.875     ,  140.625     ,  101.25      ,
            118.125     ,   84.375     ,  168.75      ,   11.25      ,
            -39.375     ,  -90.        ,  -54.        ,  -45.        ,
    ...
            -30.        , -141.42857143, -106.875     ,  146.25      ,
             67.5       ,   90.        ,  -84.375     ,   12.85714286,
            -50.625     ,   28.125     ,  105.        , -135.        ,
            -39.375     ,   84.375     , -168.75      ,   95.625     ,
             61.875     ,  -11.25      ,   61.875     ,  157.5       ,
           -135.        ,  -61.875     ,   30.        , -180.        ,
            -45.        ,  -67.5       ,   22.5       , -123.75      ,
           -112.5       ,  -78.75      ,   33.75      ,  174.375     ,
           -140.625     ,  150.        , -108.        ,  -90.        ,
             56.25      ,   67.5       ,   38.57142857,   45.        ,
             90.        , -180.        ,  -95.625     ,  154.28571429,
            -56.25      , -135.        ,    0.        , -146.25      ,
            -90.        ,  -56.25      ,   -5.625     ,   95.625     ,
              0.        , -180.        ,   16.875     ,  -77.14285714,
            -67.5       ,  174.375     ,   73.125     ,  167.14285714,
           -112.5       ,  141.42857143, -112.5       ,   72.        ,
            146.25      ,  -16.875     ,   38.57142857, -140.625     ,
            -33.75      ,  129.375     ,   45.        ,  101.25      ,
             90.        ,   90.        ,  -11.25      , -146.25      ,
             11.25      ,  -90.        ])

  • node_lat
    (n_node)
    float64
    -9.594 90.0 -24.62 ... 30.0 -41.81

    standard_name :

    latitude

    long name :

    Latitude of the corner nodes of each face

    units :

    degrees_north

    array([ -9.59406823,  90.        , -24.62431835,  -9.59406823,
            35.68533471,  -4.78019185,  35.68533471,   0.        ,
           -54.3409123 , -30.        ,   0.        , -35.68533471,
            54.3409123 ,   4.78019185, -48.14120779,  66.44353569,
            72.38756093, -30.        ,   9.59406823,   0.        ,
            66.44353569, -41.8103149 , -41.8103149 ,  60.43443884,
            35.68533471,  35.68533471, -14.47751219, -30.        ,
            14.47751219,  54.3409123 ,  19.47122063, -14.47751219,
            41.8103149 , -41.8103149 ,  24.62431835,   0.        ,
            -4.78019185,  30.        , -54.3409123 , -48.14120779,
             4.78019185,  66.44353569,  19.47122063,  -9.59406823,
           -14.47751219, -60.43443884,  72.38756093, -66.44353569,
           -54.3409123 ,  30.        , -72.38756093,  19.47122063,
            -9.59406823, -14.47751219,  -4.78019185,   0.        ,
           -41.8103149 ,   4.78019185,  -4.78019185,   4.78019185,
           -84.14973294,   9.59406823, -35.68533471,  -9.59406823,
            41.8103149 ,   4.78019185,   4.78019185,   4.78019185,
           -30.        ,  24.62431835, -35.68533471, -30.        ,
             4.78019185,  -4.78019185,  19.47122063, -41.8103149 ,
            24.62431835, -48.14120779, -60.43443884, -54.3409123 ,
    ...
            72.38756093,  48.14120779, -35.68533471,  41.8103149 ,
           -66.44353569, -48.14120779,  14.47751219, -48.14120779,
           -35.68533471, -24.62431835,  54.3409123 ,  -9.59406823,
            35.68533471,  24.62431835,   9.59406823,  14.47751219,
            24.62431835, -41.8103149 , -14.47751219,   0.        ,
            30.        ,   4.78019185, -54.3409123 ,  78.28414761,
            30.        ,  19.47122063, -19.47122063,  19.47122063,
           -41.8103149 ,   0.        , -41.8103149 , -14.47751219,
           -35.68533471, -72.38756093, -60.43443884, -19.47122063,
             9.59406823,  66.44353569,  48.14120779,   9.59406823,
            84.14973294,  19.47122063, -24.62431835, -48.14120779,
             0.        ,   9.59406823,  41.8103149 ,  41.8103149 ,
            72.38756093,  30.        , -24.62431835,  35.68533471,
           -41.8103149 , -41.8103149 ,   4.78019185, -48.14120779,
           -30.        , -24.62431835,   4.78019185,  48.14120779,
            30.        ,  48.14120779,  41.8103149 , -60.43443884,
             9.59406823,  -4.78019185, -48.14120779, -14.47751219,
             0.        , -24.62431835, -30.        , -19.47122063,
            66.44353569,  19.47122063,   9.59406823, -19.47122063,
            30.        , -41.8103149 ])

  • face_lon
    (n_face)
    float64
    45.0 50.62 39.38 ... -50.62 -45.0

    standard_name :

    longitude

    long name :

    Longitude of the center of each face

    units :

    degrees_east

    array([  45.        ,   50.625     ,   39.375     ,   45.        ,
             56.25      ,   61.875     ,   50.625     ,   56.25      ,
             33.75      ,   39.375     ,   28.125     ,   33.75      ,
             45.        ,   50.625     ,   39.375     ,   45.        ,
             67.5       ,   73.125     ,   61.875     ,   67.5       ,
             78.75      ,   84.375     ,   73.125     ,   83.57142857,
             56.25      ,   61.875     ,   50.625     ,   57.85714286,
             70.71428571,   82.5       ,   67.5       ,   81.        ,
             22.5       ,   28.125     ,   16.875     ,   22.5       ,
             33.75      ,   39.375     ,   28.125     ,   32.14285714,
             11.25      ,   16.875     ,    5.625     ,    6.42857143,
             19.28571429,   22.5       ,    7.5       ,    9.        ,
             45.        ,   52.5       ,   37.5       ,   45.        ,
             63.        ,   78.75      ,   56.25      ,   75.        ,
             27.        ,   33.75      ,   11.25      ,   15.        ,
             45.        ,   67.5       ,   22.5       ,   45.        ,
            135.        ,  140.625     ,  129.375     ,  135.        ,
            146.25      ,  151.875     ,  140.625     ,  146.25      ,
            123.75      ,  129.375     ,  118.125     ,  123.75      ,
            135.        ,  140.625     ,  129.375     ,  135.        ,
    ...
           -135.        , -129.375     , -140.625     , -135.        ,
           -123.75      , -118.125     , -129.375     , -123.75      ,
           -146.25      , -140.625     , -151.875     , -146.25      ,
           -135.        , -129.375     , -140.625     , -135.        ,
            -45.        ,  -22.5       ,  -67.5       ,  -45.        ,
            -15.        ,  -11.25      ,  -33.75      ,  -27.        ,
            -75.        ,  -56.25      ,  -78.75      ,  -63.        ,
            -45.        ,  -37.5       ,  -52.5       ,  -45.        ,
             -9.        ,   -7.5       ,  -22.5       ,  -19.28571429,
             -6.42857143,   -5.625     ,  -16.875     ,  -11.25      ,
            -32.14285714,  -28.125     ,  -39.375     ,  -33.75      ,
            -22.5       ,  -16.875     ,  -28.125     ,  -22.5       ,
            -81.        ,  -67.5       ,  -82.5       ,  -70.71428571,
            -57.85714286,  -50.625     ,  -61.875     ,  -56.25      ,
            -83.57142857,  -73.125     ,  -84.375     ,  -78.75      ,
            -67.5       ,  -61.875     ,  -73.125     ,  -67.5       ,
            -45.        ,  -39.375     ,  -50.625     ,  -45.        ,
            -33.75      ,  -28.125     ,  -39.375     ,  -33.75      ,
            -56.25      ,  -50.625     ,  -61.875     ,  -56.25      ,
            -45.        ,  -39.375     ,  -50.625     ,  -45.        ])

  • face_lat
    (n_face)
    float64
    4.78 9.594 9.594 ... -9.594 -4.78

    standard_name :

    latitude

    long name :

    Latitude of the center of each face

    units :

    degrees_north

    array([  4.78019185,   9.59406823,   9.59406823,  14.47751219,
            14.47751219,  19.47122063,  19.47122063,  24.62431835,
            14.47751219,  19.47122063,  19.47122063,  24.62431835,
            24.62431835,  30.        ,  30.        ,  35.68533471,
            24.62431835,  30.        ,  30.        ,  35.68533471,
            35.68533471,  41.8103149 ,  41.8103149 ,  48.14120779,
            35.68533471,  41.8103149 ,  41.8103149 ,  48.14120779,
            48.14120779,  54.3409123 ,  54.3409123 ,  60.43443884,
            24.62431835,  30.        ,  30.        ,  35.68533471,
            35.68533471,  41.8103149 ,  41.8103149 ,  48.14120779,
            35.68533471,  41.8103149 ,  41.8103149 ,  48.14120779,
            48.14120779,  54.3409123 ,  54.3409123 ,  60.43443884,
            48.14120779,  54.3409123 ,  54.3409123 ,  60.43443884,
            60.43443884,  66.44353569,  66.44353569,  72.38756093,
            60.43443884,  66.44353569,  66.44353569,  72.38756093,
            72.38756093,  78.28414761,  78.28414761,  84.14973294,
             4.78019185,   9.59406823,   9.59406823,  14.47751219,
            14.47751219,  19.47122063,  19.47122063,  24.62431835,
            14.47751219,  19.47122063,  19.47122063,  24.62431835,
            24.62431835,  30.        ,  30.        ,  35.68533471,
    ...
           -35.68533471, -30.        , -30.        , -24.62431835,
           -24.62431835, -19.47122063, -19.47122063, -14.47751219,
           -24.62431835, -19.47122063, -19.47122063, -14.47751219,
           -14.47751219,  -9.59406823,  -9.59406823,  -4.78019185,
           -84.14973294, -78.28414761, -78.28414761, -72.38756093,
           -72.38756093, -66.44353569, -66.44353569, -60.43443884,
           -72.38756093, -66.44353569, -66.44353569, -60.43443884,
           -60.43443884, -54.3409123 , -54.3409123 , -48.14120779,
           -60.43443884, -54.3409123 , -54.3409123 , -48.14120779,
           -48.14120779, -41.8103149 , -41.8103149 , -35.68533471,
           -48.14120779, -41.8103149 , -41.8103149 , -35.68533471,
           -35.68533471, -30.        , -30.        , -24.62431835,
           -60.43443884, -54.3409123 , -54.3409123 , -48.14120779,
           -48.14120779, -41.8103149 , -41.8103149 , -35.68533471,
           -48.14120779, -41.8103149 , -41.8103149 , -35.68533471,
           -35.68533471, -30.        , -30.        , -24.62431835,
           -35.68533471, -30.        , -30.        , -24.62431835,
           -24.62431835, -19.47122063, -19.47122063, -14.47751219,
           -24.62431835, -19.47122063, -19.47122063, -14.47751219,
           -14.47751219,  -9.59406823,  -9.59406823,  -4.78019185])

• Cartesian Coordinates: (0)
• Connectivity: (1)
  • face_node_connectivity
    (n_face, n_max_face_nodes)
    int64
    664 731 466 399 ... 673 377 134 143

    cf_role :

    face_node_connectivity

    long name :

    Maps every face to its corner nodes.

    start_index :

    0

    _FillValue :

    -9223372036854775808

    array([[664, 731, 466, 399],
           [728, 665, 731, 664],
           [731, 579, 359, 466],
           ...,
           [320, 673, 143, 642],
           [143, 134, 250, 337],
           [673, 377, 134, 143]], shape=(768, 4))

• Descriptors: (0)
• Attributes: (5)

  zoom :

  3

  n_side :

  8

  n_pix :

  768

  nest :

  True

  source_grid_spec :

  HEALPix

However, even if you load in a HEALPix grid specifying that you do not want the connectivity upfront, they can still be constructed when desired because of UXarray’s internal design.

ux.Grid.from_healpix(zoom=3, pixels_only=True).face_node_connectivity

<xarray.DataArray 'face_node_connectivity' (n_face: 768, n_max_face_nodes: 4)> Size: 25kB
array([[212, 760, 378, 697],
       [651, 586, 760, 212],
       [760, 455, 536, 378],
       ...,
       [580, 593, 699, 671],
       [699, 590, 138, 188],
       [593, 325, 590, 699]], shape=(768, 4))
Dimensions without coordinates: n_face, n_max_face_nodes
Attributes:
    cf_role:      face_node_connectivity
    long name:    Maps every face to its corner nodes.
    start_index:  0
    _FillValue:   -9223372036854775808

xarray.DataArray

'face_node_connectivity'

• n_face: 768
• n_max_face_nodes: 4

• 212 760 378 697 651 586 760 212 ... 699 590 138 188 593 325 590 699

  array([[212, 760, 378, 697],
         [651, 586, 760, 212],
         [760, 455, 536, 378],
         ...,
         [580, 593, 699, 671],
         [699, 590, 138, 188],
         [593, 325, 590, 699]], shape=(768, 4))

• Coordinates: (0)
• Indexes: (0)
• Attributes: (4)

  cf_role :

  face_node_connectivity

  long name :

  Maps every face to its corner nodes.

  start_index :

  0

  _FillValue :

  -9223372036854775808

Grid-Agnostic Functionality

Once loaded in, UXarray does not care about the underlying grid format, as it represents all formats in its unified UGRID-like convention. This means that all existing functionality is supported through the same UXarray inferface. Below are basic examples of plotting & remapping.

Plotting

By using UXarray’s plotting functionality, we can observe how increasing the zoom level leads to a higher-resolution grid.

(
    ux.Grid.from_healpix(zoom=2).plot(
        periodic_elements="split", projection=ccrs.Orthographic(), title="zoom=2"
    )
    + ux.Grid.from_healpix(zoom=3).plot(
        periodic_elements="split", projection=ccrs.Orthographic(), title="zoom=3"
    )
    + ux.Grid.from_healpix(zoom=4).plot(
        periodic_elements="split", projection=ccrs.Orthographic(), title="zoom=4"
    )
).cols(1)

Remapping

Below is a simple example of remapping UGRID data residing on a CSne30 grid to a HEALPix grid with a zoom level of 5.

source_uxds = ux.open_dataset(
    "../../test/meshfiles/ugrid/outCSne30/outCSne30.ug",
    "../../test/meshfiles/ugrid/outCSne30/outCSne30_vortex.nc",
)

# source data & grid
source_uxds["psi"].plot(
    cmap="inferno", projection=ccrs.Orthographic(), title="Source Data"
)

# destination grid
hp_grid = ux.Grid.from_healpix(zoom=5)

Before remapping, we can plot our Source and Destination grids.

source_uxds.uxgrid.plot(
    projection=ccrs.Orthographic(), title="Source Grid (CSne30)"
) + hp_grid.plot(projection=ccrs.Orthographic(), title="Destination Grid (HEALPix)")

We can now perform our remapping. In this case, we apply a simple nearest neighbor remapping.

psi_hp = source_uxds["psi"].remap.nearest_neighbor(destination_grid=hp_grid)
psi_hp

<xarray.UxDataArray 'psi' (n_face: 12288)> Size: 98kB
array([0.631794, 0.634404, 0.666049, ..., 1.424628, 1.437251, 1.437746],
      shape=(12288,))
Dimensions without coordinates: n_face

<xarray.UxDataArray 'psi' (n_face: 12288)> Size: 98kB
array([0.631794, 0.634404, 0.666049, ..., 1.424628, 1.437251, 1.437746],
      shape=(12288,))
Dimensions without coordinates: n_face

uxarray.UxDataArray

'psi'

• n_face: 12288

• 0.6318 0.6344 0.666 0.666 0.6344 ... 1.437 1.425 1.425 1.437 1.438

  array([0.631794, 0.634404, 0.666049, ..., 1.424628, 1.437251, 1.437746],
        shape=(12288,))

• Coordinates: (0)
• Indexes: (0)
• Attributes: (0)

Show Grid Information

<uxarray.Grid>
Original Grid Type: HEALPix
Grid Dimensions:
  * n_node: 12290
  * n_face: 12288
  * n_max_face_nodes: 4
Grid Coordinates (Spherical):
  * node_lon: (12290,)
  * node_lat: (12290,)
  * face_lon: (12288,)
  * face_lat: (12288,)
Grid Coordinates (Cartesian):
  * face_x: (12288,)
  * face_y: (12288,)
  * face_z: (12288,)
Grid Connectivity Variables:
  * face_node_connectivity: (12288, 4)
Grid Descriptor Variables:
  * n_nodes_per_face: (12288,)

uxarray.UxDataArray.uxgrid

• Dimensions:
  • n_face: 12288
  • n_node: 12290
  • n_max_face_nodes: 4
• Spherical Coordinates: (4)
  • node_lon
    (n_node)
    float64
    115.3 74.53 -167.3 ... 90.0 5.625

    standard_name :

    longitude

    long name :

    Longitude of the corner nodes of each face

    units :

    degrees_east

    array([ 115.3125 ,   74.53125, -167.34375, ...,  -30.9375 ,   90.     ,
              5.625  ], shape=(12290,))

  • node_lat
    (n_node)
    float64
    -19.47 25.94 ... -61.94 -14.48

    standard_name :

    latitude

    long name :

    Latitude of the corner nodes of each face

    units :

    degrees_north

    array([-19.47122063,  25.94447977,  -1.19374844, ..., -14.47751219,
           -61.94383702, -14.47751219], shape=(12290,))

  • face_lon
    (n_face)
    float64
    45.0 46.41 43.59 ... -46.41 -45.0

    standard_name :

    longitude

    long name :

    Longitude of the center of each face

    units :

    degrees_east

    array([ 45.     ,  46.40625,  43.59375, ..., -43.59375, -46.40625,
           -45.     ], shape=(12288,))

  • face_lat
    (n_face)
    float64
    1.194 2.388 2.388 ... -2.388 -1.194

    standard_name :

    latitude

    long name :

    Latitude of the center of each face

    units :

    degrees_north

    array([ 1.19374844,  2.38801546,  2.38801546, ..., -2.38801546,
           -2.38801546, -1.19374844], shape=(12288,))

• Cartesian Coordinates: (3)
  • face_x
    (n_face)
    float64
    0.707 0.6889 ... 0.6889 0.707

    standard_name :

    x

    long name :

    Cartesian x location of the center of each face

    units :

    meters

    array([0.70695331, 0.68894173, 0.72361812, ..., 0.72361812, 0.68894173,
           0.70695331], shape=(12288,))

  • face_y
    (n_face)
    float64
    0.707 0.7236 ... -0.7236 -0.707

    standard_name :

    y

    long name :

    Cartesian y location of the center of each face

    units :

    meters

    array([ 0.70695331,  0.72361812,  0.68894173, ..., -0.68894173,
           -0.72361812, -0.70695331], shape=(12288,))

  • face_z
    (n_face)
    float64
    0.02083 0.04167 ... -0.02083

    standard_name :

    z

    long name :

    Cartesian z location of the center of each face

    units :

    meters

    array([ 0.02083333,  0.04166667,  0.04166667, ..., -0.04166667,
           -0.04166667, -0.02083333], shape=(12288,))

• Connectivity: (1)
  • face_node_connectivity
    (n_face, n_max_face_nodes)
    int64
    49 4544 11779 ... 9830 1230 7419

    cf_role :

    face_node_connectivity

    long name :

    Maps every face to its corner nodes.

    start_index :

    0

    _FillValue :

    -9223372036854775808

    array([[   49,  4544, 11779,  1108],
           [ 8505,   516,  4544,    49],
           [ 4544, 10549, 12207, 11779],
           ...,
           [ 3724,  5105,  7419,   625],
           [ 7419,  1230,  6474, 11990],
           [ 5105,  9830,  1230,  7419]], shape=(12288, 4))

• Descriptors: (1)
  • n_nodes_per_face
    (n_face)
    int64
    4 4 4 4 4 4 4 4 ... 4 4 4 4 4 4 4 4

    cf_role :

    n_nodes_per_face

    long name :

    Number of nodes per face

    array([4, 4, 4, ..., 4, 4, 4], shape=(12288,))

• Attributes: (5)

  zoom :

  5

  n_side :

  32

  n_pix :

  12288

  nest :

  True

  source_grid_spec :

  HEALPix

Our original data variable now resides on our HEALPix grid.

psi_hp.plot(cmap="inferno", projection=ccrs.Orthographic(), title="Remapped Data")

We can now chain together a few functions to convert our output from a UXarray Dataset to a NetCDF file, with the grid represented in the HEALPix format.

• to_dataset(): Converts the ux.UxDataArray to a ux.UxDataset

• to_xarray(grid_format="HEALPix"): Converts our ux.UxDataset to a xr.Dataset encoded in the HEALPix format.

• to_netcdf("psi_healpix.nc"): Saves our dataset to disk as a NetCDF file.

psi_hp.to_dataset().to_xarray(grid_format="HEALPix").to_netcdf("psi_healpix.nc")

Loading HEALPix Data

In the remapping example above, we successfully remapped a data variable onto a HEALPix grid and saved it as a NetCDF file.

UXarray extends Xarray’s Dataset and DataArray classes to provide grid-aware implementations.

Using the example we generated above, we can load in data that is stored in the HEALPix format using the UxDataset.from_healpix() classmethod.

uxds = ux.UxDataset.from_healpix("psi_healpix.nc")
uxds

<xarray.UxDataset> Size: 98kB
Dimensions:  (n_face: 12288)
Dimensions without coordinates: n_face
Data variables:
    psi      (n_face) float64 98kB ...

<xarray.UxDataset> Size: 98kB
Dimensions:  (n_face: 12288)
Dimensions without coordinates: n_face
Data variables:
    psi      (n_face) float64 98kB ...

uxarray.UxDataset

• Dimensions:
  • n_face: 12288
• Coordinates: (0)
• Data variables: (1)
  • psi
    (n_face)
    float64
    ...

    [12288 values with dtype=float64]

• Indexes: (0)
• Attributes: (0)

Show Grid Information

<uxarray.Grid>
Original Grid Type: HEALPix
Grid Dimensions:
  * n_face: 12288
Grid Coordinates (Spherical):
  * face_lon: (12288,)
  * face_lat: (12288,)
Grid Coordinates (Cartesian):
Grid Connectivity Variables:
Grid Descriptor Variables:

uxarray.UxDataset.uxgrid

• Dimensions:
  • n_face: 12288
• Spherical Coordinates: (2)
  • face_lon
    (n_face)
    float64
    45.0 46.41 43.59 ... -46.41 -45.0

    standard_name :

    longitude

    long name :

    Longitude of the center of each face

    units :

    degrees_east

    array([ 45.     ,  46.40625,  43.59375, ..., -43.59375, -46.40625,
           -45.     ], shape=(12288,))

  • face_lat
    (n_face)
    float64
    1.194 2.388 2.388 ... -2.388 -1.194

    standard_name :

    latitude

    long name :

    Latitude of the center of each face

    units :

    degrees_north

    array([ 1.19374844,  2.38801546,  2.38801546, ..., -2.38801546,
           -2.38801546, -1.19374844], shape=(12288,))

• Cartesian Coordinates: (0)
• Connectivity: (0)
• Descriptors: (0)
• Attributes: (5)

  zoom :

  5

  n_side :

  32

  n_pix :

  12288

  nest :

  True

  source_grid_spec :

  HEALPix

The interface above looks almost identical to what you would see if you loaded in the file directly with Xarray.

import xarray as xr

xr.open_dataset("psi_healpix.nc")

<xarray.Dataset> Size: 98kB
Dimensions:  (cell: 12288)
Dimensions without coordinates: cell
Data variables:
    psi      (cell) float64 98kB ...

xarray.Dataset

• Dimensions:
  • cell: 12288
• Coordinates: (0)
• Data variables: (1)
  • psi
    (cell)
    float64
    ...

    [12288 values with dtype=float64]

• Indexes: (0)
• Attributes: (0)

However, there are a few noticeable differences and additions that streamline UXarray’s implementation and provide more context on what grid the data resides on:

1. The “Show Grid Information” tab provides information on the underlying Grid object that is attached via the .uxgrid attribute

2. The zoom for HEALPix grids is automatically determined from the cells dimension, with an appropriate Grid constructed from that 3The dimensions are renamed to match the UGRID conventions, with cells being renamed to n_face for the case of HEALPix grids

We can then directly access our Grid using the .uxgrid attribute, allowing for grid-specific functionallity as described in the sections above.

uxds.uxgrid

<uxarray.Grid>
Original Grid Type: HEALPix
Grid Dimensions:
  * n_face: 12288
Grid Coordinates (Spherical):
  * face_lon: (12288,)
  * face_lat: (12288,)
Grid Coordinates (Cartesian):
Grid Connectivity Variables:
Grid Descriptor Variables:

uxarray.Grid

• Dimensions:
  • n_face: 12288
• Spherical Coordinates: (2)
  • face_lon
    (n_face)
    float64
    45.0 46.41 43.59 ... -46.41 -45.0

    standard_name :

    longitude

    long name :

    Longitude of the center of each face

    units :

    degrees_east

    array([ 45.     ,  46.40625,  43.59375, ..., -43.59375, -46.40625,
           -45.     ], shape=(12288,))

  • face_lat
    (n_face)
    float64
    1.194 2.388 2.388 ... -2.388 -1.194

    standard_name :

    latitude

    long name :

    Latitude of the center of each face

    units :

    degrees_north

    array([ 1.19374844,  2.38801546,  2.38801546, ..., -2.38801546,
           -2.38801546, -1.19374844], shape=(12288,))

• Cartesian Coordinates: (0)
• Connectivity: (0)
• Descriptors: (0)
• Attributes: (5)

  zoom :

  5

  n_side :

  32

  n_pix :

  12288

  nest :

  True

  source_grid_spec :

  HEALPix

Future Work

Support for the HEALPix format is still in its early stages. We welcome your suggestions and contributions! To get started, please check out our Contributors Guide.