Skip to main content

xarray Tutorial: Core Concepts

xarray is a powerful library designed for handling multi-dimensional arrays with labeled axes (dimensions). It is particularly useful for scientific computing tasks, especially when working with data that has more than two dimensions (like time, latitude, longitude, pressure levels, etc.).

In this tutorial, we'll cover the core concepts and methods of xarray, including how to load, index, slice, filter, and combine datasets.

📥 Download the Sample Data​

These datasets are used throughout the tutorial for hands-on practice with multi-dimensional data.

FileDescriptionLink
grid_data.csv3D gridded weather data (time × latitude × longitude) — 15,000 rowsDownload

💡 Tip: Save the file to your working directory. Load it with pd.read_csv() and convert to an xarray Dataset using xr.Dataset.from_dataframe() after setting the appropriate index, or use xr.open_dataset() for NetCDF files.

1. Introduction to xarray​

At the heart of xarray are two main objects:

  • Dataset: A container for multiple variables, along with their dimensions and coordinates.
  • DataArray: A multi-dimensional array representing a single variable, with labeled axes (e.g., time, latitude, longitude).

Key Features of xarray:​

  • Labeled dimensions: Labels like time, latitude, and longitude for better indexing and manipulation.
  • Support for multi-dimensional arrays: Great for complex scientific data, such as climate or weather data.
  • Integration with Pandas: Seamless handling of time-based data with datetime support.

2. Installing xarray​

You can install xarray via pip:

pip install xarray

3. Importing xarray​

import xarray as xr

This imports xarray as xr, which is the standard convention.

4. Loading Data into xarray​

Loading from a CSV into xarray​

The sample dataset grid_data.csv contains weather data with three dimensions: time, latitude, and longitude. Since xarray works best with labeled multi-dimensional data, we first load the CSV with pandas and then convert it to an xarray Dataset.

import pandas as pd
import xarray as xr

# Load the CSV with pandas
df = pd.read_csv('grid_data.csv')

# Convert to an xarray Dataset by setting the index
# and using from_dataframe()
ds = df.set_index(['time', 'latitude', 'longitude']).to_xarray()
print(ds)

This creates an xarray Dataset with:

  • Dimensions: time (30 steps), latitude (20 values), longitude (25 values)
  • Variables: temperature and precipitation
  • Coordinates: labeled axes for each dimension

open_dataset(): Load NetCDF data​

The open_dataset() function is used to read multi-dimensional data (such as NetCDF, GRIB, HDF5) into an xarray Dataset.

dataset = xr.open_dataset('data.nc')

This loads the dataset from a NetCDF file (data.nc) into an xarray Dataset.

Core concepts:​

  • The Dataset contains one or more DataArray objects (representing variables like temperature, pressure, etc.).
  • The Dataset also stores the coordinates for each dimension (e.g., time, latitude, longitude).

5. Accessing Variables in a Dataset​

Once a dataset is loaded, you can access the variables (DataArrays) by their names. Each variable can be thought of as a DataArray.

# Using the grid_data we loaded above
temperature = ds['temperature']
precipitation = ds['precipitation']

print(temperature)
# <xarray.DataArray 'temperature' (time: 30, latitude: 20, longitude: 25)>

Here, temperature and precipitation are variables in the dataset, represented as DataArray objects with their labeled dimensions.

6. Indexing and Slicing Data​

.isel(): Index data by position​

The isel() method allows you to index data by position, similar to how you index arrays in NumPy.

# Select the first time step and first latitude from our grid data
temperature_slice = ds['temperature'].isel(time=0, latitude=0)
print(temperature_slice)
# <xarray.DataArray 'temperature' (longitude: 25)>

Here, isel() selects the first time step (time=0) and the first latitude index (latitude=0) from the temperature variable, returning a 1D DataArray along longitude.

.sel(): Slice data by labeled coordinates​

Unlike isel(), which uses index positions, sel() allows you to slice data by the actual coordinates (labels) of the data, like a specific timestamp or location.

# Select temperature at a specific time and location from our grid data
temperature_slice = ds['temperature'].sel(time='2024-01-01', latitude=-10.0, longitude=100.0)
print(temperature_slice)

In this example, sel() selects the temperature data for January 1st, 2024, at latitude -10.0 and longitude 100.0.

7. Applying Conditional Filters​

where(): Apply conditional filters to data​

The where() method is used to filter data based on conditions. It returns the data where the condition is True, and the remaining values are replaced with NaN.

# Filter our grid data to only show temperatures above 25°C
temperature_filtered = ds['temperature'].where(ds['temperature'] > 25)

This will return only those temperature values that are greater than 25. All other values will be replaced with NaN.

8. Combining Datasets​

concat(): Combine multiple datasets along a dimension​

Sometimes, data is split across multiple files or time periods. You can combine these datasets using the concat() method.

# Split our grid data into two time periods and recombine
ds_first_half = ds.isel(time=slice(0, 15))
ds_second_half = ds.isel(time=slice(15, 30))
combined_dataset = xr.concat([ds_first_half, ds_second_half], dim='time')

This concatenates two subsets of the dataset along the time dimension, effectively stacking them back together.

9. Handling Missing Data​

fillna(): Filling missing data​

If your dataset contains missing values (e.g., NaN), you can use fillna() to replace those values with a specific value or the result of an operation.

dataset_filled = ds.fillna(0)

This replaces all NaN values in the dataset with 0.

10. Plotting Data with xarray​

xarray integrates seamlessly with matplotlib, enabling you to quickly plot your data.

# Plot temperature at the first time step
ds['temperature'].isel(time=0).plot()

This will generate a 2D plot of the temperature variable at the first time step, using latitude and longitude as axes.

Summary​

xarray is a powerful library for working with multi-dimensional arrays, particularly for scientific and geospatial data. Here's a recap of the key functions we used:

  • set_index().to_xarray(): Convert a pandas DataFrame to an xarray Dataset.
  • open_dataset(): Load NetCDF data into an xarray Dataset.
  • .isel(): Index data along dimensions by position.
  • .sel(): Slice data by labeled coordinates.
  • where(): Apply conditional filters to data.
  • concat(): Combine multiple datasets along a dimension.