tj-hyd-nam 1.1.0

Python implementation of NedborAfstromnings Model (NAM) lumped rainfall–runoff model

TJ_HYD_NAM

Python implementation of NedborAfstromnings Model (NAM) lumped rainfall–runoff model, based on the original code from NAM_Model by hckaraman

Installation

pip install tj_hyd_nam

Getting Started

Prepare the Dataset

The dataset should include columns: Date, Temperature, Precipitation, Evapotranspiration, and Discharge, with column names customizable.

Date	Temp	Q	P	E
10/9/2016	15.4	0.25694	0	2.79
10/10/2016	14.4	0.25812	0	3.46
10/11/2016	14.9	0.30983	0	3.65
10/12/2016	16.1	0.31422	0	3.46
10/13/2016	20.1	0.30866	0	5.64
10/14/2016	13.9	0.30868	0	3.24
10/15/2016	11.1	0.31299	0	3.41
...	...	...	...	...

The time intervals between dates must be equal (e.g., 24 hours) for the model to function accurately.

Initialize the NAM Model

import pandas as pd
from tj_hyd_nam import TJHydNAM, NAMColNames, NAMConfig

# Load the dataset
df = pd.read_csv('data_example.csv')
# Specify the column names as required
nam_col_names = NAMColNames(
    date='Date',
    temperature='Temp',
    precipitation='P',
    evapotranspiration='E',
    discharge='Q'
)
# Configure the model parameters
nam_config = NAMConfig(
    area=58.8,
    start_date=None,
    end_date=None,
    interval=24.0,
    spin_off=0.0,
    umax=0.97,
    lmax=721.56,
    cqof=0.18,
    ckif=495.91,
    ck12=25.16,
    tof=0.97,
    tif=0.11,
    tg=0.19,
    ckbf=1121.74,
    csnow=2.31,
    snowtemp=3.51,
)
NAM = TJHydNAM(
    dataset=df,
    nam_col_names=nam_col_names,
    nam_config=nam_config
)
print(NAM)

The output will detail the NAM model based on the loaded dataset:

TJ_HYD_NAM 🍃 🌧 ☔ 💦
FROM: 2016-10-09 00:00:00+00:00
TO: 2018-09-30 00:00:00+00:00
NAMConfig(area=58.8, start_date=None, end_date=None, flow_rate=0.6805555555555555, interval=24.0, spin_off=0.0, umax=0.97, lmax=721.56, cqof=0.18, ckif=495.91, ck12=25.16, tof=0.97, tif=0.11, tg=0.19, ckbf=1121.74, csnow=2.31, snowtemp=3.51)
NAMStatistic(nse=-0.17835445482281131, rmse=1.7864602332317054, fbias=75.23828249740461)

Display and Save Graphs

# Plot and save the discharge comparison graph
NAM.show_discharge(save=True, filename='discharge.png')
# Plot and save all calculated model information
NAM.show(save=True, filename='result.png')

Optimize the Model

NAM.optimize()
print(NAM)

Optimization terminated successfully    (Exit mode 0)
            Current function value: 2.036882878807083
            Iterations: 7
            Function evaluations: 70
            Gradient evaluations: 7
TJ_HYD_NAM 🍃 🌧 ☔ 💦
FROM: 2016-10-09 00:00:00+00:00
TO: 2018-09-30 00:00:00+00:00
NAMConfig(area=58.8, start_date=None, end_date=None, flow_rate=0.6805555555555555, interval=24.0, spin_off=0.0, umax=0.97, lmax=721.56, cqof=0.18, ckif=495.91, ck12=25.16, tof=0.97, tif=0.11, tg=0.19, ckbf=1121.74, csnow=2.31, snowtemp=3.51)
NAMStatistic(nse=-0.5318680456177058, rmse=2.036882878807083, fbias=91.77841692580132)

Reconfigure the Model Based on Properties

The model parameters will change and be recalculated based on new properties.

NAM.re_config_by_props(
    start_date=pd.to_datetime('09/10/2016', dayfirst=True, utc=True),
    end_date=pd.to_datetime('20/10/2016', dayfirst=True, utc=True)
)

Reconfigure All Parameters

NAM.re_config(
    NAMConfig(
        area=60,
        start_date=None,
        end_date=None,
        interval=24.0,
        spin_off=0.0,
        umax=0.8,
        lmax=719.56,
        cqof=0.14,
        ckif=493.86,
        ck12=45.16,
        tof=0.97,
        tif=0.45,
        tg=0.19,
        ckbf=1121.74,
        csnow=2.31,
        snowtemp=3.51,
    )
)

Save Calculated Model Data

NAM.save_to_csv('result.csv')

Convert Calculated Data to DataFrame

nam_df = NAM.to_dataframe()

Save the Model

NAM.save('nam_model')

Load a Saved Model

SAVED_NAM = NAM.load('nam_model.tjnam')

Use the Previous Model's Configuration for Prediction

PRED_NAM = TJHydNAM(
    pd.read_csv('future_data.csv'),
    NAMColNames(
        date='Date',
        temperature='Temp',
        precipitation='P',
        evapotranspiration='E',
        discharge='Q'
    ),
    SAVED_NAM.config
)

Accessing calculated variables (>=1.1.0)

NAM.size       # Access the value of _size
NAM.date       # Access the value of _date
NAM.T          # Access the value of _T (temperature series)
NAM.P          # Access the value of _P (precipitation series)
NAM.E          # Access the value of _E (evaporation series)
NAM.Q_obs      # Access the value of _Q_obs (observed discharge)
NAM.U_soil     # Access the value of _U_soil (upper soil layer moisture)
NAM.S_snow     # Access the value of _S_snow (snow storage)
NAM.Q_snow     # Access the value of _Q_snow (snowmelt discharge)
NAM.Q_inter    # Access the value of _Q_inter (interflow discharge)
NAM.E_eal      # Access the value of _E_eal (actual evapotranspiration)
NAM.Q_of       # Access the value of _Q_of (overland flow)
NAM.Q_g        # Access the value of _Q_g (groundwater discharge)
NAM.Q_bf       # Access the value of _Q_bf (baseflow)
NAM.Q_sim      # Access the value of _Q_sim (simulator discharge)
NAM.L_soil     # Access the value of _L_soil (soil moisture)