Metadata-Version: 2.4
Name: physoce-datasets
Version: 0.3.0
Summary: A Python package and CLI for downloading various physical oceanographic datasets.
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: beautifulsoup4>=4.14.3
Requires-Dist: cdsapi>=0.7.7
Requires-Dist: cfgrib>=0.9.15.1
Requires-Dist: click>=8.2.1
Requires-Dist: copernicusmarine>=2.3.0
Requires-Dist: earthaccess>=0.18.0
Requires-Dist: ecmwf-datastores-client>=0.5.1
Requires-Dist: gcsfs>=2026.3.0
Requires-Dist: gsw>=3.6.21
Requires-Dist: h5py>=3.16.0
Requires-Dist: harmony-py>=1.3.4
Requires-Dist: ipykernel>=7.2.0
Requires-Dist: metpy>=1.7.1
Requires-Dist: numpy>=2.4.4
Requires-Dist: pycoare>=0.4.0
Requires-Dist: pydap>=3.5.9
Requires-Dist: xarray[accel,io,parallel]>=2026.2.0
Description-Content-Type: text/markdown

# physoce-datasets

A Python package and command line interface aimed at standardizing the access of various oceanographic datasets and calculating derived parameters according to modern best practices.

> [!WARNING]
> Due to issues with the [NASA Harmony API](https://forum.earthdata.nasa.gov/viewtopic.php?t=7954&sid=bdeec61e589c16e9d8642040d2fb01ff), the SST dataset is currently unavailable with an unknown fix timeline. Running any of the `sst` commands will fail with a `NotImplementedError` until this is fixed.

## Why physoce-datasets?

This package provides an *opinionated* interface which aims to simplify and align access to datasets across providing institutions (NASA, ECMWF, etc.); as such, it is aimed primarily at those looking for streamlined data access. If you are an expert user who wants a lot of control over the details of the download and analysis process, this may not be for you. However, if you want:

- a unified command line and Python interface across datasets
- expert-informed derived variables such as wind stress and eddy kinetic energy
- long time series at a single or a few locations
- the simplest downloading and opening process possible

then this package is designed for you!

## Install

### uv

`uv` is the preferred way to manage this package. Please refer to the [uv installation instructions](https://docs.astral.sh/uv/getting-started/installation/). Once uv is installed, you can initialize a virtual environment with `uv sync` or you can run any commands directly with `uv run` and `uv` will handle the `venv` creation and activation auto-magically.

```bash
# add physoce-datasets to your project folder, equivalent to a pip install
uv add physoce-datasets
# you can now run physoce-datasets from your project folder
uv run physoce-datasets --help
```

Once you've added `physoce-datasets` to your project, you can import any of the download classes in your scripts:

```python
# note the import uses underscore in place of dash
from physoce_datasets import EKEDownloader, SSTDownloader, WindStressDownloader
```

Alternatively, you can run the command line interface from anywhere using [uv tools](https://docs.astral.sh/uv/guides/tools/):

```bash
# run physoce-datasets from the command line anywhere!
uvx physoce-datasets --help
```

### pip

Of course, you can also use the classic `pip`, but you have to handle creating and activating the `venv` yourself:

```bash
python -m venv .venv
source .venv/bin/activate
pip install physoce-datasets
```

## Credentials

Upon usage, this package may prompt for credentials to various data stores. Please refer to their documentation for how to access credentials and how credentials are stored:

- [Copernicus Marine Services](https://toolbox-docs.marine.copernicus.eu/en/stable/usage/login-usage.html)
- [Copernicus Climate Data Store](https://cds.climate.copernicus.eu/how-to-api)
- [NASA Earthdata](https://urs.earthdata.nasa.gov/users/new)

## Command Line Interface

Run the CLI with uv:

```bash
uv run physoce-datasets --help
```

Note that if you prefer the `pip` environment management, activate your environment according to the above and replace all `uv run` commands with `python`, e.g.:

```bash
python physoce-datasets --help
```

Available commands:

- `eke`: Download altimetry-derived geostrophic velocities and compute eddy kinetic energy from Copernicus Marine Services.
- `wind-stress`: Download ERA5 wind velocities and compute wind stress using the [COARE 3.5 algorithm](https://github.com/pyCOARE/coare).
- `sst`: Download NASA Multi-scale Ultra-high Resolution (MUR) sea surface temperature.

Show command help:

```bash
uv run physoce-datasets eke --help
```

### Options

All commands share the same base options:

- `--location`: Location for the dataset in the format 'lon,lat' (e.g., '-132.0,36.55'). **Required for all commands!**
- `--save-dir`: Directory where the dataset file is written. If not set, defaults to `.data/`, relative to the current working directory.
- `--save-file`: File name to save the dataset. If not set, a default file name based on the data to be downloaded will be used.
- `--start-date`: Start date in `YYYY-MM-DD` format. If not set, uses `2000-01-01`, or the earliest available date, whichever is later.
- `--end-date`: End date in `YYYY-MM-DD` format. If not set, uses the current date or the latest available date, whicher is earlier.

### Examples

Run `eke` download with defaults:

```bash
uv run physoce-datasets eke
```

Run `wind-stress` with specified options:

```bash
uv run physoce-datasets wind-stress --save-dir data --save-file wind-stress.nc --start-date 2020-01-01 --end-date 2020-01-31 --area -140,-120,30,50
```

## Python Interface

Downloaders can also be used within Python scripts and Python notebooks as well.

Importing and initializing the classes takes the same arguments as the command line interface:

```python
from physoce_datasets import EKEDownloader

# initialize the downloader
eke_downloader = EKEDownloader(
    location="-130,45",
    start_date="2020-01-01",
    end_date="2020-12-31",
    save_dir="data",
    save_file="eke.nc",
)

# perform the download
eke_downloader.download()

# open the dataset; **kwargs are passed to underlying xr.open_dataset() call
ds = eke_downloader.open_dataset(**kwargs)
```

`WindStressDownloader` and `SSTDownloader` follow the exact same interface.

If you'd like to turn off logging in scripts, you can do so with the [Python standard library `logging` module](https://docs.python.org/3/library/logging.html):

```python
import logging

# supress info logging from physoce_datasets
logging.getLogger("physoce_datasets").setLevel(logging.WARNING)
```

## Contributions

Do you have a publicly available dataset that you've got a great download script for? Do you have specialist knowledge required for calculating derived data products? Please consider [opening an issue](https://github.com/andrew-s28/physoce-datasets/issues) or [submitting a pull request](https://github.com/andrew-s28/physoce-datasets/pulls)! We welcome any and all contributions to this project.

If you'd like to contribute to the code or documentation, please refer to the developer instructions below:

1. Fork the repo on GitHub using the "Fork" button in the top right of the [repository home page](https://github.com/andrew-s28/physoce-datasets).
2. Clone your fork to your local machine:

    ```bash
    git clone https://github.com/your-username-here/physoce-datasets.git
    cd physoce-datasets
    ```

3. Setup the development environment by installing development and documentation dependencies and installing pre-commit hooks:

    ```bash
    uv sync --group dev --group docs
    pre-commit install
    ```

    If you're only updating code, you don't need the docs group. If you're only updating docs, you *do* need the dev group.

4. Create a new branch with a helpful name:

    ```bash
    git checkout -b your-great-new-feature
    ```

5. Make your code changes, stage them via `git add`, and commit them with `git commit -m 'here's my great code changes'`.
6. Push your changes to your fork using:

    ```bash
    git push -u origin your-great-new-feature
    ```

7. Open a pull request in the [upstream repository](https://github.com/andrew-s28/physoce-datasets/pulls).

Thanks so much for contributing to open source code!

### AI Contribution Policy

The core developers have made use of modern large language model (LLM) auto-complete and other minor LLM assistance in the development of this project. LLMs can be great for documentation and boiler plate as well as configuration such as GitHub actions, but they are not substitues for a deep understanding of functional code that you are submitting in a pull request. For this reason, **all pull requests that utilize a significant amount of LLM assistance, defined in this case as going above and beyond basic auto-complete and documentation, must include a statement of what code was written exclusively or predominantly by AI**. PRs that do not adhere to this policy may be closed without review, under the sole judgement of project maintainers.
