Metadata-Version: 2.1
Name: xcdo
Version: 0.0.0
Author-Email: Prajeesh Ag <prajeeshag@gmail.com>
License: MIT License
         
         Copyright (c) 2024 Prajeesh Ag
         
         Permission is hereby granted, free of charge, to any person obtaining a copy
         of this software and associated documentation files (the "Software"), to deal
         in the Software without restriction, including without limitation the rights
         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
         copies of the Software, and to permit persons to whom the Software is
         furnished to do so, subject to the following conditions:
         
         The above copyright notice and this permission notice shall be included in all
         copies or substantial portions of the Software.
         
         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
         SOFTWARE.
         
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Project-URL: homepage, https://prajeeshag.github.io/xcdo
Project-URL: repository, https://github.com/prajeeshag/xcdo
Project-URL: documentation, https://prajeeshag.github.io/xcdo
Requires-Python: <3.14,>=3.12
Requires-Dist: cartopy<2.0.0,>=0.24.1
Requires-Dist: cf-xarray<1.0.0,>=0.10.0
Requires-Dist: cfgrib<1.0.0,>=0.9.14.1
Requires-Dist: cftime<2.0.0,>=1.6.4.post1
Requires-Dist: clios<0.5,>=0.4
Requires-Dist: dask[array,distributed]<2025.0.0,>=2024.11.2
Requires-Dist: eccodes<3.0.0,>=2.39.0
Requires-Dist: nc-time-axis<2.0.0,>=1.4.1
Requires-Dist: netcdf4<2.0.0,>=1.7.2
Requires-Dist: numpy<3.0.0,>=2.1.3
Requires-Dist: xarray<2025.0.0,>=2024.11
Requires-Dist: zarr<3.0.0,>=2.18.3
Description-Content-Type: text/markdown


# XCDO

![Test](https://github.com/prajeeshag/xcdo/actions/workflows/test.yml/badge.svg)
![Doc](https://github.com/prajeeshag/xcdo/actions/workflows/build-docs.yml/badge.svg)
![PyPI - Version](https://img.shields.io/pypi/v/xcdo)
[![codecov](https://codecov.io/gh/prajeeshag/xcdo/graph/badge.svg?token=UNNUW30IQL)](https://codecov.io/gh/prajeeshag/xcdo)
[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit)

**XCDO** is a Python-based command-line tool built around [Xarray](https://docs.xarray.dev/en/stable/). It provides a collection of operators for working with datasets such as NetCDF, GRIB, and Zarr, using a familiar [CDO](https://code.mpimet.mpg.de/projects/cdo/)-style 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.

## Why XCDO?
Why build another CDO-style tool—even if it won’t be as fast as the original CDO? Because XCDO offers a different kind of power:

- Write operators as simple Python functions. If you know Python, you can create new operators instantly. This opens the door for real community-driven development.
- As these operators are Python functions, it can be called from Python scripts as well.
- Use your own code as operators. Drop a Python function into a file and call it like any other XCDO operator. This keeps workflows clean, modular, and easy to reuse.
- Full Zarr support. Since XCDO builds on Xarray, it naturally supports modern formats like Zarr, which CDO doesn’t handle yet.
- Smooth 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.


## Installation
<!--termynal-->
```
$ pip install xcdo
```

You may want to install `xcdo` to an isolated virtual environment to avoid conflicts with other packages. Use any virtual environment manager such as [micromamba](https://mamba.readthedocs.io/en/latest/user_guide/micromamba.html) or [conda](https://docs.conda.io/en/latest/) or [virtualenv](https://virtualenv.pypa.io/en/latest/) or [venv](https://docs.python.org/3/library/venv.html)

Optionaly, you may also install `cdo` for using the `-cdo`.

## Usage
To get a list of all available operators and their short descriptions, use:

```bash
$ xcdo --list
```

<!--termynal--->
```
$ 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>
```
<!--termynal--->
```
$ 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                     │
│                                                             │
╰─────────────────────────────────────────────────────────────╯
```


As it mimics the CDO interface, using XCDO is generally the same as using CDO. for e.g:
<!--termynal--->
```
$ xcdo -selvar,var1 indata.nc outdata.nc
$ xcdo -timemean -zonmean in.nc out.nc
```

## Custom Operators
A simple python function can be used as a custom operator of XCDO.
For example: a simple operator to print the dataset to terminal can be defined as follows in file a `dump.py`:

```python
# dump.py
from xcdo import operator, DatasetIn

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

And this can be used as follows in `xcdo`:

```bash
$ xcdo -dump.py in.nc
```

Notice the ".py" extension for the custom operator? Yes, basically the operator name is just the path of the python file.

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

```bash
$ xcdo --show dump.py

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

```

<!--For a more complete example including more features, see the Tutorial - User Guide.-->
