Metadata-Version: 2.4
Name: rpgPy
Version: 0.15.13
Summary: Cython code for reading binary files from RPG cloud radar.
Author-email: Simo Tukiainen <simo.tukiainen@fmi.fi>
License: MIT License
        
        Copyright (c) 2019 Simo Tukiainen
        
        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.
        
Project-URL: Homepage, https://github.com/actris-cloudnet/rpgpy
Project-URL: Repository, https://github.com/actris-cloudnet/rpgpy
Project-URL: Changelog, https://github.com/actris-cloudnet/rpgpy/blob/main/CHANGELOG.md
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
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
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cython
Requires-Dist: netCDF4
Requires-Dist: numpy
Requires-Dist: tqdm
Provides-Extra: full
Requires-Dist: numba; extra == "full"
Provides-Extra: test
Requires-Dist: mypy; extra == "test"
Requires-Dist: pytest-flakefinder; extra == "test"
Requires-Dist: types-tqdm; extra == "test"
Provides-Extra: dev
Requires-Dist: pre-commit; extra == "dev"
Requires-Dist: release-version; extra == "dev"
Dynamic: license-file

# rpgPy

![](https://github.com/actris-cloudnet/rpgpy/workflows/RpgPy%20CI/badge.svg)
[![PyPI version](https://badge.fury.io/py/rpgPy.svg)](https://badge.fury.io/py/rpgPy)

RpgPy is a Python / Cython software for

- Reading [RPG cloud radar](https://www.radiometer-physics.de/products/microwave-remote-sensing-instruments/fmcw-doppler-cloud-radar/) Level 0 and Level 1 binary files
- Calculating spectral moments from RPG Level 0 data
- Converting RPG binary data to [netCDF4](https://www.unidata.ucar.edu/software/netcdf/) 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

```python
>>> 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.

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

[API reference of `rpg2nc`](#rpg2nc)

### Converting multiple files individually

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

```python
>>> 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`](#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.

```python
>>> 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`](#spectra2nc)

### Reading RPG binary file

If you don't need the netCDF4 file:

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

[API reference of `read_rpg`](#read_rpg)

### Calculating spectral moments

```python
>>> 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`](#spectra2moments)

## API reference

### Index

- [rpg2nc](#rpg2nc)
- [rpg2nc_multi](#rpg2nc_multi)
- [spectra2nc](#spectra2nc)
- [read_rpg](#read_rpg)
- [spectra2moments](#spectra2moments)

##

### `rpg2nc`

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

```python
rpg2nc(path_to_files, output_file, **kwargs)
```

Positional arguments:

| Name            | Type                        | Description                                                                                     |
| :-------------- | :-------------------------- | :---------------------------------------------------------------------------------------------- |
| `path_to_files` | `str` &#124; `pathlib.Path` | Filename of single file, or multiple files identified using a wildcard, e.g., `/foo/bar/*.LV0`. |
| `output_file`   | `str` &#124; `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.

```python
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` &#124; `pathlib.Path` | current working directory | Root path of the search.                             |
| `output_directory` | `str` &#124; `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.

```python
spectra2nc(input_file, output_file, **kwargs)
```

Positional arguments:

| Name          | Type                        | Description                   |
| :------------ | :-------------------------- | :---------------------------- |
| `input_file`  | `str` &#124; `pathlib.Path` | Filename of RGP Level 0 file. |
| `output_file` | `str` &#124; `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.

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

Positional arguments:

| Name       | Type                        | Description                                                 |
| :--------- | :-------------------------- | :---------------------------------------------------------- |
| `filename` | `str` &#124; `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`](#read_rpg)
is required before using this function.

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

Positional arguments:

| Name     | Type   | Description                                             |
| :------- | :----- | :------------------------------------------------------ |
| `data`   | `dict` | Level 0 data dictionary from [`read_rpg`](#read_rpg).   |
| `header` | `dict` | Level 0 header dictionary from [`read_rpg`](#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](https://pre-commit.com/) 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
