Skip to content

About

Builds standardised wind, current and wave conditions along vessel routes — harmonises ocean data and samples it onto route geometry into a ready-to-use table for water-path.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

water-routefinder

CI Docs codecov License: Apache-2.0

Builds standardised wind, current and wave conditions along vessel routes — downloads met-ocean data (Copernicus Marine and/or ERA5), harmonises it onto one grid, and samples it onto route geometry into the ready-to-use bundle water-path consumes. A Snakemake workflow, managed with pixi.

📖 Full documentation: frasanvit.github.io/water-routefinder — quickstart, every config/config.yaml key, architecture, and the v0.2 bundle contract.

The workflow supports only cmems and era5 for now (a later stage may add an offline mock provider back for demos/CI) — running run-demo for real needs live credentials (see the Quickstart).

Quickstart

pixi install                # creates the project environment (pixi.toml)
pixi run test-unit           # offline unit + input-format tests (no credentials needed)
pixi run dry-run              # sanity-check the DAG without running anything (no credentials needed)

cp .env.example .env         # then fill in CMEMS_USERNAME/CMEMS_PASSWORD (see the docs
                               #   for alternatives, incl. `copernicusmarine login`)
pixi run run-demo            # builds resources/user/dublin-bay -> results/dublin-bay/

run-demo produces, from the example network under resources/user/dublin-bay/:

results/dublin-bay/
  network/{harbours.csv, routes.geojson}      # the water-path bundle
  environment/{conditions.parquet, conditions.meta.yaml}
  validation.txt                              # "OK", or the contract violations found
  dublin-bay_diag_plot.png                    # route map (real coastlines) + conditions-over-time + data-quality panel

See Configuring your own network for routes.geojson/harbours.csv shape and every config/config.yaml key.

Layout

pixi.toml, pyproject.toml   # pixi workspace + the water_routefinder package (hatchling)
mkdocs.yml, docs/            # the documentation site (published to GitHub Pages)
INTERFACE.yaml               # path-variable documentation
config/                      # user-editable config + its schema doc
workflow/                    # Snakefile, rules/*.smk, scripts/*.py, internal/ (schema + settings)
src/water_routefinder/       # the reusable, unit-tested core the workflow scripts call into
resources/user/              # your input networks (routes.geojson + harbours.csv)
resources/automatic/          # downloads + intermediates (safe to delete; regenerated)
resources/basemap/            # bundled offline land polygons for the diagnostic plot's map panel
results/                      # the built bundle(s) + validation report + diagnostic plot
tests/                        # unit, input-format, and end-to-end workflow tests

See Architecture for how it fits together and the bundle contract for the exact output format.

Tests

pixi run test-unit             # offline: unit tests + input-format tests
pixi run test                  # same, minus any @pytest.mark.integration test
pixi run test-cov               # same, + a coverage report (coverage.xml, for Codecov)
pixi run test-integration-live # needs CMEMS_USERNAME/CMEMS_PASSWORD and/or CDS API credentials
                                 #   -- includes the full end-to-end Snakemake workflow test

Docs site

docs/ (built with MkDocs Material) is published automatically to GitHub Pages on every push to main that touches it (.github/workflows/docs.yml). To preview locally:

pixi run docs-serve   # http://127.0.0.1:8000, live-reloads on edit
pixi run docs-build    # static build to site/ (--strict: fails on broken links)

License

Apache-2.0 — see LICENSE.

About

Builds standardised wind, current and wave conditions along vessel routes — harmonises ocean data and samples it onto route geometry into a ready-to-use table for water-path.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages