uxarray.open_dataset

Contents

uxarray.open_dataset#

uxarray.open_dataset(grid_filename_or_obj, filename_or_obj=None, chunks=None, chunk_grid=True, use_dual=False, grid_kwargs=None, **kwargs)#

Wraps xarray.open_dataset() for loading in a dataset paired with a grid file.

Parameters:

  • grid_filename_or_obj (str | os.PathLike[Any] | dict | xr.Dataset) – Grid information for the UxDataset. Strings and Path objects are interpreted as a path to a grid file. Xarray Datasets assume that each member variable is in the UGRID conventions and will be used to create a ux.Grid. Similarly, a dictionary containing UGRID variables can be used to create a ux.Grid. A path to a directory containing grid files (e.g. a FESOM2 ASCII grid) is also accepted, but only when filename_or_obj is provided; directory input is not supported in the single-argument form below.

  • filename_or_obj (str | os.PathLike[Any] | xr.Dataset, optional) – String or Path object as a path to a netCDF file or an OpenDAP URL that stores the actual data set, or an already-open xarray.Dataset. It is the same filename_or_obj in xarray.open_dataset. If omitted, grid_filename_or_obj is also used as the data source, allowing a combined grid-and-data file or xarray.Dataset to be opened with a single argument. In this single-argument form the file is used to build the grid and also treated as data; all variables it contains, including grid variables, will be included as data.

  • chunks (int, dict, 'auto' or None, default: None) –

    If provided, used to load the grid into dask arrays.

    • chunks="auto" will use dask auto chunking taking into account the engine preferred chunks.

    • chunks=None skips using dask, which is generally faster for small arrays.

    • chunks=-1 loads the data with dask using a single chunk for all arrays.

    • chunks={} loads the data with dask using the engine’s preferred chunk size, generally identical to the format’s chunk size. If not available, a single chunk for all arrays.

  • chunk_grid (bool, default: True) – If valid chunks are passed in, determines whether to also apply the same chunks to the attached Grid

  • use_dual (bool, optional) – Specify whether to use the primal (use_dual=False) or dual (use_dual=True) mesh if the file type is MPAS

  • grid_kwargs (dict, optional) – Additional arguments passed on to ux.open_grid when opening up a Grid File.

  • **kwargs – Additional arguments passed on to xarray.open_dataset. Refer to the xarray docs for accepted keyword arguments.

Returns:

uxds – Dataset with linked uxgrid property of type Grid.

Return type:

uxarray.UxDataset

Notes

The grid need not be a complete or fully UGRID-compliant mesh, nor represent a spherical/Earth-science domain. A partial grid can be opened; operations requiring information absent from the file will raise when used, but unrelated functionality remains available.

Examples

Open a dataset with a grid file and data file

>>> import uxarray as ux
>>> ux_ds = ux.open_dataset("grid_file.nc", "data_file.nc")

Open a dataset stored in a single combined grid-and-data file

>>> ux_ds = ux.open_dataset("combined_file.nc")
Contents