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.