Metadata-Version: 2.4
Name: pyshadoz
Version: 0.2.0
Summary: pyshadoz is a pure Python package to read and write NASA Southern Hemisphere ADditional OZonesondes (SHADOZ) data
Author-email: Tom Kralidis <tomkralidis@gmail.com>
Maintainer-email: Tom Kralidis <tomkralidis@gmail.com>
License-Expression: MIT
Project-URL: homepage, https://github.com/wmo-cop/pyshadoz
Project-URL: source, https://github.com/wmo-cop/pyshadoz
Project-URL: documentation, https://github.com/wmo-cop/pyshadoz
Project-URL: issues, https://github.com/wmo-cop/pyshadoz/issues
Keywords: shadoz,Southern Hemisphere ADditional OZonesondes,ozonesonde,tropics,subtropics,nasa,wmo
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: click
Provides-Extra: dev
Requires-Dist: flake8; extra == "dev"
Provides-Extra: release
Requires-Dist: build; extra == "release"
Requires-Dist: twine; extra == "release"
Requires-Dist: wheel; extra == "release"
Dynamic: license-file

# pyshadoz

[![Build Status](https://github.com/wmo-cop/pyshadoz/workflows/build%20%E2%9A%99%EF%B8%8F/badge.svg)](https://github.com/wmo-im/pyshadoz/actions)

## Overview

pyshadoz is a pure Python package to read and write [NASA Southern Hemisphere
ADditional OZonesondes](https://tropo.gsfc.nasa.gov/shadoz/) (SHADOZ) data.

Versions 5 and 6 are supported.

## Installation

The easiest way to install pyshadoz is via the Python [pip](https://pip.pypa.io/en/stable/)
utility:

```bash
pip3 install pyshadoz
```

### Requirements
- Python 3
- [virtualenv](https://virtualenv.pypa.io/)

### Dependencies
Dependencies are listed in [pyproject.toml](pyproject.toml). Dependencies
are automatically installed during pyshadoz installation.

### Installing pyshadoz

```bash
# setup virtualenv
virtualenv --system-site-packages -p python3 pyshadoz
cd pyshadoz
source bin/activate

# clone codebase and install
git clone https://github.com/wmo-cop/pyshadoz.git
cd pyshadoz
pip3 install .
```

## Running

```bash
# help
pyshadoz --help

# get version
pyshadoz --version

# parse a single shadoz file
pyshadoz -f </path/to/shadoz_file>

# add verbose mode
pyshadoz -v -f </path/to/shadoz_file>

# parse a directory of shadoz files
pyshadoz -d </path/to/directory>

# parse a directory of shadoz files recursively
pyshadoz -r -d </path/to/directory>
```

### Using the API
```python
from pyshadoz import SHADOZ

# read SHADOZ data
with open('/path/to/directory') as ff:
    s = SHADOZ(ff)

    for key, value in s.metadata:
        print(key, value)

    print(s.data_fields)
    print(s.data_fields_units)
    print(len(s.data))

    # get index of a data field
    index = s.get_data_index('W Dir')

    # get index of a data field and data field unit
    index = s.get_data_index('W Dir', 'deg')

    # get all data
    data = s.get_data()

    # get data by index
    data = s.get_data(by_index=index)

    # get all data by field
    data = s.get_data('W Spd')

    # get all data by field and unit
    data = s.get_data('O3', 'ppmv')

# read SHADOZ data using convenience functions
# parse file
s = load('/path/to/shadoz_file.dat')  # returns SHADOZ object

# parse string
with open('/path/to/shadoz_file.dat') as ff:
    shadoz_string = ff.read()
s = loads(shadoz_string)  # returns SHADOZ object

# write SHADOZ data
s = SHADOZ()
# build metadata dict
s.metadata['NASA/GSFC/SHADOZ Archive'] = 'http://croc.gsfc.nasa.gov/shadoz'
....
# build data fields
s.data_fields = ['Time', 'Press', 'Alt', 'Temp', 'RH', 'O3', 'O3', 'O3',
                 'W Dir', 'W Spd', 'T Pump', 'I O3', 'GPSLon', 'GPSLat',
                 'GPSAlt']

# build data field units
s.data_fields_units = ['sec','hPa','km', 'C', '%', 'mPa', 'ppmv', 'du', 'deg',
                       'm/s', 'C', 'uA', 'deg', 'deg', 'km']

# build data
s.data = [
    [0, 1013.85, 0.01, 24.22, 71.0, 32.91, 32.91, 0.0, 32.91, 5.29, 32.91, 9000.0, -155.049, 19.717, 0.041],
    [0, 1013.66, 0.012, 23.89, 70.0, 32.79, 32.79, 0.049, 32.79, 5.01, 32.79, 9000.0, -155.049, 19.717, 0.045]
]

# serialize data to file
shadoz_data = s.write()
with open('new_shadoz_file.dat', 'w') as ff:
    ff.write(shadoz_data)
```

## Development

### Running Tests

```bash
python3 pyshadoz/tests/run_tests.py

```

## Releasing

```bash
# create release (x.y.z is the release version)
vi pyproject.toml  # update [project]/version
git commit -am 'update release version x.y.z'
git push origin main
git tag -a x.y.z -m 'tagging release version x.y.z'
git push --tags

# upload to PyPI
rm -fr build dist *.egg-info
python3 -m build
twine upload dist/*

# publish release on GitHub (https://github.com/wmo-cop/pyshadoz/releases/new)

# bump version back to dev
vi pyproject.toml  # update [project]/version
git commit -am 'back to dev'
git push origin main
```

### Code Conventions

* [PEP8](https://www.python.org/dev/peps/pep-0008)

### Bugs and Issues

All bugs, enhancements and issues are managed on [GitHub](https://github.com/wmo-cop/pyshadoz/issues).

## Contact

* [Tom Kralidis](https://github.com/tomkralidis)
