xcdo 0.2.0

No project description provided

XCDO

XCDO is a Python-based command-line tool built around Xarray. It provides a collection of operators for working with datasets such as NetCDF, GRIB, and Zarr, using a familiar CDO like interface. With the help of Python’s type annotations, creating new operators becomes effortless, making it easy to extend the tool with simple functions and build reusable, organised analysis workflows.

Installation

$ pip install xcdo

!!! Known issues - Only works with Python 3.12 and 3.13 on macOS. - Not well tested on Windows.

### Installing in a virtual environment You may want to install `xcdo` to an isolated virtual environment to avoid conflicts with other packages.

micromamba/mamba/conda

# Choose any of: micromamba, mamba, or conda
$ micromamba create -n xcdo python=3.13
$ micromamba activate xcdo
(xcdo)$ pip install xcdo

uv

$ uv venv --python 3.13 .venv
$ source .venv/bin/activate
(.venv)$ pip install xcdo

Usage

Generally, XCDO works much like CDO. For example:

$ xcdo -selvar,var1 indata.nc outdata.nc
$ xcdo -timemean -zonmean in.nc out.nc

You can find a list of all available operators here. or run xcdo --list on the command line.

$ xcdo --list

                            Available Operators
┏━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Operator      ┃ Description                                   ┃
┡━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ cdo           │ Operator to run CDO commands                  │
│ showtimestamp │ Show time stamp                               │
│ mermean       │ Meridional mean                               │
│ mermin        │ Meridional minimum                            │
│ mermax        │ Meridional maximum                            │
│ merstd        │ Meridional standard deviation                 │
│ mersum        │ Meridional sum                                │

To get detailed information and the synopsis (or signature) about a specific operator, use:

$ xcdo --show <operator>

$ xcdo --show selvar
╭─ Synopsis ──────────────────────────────────────────────────╮
│                                                             │
│  xcdo -selvar,name input output                             │
│                                                             │
╰─────────────────────────────────────────────────────────────╯
╭─ Description ───────────────────────────────────────────────╮
│                                                             │
│  Select a data variable by name.                            │
│                                                             │
╰─────────────────────────────────────────────────────────────╯
                 Positional Arguments
┏━━━━━━━━━━━┳━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━┓
┃ Parameter ┃ Type ┃ Required ┃ Description          ┃
┡━━━━━━━━━━━╇━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━┩
│ name      │ TEXT │ Required │ Name of the variable │
└───────────┴──────┴──────────┴──────────────────────┘
╭─ Examples ──────────────────────────────────────────────────╮
│                                                             │
│  xcdo -selvar,tas infile.nc outfile.nc                      │
│  xcdo -selname,tas infile.nc outfile.nc                     │
│                                                             │
╰─────────────────────────────────────────────────────────────╯

User-defined operators

You can easily turn a regular Python function into your own XCDO operator. For example, here’s a small operator in a file named dump.py that simply prints a dataset to the terminal:

# dump.py
from xcdo import operator, DatasetIn

@operator()
def main(input: DatasetIn):
    print(input)

And this can be used as follows in xcdo:

$ xcdo -dump.py in.nc

You can see the signature and documentation of the custom operator by running:

$ xcdo --show dump.py

╭─ Synopsis ──────────────────────────────────────────────────╮
│                                                             │
│  xcdo -dump.py input                                        │
│                                                             │
╰─────────────────────────────────────────────────────────────╯

!!! Note Notice the .py extension on the custom operator? That’s because the operator name simply comes from the Python file’s name.

See Writing your own operators for more details.

Why XCDO?

• Simple Python functions. If you know Python, you can create new operators instantly. This opens the door for real community-driven development.
• Automatic help and documentation. XCDO automatically generates help and documentation for your operators, making it easy to share and reuse them.
• CLI and Library. As these operators are Python functions, it can be called from Python scripts as well.
• Custom operators. Drop a Python function into a file and call it like any other XCDO operator. This keeps your analysis workflows clean, modular, and easy to reuse.
• Zarr support. Since XCDO builds on Xarray, it naturally supports modern formats like Zarr, which CDO doesn’t handle yet.
• CDO integration. When you need the performance of CDO, you can call it directly with the “-cdo” operator and combine it with XCDO or custom operators in one chain.

With community support, XCDO can grow into a unified library of reusable and well-structured tools for climate and weather analysis.

Issues

Please report any issues here.

Contributing

Fork the repository and make your changes and submit a pull request.

Please contact me at [e-mail] for any questions or start a discussion on GitHub Discussions.

!!! warning "Under active development" XCDO is under active development. Although everything will work as expected, many features are not documented well yet.