rpgPy 0.15.13

Cython code for reading binary files from RPG cloud radar.

rpgPy

RpgPy is a Python / Cython software for

• Reading RPG cloud radar Level 0 and Level 1 binary files
• Calculating spectral moments from RPG Level 0 data
• Converting RPG binary data to netCDF4 format

Installation

From PyPI

python3 -m pip install rpgpy

From source

git clone  https://github.com/actris-cloudnet/rpgpy/
cd rpgpy/
python3 -m venv venv
source venv/bin/activate
python3 -m pip install --upgrade pip
python3 -m pip install .
python3 setup.py build_ext --inplace

NOTE: A C-compiler is required because the Cython code is compiled locally during installation. If you get an error about missing Python.h, you need to install the missing header files with $ apt install python3-dev (or similar).

Quickstart

Converting RPG binary files into netCDF4

>>> from rpgpy import rpg2nc
>>> rpg2nc('rpg-data.LV1', 'rpg-file.nc')

This writes a compressed netCDF4 file and works with both Level 0 and Level 1 data.

Several RPG files can be concatenated into singe netCDF file using wildcard. With Level 0 data, this can lead to a very large file.

>>> rpg2nc('/path/to/files/*.LV0', 'huge-file.nc')

API reference of rpg2nc

Converting multiple files individually

Multiple RPG files can be converted into corresponding individual netCDF4 files using rpg2nc_multi.

>>> from rpgpy import rpg2nc_multi
>>> filenames = rpg2nc_multi(file_directory='/path/to/files')

Default functionality is that every file with an extension .LV0, .lv0, .LV1 or .lv1 in every subdirectory of the specified path will be converted.

API reference of rpg2nc_multi

Creating custom Level 1 netCDF4 file

rpgpy can estimate spectral moments from Level 0 data. The estimation is based on the most prominent peak of each time / range point.

>>> from rpgpy import spectra2nc
>>> spectra2nc('rpg-data.LV0', 'level1.nc')

This calculates spectral moments from Level 0 data and writes the results in a netCDF4 file.

API reference of spectra2nc

Reading RPG binary file

If you don't need the netCDF4 file:

>>> from rpgpy import read_rpg
>>> header, data = read_rpg('rpg-data.LV1')

API reference of read_rpg

Calculating spectral moments

>>> from rpgpy import read_rpg, spectra2moments
>>> header, data = read_rpg('rpg-data.LV0')
>>> moments = spectra2moments(data, header)

This works only with Level 0 data.

API reference of spectra2moments

API reference

Index

• rpg2nc
• rpg2nc_multi
• spectra2nc
• read_rpg
• spectra2moments

rpg2nc

Convert RPG cloud radar file(s) into single netCDF file.

rpg2nc(path_to_files, output_file, **kwargs)

Positional arguments:

Name	Type	Description
path_to_files	str | pathlib.Path	Filename of single file, or multiple files identified using a wildcard, e.g., /foo/bar/*.LV0.
output_file	str | pathlib.Path	Output file name.

Keyword arguments:

Name	Type	Default value	Description
global_attr	dict	None	Additional global attributes.

rpg2nc_multi

Convert RPG cloud radar files into several corresponding netCDF files.

filenames = rpg2nc_multi(**kwargs)

Default functionality:

• Input files are searched recursively starting from the current working directory
• Files with the suffix .LV0, .lv0, .LV1 or .lv1 suffix are converted
• netCDF4 files are written to the current working directory

Keyword arguments:

Name	Type	Default value	Description
file_directory	str | pathlib.Path	current working directory	Root path of the search.
output_directory	str | pathlib.Path	current working directory	Path name where the netCDF4 files are written.
include_lv0	bool	True	If False, excludes Level 0 files.
recursive	bool	True	If False, does not search input files recursively.
base_name	str	None	Optional filename prefix for the converted files.
global_attr	dict	None	Additional global attributes.

Returns:

Type	Description
list	Full paths of the successfully created netCDF files.

spectra2nc

Calculate moments from RPG Level 0 spectra and write a netCDF4 file.

spectra2nc(input_file, output_file, **kwargs)

Positional arguments:

Name	Type	Description
input_file	str | pathlib.Path	Filename of RGP Level 0 file.
output_file	str | pathlib.Path	Output file name.

Keyword arguments:

Name	Type	Default value	Description
global_attr	dict	None	Additional global attributes.
n_points_min	int	4	Minimum number of points in a proper spectral line.

read_rpg

Read RPG cloud radar binary file.

header, data = read_rpg(filename, **kwargs)

Positional arguments:

Name	Type	Description
filename	str | pathlib.Path	Filename of RPG cloud radar Level 1 or Level 0 binary file.

Keyword arguments:

Name	Type	Default value	Description
rpg_names	bool	True	If True, uses RPG manual names in the returned dictionary, else uses more human-readable names.

Returns:

Type	Description
tuple	2-element tuple containing header and data dictionary.

spectra2moments

Calculate spectral moments from Level 0 spectral data. A call to read_rpg is required before using this function.

moments = spectra2moments(data, header, **kwargs)

Positional arguments:

Name	Type	Description
data	dict	Level 0 data dictionary from read_rpg.
header	dict	Level 0 header dictionary from read_rpg.

Keyword arguments:

Name	Type	Default value	Description
spec_var	str	"TotSpec"	Spectral variable to be analyzed: "TotSpec" or "HSpec".
fill_value	float	-999.0	Value for the clear sky data points.
n_points_min	int	4	Minimum number of points in a proper spectral line.

Returns:

Type	Description
dict	Dictionary containing Ze (reflectivity), MeanVel (mean velocity), SpecWidth (spectral width), Skewn (skewness) and Kurt (kurtosis), which are 2D numpy arrays (time x range).

Development

Install test-dependencies and pre-commit hooks:

python3 -m pip install -e .[test,dev]
pre-commit install

Compile Cython (repeat if you change .pyx files):

python3 setup.py build_ext --inplace

Tests

Run unit tests:

pytest

Run end-to-end tests:

for f in tests/e2e/*/*runner.py; do $f; done

Force pre-commit checks of all files:

pre-commit run --all

Performance

For reading RPG binary files, depending on the radar settings, RpgPy is roughly 20-30 times faster than equivalent native Python or Matlab implementations.

License

MIT