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
python3 -m pip install rpgpy
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).
>>> 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')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.
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.
If you don't need the netCDF4 file:
>>> from rpgpy import read_rpg
>>> header, data = read_rpg('rpg-data.LV1')>>> 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
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. |
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,.LV1or.lv1suffix 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. |
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 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. |
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). |
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
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
For reading RPG binary files, depending on the radar settings, RpgPy is roughly 20-30 times faster than equivalent native Python or Matlab implementations.
MIT
