| Name | tj-hyd-tank JSON |
| Version |
1.3.0
JSON |
| download |
| home_page | None |
| Summary | Python implementation of Tank Hydrological model by Sugawara and Funiyuki (1956) |
| upload_time | 2024-09-09 08:08:13 |
| maintainer | None |
| docs_url | None |
| author | Duy Nguyen |
| requires_python | <4.0,>=3.9 |
| license | None |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# TJ_HYD_TANK
**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 [hckaraman](https://github.com/nzahasan).**
## Installation
To install the package, run:
```bash
pip install tj_hyd_tank
```
## Getting Started
### Prepare the Dataset
#### Dataset Requirements
Your dataset should contain the following columns: **Date**, **Precipitation**, **Evapotranspiration**, and **Discharge
**. The column names are customizable.
Example:
| Date | Q | P | E |
|------------|---------|-----|------|
| 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 |
| ... | ... | ... | ... |
Ensure the time intervals between dates are consistent (e.g., 24 hours) for accurate model performance.
#### Basin File
Use a HEC-HMS basin file.
### Quick Start
```python
import pandas as pd
from tj_hyd_tank import TJHydTANK, TANKColNames, TANKConfig
df = pd.read_csv('assets/data_example.csv')
tank_cols_name = TANKColNames(
date='Date',
precipitation='P',
evapotranspiration='E',
discharge='Q'
)
tank_config = TANKConfig(
start_date=None,
end_date=None,
interval=24.0
)
tank = TJHydTANK(
basin_file='assets/CedarCreek.basin',
df=df,
tank_col_names=tank_cols_name,
tank_config=tank_config
)
```
### Accessing Basin Definitions
```python
from tj_hyd_tank import Subbasin, Reach
for basin_def in tank.basin_defs:
print(basin_def.name, basin_def.type)
print(basin_def.stats)
if isinstance(basin_def, (Subbasin, Reach)):
print(basin_def.params)
```
### Accessing Root Nodes
```python
from tj_hyd_tank import Subbasin, Reach
for root_node in tank.root_node:
print(root_node.name, root_node.type)
print(root_node.stats)
if isinstance(root_node, (Subbasin, Reach)):
print(root_node.params)
```
### Plotting Q_obs vs Q_sim for a Basin Definition
```python
outlet1 = tank.get_basin_def_by_name('Outlet1')
if outlet1 is not None:
tank.show_discharge(outlet1)
```
### Reconfiguring and Displaying Subbasin Properties
```python
from tj_hyd_tank import SubbasinParams
w170 = tank.get_basin_def_by_name('W170')
if w170 is not None:
if isinstance(w170, Subbasin):
tank.reconfig_subbasin_params(
w170,
SubbasinParams(
t0_is=0.02,
t0_soc_uo=80.0
)
)
print('Q_tank_0', w170.Q_tank_0.tolist())
print('Q_tank_1', w170.Q_tank_1.tolist())
print('Q_tank_2', w170.Q_tank_2.tolist())
print('Q_tank_3', w170.Q_tank_3.tolist())
print('bottom_outlet_flow_tank_0', w170.bottom_outlet_flow_tank_0.tolist())
print('bottom_outlet_flow_tank_1', w170.bottom_outlet_flow_tank_1.tolist())
print('bottom_outlet_flow_tank_2', w170.bottom_outlet_flow_tank_2.tolist())
```
### Reconfiguring the TANK Model
```python
tank.reconfig_tank(
TANKConfig(
start_date=pd.to_datetime('09/10/2016', dayfirst=True, utc=True),
end_date=pd.to_datetime('20/10/2016', dayfirst=True, utc=True)
)
)
```
### Exporting Data to DataFrame
```python
outlet1_df = tank.to_dataframe(outlet1)
outlet1_df
```
### Viewing Logs
```python
print(tank.logs)
```
## BasinDef Subclass
### `Subbasin`
- Params: `SubbasinParams`
### `Junction`
- Params: `BasinDefParams`
### `Sink`
- Params: `BasinDefParams`
### `Reach`
- Params: `ReachParams`
## Exception Classes
### `InvalidBasinFileException`
Raised when a basin file is invalid, possibly due to incorrect format or corrupted data.
### `FileNotFoundException`
Raised when a specified file cannot be located. The missing file's name is included for easy identification.
### `MissingColumnsException`
Raised when required columns are missing from the dataset. The exception specifies which column is absent.
### `ColumnContainsEmptyDataException`
Raised when a specified column contains empty data, ensuring all necessary fields are populated.
### `InvalidDatetimeException`
Raised for invalid datetime entries, such as incorrect formatting or out-of-range values.
### `InvalidDatetimeIntervalException`
Raised when the provided datetime interval is invalid, ensuring consistency in date ranges or intervals.
### `InvalidStartDateException`
Raised for invalid start dates, particularly for time-based events or ranges.
### `InvalidEndDateException`
Raised for invalid end dates, handling errors related to the conclusion of time-based events or ranges.
### `InvalidDateRangeException`
Raised when the date range is invalid, such as when the start date is after the end date. An optional message may
provide additional context.
Raw data
{
"_id": null,
"home_page": null,
"name": "tj-hyd-tank",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": null,
"keywords": null,
"author": "Duy Nguyen",
"author_email": "duynguyen02.dev@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/03/66/dabc2ea3427751a669b7bdfd57a2a88e0455d976c9bebb40fb161d537479/tj_hyd_tank-1.3.0.tar.gz",
"platform": null,
"description": "# TJ_HYD_TANK\n\n\n\n**Python 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 [hckaraman](https://github.com/nzahasan).**\n\n## Installation\n\nTo install the package, run:\n\n```bash\npip install tj_hyd_tank\n```\n\n## Getting Started\n\n### Prepare the Dataset\n\n#### Dataset Requirements\n\nYour dataset should contain the following columns: **Date**, **Precipitation**, **Evapotranspiration**, and **Discharge\n**. The column names are customizable.\n\nExample:\n\n| Date | Q | P | E |\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\nEnsure the time intervals between dates are consistent (e.g., 24 hours) for accurate model performance.\n\n#### Basin File\n\nUse a HEC-HMS basin file.\n\n### Quick Start\n\n```python\nimport pandas as pd\nfrom tj_hyd_tank import TJHydTANK, TANKColNames, TANKConfig\n\ndf = pd.read_csv('assets/data_example.csv')\ntank_cols_name = TANKColNames(\n date='Date',\n precipitation='P',\n evapotranspiration='E',\n discharge='Q'\n)\ntank_config = TANKConfig(\n start_date=None,\n end_date=None,\n interval=24.0\n)\n\ntank = TJHydTANK(\n basin_file='assets/CedarCreek.basin',\n df=df,\n tank_col_names=tank_cols_name,\n tank_config=tank_config\n)\n```\n\n### Accessing Basin Definitions\n\n```python\nfrom tj_hyd_tank import Subbasin, Reach\n\nfor basin_def in tank.basin_defs:\n print(basin_def.name, basin_def.type)\n print(basin_def.stats)\n if isinstance(basin_def, (Subbasin, Reach)):\n print(basin_def.params)\n```\n\n### Accessing Root Nodes\n\n```python\nfrom tj_hyd_tank import Subbasin, Reach\n\nfor root_node in tank.root_node:\n print(root_node.name, root_node.type)\n print(root_node.stats)\n if isinstance(root_node, (Subbasin, Reach)):\n print(root_node.params)\n```\n\n### Plotting Q_obs vs Q_sim for a Basin Definition\n\n```python\noutlet1 = tank.get_basin_def_by_name('Outlet1')\nif outlet1 is not None:\n tank.show_discharge(outlet1)\n```\n\n### Reconfiguring and Displaying Subbasin Properties\n\n```python\nfrom tj_hyd_tank import SubbasinParams\n\nw170 = tank.get_basin_def_by_name('W170')\nif w170 is not None:\n if isinstance(w170, Subbasin):\n tank.reconfig_subbasin_params(\n w170,\n SubbasinParams(\n t0_is=0.02,\n t0_soc_uo=80.0\n )\n )\n print('Q_tank_0', w170.Q_tank_0.tolist())\n print('Q_tank_1', w170.Q_tank_1.tolist())\n print('Q_tank_2', w170.Q_tank_2.tolist())\n print('Q_tank_3', w170.Q_tank_3.tolist())\n print('bottom_outlet_flow_tank_0', w170.bottom_outlet_flow_tank_0.tolist())\n print('bottom_outlet_flow_tank_1', w170.bottom_outlet_flow_tank_1.tolist())\n print('bottom_outlet_flow_tank_2', w170.bottom_outlet_flow_tank_2.tolist())\n```\n\n### Reconfiguring the TANK Model\n\n```python\ntank.reconfig_tank(\n TANKConfig(\n start_date=pd.to_datetime('09/10/2016', dayfirst=True, utc=True),\n end_date=pd.to_datetime('20/10/2016', dayfirst=True, utc=True)\n )\n)\n```\n\n### Exporting Data to DataFrame\n\n```python\noutlet1_df = tank.to_dataframe(outlet1)\noutlet1_df\n```\n\n### Viewing Logs\n\n```python\nprint(tank.logs)\n```\n\n## BasinDef Subclass\n\n### `Subbasin`\n\n- Params: `SubbasinParams`\n\n### `Junction`\n\n- Params: `BasinDefParams`\n\n### `Sink`\n\n- Params: `BasinDefParams`\n\n### `Reach`\n\n- Params: `ReachParams`\n\n## Exception Classes\n\n### `InvalidBasinFileException`\n\nRaised when a basin file is invalid, possibly due to incorrect format or corrupted data.\n\n### `FileNotFoundException`\n\nRaised when a specified file cannot be located. The missing file's name is included for easy identification.\n\n### `MissingColumnsException`\n\nRaised when required columns are missing from the dataset. The exception specifies which column is absent.\n\n### `ColumnContainsEmptyDataException`\n\nRaised when a specified column contains empty data, ensuring all necessary fields are populated.\n\n### `InvalidDatetimeException`\n\nRaised for invalid datetime entries, such as incorrect formatting or out-of-range values.\n\n### `InvalidDatetimeIntervalException`\n\nRaised when the provided datetime interval is invalid, ensuring consistency in date ranges or intervals.\n\n### `InvalidStartDateException`\n\nRaised for invalid start dates, particularly for time-based events or ranges.\n\n### `InvalidEndDateException`\n\nRaised for invalid end dates, handling errors related to the conclusion of time-based events or ranges.\n\n### `InvalidDateRangeException`\n\nRaised when the date range is invalid, such as when the start date is after the end date. An optional message may\nprovide additional context.\n",
"bugtrack_url": null,
"license": null,
"summary": "Python implementation of Tank Hydrological model by Sugawara and Funiyuki (1956)",
"version": "1.3.0",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b754dd424a6400e9d14701daca2142a86e9241b3a70f9e771cfffe6c086645e1",
"md5": "dc226af5d96fe62e368bcf54e6100bae",
"sha256": "7fecc11e645b42d5e5edee36f8b5699bae62577a4ca5c5cf8eab021f22f77dce"
},
"downloads": -1,
"filename": "tj_hyd_tank-1.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "dc226af5d96fe62e368bcf54e6100bae",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 10368,
"upload_time": "2024-09-09T08:08:12",
"upload_time_iso_8601": "2024-09-09T08:08:12.533929Z",
"url": "https://files.pythonhosted.org/packages/b7/54/dd424a6400e9d14701daca2142a86e9241b3a70f9e771cfffe6c086645e1/tj_hyd_tank-1.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0366dabc2ea3427751a669b7bdfd57a2a88e0455d976c9bebb40fb161d537479",
"md5": "b7ee96bb1d3baf849810e5034b9ea97d",
"sha256": "115cb1798de4fcdf9e7cf2926277944277f3965dee5e3e0fd0c2812682d25f95"
},
"downloads": -1,
"filename": "tj_hyd_tank-1.3.0.tar.gz",
"has_sig": false,
"md5_digest": "b7ee96bb1d3baf849810e5034b9ea97d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 10396,
"upload_time": "2024-09-09T08:08:13",
"upload_time_iso_8601": "2024-09-09T08:08:13.901742Z",
"url": "https://files.pythonhosted.org/packages/03/66/dabc2ea3427751a669b7bdfd57a2a88e0455d976c9bebb40fb161d537479/tj_hyd_tank-1.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-09 08:08:13",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "tj-hyd-tank"
}
