tj-hyd-tank


Nametj-hyd-tank JSON
Version 1.3.0 PyPI version JSON
download
home_pageNone
SummaryPython implementation of Tank Hydrological model by Sugawara and Funiyuki (1956)
upload_time2024-09-09 08:08:13
maintainerNone
docs_urlNone
authorDuy Nguyen
requires_python<4.0,>=3.9
licenseNone
keywords
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # TJ_HYD_TANK
![PyPI - Version](https://img.shields.io/pypi/v/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![PyPI - Version](https://img.shields.io/pypi/v/tj-hyd-tank)\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"
}
        
Elapsed time: 0.38087s