Skip to content

Commit dcca6e7

Browse files
corentincartoncorentincarton
authored
Merge pull request #1 from ecmwf/feature/graph_drainage
Feature/graph drainage
2 parents b221e35 + 460a02b commit dcca6e7

File tree

17 files changed

+1826
-4
lines changed

17 files changed

+1826
-4
lines changed

‎.github/workflows/ci.yml

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
name: ci
2+
3+
on:
4+
push:
5+
branches: [ "main", "develop" ]
6+
pull_request:
7+
branches: [ "main", "develop" ]
8+
9+
jobs:
10+
11+
quality_assurance:
12+
runs-on: ubuntu-latest
13+
steps:
14+
- uses: actions/checkout@v2
15+
- run: pip install ruff
16+
- run: ruff check # check linting violations
17+
- run: ruff format --check # check formatting
18+
19+
setup_and_test:
20+
runs-on: ubuntu-latest
21+
steps:
22+
- uses: actions/checkout@v3
23+
- uses: actions/setup-python@v2
24+
- name: install earthkit-hydro
25+
shell: bash -l {0}
26+
run: pip install .[test]
27+
- name: run tests
28+
shell: bash -l {0}
29+
run: pytest

‎.gitignore

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
__pycache__/
2+
.ipynb_checkpoints/
3+
*.egg-info

‎.pre-commit-config.yaml

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
default_language_version:
2+
python: python3
3+
default_stages:
4+
- commit
5+
- push
6+
repos:
7+
- repo: https://github.com/charliermarsh/ruff-pre-commit
8+
rev: v0.5.6
9+
hooks:
10+
- id: ruff # fix linting violations
11+
args: [ --fix ]
12+
- id: ruff-format # fix formatting
13+
- repo: https://github.com/pre-commit/pre-commit-hooks
14+
rev: v4.4.0
15+
hooks:
16+
- id: detect-private-key
17+
- id: check-ast
18+
- id: end-of-file-fixer
19+
- id: mixed-line-ending
20+
args: [--fix=lf]
21+
- id: trailing-whitespace
22+
- id: check-case-conflict
23+
- repo: local
24+
hooks:
25+
- id: forbid-to-commit
26+
name: Don't commit rej files
27+
entry: |
28+
Cannot commit .rej files. These indicate merge conflicts that arise during automated template updates.
29+
Fix the merge conflicts manually and remove the .rej files.
30+
language: fail
31+
files: '.*\.rej$'

‎README.md

Lines changed: 109 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,116 @@
11
# earthkit-hydro
22

33
**DISCLAIMER**
4-
This project is **BETA** and will be **Experimental** for the foreseeable future.
5-
Interfaces and functionality are likely to change, and the project itself may be scrapped.
6-
**DO NOT** use this software in any project/software that is operational.
74

8-
**earthkit-hydro** is a home for hydrological functions
5+
> This project is in the **BETA** stage of development. Please be aware that interfaces and functionality may change as the project develops. If this software is to be used in operational systems you are **strongly advised to use a released tag in your system configuration**, and you should be willing to accept incoming changes and bug fixes that require adaptations on your part. ECMWF **does use** this software in operations and abides by the same caveats.
6+
7+
**earthkit-hydro** is a Python library for common hydrological functions.
8+
9+
## Installation
10+
Clone source code repository
11+
12+
```
13+
git clone https://github.com/ecmwf/earthkit-hydro.git
14+
cd earthkit-hydro
15+
```
16+
17+
Create and activate conda environment
18+
19+
```
20+
conda create -n hydro python=3.10
21+
conda activate hydro
22+
```
23+
24+
For default installation, run
25+
26+
```
27+
pip install .
28+
```
29+
30+
For a developer installation (includes linting and test libraries), run
31+
32+
```
33+
pip install -e .[dev]
34+
pre-commit install
35+
```
36+
37+
If you only plan to run the tests, instead run
38+
39+
```
40+
pip install -e .[test]
41+
```
42+
43+
## Documentation
44+
Earthkit-hydro can be imported as following:
45+
```
46+
import earthkit.hydro as ekh
47+
```
48+
49+
The package contains different ways of constructing or loading a `RiverNetwork` object. A `RiverNetwork` object is a representation of a river network on a grid.
50+
It can be used to compute basic hydrological functions, such as propagating a scalar along the river network or extract a catchment from the river network.
51+
52+
### Readers
53+
54+
```
55+
ekh.load_river_network(domain="efas", version="5")
56+
```
57+
Loads a precomputed `RiverNetwork`. Current options are
58+
- domain: "efas", version: "5"
59+
- domain: "glofas", version: "4"
60+
61+
62+
```
63+
ekh.from_netcdf_d8(filename)
64+
```
65+
Creates a `RiverNetwork` from a D8 (PCRaster LDD convention) NetCDF format.
66+
67+
```
68+
ekh.from_netcdf_cama(filename, type)
69+
```
70+
Creates a `RiverNetwork` from a CaMa-Flood NetCDF format of type "downxy" or "nextxy".
71+
72+
```
73+
ekh.from_bin_cama(filename, type)
74+
```
75+
Creates a `RiverNetwork` from a CaMa-Flood bin format of type "downxy" or "nextxy".
76+
77+
### RiverNetwork methods
78+
79+
```
80+
network.accuflux(field)
81+
```
82+
Calculates the total accumulated flux down a river network.
83+
84+
<img src="docs/images/accuflux.gif" width="200px" height="160px" />
85+
86+
```
87+
network.upstream(field)
88+
```
89+
Updates each node with the sum of its upstream nodes.
90+
91+
```
92+
network.downstream(field)
93+
```
94+
Updates each node with its downstream node.
95+
96+
```
97+
network.catchment(field)
98+
```
99+
Finds the catchments (all upstream nodes of specified nodes, with overwriting).
100+
101+
<img src="docs/images/catchment.gif" width="200px" height="160px" />
102+
103+
```
104+
network.subcatchment(field)
105+
```
106+
Finds the subcatchments (all upstream nodes of specified nodes, without overwriting).
107+
108+
<img src="docs/images/subcatchment.gif" width="200px" height="160px" />
109+
110+
```
111+
network.export(filename)
112+
```
113+
Exports the `RiverNetwork` as a joblib pickle.
9114

10115
## License
11116

‎docs/images/accuflux.gif

34.6 KB
Loading

‎docs/images/catchment.gif

14.4 KB
Loading

‎docs/images/subcatchment.gif

14.3 KB
Loading

‎docs/notebooks/example.ipynb

Lines changed: 234 additions & 0 deletions
Large diffs are not rendered by default.

‎pyproject.toml

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
[build-system]
2+
requires = ["setuptools>=65", "setuptools_scm[toml]>=6.2"]
3+
build-backend = "setuptools.build_meta"
4+
5+
[project]
6+
name = "earthkit-hydro"
7+
requires-python = ">=3.8"
8+
authors = [
9+
{name = "European Centre for Medium-Range Weather Forecasts (ECMWF)", email = "[email protected]"},
10+
]
11+
maintainers = [
12+
{name = "Corentin Carton de Wiart", email = "[email protected]"},
13+
]
14+
description = "Earthkit hydrological module"
15+
license = {file = "LICENSE"}
16+
classifiers = [
17+
"Development Status :: 4 - Beta",
18+
"Intended Audience :: Science/Research",
19+
"License :: OSI Approved :: Apache Software License",
20+
"Natural Language :: English",
21+
"Operating System :: OS Independent",
22+
"Programming Language :: Python :: 3",
23+
"Programming Language :: Python :: 3 :: Only",
24+
"Programming Language :: Python :: 3.8",
25+
"Programming Language :: Python :: 3.10",
26+
"Topic :: Scientific/Engineering",
27+
]
28+
dynamic = ["version", "readme"]
29+
30+
dependencies = [
31+
"numpy",
32+
"xarray",
33+
"joblib"
34+
]
35+
36+
[project.urls]
37+
repository = "https://github.com/ecmwf/earthkit-hydro"
38+
documentation = "https://github.com/ecmwf/earthkit-hydro"
39+
issues = "https://github.com/ecmwf/earthkit-hydro/issues"
40+
41+
[project.optional-dependencies]
42+
test = [
43+
"pytest",
44+
"pytest-cases",
45+
]
46+
dev = [
47+
"pytest",
48+
"pytest-cases",
49+
"ruff",
50+
"pre-commit"
51+
]
52+
53+
# Linting settings
54+
[tool.ruff]
55+
line-length = 120
56+
indent-width = 4
57+
58+
[tool.ruff.format]
59+
quote-style = "double"
60+
indent-style = "space"
61+
62+
[tool.ruff.lint.per-file-ignores]
63+
"__init__.py" = [
64+
"F401", # unused imports
65+
]
66+
"tests/*" = [
67+
"F405", # variable may be undefined, or defined from star imports
68+
"F403" # use of wildcard imports
69+
]
70+
71+
# Testing
72+
[tool.pytest]
73+
addopts = "--pdbcls=IPython.terminal.debugger:Pdb"
74+
testpaths = [
75+
"tests",
76+
]
77+
78+
# Packaging/setuptools options
79+
[tool.setuptools]
80+
include-package-data = true
81+
82+
[tool.setuptools.dynamic]
83+
readme = {file = ["README.md"], content-type = "text/markdown"}
84+
85+
[tool.setuptools.packages.find]
86+
where = ["src"]
87+
exclude = ["tests"]
88+
89+
[tool.setuptools_scm]
90+
write_to = "src/earthkit/hydro/_version.py"
91+
write_to_template = '''
92+
# Do not change! Do not track in version control!
93+
__version__ = "{version}"
94+
'''
95+
parentdir_prefix_version='earthkit-hydro-' # get version from GitHub-like tarballs
96+
fallback_version='0.1'

‎pytest.ini

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
[pytest]
2+
minversion = 7.0
3+
addopts = -v "--pdbcls=IPython.terminal.debugger:Pdb"
4+
testpaths =
5+
tests

0 commit comments

Comments
 (0)