HydroCNHS package

Subpackages

Submodules

HydroCNHS.data_collector module

class HydroCNHS.data_collector.Data_collector

Bases: object

add_field(field, data_type={}, check_exist=True)

Add a field to the data collector.

fieldstr

Field name.

data_typedict, optional

Data type of the field (e.g., {} and [])., by default {}

check_existbool, optional

If Ture, check the given field name is not existed before adding, by default True

get_dict()

Get data collector in dictionary format.

dict

A dictionary contains all fields.

get_field(field)

Get field.

fieldstr

Field name.

Assigned field type.

list_fields()

Print available fields in the data collector.

HydroCNHS.hydrocnhs module

class HydroCNHS.hydrocnhs.Model(model, name=None, rn_gen=None, checked=False, parsed=False)

Bases: object

get_model_object()

Get the model object in a dictionary form.

dict

model object dictionary.

load_weather_data(temp, prec, pet=None, lsm_outlets=None)

Load temperature and precipitation data.

tempdict

[degC] Daily mean temperature time series data (value) for each subbasin named by its outlet.

precdict

[cm] Daily precipitation time series data (value) for each subbasin named by its outlet.

petdict, optional

[cm] Daily potential evapotranpiration time series data (value) for each subbasin named by its outlet, by default None

lsm_outletslist, optional

Name list of subbasins’ outlets (i.e., self.ws[“Outlets”]), by default None

run(temp, prec, pet=None, assigned_Q={}, assigned_UH={}, disable=False)

Run HydroCNHS simulation.

tempdict

[degC] Daily mean temperature.

precdict

[cm] Daily precipitation.

petdict, optional

[cm] Potential evapotranspiration, by default None. If none, pet is calculted by Hamon’s method.

assigned_Qdict, optional

[cms] If user want to manually assign Q for certain outlet {“outlet”: array}, by default {}.

assigned_UHdict, optional

If user want to manually assign UH (Lohmann) for certain outlet {“outlet”: array}, by default {}.

disablebool, optional

Disable display progress bar, by default False.

dict

A dictionary of flow time series.

HydroCNHS.indicators module

class HydroCNHS.indicators.Indicator

Bases: object

static CP(x_obv, y_sim, r_na=False)

Correlation of persistence.

x_obvarray

Observation data.

y_simarray

Simulation data.

r_nabool, optional

Remove nan, by default True

float

Correlation of persistence.

static KGE(x_obv, y_sim, r_na=True)

Kling–Gupta efficiency.

x_obvarray

Observation data.

y_simarray

Simulation data.

r_nabool, optional

Remove nan, by default True

float

Kling–Gupta efficiency.

static NSE(x_obv, y_sim, r_na=False)

Nash–Sutcliffe efficiency.

x_obvarray

Observation data.

y_simarray

Simulation data.

r_nabool, optional

Remove nan, by default True

float

Nash–Sutcliffe efficiency.

static RSR(x_obv, y_sim, r_na=False)

RMSE-observations standard deviation ratio.

x_obvarray

Observation data.

y_simarray

Simulation data.

r_nabool, optional

Remove nan, by default True

float

RMSE-observations standard deviation ratio.

static cal_indicator_df(x_obv, y_sim, index_name='value', indicators_list=None, r_na=True)
static iKGE(x_obv, y_sim, r_na=True)

Inverse Kling–Gupta efficiency.

x_obvarray

Observation data.

y_simarray

Simulation data.

r_nabool, optional

Remove nan, by default True

float

Inverse Kling–Gupta efficiency.

static iNSE(x_obv, y_sim, r_na=False)

Inverse Nash–Sutcliffe efficiency.

x_obvarray

Observation data.

y_simarray

Simulation data.

r_nabool, optional

Remove nan, by default True

float

Inverse Nash–Sutcliffe efficiency.

static r(x_obv, y_sim, r_na=True)

Correlation.

x_obvarray

Observation data.

y_simarray

Simulation data.

r_nabool, optional

Remove nan, by default True

float

r coefficient.

static r2(x_obv, y_sim, r_na=True)

Coefficient of determination.

x_obvarray

Observation data.

y_simarray

Simulation data.

r_nabool, optional

Remove nan, by default True

float

r2 coefficient.

static remove_na(x_obv, y_sim)

Remove nan in x_obv and y_sim.

This function makes sure there is no nan involves in the indicator calculation. If nan is detected, data points will be remove from x_obv and y_sim simultaneously.

x_obvarray

Observation data.

y_simarray

Simulation data.

tuple

Updated (x_obv, y_sim)

static rmse(x_obv, y_sim, r_na=False)

Root mean square error.

x_obvarray

Observation data.

y_simarray

Simulation data.

r_nabool, optional

Remove nan, by default True

float

Root mean square error.

HydroCNHS.model_builder module

class HydroCNHS.model_builder.ModelBuilder(wd)

Bases: object

help()
print_model()
set_ABM(abm_module_path='')

Setup ABM if it is a coupled model.

Please manually setup the rest of ABM setting by editing .yaml file directly following our tutorial. Note ABM is not required if the model is not a coupled model.

set_lsm(outlet_list, lsm_model='GWLF')

Setup LSM.

outlet_listlist

List of outlet names.

lsm_modelstr, optional

“GWLF” or “ABCD”, by default “GWLF”

set_routing_outlet(routing_outlet, upstream_outlet_list, instream_outlets=[])

Setup routing outlet one by one.

routing_outletstr

Name of routing outlet. routing_outlet should be one of outlets in LSM.

upstream_outlet_listlist

A list of outlets or dam agents that contribute to the streamflow at routing_outlet.

instream_outletslist, optional

A list of instream outlets’ names (i.e., dam agents), by default [].

set_water_system(start_date, end_date)

Setup WaterSystem.

start_datestr

“yyyy/mm/dd”

end_datestr

“yyyy/mm/dd”

write_model_to_yaml(filename)

HydroCNHS.routing module

HydroCNHS.routing.form_UH_Lohmann(inputs, routing_pars, force_ingrid_off=False)

Derive HRU’s UH at the (watershed) outlet.

inputsdict

Inputs dictionary containing FlowLength [m] Travel distence of flow between two outlets [float] and InstreamControl [bool].

routing_parsdict

Four parameters for routing: GShape, GScale, Velo, Diff [float]

force_ingrid_offbool, optional

If True, then within subbasin routing will be forced to turn off, by default False.

HydroCNHS.routing.run_step_Lohmann(routing_outlet, routing, UH_Lohmann, Q, Q_LSM, t)

Calculate a single time step routing for a given routing_outlet at time t.

routing_outletstr

routing outlet.

routingdict

Routing setting dictionary from model.yaml file.

UH_Lohmanndict

A dictionary containing pre-formed UHs.

Qdict

A dictionary containing newest routed flows.

Q_LSMdict

A dictionary containing newest unrouted flows without.

tint

Index of current time step [day].

float

Routed flow of routing_outlet at time t.

HydroCNHS.routing.run_step_Lohmann_convey(routing_outlet, routing, UH_Lohmann_convey, Q_convey, t)

Calculate a single time step conveying water routing for a given routing_outlet at time t.

routing_outletstr

routing outlet.

routingdict

Routing setting dictionary from model.yaml file.

UH_Lohmann_conveydict

A dictionary containing pre-formed conveying UHs (i.e., no within subbasin routing).

Q_conveydict

A dictionary containing conveying water.

tint

Index of current time step [day].

float

Routed conveying flow of routing_outlet at time t.

HydroCNHS.util module

HydroCNHS.util.check_LSM(model_dict)
HydroCNHS.util.check_WS(model_dict)
HydroCNHS.util.check_agent_in_routing(model_dict)
HydroCNHS.util.check_model(model_dict)

Check the model dictionary

model_dictdict

Model dictionary

bool

True if pass the check.

HydroCNHS.util.create_rn_gen(seed)

Create random number generator based on numpy module.

seedint

Random seed.

object

Random number generator.

HydroCNHS.util.default_config()

Return HydroCNHS to default system configuration.

HydroCNHS.util.dict_to_string(dictionary, indentor='  ')

Ture a dictionary into a printable string.

dictionarydict

A dictionary.

indentorstr, optional

Indentor, by default ” “

str

String.

HydroCNHS.util.form_sim_seq(node_list, back_tracking_dict)
HydroCNHS.util.load_customized_module_to_class(Class, module_name, path)

Load classes and functions in a user defined module (.py) into a given Class.

Classclass

A class to collect classes and functions in a given module.

module_namestr

filename.py or filename.

pathstr

Directory of filename.py.

HydroCNHS.util.load_df_to_model_dict(model_dict, df, section, key)

Load dataframe to model dictionary.

Note that the column and index names have to be identical as outputted from write_model_to_df() function.

model_dictdict

Model dictionary.

dfDataFrame

Dataframe.

sectionstr

LSM or Routing or ABM.

keystr

nputs or Pars or Attributes.

dict

Updated model_dict.

HydroCNHS.util.load_model(model, checked=False, parsed=False, print_summary=True)

Load model.yaml or model dictionary.

modelstr/dict

Filename (e.g., model.yaml) or model dictionary.

checkedbool, optional

If True, no pre-check will be implemented, by default False.

parsedbool, optional

If True, model will not be re-parses, by default False.

print_summarybool, optional

Print the summary of loaded model, by default True.

dict

Model dictionary.

HydroCNHS.util.load_system_config()

Load HydroCNHS Config.yaml.

Config.yaml is located at package installed directory.

dict

HydroCNHS system configuration dictionary.

HydroCNHS.util.parse_model(model_dict, print_summary=True)

Parse model dictionary. Populate SystemParsedData.

Args:

model_dict (dict): Load from model.yaml.

Returns:

dict: model_dict

HydroCNHS.util.parse_sim_seq(model_dict, print_summary=True)
HydroCNHS.util.update_sim_seq_with_group(sim_seq, group, back_tracking_dict)
HydroCNHS.util.update_system_config(modified_config)

Given the dictionary of modified setting, this function will over write Config.yaml.

modified_configdict

Dictionary of modified config settings.

HydroCNHS.util.write_model(model_dict, filename, org_model=None)

Write model dictionary to .yaml file

If org_model is given, comments in the original file will be kept in the output model file.

model_dictdict

Model dictionary.

filenamestr

Output filename (e.g. model.yaml).

org_modelstr, optional

Original model name (e.g. org_model.yaml), by default None.

HydroCNHS.util.write_model_to_csv(folder_path, model_dict, key_option=['Pars'], prefix='')

Write model (dictionary) to csv files.

folder_pathstr

Output folder directory.

model_dictdict

Model dictionary.

key_optionlist, optional

Output sections (e.g., Pars, Inputs, Attributes), by default [“Pars”].

prefixstr, optional

Prefix for the filenames, by default “”.

list

List of filenames.

HydroCNHS.util.write_model_to_df(model_dict, key_option=['Pars'], prefix='')

Write model (dictionary) to dataframes.

This function will convert model dictionary to dataframes according to user’s specified sections (key_option).

model_dictdict

Model dictionary.

key_optionlist, optional

Output sections (e.g., Pars, Inputs, Attributes), by default [“Pars”].

prefixstr, optional

Prefix for the filenames, by default “”.

HydroCNHS.visual module

class HydroCNHS.visual.Visual

Bases: object

Collection of some plotting functions.

static plot_reg(x_obv, y_sim, title=None, xy_labal=None, same_xy_limit=True, return_reg_par=False, save_fig_path=None, show=True)

Plot regression.

x_obvarray

Observation data.

y_simarray

Simulation data.

titlestr, optional

Title, by default None.

xy_laballist, optional

List of x and y labels, by default None.

same_xy_limitbool, optional

If True same limit will be applied to x and y axis, by default True.

return_reg_parbool, optional

If True, slope and interception will be return, by default False.

save_fig_pathstr, optional

If given, plot will be save as .png, by default None.

showbool, optional

If True, the plot will be shown in the console, by default True.

ax or list

axis object or [slope, intercept].

static plot_simple_ts(df, title=None, xy_labal=None, data_dots=True, save_fig_path=None, **kwargs)

Plot timeseries.

dfDataFrame

Dataframe.

titlestr, optional

Title, by default None.

xy_laballist, optional

List of x and y labels, by default None.

data_dotsbool, optional

If Ture, show data marker, by default True.

save_fig_pathstr, optional

If given, plot will be save as .png, by default None.

object

axis object.

static plot_timeseries(x_obv, y_sim, xticks=None, title=None, xy_labal=None, save_fig_path=None, legend=True, show=True, **kwargs)

Plot timeseries.

This function can plot two DataFrames with same column names.

x_obvarray/DataFrame

Observation data.

y_simarray/DataFrame

Simulation data.

xtickslist, optional

Ticks for x-axis, by default None.

titlestr, optional

Title, by default None.

xy_laballist, optional

List of x and y labels, by default None.

save_fig_pathstr, optional

If given, plot will be save as .png, by default None.

legendbool, optional

If True, plot legend, by default None.

showbool, optional

If True, the plot will be shown in the console, by default True.

kwargsoptional

Other keywords for matplotlib.

object

axis object.

Module contents

HydroCNHS.load_logging_config()

Load logging configuration and setup logging.