xradar

0.11.1 · active · verified Fri Apr 17

xradar (version 0.11.1) provides tools to load and process weather radar data into the xarray data model, enabling efficient, labeled multi-dimensional array computing. It focuses on reading various radar formats (e.g., ODIM H5, IRIS, GPM) and converting them into structured xarray Datasets or Groups, often leveraging internal dependencies like wradlib and pyodim. The library is actively maintained with several releases per year, evolving its API and adding support for new data formats and processing capabilities.

Common errors

```
FileNotFoundError: [Errno 2] No such file or directory: 'your_radar_file.h5'
```
cause The specified radar file path is incorrect, or the file does not exist at that location.

fix Double-check the file path. Ensure the file exists and is accessible from where your Python script is run. Use `os.path.exists(file_path)` to verify before attempting to read.
```
KeyError: 'sweep_0' (or similar for other sweep/variable names)
```
cause The radar file's internal structure does not contain the expected sweep or variable name. Radar formats vary, and specific files might use different naming conventions or omit certain data products.

fix Inspect the loaded `xarray.Group` (or `xarray.Dataset`) using `ds_group.keys()` and `ds_group['sweep_name'].data_vars.keys()` to discover the actual names of sweeps and variables available in your specific file.
```
OSError: Can't open object (object 'your_radar_file.h5' doesn't exist)
```
cause Similar to `FileNotFoundError`, but often indicates an issue with the underlying HDF5 or NetCDF library failing to locate or open the file, possibly due to path, permissions, or a corrupted file.

fix Verify the file path and permissions. Ensure the file is not corrupted and is a valid ODIM H5/NetCDF file. Try opening it with a different HDF5/NetCDF viewer if possible to confirm integrity. Also, check for system-level HDF5/NetCDF library installations.
```
TypeError: Cannot interpret 'xarray.Group' as a Dataset
```
cause You are attempting to apply an `xarray.Dataset` method directly to an `xarray.Group` object, or expecting a single `Dataset` when `xradar` returned a Group containing multiple sweeps.

fix Remember that `xradar` often returns an `xarray.Group`. Access individual sweeps using `ds_group['sweep_name']` (e.g., `ds_group['sweep_0']`) before applying Dataset-specific operations like `ds.where()` or `ds.sel()`.

Warnings

breaking The internal implementation of IO functions might change, especially for complex formats, potentially affecting performance or requiring specific versions of underlying parsers (like `pyodim`). While the high-level `read_*` API aims for stability, argument changes are possible in 0.x.x versions.
Fix: Always consult the latest documentation for `xradar.io` functions. Pin your xradar version for production environments to avoid unexpected API changes in minor releases, or carefully review release notes before upgrading.
gotcha xradar often returns an `xarray.Group` object where each radar sweep is a separate `xarray.Dataset`. Users accustomed to a single `xarray.Dataset` may find this hierarchical structure unexpected, requiring careful indexing (e.g., `ds_group['sweep_0']`) to access data.
Fix: Familiarize yourself with the `xarray.Group` API. Use `ds_group.keys()` to see available sweeps and `ds_group['sweep_idx']` to select a specific sweep. The official xradar documentation provides examples of navigating this structure.
gotcha Radar data comes with complex coordinate systems (e.g., polar coordinates, varying projections). xradar ingests these, but direct plotting on geographical maps often requires explicit projection handling and transformations, often using `wradlib` or `cartopy`, which are not always automatic.
Fix: Understand the coordinate reference system (CRS) embedded in your radar data (if any). Use `wradlib.georef` or `pyproj` for transformations if mapping to common geographic projections. Refer to `xradar`'s plotting examples or integrate with `wradlib`'s mapping capabilities.
gotcha Some radar formats might require specific C libraries (e.g., HDF5, netCDF-C) to be installed on your system in addition to the Python packages (`h5py`, `netcdf4`). Missing these can lead to errors during file reading.
Fix: Ensure you have the necessary system-level dependencies for HDF5 and NetCDF. On Linux, this usually involves `sudo apt-get install libhdf5-dev libnetcdf-dev`. On other OS, consult the documentation for `h5py` and `netcdf4`.

Install

pip install xradar Install core library
pip install xradar[all] Install with all optional dependencies (e.g., for plotting)

Imports

read_odim_h5
wrong:
```
from xradar import read_odim_h5
```
correct:
```
import xradar as xrdr
ds = xrdr.io.read_odim_h5(...)
```
Most IO functions are nested under `xradar.io`. It's best practice to import `xradar` itself and access submodules.
xradar.io
wrong:
```
import xradar.io as xio
ds = xio.read_iris(...)
```
correct:
```
import xradar as xrdr
ds = xrdr.io.read_iris(...)
```
While `import xradar.io as xio` works, `import xradar as xrdr` is the most common and recommended alias, accessing `xrdr.io`.

Quickstart

This quickstart demonstrates how to load a common ODIM H5 radar file using `xradar.io.read_odim_h5`. It then shows how to access the resulting xarray Group, navigate to individual sweeps (which are xarray Datasets), and inspect a data variable like reflectivity (DBZH). A helper comment is included to assist in downloading a suitable example file if you don't have one.

import xradar as xrdr
import xarray as xr
import os

# --- Instructions to get an example ODIM H5 file ---
# Option 1: Download it (requires 'wget' or equivalent)
# If you don't have 'wget' (e.g., on Windows), manually download from:
# https://github.com/xarray-contrib/xradar/raw/main/doc/source/notebooks/data/example.h5
# Save it as 'example.h5' in the same directory as this script.
# os.system("wget -nc https://github.com/xarray-contrib/xradar/raw/main/doc/source/notebooks/data/example.h5 -O example.h5")

file_path = "example.h5"

if os.path.exists(file_path):
    try:
        # Read the ODIM H5 file into an xarray Group of Datasets
        # Each sweep is typically a separate Dataset within the Group
        ds_group = xrdr.io.read_odim_h5(file_path)

        print(f"Successfully loaded data from: {file_path}")
        print("Dataset Group structure:")
        print(ds_group)

        # Access a specific sweep (e.g., 'sweep_0')
        if 'sweep_0' in ds_group.keys():
            sweep_0 = ds_group['sweep_0']
            print("\nFirst sweep (sweep_0) details:")
            print(sweep_0)
            
            # Access a specific data variable (e.g., 'DBZH' - Reflectivity)
            if 'DBZH' in sweep_0.data_vars:
                print("\nFirst sweep's reflectivity (DBZH) data snippet:")
                print(sweep_0.DBZH.isel(range=slice(0, 5), azimuth=slice(0, 5)))
            else:
                print("\n'DBZH' variable not found in sweep_0.")
        else:
            print("\n'sweep_0' not found in the dataset group.")

    except Exception as e:
        print(f"Error processing file '{file_path}': {e}")
        print("Please ensure the file is a valid ODIM H5 radar file and dependencies are installed.")
else:
    print(f"Error: Example file '{file_path}' not found.")
    print("Please download it as per the instructions above, or provide your own ODIM H5 file.")

view raw JSON →