Metadata-Version: 2.4
Name: radarx
Version: 0.4.0
Summary: Xarray based radar toolkit
Author-email: Hamid Ali Syed <hamidsyed37@gmail.com>
Maintainer-email: Hamid Ali Syed <hamidsyed37@gmail.com>
License: MIT license
Project-URL: bugs, https://github.com/syedhamidali/radarx/issues
Project-URL: changelog, https://github.com/syedhamidali/radarx/blob/master/changelog.md
Project-URL: homepage, https://github.com/syedhamidali/radarx
Project-URL: documentation, https://radarx.reathedocs.io
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: AUTHORS.md
Requires-Dist: cmweather
Requires-Dist: lat_lon_parser
Requires-Dist: netCDF4
Requires-Dist: numpy
Requires-Dist: pyproj
Requires-Dist: cartopy
Requires-Dist: scipy
Requires-Dist: xarray>=2024.10.0
Requires-Dist: xmltodict
Requires-Dist: matplotlib
Requires-Dist: xradar
Requires-Dist: pooch
Requires-Dist: boto3
Provides-Extra: plot
Requires-Dist: hvplot; extra == "plot"
Requires-Dist: holoviews; extra == "plot"
Requires-Dist: bokeh; extra == "plot"
Requires-Dist: panel; extra == "plot"
Requires-Dist: datashader; extra == "plot"
Provides-Extra: uxarray
Requires-Dist: uxarray; extra == "uxarray"
Requires-Dist: spatialpandas; extra == "uxarray"
Requires-Dist: geopandas; extra == "uxarray"
Provides-Extra: dev
Requires-Dist: coverage; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: pooch; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Requires-Dist: black[jupyter]==24.2.0; extra == "dev"
Requires-Dist: blackdoc; extra == "dev"
Requires-Dist: codespell; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: pytest-mock; extra == "dev"
Requires-Dist: pytest-check; extra == "dev"
Requires-Dist: pytest-sugar; extra == "dev"
Requires-Dist: pytest-watcher; extra == "dev"
Requires-Dist: deepdiff; extra == "dev"
Requires-Dist: pip-tools; extra == "dev"
Requires-Dist: bumpver; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: wheel; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: setuptools>=61.0.0; extra == "dev"
Requires-Dist: sphinx; extra == "dev"
Requires-Dist: sphinx-gallery; extra == "dev"
Requires-Dist: sphinx-book-theme; extra == "dev"
Requires-Dist: myst-nb; extra == "dev"
Requires-Dist: jupytext; extra == "dev"
Requires-Dist: sphinx_mdinclude; extra == "dev"
Dynamic: license-file

# Radarx

![Radarx Logo](https://github.com/syedhamidali/radarx/raw/main/docs/_static/Radarx_Logo_micro.png)

[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.14699306.svg)](https://doi.org/10.5281/zenodo.14699306)
[![Python Versions](https://img.shields.io/badge/Python-3.10%20|%203.11%20|%203.12%20|%203.13-blue)](https://www.python.org/downloads/)
[![PyPI Version](https://img.shields.io/pypi/v/radarx.svg)](https://pypi.org/project/radarx/)
[![PyPI Downloads](https://img.shields.io/pypi/dm/radarx.svg?label=PyPI%20downloads)](https://pypi.org/project/radarx/)

[![Conda Version](https://img.shields.io/conda/vn/conda-forge/radarx.svg?logo=conda-forge&logoColor=white)](https://anaconda.org/conda-forge/radarx)
[![Conda Downloads](https://img.shields.io/conda/dn/conda-forge/radarx.svg?label=Conda%20downloads)](https://anaconda.org/conda-forge/radarx)

[![CI](https://github.com/syedhamidali/radarx/actions/workflows/ci.yml/badge.svg)](https://github.com/syedhamidali/radarx/actions/workflows/ci.yml)
[![Build distribution](https://github.com/syedhamidali/radarx/actions/workflows/upload_pypi.yml/badge.svg)](https://github.com/syedhamidali/radarx/actions/workflows/upload_pypi.yml)
[![Docs](https://readthedocs.org/projects/radarx/badge/?version=latest)](https://radarx.readthedocs.io/en/latest/)
[![License](https://img.shields.io/github/license/syedhamidali/radarx)](https://github.com/syedhamidali/radarx/blob/main/LICENSE)
![pre-commit enabled](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)

[![Black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![CodeFactor](https://www.codefactor.io/repository/github/syedhamidali/radarx/badge)](https://www.codefactor.io/repository/github/syedhamidali/radarx)
[![codecov](https://codecov.io/gh/syedhamidali/radarx/graph/badge.svg?token=59WL4GNQOP)](https://codecov.io/gh/syedhamidali/radarx)
[![Codacy Badge](https://app.codacy.com/project/badge/Grade/092c74b48c0443aaa35cd292fa5aef54)](https://app.codacy.com/gh/syedhamidali/radarx/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)



Radarx is a Python library for weather radar data processing and visualization. It builds on [xradar](https://xradar.readthedocs.io/en/latest/), which reads radar data from many formats into [xarray](https://docs.xarray.dev/) [DataTree](https://docs.xarray.dev/en/stable/user-guide/hierarchical-data.html) structures, and adds gridding, retrievals and plotting through the `.radarx` accessor.

[![Project Status: Beta](https://img.shields.io/badge/status-beta-blue.svg)](https://www.repostatus.org/#beta)

> [!WARNING]
> **This project is currently in high development mode.**
> Features may change frequently, and some parts of the library may be incomplete or subject to change. Please proceed with caution.


## Key Features

- **Fast, accurate gridding**: Cone gridding interpolates within each sweep and then between sweeps, using the radar's own geometry. A compiled C++ kernel grids tens of millions of cells in a fraction of a second, with no smoothing radius to tune (`dtree.radarx.to_grid()`). Barnes interpolation is also available.
- **CAPPI retrieval**: Constant-altitude PPIs with several methods (`dtree.radarx.create_cappi()`).
- **Interactive plotting**: [hvplot](https://hvplot.holoviz.org/)-based range-azimuth, PPI, RHI, CAPPI and Max-CAPPI views on DataArrays, Datasets and DataTrees (`.radarx.plot`), plus matplotlib plots.
- **Unstructured grids**: Convert a sweep into a [uxarray](https://uxarray.readthedocs.io/) dataset with one cell per gate, for true gate footprints, area-weighted statistics and remapping (`.radarx.to_uxarray()`).
- **Radar fundamentals**: Functions for radar equations, beam geometry, Doppler, attenuation and more (`radarx.fundamentals`).
- **Cloud data access**: List and download NEXRAD and MRMS data from AWS (`radarx.io`).

## Installation

You can install `radarx` using conda from the `conda-forge` channel (recommended):

```bash
conda install -c conda-forge radarx
```

You can also install `radarx` via pip from PyPI:

```bash
python -m pip install radarx
```

Optional features need extra packages:

```bash
python -m pip install "radarx[plot]"     # interactive hvplot plots
python -m pip install "radarx[uxarray]"  # unstructured grids with uxarray
```

With conda, install them directly, e.g. `conda install -c conda-forge hvplot datashader` or `conda install -c conda-forge uxarray spatialpandas geopandas`.

Alternatively, you can install it from source by cloning the repository
and running:

```bash
git clone https://github.com/syedhamidali/radarx.git
cd radarx
python -m pip install .
```

Building from source compiles the C++ gridding kernel if a C++ compiler is available; otherwise radarx falls back to an equivalent NumPy implementation.

## Usage

Read a radar volume with [xradar](https://xradar.readthedocs.io/en/latest/), then grid, retrieve and plot it with radarx:

```python
import xradar as xd
from open_radar_data import DATASETS

import radarx  # noqa: F401  registers the .radarx accessors

filename = DATASETS.fetch("KLBB20160601_150025_V06")
dtree = xd.io.open_nexradlevel2_datatree(filename)

# 3D grid with cone gridding (500 m spacing, 0.5 to 15 km height)
grid = dtree.radarx.to_grid(
    data_vars=["DBZH"],
    x_lim=(-150e3, 150e3), y_lim=(-150e3, 150e3), z_lim=(500, 15e3),
    x_step=500, y_step=500, z_step=500,
)

# interactive plots (requires radarx[plot])
dtree.radarx.plot.ppi("DBZH", sweeps=0)
grid.radarx.plot.max_cappi("DBZH")
```

See the [documentation](https://radarx.readthedocs.io/) for more examples, including CAPPIs, IMD data and unstructured grids.

> [!WARNING]
> The radarx IMD reader (`rx.io.read_sweep`, `rx.io.read_volume`, `rx.io.to_cfradial2`,
> `rx.io.to_cfradial2_volumes`) is **deprecated** and will be removed in a future release.
> IMD data is read natively by xradar (releases after 0.12.0): use
> `xr.open_dataset(file, engine="imd")` or `xd.io.open_imd_datatree(files)` instead.


## Documentation

For full documentation, see [radarx.readthedocs.io](https://radarx.readthedocs.io/).


## Contributing

Contributions are welcome! If you'd like to contribute, please follow
the steps below:

1.  Fork the repository.
2.  Create a new branch for your feature or bugfix.
3.  Write tests for your changes.
4.  Submit a pull request.

Please ensure that your code passes the pre-commit hooks and test suite
before submitting your PR.


## License

Radarx is licensed under the MIT License. See the
[LICENSE](https://github.com/syedhamidali/radarx/blob/main/LICENSE) file
for more details.


## Authors

-   Syed Hamid Ali

## Citation

If you use radarx, please cite this DOI. It covers all versions of radarx and always points to the latest release, so citations of every version are counted together. To record the exact version you used, add it to the citation (e.g. `version = {0.3.1}` in BibTeX).

> Syed, H. A. Radarx: An Xarray-based Python package for radar data processing. Zenodo. https://doi.org/10.5281/zenodo.14699306

```bibtex
@software{syed_radarx,
  author    = {Syed, Hamid Ali},
  title     = {Radarx: An Xarray-based Python package for radar data processing},
  publisher = {Zenodo},
  doi       = {10.5281/zenodo.14699306},
  url       = {https://doi.org/10.5281/zenodo.14699306},
}
```
