oceanicospy 0.1.0rc3

A Python library for oceanographic data analysis, numerical model preprocessing, and data retrieval

oceanicospy

A Python library for oceanographic data analysis, numerical model preprocessing, and data retrieval.

oceanicospy centralizes and standardizes the code produced by the OCEANICOS research group, turning recurring tasks in oceanography and coastal engineering into reusable, well-tested building blocks.

---

Features

• Observations — read data from RBR, AQUAlogger, AWAC, CTD, weather stations, and more.
• Analysis — temporal and spectral techniques, including WaveSpectralAnalyzer and tidal analysis.
• Models — preprocessing automation for numerical models (SWAN, WW3, XBeach).
• Retrievals — automated downloads from ERA5, Copernicus Marine (CMEMS), and UHSLC real-time data.
• GIS — geospatial utilities for coastal data (shapefiles, XYZ grids, projections).
• Plots — quick, publication-ready visualizations of oceanographic variables.
• Utils — shared helper functions used across all subpackages.

---

Installation

oceanicospy is currently in beta. The pre-release flag is required to install the latest version.

Local environment

Create a Python environment (conda, venv, or similar) and install from PyPI:

pip install --pre oceanicospy

Verify the installation:

pip show oceanicospy

Expected output:

Name: oceanicospy
Version: 0.1.0rc3
Summary: A Python library for oceanographic data analysis, numerical model preprocessing, and data retrieval
Author-email: OCEANICOS developer team <[e-mail]>
License: GPLv3

Google Colab

Install the latest pre-release directly in a Colab notebook:

!pip install --pre oceanicospy

A runtime restart may be required after installation due to dependency conflicts with Colab's pre-installed packages.

---

Quick start

Import the full package:

import oceanicospy

Or import only what you need:

from oceanicospy.observations.pressure_sensors import RBR
from oceanicospy.analysis import WaveSpectralAnalyzer

Wildcard imports (from oceanicospy.analysis import *) are convenient for exploration but can shadow names from other libraries. Prefer explicit imports in scripts.

---

Package structure

oceanicospy/
├── analysis/      # temporal and spectral analysis (WaveSpectralAnalyzer, tidal analysis, …)
├── gis/           # geospatial utilities (shapefiles, XYZ data, projections)
├── models/        # numerical model preprocessing (SWAN, WW3, XBeach)
├── observations/  # instrument readers (RBR, AQUAlogger, AWAC, CTD, …)
├── plots/         # visualization utilities
├── retrievals/    # automated data retrieval (ERA5, CMEMS, UHSLC)
└── utils/         # shared helpers

---

Contributing

Contributions are welcome. The workflow follows the standard GitHub fork-and-pull-request model.

1. Fork the repository

Go to github.com/oceanicos-dev-org/oceanicospy and click Fork.

2. Set up SSH authentication

Follow the GitHub SSH guide if you haven't already.

3. Clone your fork

git clone [e-mail]:YOUR-USERNAME/oceanicospy.git
cd oceanicospy

Optionally add the upstream remote to stay in sync:

git remote add upstream [e-mail]:oceanicos-dev-org/oceanicospy.git

4. Install in editable mode

pip install -e .

Install optional dependency groups for documentation or development:

pip install -e ".[docs]"   # sphinx, sphinx-book-theme, nbsphinx, myst-nb
pip install -e ".[dev]"    # pytest, build, twine

5. Create a feature branch

Never commit directly to main or integration:

git checkout -b YOUR-USERNAME/my-feature

6. Commit and push

git add path/to/changed_file.py
git commit -m "add some particular feature to certain module"
git push origin YOUR-USERNAME/my-feature

7. Open a pull request

On GitHub, navigate to your fork and click Contribute → Open a pull request. Provide a clear title and description of what changed and why.

---

License

Distributed under the GNU General Public License v3 (GPLv3). See LICENSE for details.

---

Contact

OCEANICOS developer team — [e-mail]