DOCSEARCHbyAlgolia
Submit Docs

xarray Documentation

repository·main·Indexed 26 days ago

https://github.com/pydata/xarray

A Python library for N-dimensional labeled arrays and datasets. xarray provides intuitive tools for working with multi-dimensional scientific data by introducing dimensions, coordinates, and attributes on top of NumPy-like arrays. Key features include dimension-based operations, label-based selection, dimension-aware broadcasting, and integration with dask for parallel computing. It is particularly well-suited for netCDF files.

Tokens
105.4K
Snippets
158
Records
873
Agent score
87%

What's inside xarray

  1. Overview of the named-array package

    main

    The named-array package is a standalone, lightweight implementation of the xarray.Variable data structure. It is designed to provide N-dimensional arrays with named axes (dimensions) and arbitrary metadata (attributes) without the heavy dependency on Pandas required by the full Xarray library.

    Key features include:

    • Named Axes: Each dimension can be assigned a descriptive name for intuitive broadcasting and indexing.
    • Metadata Support: Supports attaching arbitrary metadata as a dictionary (attrs).
    • Interoperability: Designed to wrap various 'duck-array' objects such as NumPy, Dask, Sparse, Pint, CuPy, and PyTorch by following scientific Python community standards and the Python array API standard.

  2. Overview of xarray

    main
    xarray is an open source Python package for working with labeled multi-dimensional arrays. It introduces dimensions, coordinates, and attributes on top of NumPy-like arrays, providing a more intuitive and less error-prone experience than raw arrays. It is particularly well-suited for netCDF files and integrates with dask for parallel computing.

  3. Introduction to Xarray plotting

    main

    Xarray's plotting capabilities are centered around DataArray objects. To plot Dataset objects, access the relevant DataArray (e.g., dset['var1']).

    Xarray plotting is a thin wrapper around matplotlib. To use it, you must have matplotlib installed. For time coordinates containing cftime.datetime objects, you must also install nc-time-axis (v1.3.0 or later).

    For more advanced visualization, consider these integrations:

    • Seaborn: High-level statistical graphics.
    • HoloViews and GeoViews: Composable, declarative data structures with native xarray support.
    • hvplot: Adds an hvplot accessor to DataArrays for dynamic plots.
    • Cartopy: Cartographic tools.

  4. Overview of Xarray indexing methods

    main

    Xarray provides four primary ways to index and select data from DataArray and Dataset objects, combining NumPy-style positional indexing with pandas-style label-based indexing.

    Dimension lookupIndex lookupDataArray syntaxDataset syntax
    PositionalBy integerda[:, 0]not available
    PositionalBy labelda.loc[:, 'IA']not available
    By nameBy integerda.isel(space=0) or da[dict(space=0)]ds.isel(space=0) or ds[dict(space=0)]
    By nameBy labelda.sel(space='IA') or da.loc[dict(space='IA')]ds.sel(space='IA') or ds.loc[dict(space='IA')]

  5. Explore the Xarray ecosystem for Geosciences

    main

    Xarray is widely used in geosciences through various specialized libraries. Key tools include:

    • Data Access & Manipulation: argopy (Argo data), grib2io (GRIB2 files with Dask support), SatPy (meteorological remote sensing), SARXarray (SAR data), and xmitgcm (MITgcm binary files).
    • Geospatial & Raster Analysis: geocube (GeoPandas to xarray), rioxarray (geospatial extension via rasterio), regionmask (spatial region masking), salem (geolocalised subsetting/masking), and xarray-spatial (Numba-accelerated raster processing).
    • Climate & Meteorology: cf_xarray (interprets CF metadata via .cf accessor), xclim (climate science indices), MetPy (weather data calculations), and xgcm (finite volume grid cell support).
    • Regridding & Interpolation: xESMF (universal regridding), pyinterp (geo-referenced interpolation), and xarray-regrid (rectilinear data regridding).
    • Large Scale Analysis: Pangeo (big data geoscience in the cloud) and Open Data Cube (continental scale Earth Observation).

  6. Work with DataTree structures

    main

    A DataTree is a hierarchical, tree-like collection of Dataset objects.

    • Nodes: Each node is a DataTree instance that can store a Dataset (via .dataset).
    • Hierarchy: Nodes can have children (stored in a dictionary-like manner) and a single parent. The top-level node is the root.
    • Subtree/Group: A section of a tree consisting of a node and all its descendants. This is analogous to NetCDF or Zarr groups.

  7. Extend xarray with custom indexing and grids

    main
    Xarray is moving towards a more flexible indexing model. While current indexing often relies on pandas.Index stored in xarray.IndexVariable objects, the project aims to elevate indexes to an explicit part of the data model as attributes on Dataset and DataArray. This allows indexes to refer to multiple coordinates and enables third-party libraries to implement custom indexing routines, such as geospatial look-ups.

  8. Understand Xarray's API stability and public API surface

    main

    Xarray prioritizes backwards compatibility for its public API. Breaking changes are rare and are typically preceded by FutureWarnings to allow users to migrate.

    Public vs. Private API:

    • Public API: Only functions and methods explicitly documented in the official Xarray API documentation are considered part of the public API.
    • Private API: Most contents within xarray.core that are not exposed in the top-level xarray namespace are considered private implementation details and may change without notice.
    • Accessors: Objects used for fluent interfaces (like .plot(), .groupby(), or .str) are documented for convenience, but only the methods called on DataArray or Dataset objects are considered part of the public API. The underlying internal classes (e.g., xarray.core.groupby.DataArrayGroupBy) are private.

  9. Understand xarray.DataArray

    main

    An xarray.DataArray is a labeled, multi-dimensional array. It extends NumPy-like arrays by adding metadata that enables dimension-aware operations and label-based indexing.

    Key properties:

    • values: The underlying numpy.ndarray or numpy-like array holding the data.
    • dims: Dimension names for each axis (e.g., ('x', 'y', 'z')).
    • coords: A dict-like container of arrays (coordinates) that label each point (e.g., datetime objects, strings, or numbers).
    • attrs: A dict used to hold arbitrary metadata (attributes).
    • name: A string identifying the instance.

    Dimensions allow you to use names instead of integer axis arguments, and coordinates enable fast label-based indexing and alignment similar to pandas.

  10. Understand the relationship between xarray and pandas

    main

    xarray is designed for multi-dimensional data (ndim > 2), whereas pandas is optimized for tabular, low-dimensional (1D or 2D) data.

    Key differences:

    • Dimensions: xarray uses named dimensions (e.g., 'time', 'latitude', 'longitude'), making indexing and broadcasting more intuitive. In pandas, dimensions are typically identified by axis numbers.
    • Interoperability: xarray provides built-in methods to convert back and forth between pandas tabular structures and xarray multi-dimensional structures.
    • Use Case: Use pandas for unstructured or one-dimensional data where performance for operations like groupby is critical. Use xarray when the order of dimensions shouldn't matter or when working with complex N-D arrays (e.g., movie frames with dimensions: time, row, column, color).

  11. Integrate alternative N-D array implementations

    main
    Xarray is designed to work with various N-D array implementations by leveraging NumPy's array API and duck-typing. It currently supports wrapping NumPy, Dask, and pandas arrays. Future improvements aim to facilitate seamless wrapping of arrays holding physical units, lazily computed arrays, and other objects like sparse arrays, xnd, xtensor, CuPy, or PyTorch.

  12. Understand the xarray.Dataset structure

    main

    An xarray.Dataset is a multi-dimensional, dict-like container of labeled xarray.DataArray objects with aligned dimensions. It is modeled after the netCDF file format.

    A Dataset consists of four key properties:

    • dims: A dictionary mapping dimension names to their fixed lengths.
    • data_vars: A dict-like container of DataArray objects representing measured/dependent variables.
    • coords: A dict-like container of DataArray objects used to label points (e.g., coordinates, timestamps, or strings).
    • attrs: A dict for storing arbitrary metadata.

    While dictionary-like access can retrieve both data and coordinate variables, the distinction is important for indexing and computation: coordinates represent independent quantities, while data variables represent dependent quantities.