Metadata-Version: 2.4
Name: seagliderOG1
Version: 0.0.2
Summary: Convert from Seaglider basestation to OG1 format
Maintainer-email: Eleanor Frajka-Williams <eleanorfrajka@gmail.com>, Till Moritz <till.moritz@uni-hamburg.de>
License: MIT License
        
        Copyright (c) 2024 Eleanor Frajka-Williams
        
        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: documentation, https://github.com/ocean-uhh/seagliderOG1
Project-URL: homepage, https://github.com/ocean-uhh/seagliderOG1
Project-URL: repository, https://github.com/ocean-uhh/seagliderOG1
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.23
Requires-Dist: scipy>=1.10
Requires-Dist: pandas>=2.1
Requires-Dist: netCDF4>=1.6
Requires-Dist: xarray>=2025.1.1
Requires-Dist: pooch>=1.7
Requires-Dist: beautifulsoup4>=4.12
Requires-Dist: requests>=2.31
Requires-Dist: gsw>=3.6
Requires-Dist: cartopy>=0.21
Requires-Dist: matplotlib>=3.6
Requires-Dist: tqdm>=4.65
Dynamic: license-file

# seagliderOG1

[![Run tests](https://github.com/ocean-uhh/seagliderOG1/actions/workflows/tests.yml/badge.svg)](https://github.com/ocean-uhh/seagliderOG1/actions/workflows/tests.yml)
[![Deploy Documentation](https://github.com/ocean-uhh/seagliderOG1/actions/workflows/docs_deploy.yml/badge.svg)](https://github.com/ocean-uhh/seagliderOG1/actions/workflows/docs_deploy.yml)

This repository converts Seaglider basestation files (`pSSSDDDD*.nc`) into [OG1 format](https://oceangliderscommunity.github.io/OG-format-user-manual/OG_Format.html) for standardized oceanographic glider data.

Code is based on [votoutils](https://github.com/voto-ocean-knowledge/votoutils/blob/main/votoutils/glider/convert_to_og1.py).

## Installation

### Recommended: Using pip

For most users, pip installation is the simplest approach:

```bash
# Install from PyPI (when available)
pip install seagliderOG1

# Or install from source
pip install git+https://github.com/ocean-uhh/seagliderOG1.git
```

### Development setup

For contributors and developers:

```bash
# Clone the repository
git clone https://github.com/ocean-uhh/seagliderOG1.git
cd seagliderOG1

# Install dependencies and package in development mode
pip install -r requirements-dev.txt
pip install -e .
```

### Alternative: Using conda/micromamba

If you prefer conda environments:

```bash
# Using conda
conda env create -f environment.yml
conda activate TEST

# Using micromamba (faster)
micromamba env create -f environment.yml
micromamba activate TEST
```

## Package Structure

Scripts within the `seagliderOG1` package are organized by functionality:

- **readers.py** - Reads basestation files (`*.nc`) from server or local directory
- **writers.py** - Writes OG1 `*.nc` files to output directory (default: `data/`)
- **plotters.py** - Basic plotting and data visualization functions
- **convertOG1.py** - Main conversion logic from basestation to OG1 format
- **vocabularies.py** - Vocabulary translation mappings for OG1 compliance
- **tools.py** - User-facing utility functions
- **utilities.py** - Internal helper functions for data processing

## Configuration

The `seagliderOG1/config/` directory contains YAML files that define OG1 format specifications:

- `OG1_global_attrs.yaml` - Global attributes for OG1 format
- `OG1_var_names.yaml` - Variable name mappings
- `OG1_sensor_attrs.yaml` - Sensor attribute definitions
- `OG1_vocab_attrs.yaml` - Vocabulary attribute mappings
- `OG1_author.yaml` - Author information template
- `mission_yaml.yaml` - Mission configuration template

## Usage

### Basic conversion

```python
from seagliderOG1 import convertOG1, readers

# Load basestation files
datasets = readers.load_basestation_files("path/to/basestation/files/")

# Convert to OG1 format
og1_dataset, variable_list = convertOG1.convert_to_OG1(datasets)

# Save result
from seagliderOG1 import writers
writers.save_dataset(og1_dataset, "output_file.nc")
```

### Examples

See the `notebooks/` directory for detailed examples:
- `demo.ipynb` - Basic usage demonstration
- `dev_notebooks/` - Development and troubleshooting notebooks

## Development

### Running tests

```bash
pytest                    # Run all tests
pytest -v                 # Verbose output
pytest tests/test_*.py    # Run specific test file
```

### Code quality

```bash
black .                   # Format code
ruff check --fix          # Lint and auto-fix
pre-commit run --all-files # Run all pre-commit hooks
```

### Building documentation

```bash
cd docs
make clean html
```

## Dependencies

The project uses different dependency files for different use cases:

- **requirements.txt** - Core runtime dependencies (recommended for most users)
- **requirements-dev.txt** - Additional development tools (testing, documentation, code quality)
- **environment.yml** - Complete conda/micromamba environment (alternative for conda users)

### Core dependencies

- **xarray** & **netCDF4** - NetCDF file handling and data manipulation
- **numpy**, **pandas** - Numerical operations and data structures
- **gsw** - Seawater property calculations (TEOS-10)
- **matplotlib** - Plotting and visualization
- **pooch** - Data downloading and caching

## Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Run tests and ensure they pass
5. Commit your changes (`git commit -m 'Add amazing feature'`)
6. Push to the branch (`git push origin feature/amazing-feature`)
7. Open a Pull Request

## Status

This project is under active development. Collaborations and contributions are welcome!

## License

See [LICENSE](LICENSE) for details.
