Python toolbox for performing Observing System Simulation Experiments (OSSEs) in ocean general circulation models.
OceanOSSE is an open-soource Python toolbox developed as part of the Explaining and Predicting the Ocean Conveyor (EPOC) project for performing Observing System Simulation Experiments (OSSEs) in ocean general circulation models.
OceanOSSE allows users to generate seawater property fields (analogous to a Level 4 gridded product) from synthetic observations (e.g., Argo, moorings etc.) of time-evolving ocean model outputs. Critically, OceanOSSE also regrids the sparse, synthetic observations onto the native ocean model grid, enabling familiar, grid-aware computation with the resulting output fields.
OceanOSSE uses a modular and customisable framework; the main experiment pipeline implements four Abstract Base Classes:
-
DataLoader:
Read ocean model input files, climatology & domain variables.
-
ObsSampler:
Perform synthetic sampling of ocean model "truth", returning a sparse Dataset of observations.
-
Regridder:
Regrid sparse synthetic observations onto the native ocean model grid.
-
DataWriter:
Write regridded synthetically observed variables to output file.
To get started using OceanOSSE create and activate a new Python virtual environment:
- Using miniconda or miniforge:
# Creating a virtual environment:
conda create -n env_oceanosse python=3.13
# Activate virtual environment <env_oceanosse>
conda activate env_oceanosse- Using venv:
# Alternatively, creating a virtual environment using -> venv:
python -m venv env_oceanosse
# Activate virtual environment <env_oceanosse>
source /path/to/env_oceanosse/bin/activateNext, install the package into the new virtual using pip:
# Install OceanOSSE using pip:
pip install .Clone the repository and set up the full development environment:
git clone https://github.com/AMOCcommunity/OceanOSSE.git
cd OceanOSSE
pixi installAll development tasks (tests, linting, formatting, docs) are available as Pixi tasks:
# Show available tasks:
pixi task list
# Run pytest unit test suite:
pixi run testsSee CONTRIBUTING.md for full details on the development workflow.
To run a new OSSE experiment with OceanOSSE, we can use the oceanosse command-line interface:
oceanosse run Full documentation, including the API reference and tutorials, is available at:
https://amoccommunity.github.io/OceanOSSE/
Contributions are welcome! Please read CONTRIBUTING.md for details on how to set up your environment, code style expectations, and the pull request process.
To report a bug or request a feature, please open an issue.
A full history of changes between releases is maintained in CHANGELOG.md.
If you use this software in your research, please cite it. A citation helps sustain the project and gives credit to its contributors.
Citing the software:
@software{<your-repo>,
author = {Last, First and Last, First},
title = {{<Project Name>}: <short description>},
year = {YYYY},
version = {v0.1.0},
publisher = {Zenodo},
doi = {10.5281/zenodo.XXXXXXX},
url = {https://doi.org/10.5281/zenodo.XXXXXXX}
}The ongoing development of OceanOSSE is funded by:
This project is licensed under the Apache 2.0 License — see the LICENSE file for details.