xdas.open#

xdas.open(paths, dim='first', tolerance=None, squeeze=None, engine=None, parallel=None, verbose=False, **kwargs)[source]#

Open one or several files as a data array or collection.

Automatically dispatches to the appropriate reader based on the shape of paths:

  • Single file (plain path string): tries to open as a data collection first, falls back to a data array if the file does not contain a data collection.

  • Multi-file (wildcarded string with *, ?, or […], or a list of paths): tries to open and combine as a multi-file data collection first, falls back to a multi-file data array if the files are not data collections.

  • Tree-like (string containing {field} placeholders): opens a directory tree as a nested data collection using open_mfdatatree().

Parameters:

  • paths (str or list of str) –

    The path(s) to open. Can be:

    • A plain file path (single file).

    • A shell-style wildcard string (*, ?, […]) matching multiple files.

    • A list of explicit file paths.

    • A tree descriptor string containing {field} (dict level) and [field] (list level) placeholders.

  • dim (str, optional) – The dimension along which multiple files are concatenated. Ignored when opening a single file. Default is "first".

  • tolerance (float or timedelta64, optional) – Maximum gap or overlap allowed between consecutive files to still be considered continuous. For time coordinates, numeric values are interpreted as seconds. Ignored when opening a single file. Default is zero tolerance.

  • squeeze (bool or None, optional) – Whether to return a DataArray instead of a DataCollection when the result contains only one data array. When None (default), the behaviour depends on the dispatch path: True for multi-file data arrays, False otherwise. Ignored when opening a single file.

  • engine (str or callable, optional) – The file format engine to use, or a custom read callable. When None (default), the xdas NetCDF format is assumed. Providing an engine skips the automatic DataCollection detection.

  • parallel (bool or int, optional) – Whether to use multiprocessing to fetch file metadata. If False or 1, runs in single-process mode. If an integer, use that many processes. If True, use as many processes as available cores. If None, use the global xdas configuration. Default to None.

  • verbose (bool, optional) – Whether to display a progress bar while reading metadata. Ignored when opening a single file. Default is False.

  • **kwargs – Additional keyword arguments forwarded to the underlying engine read function. Only used when engine is not None.

Returns:

The opened data. The exact type depends on the dispatch path and the squeeze setting.

Return type:

DataArray or DataCollection

Raises:

See also

open_dataarray

Open a single DataArray file.

open_datacollection

Open a single DataCollection file.

open_mfdataarray

Open and combine multiple DataArray files.

open_mfdatacollection

Open and combine multiple DataCollection files.

open_mfdatatree

Open a directory tree as a nested DataCollection.

Examples

Open a single file (auto-detects DataCollection vs DataArray):

>>> import xdas as xd
>>> da = xd.open("path/to/file.nc")

Open multiple files with a wildcard:

>>> da = xd.open("path/to/files/*.nc")

Open a list of explicit paths:

>>> da = xd.open(["file1.nc", "file2.nc"])

Open a directory tree:

>>> dc = xd.open("/data/{node}/[acq].nc", engine="asn")
On this page
Show Source