| Name | hydtank JSON |
| Version |
1.0.1
JSON |
| download |
| home_page | https://github.com/duynguyen02/HydTANK |
| Summary | Python implementation of Tank Hydrological model by Sugawara and Funiyuki (1956). |
| upload_time | 2024-11-30 13:50:49 |
| maintainer | None |
| docs_url | None |
| author | Duy Nguyen |
| requires_python | <4.0,>=3.10 |
| license | MIT |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# HydTANK
Python implementation of the Tank Hydrological model by Sugawara and Funiyuki (1956), based on the original code
from [tank-model](https://github.com/nzahasan/tank-model) by [nzahasan](https://github.com/nzahasan).
## Installation
```bash
pip install hydtank
```
## Getting Started
### 1. Prepare the Dataset
The dataset must include the following columns: Date, Precipitation, Evapotranspiration, and Discharge. Additionally,
ensure that:
- The time intervals between dates are consistent (e.g., 24 hours) for accurate model performance.
Example dataset:
| Date | Discharge | Precipitation | Evapotranspiration |
|------------|-----------|---------------|--------------------|
| 10/9/2016 | 0.25694 | 0 | 2.79 |
| 10/10/2016 | 0.25812 | 0 | 3.46 |
| 10/11/2016 | 0.30983 | 0 | 3.65 |
| 10/12/2016 | 0.31422 | 0 | 3.46 |
| 10/13/2016 | 0.30866 | 0 | 5.64 |
| 10/14/2016 | 0.30868 | 0 | 3.24 |
| 10/15/2016 | 0.31299 | 0 | 3.41 |
| ... | ... | ... | ... |
### 2. Prepare the HEC-HMS Basin File
In addition to the dataset, ensure you have the required HEC-HMS basin file. This file contains the hydrological and
geographical configuration needed for the TANK model.
### 3. Initialize the Model
#### 3.1 Directly from a dataset file and a basin file:
```python
from hydtank import build_hydtank
with open('data.csv') as file1, open('NuiLe_GiaUi.basin') as file2:
tank = build_hydtank(
dataset_content=file1.read(),
basin_content=file2.read(),
interval=24.0,
start=None,
end=None
)
```
#### 3.2 From a `Dataset` and a basin file:
```python
import pandas as pd
from hydtank import build_hydtank_from_dataset, Dataset, TIME_SERIES, PRECIPITATION, EVAPOTRANSPIRATION, DISCHARGE
df = pd.read_csv('data.csv')
_dataset = Dataset(
time_series=df[TIME_SERIES].tolist(),
precipitation=df[PRECIPITATION].tolist(),
evapotranspiration=df[EVAPOTRANSPIRATION].tolist(),
discharge=df[DISCHARGE].tolist(),
)
tank = build_hydtank_from_dataset(
basin_content=open('NuiLe_GiaUi.basin').read(),
_dataset=_dataset,
interval=24.0,
start=None,
end=None
)
```
#### 3.3 From an existing model:
```python
from hydtank import build_hydtank, HydTANK
with open('data.csv') as file1, open('NuiLe_GiaUi.basin') as file2:
tank = build_hydtank(
file1.read(),
file2.read()
)
# Avoid using the original model directly!
# Always make a copy before creating a new model
tank_copy = tank.copy()
tank2 = HydTANK(
tank_copy.dataset,
tank_copy.basin_defs,
tank_copy.root_node,
tank_copy.interval,
tank_copy.start,
tank_copy.end
)
```
### 4. Retrieve `BasinDef` Information by Name
```python
from hydtank.bsd_junction import Junction
from hydtank.bsd_reach import Reach
from hydtank.bsd_sink import Sink
from hydtank.bsd_subbasin import Subbasin
...
try:
nui_le: Subbasin = tank.get_basin_def_by_name('NuiLe')
giaui_local: Subbasin = tank.get_basin_def_by_name('GiaUi_Local')
reach1: Reach = tank.get_basin_def_by_name('Reach1')
junction1: Junction = tank.get_basin_def_by_name('Junction1')
sink: Sink = tank.get_basin_def_by_name('Sink1')
except ValueError:
# BasinDef not found
pass
```
### 5. Plotting
```python
tank.plot_basin_network().save('GiaUi_NuiLe_Basin_Network.png')
tank.plot_headwater_q().save('GiaUi_NuiLe_Headwater.png')
tank.plot_q().save('GiaUi_NuiLe_Qsim.png')
tank.plot_subbasin(nui_le).save('GiaUi_NuiLe_NuiLe_Subbasin.png')
tank.plot_subbasin(giaui_local).save('GiaUi_NuiLe_GiaUiLocal_Subbasin.png')
```
### 6. Reconfigure Parameters for a `BasinDef`
```python
from hydtank.parameters import SubbasinParameters, ReachParameters
...
params = reach1.parameters.copy()
params.k = 0.9235288521736096
tank.reconfig_parameters(reach1.name, params)
tank.reconfig_parameters(reach1.name, ReachParameters())
tank.reconfig_parameters(nui_le.name, SubbasinParameters())
```
### 7. Auto-Optimize Parameters for `Subbasin` and `Reach`
#### 7.1 Optimize Specific `Subbasin` and `Reach`
```python
tank.optimize([nui_le, reach1, giaui_local])
```
#### 7.2 Optimize All
**Note:** This process can take significant time as it involves optimizing parameters for all `Subbasin` and `Reach`
elements in the model.
```python
tank.optimize_all()
```
### 8. Export Calculation Results as a `pandas.DataFrame`
```python
r_df = tank.to_dataframe()
```
### 9. Set a New `Dataset`
```python
df = pd.read_csv('new_data.csv')
_dataset = Dataset(
time_series=df[TIME_SERIES].tolist(),
precipitation=df[PRECIPITATION].tolist(),
evapotranspiration=df[EVAPOTRANSPIRATION].tolist(),
discharge=df[DISCHARGE].tolist(),
)
tank.reset_dataset(_dataset, interval=24.0)
```
### 10. Configure Time Range
```python
from datetime import datetime
...
tank.set_timeseries_range(start=datetime(...), end=datetime(...))
```
## License
This library is released under the MIT License.
## Contact
For any questions or issues, please open an issue on [GitHub](https://github.com/duynguyen02/HydTANK/issues) or email us
at [duynguyen02.dev@gmail.com](mailto:duynguyen02.dev@gmail.com).
---
Raw data
{
"_id": null,
"home_page": "https://github.com/duynguyen02/HydTANK",
"name": "hydtank",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": null,
"author": "Duy Nguyen",
"author_email": "duynguyen02.dev@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/91/40/2bb6491ce7ddde88a7f4aab8343fa99e4cb6764a1505ed4823992b20b51f/hydtank-1.0.1.tar.gz",
"platform": null,
"description": "# HydTANK\n\n\n\nPython implementation of the Tank Hydrological model by Sugawara and Funiyuki (1956), based on the original code\nfrom [tank-model](https://github.com/nzahasan/tank-model) by [nzahasan](https://github.com/nzahasan).\n\n## Installation\n\n```bash\npip install hydtank\n```\n\n## Getting Started\n\n### 1. Prepare the Dataset\n\nThe dataset must include the following columns: Date, Precipitation, Evapotranspiration, and Discharge. Additionally,\nensure that:\n\n- The time intervals between dates are consistent (e.g., 24 hours) for accurate model performance.\n\nExample dataset:\n\n| Date | Discharge | Precipitation | Evapotranspiration |\n|------------|-----------|---------------|--------------------|\n| 10/9/2016 | 0.25694 | 0 | 2.79 |\n| 10/10/2016 | 0.25812 | 0 | 3.46 |\n| 10/11/2016 | 0.30983 | 0 | 3.65 |\n| 10/12/2016 | 0.31422 | 0 | 3.46 |\n| 10/13/2016 | 0.30866 | 0 | 5.64 |\n| 10/14/2016 | 0.30868 | 0 | 3.24 |\n| 10/15/2016 | 0.31299 | 0 | 3.41 |\n| ... | ... | ... | ... |\n\n### 2. Prepare the HEC-HMS Basin File\n\nIn addition to the dataset, ensure you have the required HEC-HMS basin file. This file contains the hydrological and\ngeographical configuration needed for the TANK model.\n\n### 3. Initialize the Model\n\n#### 3.1 Directly from a dataset file and a basin file:\n\n```python\nfrom hydtank import build_hydtank\n\nwith open('data.csv') as file1, open('NuiLe_GiaUi.basin') as file2:\n tank = build_hydtank(\n dataset_content=file1.read(),\n basin_content=file2.read(),\n interval=24.0,\n start=None,\n end=None\n )\n```\n\n#### 3.2 From a `Dataset` and a basin file:\n\n```python\nimport pandas as pd\nfrom hydtank import build_hydtank_from_dataset, Dataset, TIME_SERIES, PRECIPITATION, EVAPOTRANSPIRATION, DISCHARGE\n\ndf = pd.read_csv('data.csv')\n\n_dataset = Dataset(\n time_series=df[TIME_SERIES].tolist(),\n precipitation=df[PRECIPITATION].tolist(),\n evapotranspiration=df[EVAPOTRANSPIRATION].tolist(),\n discharge=df[DISCHARGE].tolist(),\n)\n\ntank = build_hydtank_from_dataset(\n basin_content=open('NuiLe_GiaUi.basin').read(),\n _dataset=_dataset,\n interval=24.0,\n start=None,\n end=None\n)\n```\n\n#### 3.3 From an existing model:\n\n```python\nfrom hydtank import build_hydtank, HydTANK\n\nwith open('data.csv') as file1, open('NuiLe_GiaUi.basin') as file2:\n tank = build_hydtank(\n file1.read(),\n file2.read()\n )\n\n # Avoid using the original model directly!\n # Always make a copy before creating a new model\n tank_copy = tank.copy()\n\n tank2 = HydTANK(\n tank_copy.dataset,\n tank_copy.basin_defs,\n tank_copy.root_node,\n tank_copy.interval,\n tank_copy.start,\n tank_copy.end\n )\n```\n\n### 4. Retrieve `BasinDef` Information by Name\n\n```python\nfrom hydtank.bsd_junction import Junction\nfrom hydtank.bsd_reach import Reach\nfrom hydtank.bsd_sink import Sink\nfrom hydtank.bsd_subbasin import Subbasin\n\n...\n\ntry:\n nui_le: Subbasin = tank.get_basin_def_by_name('NuiLe')\n giaui_local: Subbasin = tank.get_basin_def_by_name('GiaUi_Local')\n reach1: Reach = tank.get_basin_def_by_name('Reach1')\n junction1: Junction = tank.get_basin_def_by_name('Junction1')\n sink: Sink = tank.get_basin_def_by_name('Sink1')\nexcept ValueError:\n # BasinDef not found\n pass\n```\n\n### 5. Plotting\n\n```python\ntank.plot_basin_network().save('GiaUi_NuiLe_Basin_Network.png')\ntank.plot_headwater_q().save('GiaUi_NuiLe_Headwater.png')\ntank.plot_q().save('GiaUi_NuiLe_Qsim.png')\ntank.plot_subbasin(nui_le).save('GiaUi_NuiLe_NuiLe_Subbasin.png')\ntank.plot_subbasin(giaui_local).save('GiaUi_NuiLe_GiaUiLocal_Subbasin.png')\n```\n\n### 6. Reconfigure Parameters for a `BasinDef`\n\n```python\nfrom hydtank.parameters import SubbasinParameters, ReachParameters\n\n...\n\nparams = reach1.parameters.copy()\nparams.k = 0.9235288521736096\ntank.reconfig_parameters(reach1.name, params)\ntank.reconfig_parameters(reach1.name, ReachParameters())\n\ntank.reconfig_parameters(nui_le.name, SubbasinParameters())\n```\n\n### 7. Auto-Optimize Parameters for `Subbasin` and `Reach`\n\n#### 7.1 Optimize Specific `Subbasin` and `Reach`\n\n```python\ntank.optimize([nui_le, reach1, giaui_local])\n```\n\n#### 7.2 Optimize All\n\n**Note:** This process can take significant time as it involves optimizing parameters for all `Subbasin` and `Reach`\nelements in the model.\n\n```python\ntank.optimize_all()\n```\n\n### 8. Export Calculation Results as a `pandas.DataFrame`\n\n```python\nr_df = tank.to_dataframe()\n```\n\n### 9. Set a New `Dataset`\n\n```python\ndf = pd.read_csv('new_data.csv')\n\n_dataset = Dataset(\n time_series=df[TIME_SERIES].tolist(),\n precipitation=df[PRECIPITATION].tolist(),\n evapotranspiration=df[EVAPOTRANSPIRATION].tolist(),\n discharge=df[DISCHARGE].tolist(),\n)\n\ntank.reset_dataset(_dataset, interval=24.0)\n```\n\n### 10. Configure Time Range\n\n```python\nfrom datetime import datetime\n\n...\n\ntank.set_timeseries_range(start=datetime(...), end=datetime(...))\n```\n\n## License\n\nThis library is released under the MIT License.\n\n## Contact\n\nFor any questions or issues, please open an issue on [GitHub](https://github.com/duynguyen02/HydTANK/issues) or email us\nat [duynguyen02.dev@gmail.com](mailto:duynguyen02.dev@gmail.com).\n\n---",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python implementation of Tank Hydrological model by Sugawara and Funiyuki (1956).",
"version": "1.0.1",
"project_urls": {
"Homepage": "https://github.com/duynguyen02/HydTANK",
"Repository": "https://github.com/duynguyen02/HydTANK"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "cd00d77c450f11cd590f6a7de593dd7302f22a2b3c451b8ceb9c45f4bcfa4bd6",
"md5": "9c6da5897141c217a4404624f01717fc",
"sha256": "c6682cb7ed3109f65906db61fde75f430ba203cc58157c5463cf13714a2a2492"
},
"downloads": -1,
"filename": "hydtank-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9c6da5897141c217a4404624f01717fc",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 16319,
"upload_time": "2024-11-30T13:42:36",
"upload_time_iso_8601": "2024-11-30T13:42:36.036052Z",
"url": "https://files.pythonhosted.org/packages/cd/00/d77c450f11cd590f6a7de593dd7302f22a2b3c451b8ceb9c45f4bcfa4bd6/hydtank-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "91402bb6491ce7ddde88a7f4aab8343fa99e4cb6764a1505ed4823992b20b51f",
"md5": "4e9e5c944d31cd008ff911a035b8b487",
"sha256": "c960af26857cb8ce7a1c1d8c35bb1d3836651423c75de21bf5ee058089121df3"
},
"downloads": -1,
"filename": "hydtank-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "4e9e5c944d31cd008ff911a035b8b487",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 14157,
"upload_time": "2024-11-30T13:50:49",
"upload_time_iso_8601": "2024-11-30T13:50:49.324751Z",
"url": "https://files.pythonhosted.org/packages/91/40/2bb6491ce7ddde88a7f4aab8343fa99e4cb6764a1505ed4823992b20b51f/hydtank-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-30 13:50:49",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "duynguyen02",
"github_project": "HydTANK",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "hydtank"
}
