Metadata-Version: 2.1
Name: rpgPy
Version: 0.10.2
Summary: Cython code for reading binary files from RPG cloud radar.
Home-page: https://github.com/actris-cloudnet/rpgpy
Author: Simo Tukiainen
Author-email: simo.tukiainen@fmi.fi
License: MIT License
Description: # 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/94-ghz-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
        ```
        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 source
        ``` 
        $ git clone  https://github.com/actris-cloudnet/rpgpy/
        $ cd rpgpy/
        $ python3 -m venv venv
        $ source venv/bin/activate
        (venv) $ python3 -m pip install --upgrade pip
        (venv) $ python3 -m pip install .
        (venv) $ python3 setup.py build_ext --inplace
        ```
        
        # 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: str, output_file: str, **kwargs)
        ```
        
        Positional arguments:
        
        |  Name           | Type         | Description                
        | :---            | :----------  | :---
        | `path_to_files` | `str`        | Filename of single file, or multiple files identified using a wildcard, e.g., `/foo/bar/*.LV0`.   
        | `output_file`   | `str`        | 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`       | current working directory  | Root path of the search.
        | `output_directory` | `str`       | 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: str, output_file: str, **kwargs)
        ```
        
        Positional arguments:
        
        |  Name              | Type         | Description                
        | :---               | :----------  | :---
        | `input_file`       | `str`        | Filename of RGP Level 0 file.   
        | `output_file`      | `str`        | 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: str, **kwargs)
        ```
        
        Positional arguments:
        
        | Name        | Type     | Description                                | 
        | :---        | :------  | :---                                       |
        | `filename`  | `str`    | 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: dict, header: dict, **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).|
        
        
        ## Tests
        Run unit tests:
        ```
        (venv) $ pytest
        ```
        
        Run end-to-end tests:
        ```
        (venv) $ for f in tests/e2e/*/main.py; do $f; done
        ```
        
        
        ## 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
        
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3.6
Classifier: License :: OSI Approved :: MIT License
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.6
Description-Content-Type: text/markdown
