You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
> This software is **Emerging** and subject to ECMWF's guidelines on [Software Maturity](https://github.com/ecmwf/codex/raw/refs/heads/main/Project%20Maturity).
2
28
3
29
The Hydrological Analysis Toolkit (HAT) is a software suite for hydrologists working with simulated and observed river discharge. HAT performs data analysis on hydrological datasets, with its main features being:
4
30
- mapping station locations into hydrological model grids
5
-
- extraction of timeseries
31
+
- extraction of timeseries at station locations from gridded model outputs
6
32
- statistical analysis of hydrological timeseries
7
33
8
-
The documentation can be found at https://hydro-analysis-toolkit.readthedocs.io
9
-
10
-
**DISCLAIMER**
11
-
This project is **BETA** and will be **Experimental** for the foreseeable future.
12
-
Interfaces and functionality are likely to change, and the project itself may be scrapped.
13
-
**DO NOT** use this software in any project/software that is operational.
14
-
15
34
### Installation
16
35
17
-
Clone source code repository
18
-
19
-
$ git clone https://github.com/ecmwf/hat.git
20
-
$ cd hat
21
-
22
-
Create and activate conda environment
23
-
24
-
$ conda create -n hat python=3.10
25
-
$ conda activate hat
26
-
27
-
For default installation, run
28
-
29
-
$ pip install .
30
-
31
-
For a developer installation (includes linting and test libraries), run
32
-
33
-
$ pip install -e .[dev]
34
-
$ pre-commit install
35
-
36
-
If you only plan to run the tests, instead run
37
-
38
-
$ pip install -e .[test]
39
-
40
-
If you plan to build a source and a wheel distribution, it is additionally required to run
41
-
42
-
$ pip install build
36
+
For a default installation, run
43
37
44
-
### Usage
38
+
```
39
+
pip install hydro-analysis-toolkit
40
+
```
45
41
46
-
Run a command line tool
42
+
For a developer setup, run
47
43
48
-
$ hat-extract-timeseries --help
44
+
```
45
+
conda create -n hat python=3.12
46
+
conda activate hat
47
+
git clone https://github.com/ecmwf/hat.git
48
+
cd hat
49
+
pip install -e .[dev]
50
+
pre-commit install
51
+
```
49
52
50
-
### Running the tests
53
+
##Licence
51
54
52
-
Tests are stored in the `tests/` folder and can be run with
53
-
54
-
$ pytest
55
-
56
-
### Deployment
57
-
58
-
To build a source and a wheel distribution, run
59
-
60
-
$ python build
61
-
62
-
### Contributing
63
-
64
-
The main repository is hosted on [GitHub](https://github.com/ecmwf/hat). Testing, bug reports and contributions are highly welcomed and appreciated.
65
-
66
-
Please report [bug](https://github.com/ecmwf/hat/issues) reports or [pull-requests](https://github.com/ecmwf/hat/pulls) on [GitHub](https://github.com/ecmwf/hat).
67
-
68
-
We want your feedback, please e-mail: user-services@ecmwf.int
69
-
70
-
### License
71
-
72
-
Copyright 2023 European Centre for Medium-Range Weather Forecasts (ECMWF)
55
+
```
56
+
Copyright 2023, European Centre for Medium Range Weather Forecasts.
73
57
74
58
Licensed under the Apache License, Version 2.0 (the "License");
75
59
you may not use this file except in compliance with the License.
@@ -84,10 +68,6 @@ See the License for the specific language governing permissions and
84
68
limitations under the License.
85
69
86
70
In applying this licence, ECMWF does not waive the privileges and immunities
87
-
granted to it by virtue of its status as an intergovernmental organisation nor
88
-
does it submit to any jurisdiction.
89
-
90
-
91
-
### Citing
92
-
93
-
In publications, please use a link to this repository (https://github.com/ecmwf/hat) and its documentation (https://hydro-analysis-toolkit.readthedocs.io)
71
+
granted to it by virtue of its status as an intergovernmental organisation
Copy file name to clipboardExpand all lines: docs/station_mapping.md
+11-11Lines changed: 11 additions & 11 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,9 +5,9 @@
5
5
The `station_mapping` library is designed for mapping the location of hydrological station data onto the optimum location of a hydrological model grid (netcdf).
6
6
This tool is available as both [command line](#station-mapping-with-command-line) and [Python API](#station-mapping-as-python-script-eg-called-within-jupyter-notebook-or-python-file)
7
7
8
-
The optimum grid cell location is searched through optimising the upstream area error and the cell distance(s) from the station nearest grid cells. In this tool, users can define their <b>acceptable area difference/ error</b> using the parameter `max_area_difference` (%) and <b>the maximum cell radius</b> parameter: `max_neighboring_cell` (number of cells) to search for this optimum grid. The tool can also be parameterised to ignore further searching of optimum cells when upstream area difference of a station nearest grid is below, i.e. when the uspteam area of the nearest cell to the station is already deemed acceptable by defining `min_area_diff`(%).
8
+
The optimum grid cell location is searched through optimising the upstream area error and the cell distance(s) from the station nearest grid cells. In this tool, users can define their <b>acceptable area difference/ error</b> using the parameter `max_area_difference` (%) and <b>the maximum cell radius</b> parameter: `max_neighboring_cell` (number of cells) to search for this optimum grid. The tool can also be parameterised to ignore further searching of optimum cells when upstream area difference of a station nearest grid is below, i.e. when the uspteam area of the nearest cell to the station is already deemed acceptable by defining `min_area_diff`(%).
9
9
10
-
For instance, refer to illustration example below, if the specified `max_area_difference` is 10%, then the optimum grid to be returned when specified `max_neighboring_cell` = 1 cell, is the one with 7% upstream area difference (blue). While if the `max_neighboring_cell` = 2 cell, then the cell with 5% upstream area difference will be returned as the optimum grid instead.
10
+
For instance, refer to illustration example below, if the specified `max_area_difference` is 10%, then the optimum grid to be returned when specified `max_neighboring_cell` = 1 cell, is the one with 7% upstream area difference (blue). While if the `max_neighboring_cell` = 2 cell, then the cell with 5% upstream area difference will be returned as the optimum grid instead.
11
11
12
12
<imgsrc="station_mapping_search_algo.svg"alt="illustration of optimum grid search algorithm"width="450"/>
13
13
@@ -21,11 +21,11 @@ To use the `station_mapping` as command line, follow these steps:
21
21
22
22
1. Prepare your data input: station data and grid data in the appropriate format. Station data should be in a CSV file, and grid data should be in a NetCDF file.
23
23
PLease ensure all lattitudes and longitude values in [<b> decimal degree format/ DD</b>](https://en.wikipedia.org/wiki/Decimal_degrees).
24
-
24
+
25
25
2. Create a [JSON configuration](https://github.com/ecmwf/hat/tree/main/notebooks/examples/station_mapping_config_example.json) file specifying the paths to your data files, column names, and other relevant parameters.
26
-
26
+
27
27
3. Run the `station_mapping.py` script with the path to your configuration file:
28
-
28
+
29
29
`./station_mapping.py path/to/your/config.json`
30
30
31
31
@@ -48,7 +48,7 @@ config = {
48
48
"csv_ups_col": "DrainingArea.km2.Provider", # column name for metadata of upstream (string)
49
49
50
50
# Mapping parameters (3x)
51
-
"max_neighboring_cells": 5, # Parameter 1: maximum radius to search for best cells (no. of cells)
51
+
"max_neighboring_cells": 5, # Parameter 1: maximum radius to search for best cells (no. of cells)
"min_area_diff": 0, # Parameter 3: minimum upstream area difference (%) between nearest grid and the station metadata
54
54
@@ -59,15 +59,15 @@ config = {
59
59
60
60
# if Output directory is provided, it will save the geodataframe outputs to geojson and csv readable by GIS or jupyter interactive
61
61
# "out_directory": None # put none if you don't want to save the output
62
-
"out_directory": "output"
62
+
"out_directory": "output"
63
63
}
64
64
```
65
65
3. Run the `station_mapping` function with the config dictionary input and store result as dataframe (df)
66
66
Since in the above example, the out_directory is not empty/ None, i.e. hence geojson and csv output of the station mapping tool will be saved in the specified directory.
67
67
68
68
```
69
-
# import station mapping
70
-
from hat.mapping.station_mapping import station_mapping
69
+
# import station mapping
70
+
from hat.mapping.station_mapping import station_mapping
71
71
# call station_mapping function and apply on the created config dictionary
72
72
df = station_mapping(config)
73
73
```
@@ -87,7 +87,7 @@ Outputs
87
87
------
88
88
89
89
The following elements (column) will be written as dataframe as the expected `station_mapping` output.
90
-
Note: `_lat` and `_lon` refer to the actual lattitude and longitude of the location, while `_lat_idx` and `_lon_idx` refer to the lat and lon grid ID.
90
+
Note: `_lat` and `_lon` refer to the actual lattitude and longitude of the location, while `_lat_idx` and `_lon_idx` refer to the lat and lon grid ID.
0 commit comments