Py-ART: Python ARM Radar Toolkit

Py-ART is a collection of weather radar algorithms and utilities designed to examine, process, and analyze radar data.

Key Features:

• Data Ingestion: Reads common weather radar formats including Sigmet/IRIS, MDV, CF/Radial, UF, and NEXRAD Level II archive files.
• Data Export: Writes radar data to NetCDF files conforming to the CF/Radial convention.
• Visualization: Produces common radar plots such as Plan Position Indicator (PPI) and Range Height Indicator (RHI).
• Corrections: Performs antenna coordinate corrections including reflectivity attenuation correction, velocity dealiasing, and specific (Kdp) and differential (PhiDP) phase corrections.
• Gridding: Includes sophisticated mapping routines to create uniform Cartesian grids of radar fields from one or more radars. Grids can be plotted or saved to NetCDF.

The core of Py-ART is the Radar object, which serves as a unified data model for weather radar data. This object abstracts the differences between various radar data formats (such as NEXRAD, ODIM, and UF) into a standardized interface.

Key characteristics of the Radar object include:

• Standardization: Provides a consistent way to access radar fields, coordinates, and metadata regardless of the original file format.
• Interoperability: Designed to work seamlessly with the scientific Python ecosystem, including NumPy, SciPy, Matplotlib, and xarray.
• Extensibility: Users can add custom fields, attributes, or processing steps directly to the Radar object.

Py-ART follows semantic versioning.

• Backward Compatibility: Any 1.x release is guaranteed to be backward compatible with an earlier 1.y release. This means code that is correct and works on 1.y will work on a future 1.x version.
• Version Increments:
  • The x in 1.x.y is incremented when new features are released.
  • The y in 1.x.y is incremented for releases containing only bug fixes.
• Breaking Changes: Backwards-incompatible changes are only permitted when moving to version 2.0. Such changes will be accompanied by FutureWarning where appropriate.

It is recommended to use the conda-forge channel for Py-ART, as it contains the most recent versions of required packages and helps avoid dependency conflicts by keeping packages within the same channel. You can set conda-forge as your priority channel or specify it during a single installation command.

# Add conda-forge as the priority channel
conda config --add channels conda-forge

# OR, flag the channel for a specific installation
conda install -c conda-forge numpy

You can create a pre-configured conda environment using the official environment.yml file provided in the Py-ART repository. This creates an environment named pyart_env.

# Create the environment from the file
conda env create -f environment.yml

# Activate the environment
source activate pyart_env

# Deactivate the environment when finished
source deactivate pyart_env

The recommended method for installing Py-ART is using conda with Python 3. It is highly recommended to create a new conda environment to avoid dependency conflicts.

To create a new environment using the provided environment.yml file:

conda env create -f environment.yml

To create a basic environment and download optional dependencies as needed:

conda create -n pyart_env -c conda-forge arm_pyart

To install the latest version of Py-ART into your current environment:

conda install -c conda-forge arm_pyart

To update an existing installation of Py-ART to the latest release:

conda update -c conda-forge arm_pyart

The recommended way to install Py-ART is using pixi. This method automatically handles all required dependencies and builds the environment for you.

1. Install pixi from https://pixi.sh/latest/installation.
2. Initialize a new environment and add the package using the following commands:

$ pixi init pyart_dev
$ cd pyart_dev
$ pixi add arm_pyart

The most straightforward way to set up a Py-ART environment is to use the provided environment.yml file. This ensures all necessary dependencies are installed correctly.

1. Download the environment.yml file from the repository.
2. Create the environment using the following command:

   conda env create -f environment.yml

3. Activate the environment named pyart_env:

   source activate pyart_env

4. To stop using the environment, run:

   source deactivate pyart_env

To test the Py-ART installation, you must have pytest and open-radar-data installed. You can run the test suite from outside the source directory using the --pyargs flag.

# Install testing dependencies
conda install -c conda-forge pytest
conda install -c conda-forge open-radar-data

# Run the test suite
pytest --pyargs pyart

To use the CyLP package with Py-ART, you must first install its dependency coincbc and then set the COIN_INSTALL_DIR environment variable so the installer can locate it.

1. Activate your pyart_env.
2. Install coincbc from conda-forge:

   conda install -c conda-forge coincbc

3. Export the path to your environment's directory to the COIN_INSTALL_DIR variable:

   export COIN_INSTALL_DIR=/path/to/your/anaconda3/envs/pyart_env

4. Install the Python 3 compatible version of CyLP directly from GitHub using pip:

   pip install git+https://github.com/jjhelmus/CyLP.git@py3

conda install -c conda-forge coincbc
export COIN_INSTALL_DIR=/home/user/anaconda3/envs/pyart_env
pip install git+https://github.com/jjhelmus/CyLP.git@py3