Metadata-Version: 2.4
Name: roms-tools
Version: 5.0.0
Summary: Tools for running and analysing UCLA-ROMS simulations
Author-email: Nora Loose <nora.loose@gmail.com>, Thomas Nicholas <tom@cworthy.org>, Scott Eilerman <scott.eilerman@cworthy.org>, Ben Saenz <ben.saenz@cworthy.org>, Ulla Heede <ulla@cworthy.org>, Abigale Wyatt <abigale@cworthy.org>, Kristen Thyng <kristen.thyng@cworthy.org>, Chris McBride <christopher.mcbride@cworthy.org>
License: Apache-2
Project-URL: Home, https://github.com/CWorthy-ocean/roms-tools
Project-URL: Documentation, https://roms-tools.readthedocs.io/en/latest/
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: xarray<2025.8.0,>=2022.6.0
Requires-Dist: numpy<2.3,>2.0
Requires-Dist: pooch
Requires-Dist: matplotlib<3.11
Requires-Dist: cartopy
Requires-Dist: packaging
Requires-Dist: scipy>=1.18.0
Requires-Dist: gcm_filters>=0.5.1
Requires-Dist: netcdf4
Requires-Dist: PyYAML
Requires-Dist: pyamg
Requires-Dist: bottleneck
Requires-Dist: regionmask>=0.11.0
Requires-Dist: xgcm<0.11,>0.10.0
Requires-Dist: gsw
Requires-Dist: numba>=0.61.2
Requires-Dist: pydantic<3,>2
Requires-Dist: dask[diagnostics]
Requires-Dist: h5netcdf
Requires-Dist: threadpoolctl
Provides-Extra: stream
Requires-Dist: gcsfs; extra == "stream"
Requires-Dist: zarr; extra == "stream"
Requires-Dist: copernicusmarine; extra == "stream"
Provides-Extra: movie
Requires-Dist: imageio-ffmpeg; extra == "movie"
Provides-Extra: notebooks
Requires-Dist: jupyter; extra == "notebooks"
Requires-Dist: gdown; extra == "notebooks"
Requires-Dist: ipykernel; extra == "notebooks"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-xdist; extra == "dev"
Requires-Dist: coverage; extra == "dev"
Requires-Dist: pre-commit>=3.8; extra == "dev"
Requires-Dist: h5py; extra == "dev"
Requires-Dist: zarr; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx; extra == "docs"
Requires-Dist: nbsphinx; extra == "docs"
Requires-Dist: sphinx-book-theme; extra == "docs"
Requires-Dist: sphinx-design; extra == "docs"
Requires-Dist: sphinxcontrib-bibtex; extra == "docs"
Requires-Dist: myst-parser; extra == "docs"
Requires-Dist: ipykernel; extra == "docs"
Dynamic: license-file

# ROMS-Tools

[![Conda version](https://img.shields.io/conda/vn/conda-forge/roms-tools.svg)](https://anaconda.org/conda-forge/roms-tools)
[![PyPI version](https://img.shields.io/pypi/v/roms-tools.svg)](https://pypi.org/project/roms-tools/)
[![Run Tests](https://github.com/CWorthy-ocean/roms-tools/actions/workflows/tests.yaml/badge.svg)](https://github.com/CWorthy-ocean/roms-tools/actions/workflows/tests.yaml?query=branch%3Amain)
[![codecov](https://codecov.io/gh/CWorthy-ocean/roms-tools/graph/badge.svg?token=5S1oNu39xE)](https://codecov.io/gh/CWorthy-ocean/roms-tools)
[![Documentation Status](https://readthedocs.org/projects/roms-tools/badge/?version=latest)](https://roms-tools.readthedocs.io/en/latest/?badge=latest)
![Supported Python Versions](https://img.shields.io/pypi/pyversions/roms-tools)
[![PyPI Downloads](https://static.pepy.tech/personalized-badge/roms-tools?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/roms-tools)
[![DOI](https://joss.theoj.org/papers/10.21105/joss.10234/status.svg)](https://doi.org/10.21105/joss.10234)

## Overview

A suite of Python tools for setting up and analyzing a [UCLA-ROMS](https://github.com/CWorthy-ocean/ucla-roms) simulation with or without [MARBL biogeochemistry](https://marbl-ecosys.github.io/versions/latest_release/index.html).

## Installation

### ⚡️ **Installation from conda-forge (recommended)**

To install `ROMS-Tools` with all dependencies, including `xesmf`, `dask` and all packages required for streaming source data directly from the cloud, use:

```bash
conda install -c conda-forge roms-tools
```

> [!Note]
>  Installation from Conda-Forge is the recommended installation method to ensure all features of `ROMS-Tools` are available.

### 📦 **Installation from PyPI (pip) (recommend for Windows only)**

You can also install `ROMS-Tools` from `pip`:

```bash
pip install roms-tools
```

`dask` (recommended for parallel and out-of-core computation) is included by default.

If you want to use `ROMS-Tools` with all packages required for streaming source data directly from the cloud, install it with the additional dependencies:

```bash
pip install roms-tools[stream]
```


> [!Note]
>  The PyPI versions of `ROMS-Tools` do not include `xesmf`, so some features will be unavailable.


### Installation from GitHub

To obtain the latest development version, first clone the source repository:

```bash
git clone https://github.com/CWorthy-ocean/roms-tools.git
cd roms-tools
```

Next, install and activate the following conda environment:

```bash
conda env create -f ci/environment.yml
conda activate roms-tools-env
```

Finally, install `ROMS-Tools` in the same environment, along with the `dev` extra (test/lint tooling):

```bash
pip install -e ".[dev]"
```

`dask` (recommended for parallel and out-of-core computation) is included in the core dependencies by default.

If you want to use `ROMS-Tools` with all packages required for streaming source data directly from the cloud, you can
install `ROMS-Tools` along with the additional dependencies via:

```bash
pip install -e ".[dev,stream]"
```

## Getting Started

To learn how to use `ROMS-Tools`, check out the [documentation](https://roms-tools.readthedocs.io/en/latest/).

## How to cite ROMS-Tools

If you use ROMS-Tools in your work, we would be happy if you cite our paper in the Journal of Open Source Software:

> Loose, N., Nicholas, T., Maticka, S., Eilerman, S., McBride, C., Stephenson, D., Heede, U., Saenz, B., Thyng, K. M., Bachman, S., Damien, P., Karspeck, A., Long, M. C., Molemaker, M. J., & Wyatt, A. (2026). ROMS-Tools: Reproducible Preprocessing and Analysis for Regional Ocean Modeling with ROMS. *Journal of Open Source Software*, *11*(124), 10234. https://doi.org/10.21105/joss.10234

Or use the following BibTeX entry:

```bibtex
@article{loose2026romstools,
  author  = {Loose, Nora and Nicholas, Tom and Maticka, Sam and Eilerman, Scott
             and McBride, Christopher and Stephenson, Dafydd and Heede, Ulla
             and Saenz, Benjamin and Thyng, Kristen M. and Bachman, Scott
             and Damien, Pierre and Karspeck, Alicia and Long, Matthew C.
             and Molemaker, M. Jeroen and Wyatt, Abigale},
  title   = {{ROMS-Tools}: Reproducible Preprocessing and Analysis for
             Regional Ocean Modeling with {ROMS}},
  journal = {Journal of Open Source Software},
  year    = {2026},
  volume  = {11},
  number  = {124},
  pages   = {10234},
  doi     = {10.21105/joss.10234},
  url     = {https://joss.theoj.org/papers/10.21105/joss.10234},
}
```

## Feedback and contributions

**If you find a bug, have a feature suggestion, or any other kind of feedback, please start a Discussion.**

We also accept contributions in the form of Pull Requests.

## See also

- [C-Star](https://github.com/CWorthy-ocean/C-Star)
