hydtank


Namehydtank JSON
Version 1.0.1 PyPI version JSON
download
home_pagehttps://github.com/duynguyen02/HydTANK
SummaryPython implementation of Tank Hydrological model by Sugawara and Funiyuki (1956).
upload_time2024-11-30 13:50:49
maintainerNone
docs_urlNone
authorDuy Nguyen
requires_python<4.0,>=3.10
licenseMIT
keywords
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # HydTANK

![PyPI - Version](https://img.shields.io/pypi/v/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![PyPI - Version](https://img.shields.io/pypi/v/hydtank)\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"
}
        
Elapsed time: 0.39406s