Skip to main content

TJ_HYD_TANK

PyPI - Version

Python implementation of the Tank Hydrological model by Sugawara and Funiyuki (1956), based on the original code from tank-model by hckaraman.

Installation

To install the package, run:

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

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

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

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

outlet1 = tank.get_basin_def_by_name('Outlet1')
if outlet1 is not None:
    tank.show_discharge(outlet1)

Reconfiguring and Displaying Subbasin Properties

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

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

outlet1_df = tank.to_dataframe(outlet1)
outlet1_df

Viewing Logs

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.

Metadata

Release files for tj-hyd-tank 1.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for tj-hyd-tank 1.3.0
File Size Uploaded Provenance Actions
tj_hyd_tank-1.3.0.tar.gz 10.4 kB Without provenance Details for tj_hyd_tank-1.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for tj-hyd-tank 1.3.0
File Interpreter ABI Platform Actions
tj_hyd_tank-1.3.0-py3-none-any.whl Python 3 none any Details for tj_hyd_tank-1.3.0-py3-none-any.whl

Total release size: 20.8 kB

Release files / tj_hyd_tank-1.3.0.tar.gz

Download URL tj_hyd_tank-1.3.0.tar.gz
Size 10.4 kB
Tags Source
SHA-256 checksum
How to use checksums
115cb1798de4fcdf9e7cf2926277944277f3965dee5e3e0fd0c2812682d25f95
BLAKE2b-256 checksum
How to use checksums
0366dabc2ea3427751a669b7bdfd57a2a88e0455d976c9bebb40fb161d537479
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via poetry/1.8.3 CPython/3.12.3 Linux/6.8.0-41-generic

Release files / tj_hyd_tank-1.3.0-py3-none-any.whl

Download URL tj_hyd_tank-1.3.0-py3-none-any.whl
Size 10.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
7fecc11e645b42d5e5edee36f8b5699bae62577a4ca5c5cf8eab021f22f77dce
BLAKE2b-256 checksum
How to use checksums
b754dd424a6400e9d14701daca2142a86e9241b3a70f9e771cfffe6c086645e1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via poetry/1.8.3 CPython/3.12.3 Linux/6.8.0-41-generic

Security for tj-hyd-tank 1.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page