Reading & Working with Geometry Files

This notebooks demonstrates how to use the Grid.from_file() class method to load in geometry files such as:

1. Shapefile

2. GeoJSON

Highlighted is a workflow showcasing how to remap a variable from an unstructured grid to a Shapefile.

import uxarray as ux
import warnings
import geocat.datafiles as geodf

warnings.filterwarnings("ignore")

Downloading file 'registry.txt' from 'https://github.com/NCAR/GeoCAT-datafiles/raw/main/registry.txt' to '/home/docs/.cache/geocat'.

Load a shapefile and plot

• This section demonstrates how to load a shapefile using uxarray’s Grid.from_file() function

• The shapefile used in this example is the US national boundary file from the US Census Bureau. It is a 20m resolution shapefile that represents the national boundary of the United States.

• The data plotted is subset to a specific bounding box, which is defined by the latitude and longitude bounds. The result is plotted using the matplotlib backend.

shp_filename = (
    "../../test/meshfiles/shp/cb_2018_us_nation_20m/cb_2018_us_nation_20m.shp"
)
uxds = ux.Grid.from_file(shp_filename)
lat_bounds = [-90, -70]
lon_bounds = [20, 55]
uxds = uxds.subset.bounding_box(lon_bounds, lat_bounds)
uxds.plot(
    title="US 20m Focus on Mainland (cb_2018_us_nation_20m.shp)",
    backend="matplotlib",
    width=500,
)

ERROR 1: PROJ: proj_create_from_database: Open of /home/docs/checkouts/readthedocs.org/user_builds/uxarray/conda/latest/share/proj failed

Transformed CRS: EPSG:4326

Load a Geojson file and plot

• This section demonstrates how to load a Geojson file using uxarray’s Grid.from_file() function

• The Geojson file used in this example is a few buildings around downtown Chicago. The plot is shown using the “matplotlib” backend for bounds specific to the region.

geojson_filename = "../../test/meshfiles/geojson/sample_chicago_buildings.geojson"
uxgeojson = ux.Grid.from_file(geojson_filename)
lat_bounds = [41.6, 42.1]
lon_bounds = [-87.7, -87.5]
uxgeojson.subset.bounding_box(lon_bounds, lat_bounds).plot(backend="matplotlib")

Skipping field nodes: unsupported OGR type: 13

Open NetCDF mesh file using the Grid.from_file() function

• Regular NetCDF files can also be opened using this function. Backend options available are:

  • xarray

  • geopandas (default for opening shapefile, geojson file and other file formats supported by geopandas read_file function)

• In the following code, we load a NetCDF mesh file: scrip/outCSne8/outCSne8.nc and print out the grid contents.

nc_filename = "../../test/meshfiles/scrip/outCSne8/outCSne8.nc"
uxgrid = ux.Grid.from_file(nc_filename, backend="xarray")
uxgrid

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

uxarray.Grid

• Dimensions:
  • n_node: 407
  • n_face: 384
  • n_max_face_nodes: 4
• Spherical Coordinates: (4)
  • node_lon
    (n_node)
    float64
    -121.8 0.0 135.0 ... -135.0 -180.0

    array([-121.79537017,    0.        ,  135.        ,  -45.        ,
            101.25      ,  146.25      ,   90.        ,  112.5       ,
            148.20462983,  157.5       ,  -11.25      ,   45.        ,
            112.5       ,  -67.5       , -163.42207913, -123.75      ,
             90.        ,  -67.5       ,  -78.75      ,  -67.5       ,
             45.        ,   90.        ,   90.        ,   45.        ,
              0.        , -180.        ,  115.65110694, -180.        ,
            148.20462983,    0.        , -180.        ,  146.25      ,
            -90.        ,  -33.75      , -180.        ,   90.        ,
            154.34889306, -154.34889306, -157.5       , -135.        ,
            -11.25      ,  123.75      ,   22.5       ,   90.        ,
           -157.5       ,   33.75      , -135.        , -168.75      ,
            -11.25      ,   45.        ,    0.        ,   33.75      ,
            157.5       , -168.75      , -168.75      ,  135.        ,
            168.75      , -135.        ,  135.        ,  112.5       ,
           -123.75      ,  157.5       , -123.75      , -180.        ,
           -168.75      , -148.20462983,    0.        ,  -58.20462983,
           -123.75      ,   56.25      ,  -90.        , -123.75      ,
            -67.5       ,   16.57792087,   33.75      ,   25.65110694,
            -78.75      ,  -56.25      ,   78.75      , -180.        ,
    ...
            135.        ,  101.25      ,  135.        ,   22.5       ,
              0.        , -112.5       ,  -33.75      ,  -90.        ,
            -25.65110694, -101.25      ,  168.75      ,   31.79537017,
              0.        ,   45.        , -135.        ,  -11.25      ,
             33.75      ,  -22.5       ,  -11.25      ,   22.5       ,
            146.25      ,   56.25      , -135.        ,   11.25      ,
            -33.75      ,  -45.        ,    0.        ,  135.        ,
             90.        ,   90.        ,  -45.        , -146.25      ,
           -157.5       ,   67.5       ,  101.25      , -101.25      ,
            106.57792087,  -45.        , -154.34889306,  135.        ,
             90.        ,  157.5       , -115.65110694,   78.75      ,
            146.25      ,   33.75      ,   16.57792087,   31.79537017,
             33.75      , -180.        ,  101.25      ,    0.        ,
           -135.        ,   78.75      ,  -56.25      , -101.25      ,
            112.5       , -101.25      ,  154.34889306,    0.        ,
             67.5       ,  -45.        ,   45.        ,  -11.25      ,
              0.        , -157.5       ,  -56.25      ,   11.25      ,
            168.75      ,  112.5       ,  -78.75      ,  157.5       ,
           -101.25      ,  135.        ,  112.5       ,  115.65110694,
            -78.75      , -135.        , -180.        ])

  • node_lat
    (n_node)
    float64
    51.83 78.75 -25.29 ... 16.32 -45.0

    standard_name :

    latitude

    long name :

    Latitude of the corner nodes of each face

    units :

    degrees_north

    array([ 51.82725682,  78.75      , -25.28949999,  25.28949999,
            44.44421648,  29.05524671, -22.5       ,  10.41312055,
           -51.82725682,  20.94102047,  44.44421648,  59.6388066 ,
             0.        , -42.7342096 ,  55.11742333, -29.05524671,
           -11.25      , -31.68772086, -44.44421648, -20.94102047,
            74.2884649 , -45.        ,  78.75      ,  25.28949999,
           -78.75      ,  56.25      , -65.32128302, -11.25      ,
            51.82725682, -11.25      , -22.5       ,  -9.39111394,
           -33.75      ,  19.00401458,  45.        , -67.5       ,
            65.32128302, -65.32128302, -31.68772086, -59.6388066 ,
           -33.23841964, -19.00401458,  31.68772086,  33.75      ,
            42.7342096 ,  39.74249362,   8.00626179, -44.44421648,
             0.        ,  16.32494994, -22.5       ,   0.        ,
           -10.41312055,  11.03919442,  44.44421648, -59.6388066 ,
           -33.23841964,  -8.00626179,  74.2884649 ,  20.94102047,
            19.00401458,  31.68772086,   9.39111394,  78.75      ,
           -22.10967284,  51.82725682,   0.        , -51.82725682,
           -19.00401458, -19.00401458,   0.        ,  -9.39111394,
            42.7342096 ,  55.11742333,  -9.39111394, -65.32128302,
            11.03919442, -19.00401458,  11.03919442,  11.25      ,
    ...
            59.6388066 ,  22.10967284, -16.32494994, -10.41312055,
           -67.5       , -42.7342096 ,   0.        ,  56.25      ,
           -65.32128302, -33.23841964,  33.23841964, -51.82725682,
            67.5       ,  35.26438968,  74.2884649 ,  11.03919442,
           -39.74249362,   0.        , -11.03919442,  42.7342096 ,
            39.74249362,   9.39111394,  25.28949999, -22.10967284,
            39.74249362, -25.28949999,  45.        ,  25.28949999,
           -33.75      ,  11.25      ,  74.2884649 ,   0.        ,
            31.68772086, -10.41312055,  11.03919442,  44.44421648,
           -55.11742333,  46.62135285,  65.32128302, -90.        ,
            45.        , -20.94102047,  65.32128302, -11.03919442,
           -19.00401458,   9.39111394, -55.11742333,  51.82725682,
           -29.05524671, -78.75      , -33.23841964,  67.5       ,
             0.        , -33.23841964, -39.74249362, -44.44421648,
            42.7342096 ,  33.23841964, -65.32128302,   0.        ,
           -42.7342096 , -35.26438968,  46.62135285, -44.44421648,
           -11.25      ,  20.94102047,   9.39111394, -44.44421648,
           -22.10967284,  31.68772086,   0.        , -31.68772086,
            22.10967284,  35.26438968, -20.94102047,  65.32128302,
            44.44421648,  16.32494994, -45.        ])

  • face_lon
    (n_face)
    float64
    -39.51 -28.23 ... 146.9 135.0

    array([ -39.50515122,  -28.22575664,  -16.938173  ,   -5.64647178,
              5.64647178,   16.938173  ,   28.22575664,   39.50515122,
            -39.44270901,  -28.17944289,  -16.91001057,   -5.63705057,
              5.63705057,   16.91001057,   28.17944289,   39.44270901,
            -39.40093702,  -28.14642331,  -16.88903971,   -5.62987953,
              5.62987953,   16.88903971,   28.14642331,   39.40093702,
            -39.38018697,  -28.12935997,  -16.87789439,   -5.62601283,
              5.62601283,   16.87789439,   28.12935997,   39.38018697,
            -39.38018697,  -28.12935997,  -16.87789439,   -5.62601283,
              5.62601283,   16.87789439,   28.12935997,   39.38018697,
            -39.40093702,  -28.14642331,  -16.88903971,   -5.62987953,
              5.62987953,   16.88903971,   28.14642331,   39.40093702,
            -39.44270901,  -28.17944289,  -16.91001057,   -5.63705057,
              5.63705057,   16.91001057,   28.17944289,   39.44270901,
            -39.50515122,  -28.22575664,  -16.938173  ,   -5.64647178,
              5.64647178,   16.938173  ,   28.22575664,   39.50515122,
             50.49484878,   61.77424336,   73.061827  ,   84.35352822,
             95.64647178,  106.938173  ,  118.22575664,  129.50515122,
             50.55729099,   61.82055711,   73.08998943,   84.36294943,
             95.63705057,  106.91001057,  118.17944289,  129.44270901,
    ...
            -56.87605864,  -45.        ,  -29.60780059,  -10.46060642,
             10.46060642,   29.60780059,   45.        ,   56.87605864,
            -45.        ,  -33.12394136,  -20.34247552,   -6.86824391,
              6.86824391,   20.34247552,   33.12394136,   45.        ,
            -45.        ,  -33.12394136,  -20.34247552,   -6.86824391,
              6.86824391,   20.34247552,   33.12394136,   45.        ,
            -56.87605864,  -45.        ,  -29.60780059,  -10.46060642,
             10.46060642,   29.60780059,   45.        ,   56.87605864,
            -69.65752448,  -60.39219941,  -45.        ,  -17.99934362,
             17.99934362,   45.        ,   60.39219941,   69.65752448,
            -83.13175609,  -79.53939358,  -72.00065638,  -45.        ,
             45.        ,   72.00065638,   79.53939358,   83.13175609,
            -96.86824391, -100.46060642, -107.99934362, -135.        ,
            135.        ,  107.99934362,  100.46060642,   96.86824391,
           -110.34247552, -119.60780059, -135.        , -162.00065638,
            162.00065638,  135.        ,  119.60780059,  110.34247552,
           -123.12394136, -135.        , -150.39219941, -169.53939358,
            169.53939358,  150.39219941,  135.        ,  123.12394136,
           -135.        , -146.87605864, -159.65752448, -173.13175609,
            173.13175609,  159.65752448,  146.87605864,  135.        ])

  • face_lat
    (n_face)
    float64
    -32.46 -35.94 ... 45.51 40.62

    standard_name :

    latitude

    long name :

    Latitude of the center of each face

    units :

    degrees_north

    array([-32.46238087, -35.93598376, -38.16035064, -39.24358466,
           -39.24358466, -38.16035064, -35.93598376, -32.46238087,
           -22.51544319, -25.27829895, -27.10610882, -28.01403378,
           -28.01403378, -27.10610882, -25.27829895, -22.51544319,
           -13.24266966, -15.00607745, -16.19959315, -16.8010792 ,
           -16.8010792 , -16.19959315, -15.00607745, -13.24266966,
            -4.37014732,  -4.97479555,  -5.38883565,  -5.5990849 ,
            -5.5990849 ,  -5.38883565,  -4.97479555,  -4.37014732,
             4.37014732,   4.97479555,   5.38883565,   5.5990849 ,
             5.5990849 ,   5.38883565,   4.97479555,   4.37014732,
            13.24266966,  15.00607745,  16.19959315,  16.8010792 ,
            16.8010792 ,  16.19959315,  15.00607745,  13.24266966,
            22.51544319,  25.27829895,  27.10610882,  28.01403378,
            28.01403378,  27.10610882,  25.27829895,  22.51544319,
            32.46238087,  35.93598376,  38.16035064,  39.24358466,
            39.24358466,  38.16035064,  35.93598376,  32.46238087,
           -32.46238087, -35.93598376, -38.16035064, -39.24358466,
           -39.24358466, -38.16035064, -35.93598376, -32.46238087,
           -22.51544319, -25.27829895, -27.10610882, -28.01403378,
           -28.01403378, -27.10610882, -25.27829895, -22.51544319,
    ...
           -45.51187736, -52.8509202 , -58.39443121, -61.46953506,
           -61.46953506, -58.39443121, -52.8509202 , -45.51187736,
           -40.61744705, -45.51187736, -48.77916914, -50.4173049 ,
           -50.4173049 , -48.77916914, -45.51187736, -40.61744705,
            40.61744705,  45.51187736,  48.77916914,  50.4173049 ,
            50.4173049 ,  48.77916914,  45.51187736,  40.61744705,
            45.51187736,  52.8509202 ,  58.39443121,  61.46953506,
            61.46953506,  58.39443121,  52.8509202 ,  45.51187736,
            48.77916914,  58.39443121,  66.76250221,  72.30656847,
            72.30656847,  66.76250221,  58.39443121,  48.77916914,
            50.4173049 ,  61.46953506,  72.30656847,  82.06899202,
            82.06899202,  72.30656847,  61.46953506,  50.4173049 ,
            50.4173049 ,  61.46953506,  72.30656847,  82.06899202,
            82.06899202,  72.30656847,  61.46953506,  50.4173049 ,
            48.77916914,  58.39443121,  66.76250221,  72.30656847,
            72.30656847,  66.76250221,  58.39443121,  48.77916914,
            45.51187736,  52.8509202 ,  58.39443121,  61.46953506,
            61.46953506,  58.39443121,  52.8509202 ,  45.51187736,
            40.61744705,  45.51187736,  48.77916914,  50.4173049 ,
            50.4173049 ,  48.77916914,  45.51187736,  40.61744705])

• Cartesian Coordinates: (0)
• Connectivity: (1)
  • face_node_connectivity
    (n_face, n_max_face_nodes)
    int64
    389 211 297 353 ... 114 208 401 348

    cf_role :

    face_node_connectivity

    long name :

    Maps every face to its corner nodes.

    start_index :

    0

    _FillValue :

    -9223372036854775808

    array([[389, 211, 297, 353],
           [211,  94, 277, 297],
           [ 94, 391,  40, 277],
           ...,
           [170,  28, 107, 219],
           [ 28, 114, 348, 107],
           [114, 208, 401, 348]])

• Descriptors: (0)
• Attributes: (1)

  source_grid_spec :

  Scrip

Remapping from Shapefile

The following steps are needed for Remapping Global Relative Humidity Data on to a specific region defined by Shapefile using UXarray

1. Read the shapefile (uxds)

shp_filename = (
    "../../test/meshfiles/shp/chicago_neighborhoods/chicago_neighborhoods.shp"
)
uxds = ux.Grid.from_file(shp_filename)
lat_bounds = [41, 43]
lon_bounds = [-89, -90]
uxds = uxds.subset.bounding_box(lon_bounds, lat_bounds)
uxds.plot(
    title="Chicago Neighborhoods",
    backend="bokeh",
)

Original CRS: None
Assigned CRS: EPSG:4326

2. Initialize Input Data Files

   • The input datasets consist of NetCDF files that include global relative humidity data.

   • The datafiles variable points to two NetCDF files using the geodf.get function, specifying the paths:

     • The first file contains meteorological diagnostic data:
       netcdf_files/MPAS/FalkoJudt/dyamond_1/30km/diag.2016-08-20_00.00.00_subset.nc.

     • The second file provides the MPAS grid specification:
       netcdf_files/MPAS/FalkoJudt/dyamond_1/30km/x1.655362.grid_subset.nc.

3. Open the Datasets with UXarray

   • The ux.open_dataset() function is used to load these files, making them accessible as a UXarray Dataset.

   • uxds_source is the opened dataset that holds the meteorological data, such as relative humidity, structured over the MPAS grid.

datafiles = (
    geodf.get(
        "netcdf_files/MPAS/FalkoJudt/dyamond_1/30km/diag.2016-08-20_00.00.00_subset.nc"
    ),
    geodf.get("netcdf_files/MPAS/FalkoJudt/dyamond_1/30km/x1.655362.grid_subset.nc"),
)

uxds_source = ux.open_dataset(datafiles[1], datafiles[0])

Downloading file 'netcdf_files/MPAS/FalkoJudt/dyamond_1/30km/diag.2016-08-20_00.00.00_subset.nc' from 'https://github.com/NCAR/GeoCAT-datafiles/raw/main/netcdf_files/MPAS/FalkoJudt/dyamond_1/30km/diag.2016-08-20_00.00.00_subset.nc' to '/home/docs/.cache/geocat'.

Downloading file 'netcdf_files/MPAS/FalkoJudt/dyamond_1/30km/x1.655362.grid_subset.nc' from 'https://github.com/NCAR/GeoCAT-datafiles/raw/main/netcdf_files/MPAS/FalkoJudt/dyamond_1/30km/x1.655362.grid_subset.nc' to '/home/docs/.cache/geocat'.

4. Remap Relative Humidity Data

   • The relhum_200hPa variable is accessed from uxds_source to extract relative humidity data at 200 hPa pressure level.

   • Inverse Distance Weighted Remapping:

     • The data is remapped using UXarray’s inverse_distance_weighted method.

     • The remapping is done to “face centers,” adapting the data from its original grid to align with a new shape or structure.

5. Plot the Remapped Data

   • The remapped data for Chicago neighborhoods is plotted using UXarray’s plotting utilities.

   • The plot uses the sequential_blue colormap and is rendered with the bokeh backend.

   • The title of the plot is “Chicago Neighborhoods Relative Humidity,” giving a clear representation of how relative humidity varies spatially.

chicago_relative_humidty = uxds_source["relhum_200hPa"].remap.inverse_distance_weighted(
    uxds, remap_to="face centers"
)

chicago_relative_humidty[0].plot(
    cmap=ux.cmaps.sequential_blue,
    title="Chicago Neighborhoods Relative Humidty",
    backend="bokeh",
)