xcdat.open_mfdataset#

xcdat.open_mfdataset(paths, data_var=None, add_bounds=True, decode_times=True, center_times=False, lon_orient=None, data_vars='minimal', preprocess=None, **kwargs)[source]#

Wraps xarray.open_mfdataset() with post-processing options.

Parameters
  • path (Union[str, pathlib.Path, List[str], List[pathlib.Path], List[List[str]], List[List[pathlib.Path]]]) – Either a string glob in the form "path/to/my/files/*.nc" or an explicit list of files to open. Paths can be given as strings or as pathlib Paths. If concatenation along more than one dimension is desired, then paths must be a nested list-of-lists (see combine_nested for details). (A string glob will be expanded to a 1-dimensional list.)

  • add_bounds (bool, optional) – If True, add bounds for supported axes (X, Y, T) if they are missing in the Dataset, by default True. Bounds are required for many xCDAT features.

  • data_var (Optional[str], optional) – The key of the data variable to keep in the Dataset, by default None.

  • decode_times (bool, optional) – If True, attempt to decode times encoded in the standard NetCDF datetime format into cftime.datetime objects. Otherwise, leave them encoded as numbers. This keyword may not be supported by all the backends, by default True.

  • center_times (bool, optional) – If True, attempt to center time coordinates using the midpoint between its upper and lower bounds. Otherwise, use the provided time coordinates, by default False.

  • lon_orient (Optional[Tuple[float, float]], optional) – The orientation to use for the Dataset’s longitude axis (if it exists), by default None.

    Supported options:

    • None: use the current orientation (if the longitude axis exists)

    • (-180, 180): represents [-180, 180) in math notation

    • (0, 360): represents [0, 360) in math notation

  • data_vars (Union[Literal[``”minimal”, ``"different", "all"], List[str]], optional) –

    These data variables will be concatenated together:
    • “minimal”: Only data variables in which the dimension already appears are included, the default value.

    • “different”: Data variables which are not equal (ignoring attributes) across all datasets are also concatenated (as well as all for which dimension already appears). Beware: this option may load the data payload of data variables into memory if they are not already loaded.

    • “all”: All data variables will be concatenated.

    • list of str: The listed data variables will be concatenated, in addition to the “minimal” data variables.

    The data_vars kwarg defaults to "minimal", which concatenates data variables in a manner where only data variables in which the dimension already appears are included. For example, the time dimension will not be concatenated to the dimensions of non-time data variables such as “lat_bnds” or “lon_bnds”. data_vars=”minimal” is required for some XCDAT functions, including spatial averaging where a reduction is performed using the lat/lon bounds.

  • preprocess (Optional[Callable], optional) – If provided, call this function on each dataset prior to concatenation. You can find the file-name from which each dataset was loaded in ds.encoding["source"].

  • kwargs (Dict[str, Any]) – Additional arguments passed on to xarray.open_mfdataset. Refer to the 2 xarray docs for accepted keyword arguments.

Returns

xr.Dataset – The Dataset.

Notes

xarray.open_mfdataset opens the file with read-only access. When you modify values of a Dataset, even one linked to files on disk, only the in-memory copy you are manipulating in xarray is modified: the original file on disk is never touched.

References

2

https://xarray.pydata.org/en/stable/generated/xarray.open_mfdataset.html