xroms.xroms#

Functions to help read in ROMS output.

xroms.xroms.open_mfnetcdf(files, chunks={'ocean_time': 1}, xrargs={}, Vtransform=None, add_verts=False, proj=None)[source]#

Return Dataset based on a list of netCDF files.

This function is deprecated; use xroms.open_netcdf or xroms.open_zarr directly instead.

Parameters:

  • files (list of strings) – Where to find the model output. files can be a list of netCDF file names.

  • chunks (dict, optional) – The specified chunks for the Dataset. Use chunks to read in output using dask.

  • xrargs (dict, optional) –

    Keyword arguments to be passed to xarray.open_mfdataset. Anything input by the user overwrites the default selections saved in this function. Defaults are:

    {‘compat’: ‘override’, ‘combine’: ‘by_coords’,

    ’data_vars’: ‘minimal’, ‘coords’: ‘minimal’, ‘parallel’: True}

    Many other options are available; see xarray docs.

  • Vtransform (int, optional) – Vertical transform for ROMS model. Should be either 1 or 2 and only needs to be input if not available in ds.

  • add_verts (boolean, optional) – Add ‘verts’ horizontal grid to ds if True. This requires a cartopy projection to be input too. This is passed to roms_dataset.

  • proj (cartopy crs projection, optional) – Should match geographic area of model domain. Required if add_verts=True, otherwise not used. This is passed to roms_dataset. Example: >>> proj = cartopy.crs.LambertConformal(central_longitude=-98, central_latitude=30)

Returns:

ds – Model output, read into an xarray Dataset. If ‘chunks’ keyword argument is input, dask is used when reading in model output and output is read in lazily instead of eagerly.

Return type:

Dataset

Examples

>>> ds = xroms.open_mfnetcdf(files)
xroms.xroms.open_netcdf(file, chunks={'ocean_time': 1}, xrargs={}, Vtransform=None, add_verts=False, proj=None)[source]#

Return Dataset based on a single thredds or physical location.

This function is deprecated; use xroms.open_netcdf or xroms.open_zarr directly instead.

Parameters:

  • file (str) – Where to find the model output. file could be: * a string of a single netCDF file name, or * a string of a thredds server address containing model output.

  • chunks (dict, optional) – The specified chunks for the Dataset. Use chunks to read in output using dask.

  • xrargs (dict, optional) – Keyword arguments to be passed to xarray.open_dataset. See xarray docs for options.

  • Vtransform (int, optional) – Vertical transform for ROMS model. Should be either 1 or 2 and only needs to be input if not available in ds.

  • add_verts (boolean, optional) – Add ‘verts’ horizontal grid to ds if True. This requires a cartopy projection to be input too. This is passed to roms_dataset.

  • proj (cartopy crs projection, optional) – Should match geographic area of model domain. Required if add_verts=True, otherwise not used. This is passed to roms_dataset. Example: >>> proj = cartopy.crs.LambertConformal(central_longitude=-98, central_latitude=30)

Returns:

ds – Model output, read into an xarray Dataset. If ‘chunks’ keyword argument is input, dask is used when reading in model output and output is read in lazily instead of eagerly.

Return type:

Dataset

Examples

>>> ds = xroms.open_netcdf(file)
xroms.xroms.open_zarr(files, chunks={'ocean_time': 1}, xrargs={}, xrconcatargs={}, Vtransform=None, add_verts=False, proj=None)[source]#

Return a Dataset based on a list of zarr files

Parameters:

  • files (list of strings) – A list of zarr file directories.

  • chunks (dict, optional) – The specified chunks for the Dataset. Use chunks to read in output using dask.

  • xrargs (dict, optional) –

    Keyword arguments to be passed to xarray.open_zarr. Anything input by the user overwrites the default selections saved in this function. Defaults are:

    {‘consolidated’: True, ‘drop_variables’: ‘dstart’}

    Many other options are available; see xarray docs.

  • xrconcatargs (dict, optional) –

    Keyword arguments to be passed to xarray.concat for combining zarr files together. Anything input by the user overwrites the default selections saved in this function. Defaults are:

    {‘dim’: ‘ocean_time’, ‘data_vars’: ‘minimal’, ‘coords’: ‘minimal’}

    Many other options are available; see xarray docs.

  • Vtransform (int, optional) – Vertical transform for ROMS model. Should be either 1 or 2 and only needs to be input if not available in ds.

  • add_verts (boolean, optional) – Add ‘verts’ horizontal grid to ds if True. This requires a cartopy projection to be input too. This is passed to roms_dataset.

  • proj (cartopy crs projection, optional) – Should match geographic area of model domain. Required if add_verts=True, otherwise not used. This is passed to roms_dataset. Example: >>> proj = cartopy.crs.LambertConformal(central_longitude=-98, central_latitude=30)

Returns:

ds – Model output, read into an xarray Dataset. If ‘chunks’ keyword argument is input, dask is used when reading in model output and output is read in lazily instead of eagerly.

Return type:

Dataset

Examples

>>> ds = xroms.open_zarr(files)
xroms.xroms.roms_dataset(ds, Vtransform=None, add_verts=False, proj=None, include_Z0=False, include_3D_metrics=True, include_cell_volume=False, include_cell_area=False)[source]#

Modify Dataset to be aware of ROMS coordinates, with matching xgcm grid object.

Parameters:

  • ds (Dataset) – xarray Dataset with model output

  • Vtransform (int, optional) – Vertical transform for ROMS model. Should be either 1 or 2 and only needs to be input if not available in ds.

  • add_verts (boolean, optional) – Add ‘verts’ horizontal grid to ds if True. This requires a cartopy projection to be input too.

  • proj (cartopy crs projection, optional) – Should match geographic area of model domain. Required if add_verts=True, otherwise not used. Example: >>> proj = cartopy.crs.LambertConformal(central_longitude=-98, central_latitude=30)

  • include_Z0 (bool) – If True, calculate depths for quiescient state, which can be used for faster approximations for depth calculations since they are 3D instead of 4D.

  • include_3D_metrics (bool) – If True, calculate necessary grid metrics for 3D calculations with xgcm. Note that you need the 3D metrics for horizontal derivatives for ROMS.

  • include_cell_volume (bool) – If True, calculate necessary grid metrics for cell volumes. I think this is for cf-xarray.

  • include_cell_area (bool) – If True, calculate necessary grid metrics for cell areas (besides dA). I think this is for cf-xarray.

Returns:

  • ds (Dataset) – Same dataset as input, but with dimensions renamed to be consistent with xgcm and with vertical coordinates and metrics added.

  • xgrid (xgcm grid object) – Includes ROMS metrics so can be used for xgcm grid operations, which mostly have been wrapped into xroms.

Notes

Note that this could be very slow if dask is not on.

This does not need to be run by the user if xroms functions open_netcdf or open_zarr are used for reading in model output, since run in those functions.

This also uses cf-xarray to manage dimensions of variables.

Examples

>>> ds, xgrid = xroms.roms_dataset(ds)

Modules