How to add another hydrological model

Introduction

For now, TnetRUI can use 2 hydrological models: EROS, used on the french Loire watershed, and J2000 used on french Saône watershed. But other hydrological models can be used.

As an exemple, let’s imagine that we want to add another hydrological model named “MORDOR” in TnetRUI.

NetCDF files

TnetRUI use NetCDF files in order to save all intermediate and final results. In all the function you need to create in order to add another hydrological model, it’s recommended to use TNETutils_createNetCDF() to create the NetCDF file where the result of your function will be store and TNETutils_appendNetCDF to add the data in it. Doing this will unsure you that every files created by TnetRUI will have the same format.

Philosopy behind TnetRUI

All functions in TnetRUI was created with the following assomptions:

• TNET and hydrological models doesn’t share the same hydrographic network. That’s why there is 2 functions to compute Discharge in TnetRUI. TnetMORDOR_readfiles() (just as TnetJ2K_readfiles() or TnetEROS_readfiles()) will read the raw data from the hydrological model (on it’s own hydrographic network) and put it in a NetCDF file, where TnetMORDOR_computeQ() (just as TnetJ2K_computeQ() or TnetEROS_computeQ()) will dispatch the discharge from the hydrographic network of the hydrological model to the hydrographic network used by TNET (for now it’s the french hydrographic network TOPAGE). If you already have the data on the hydrographic network where you want to run T-NET, you can only use TnetMORDOR_computeQ() function to read the file with the discharge of all your river segments.

• Hydraulic data are computed using discharge data. All TnetHydraulic functions are made to compute the hydraulic data with discharge data as a simplification. If your model already compute width, depth and travel time, you can add a function TnetMORDOR_readHydraulic() in order to read files with those results.

1 - Create the file colnames_MORDOR.txt

This file must be located in the folder inst/extdata/Colnames_MODELS/ of the TnetRUI package. It’s used to defined the columns names used in the shapefile defining the hydrological network. An empty file colnames_EXEMPLE.txt can be used as a base for that. This file must contain the following columns:

Column explanation

column col_mandatory

This columns contains the names of the columns needed by the C++ T-NET model. It must be identical to the colnames_EXEMPLE.txt file.

column colname_shape

This column contain the equivalent named of the column in the hydrological network shapefile. This value can be left empty if the name is the same as the one in the column col_mandatory

column created_by

This column contain the name of the function that can be used to create the corresponding column in the hydrological network shapefile. The function can be any R function (from the TnetRUI package or not). Let the value blanck for any columns not created by R function.

The function needs to be written as the following: packageName::functionName (for exemple: TnetRUI::TNETshape_computePosition or sf::st_length)

column needed_by

This function must contain the name of the TnetRUI group function in which each hydrological network shapefile columns are used. To have all TnetRUI group name you can refer to the chapter on the Reference page

column Explanation

Contain a little explanation of the content of the column, to help the user to create it if needed

Exemple

The file colnames_EXEMPLE.txt can be found in the GIT package to help you create your own file. Here is an example of the file created for the J2000 hydrological model:

col_mandatory	colname_shape	created_by	needed_by	Explanation
gid	gid_new		TNET;TNETshape	ID of the segment
ND_INI	ID_ND_INI		TNET;TNETshape	ID of the initial node
ND_FIN	ID_ND_FIN		TNET;TNETshape	ID of the final node
vegPctL	RG_PCT_VEG			Percentage of the left bank of the segment covered by vegetation (0 - 100)
vegPctR	RD_PCT_VEG			Percentage of the right bank of the segment covered by vegetation (0 - 100)
vegHL	RG_H_MOY			Mean height of the vegetation on the left bank (m)
vegHR	RD_H_MOY			Mean height of the vegetation on the right bank (m)
X	Xcentr	TnetRUI::TNETshape_computePosition		X coordinates of the segment (WGS84)
Y	Ycentr	TnetRUI::TNETshape_computePosition		Y coordinates of the segment (WGS84)
phi_deg		TnetRUI::TNETshape_computePosition		Orientation of the segment (angle with the north in degres)
L_km	Longueur_m	sf::st_length	TNET;TNETshape	Length of the segments (in km)
id_M_1	ID_M_1	TnetRUI::TNETshape_getSafran	TNET	ID of the n°1 SAFRAN mesh crossed by the segment
id_M_2	ID_M_2	TnetRUI::TNETshape_getSafran	TNET	ID of the n°2 SAFRAN mesh crossed by the segment
id_M_3	ID_M_3	TnetRUI::TNETshape_getSafran	TNET	ID of the n°3 SAFRAN mesh crossed by the segment
id_M_4	ID_M_4	TnetRUI::TNETshape_getSafran	TNET	ID of the n°4 SAFRAN mesh crossed by the segment
id_M_5	ID_M_5	TnetRUI::TNETshape_getSafran	TNET	ID of the n°5 SAFRAN mesh crossed by the segment
id_M_6	ID_M_6	TnetRUI::TNETshape_getSafran	TNET	ID of the n°6 SAFRAN mesh crossed by the segment
id_M_7	ID_M_7	TnetRUI::TNETshape_getSafran	TNET	ID of the n°7 SAFRAN mesh crossed by the segment
id_M_8	ID_M_8	TnetRUI::TNETshape_getSafran	TNET	ID of the n°8 SAFRAN mesh crossed by the segment
Rap_M_1		TnetRUI::TNETshape_getSafran	TNET	Aspect ratio of the segment in the n°1 SAFRAN mesh
Rap_M_2		TnetRUI::TNETshape_getSafran	TNET	Aspect ratio of the segment in the n°2 SAFRAN mesh
Rap_M_3		TnetRUI::TNETshape_getSafran	TNET	Aspect ratio of the segment in the n°3 SAFRAN mesh
Rap_M_4		TnetRUI::TNETshape_getSafran	TNET	Aspect ratio of the segment in the n°4 SAFRAN mesh
Rap_M_5		TnetRUI::TNETshape_getSafran	TNET	Aspect ratio of the segment in the n°5 SAFRAN mesh
Rap_M_6		TnetRUI::TNETshape_getSafran	TNET	Aspect ratio of the segment in the n°6 SAFRAN mesh
Rap_M_7		TnetRUI::TNETshape_getSafran	TNET	Aspect ratio of the segment in the n°7 SAFRAN mesh
Rap_M_8		TnetRUI::TNETshape_getSafran	TNET	Aspect ratio of the segment in the n°8 SAFRAN mesh
	J2000		TNET	J2000 reach linked to the segment
	P_J2000		TNET;TNETshape	Is the segment the most downstream segment of the J2000 linked reach ? (1 if yes - 0 if not)
	RppAr_v	TnetRUI::TNETshape_computeCoefQcalc	TNET	Ratio of the total drain area use to dispatch discharge data from J2000 reach
	RppA_BV	TnetRUI::TNETshape_computeCoefQcalc	TNET	Ratio of the sub-watershed drain area use to dispatch lateral discharge data from J2000 reach

2 - Create the TnetMORDOR set function

You will need function in order to pass data from your raw MORDOR files to NetCDF compatibles with TnetRUI. The minimum function requiert will be the following:

• TnetMORDOR_readfiles(): To read raw files in a NetCDF TnetRUI format

• TnetMORDOR_computeQ(): To dispatch discharge data from MORDOR hydrological network to T-NET Hydrological network.

• TnetMORDOR_computeQlatSout(): To dispatch underground discharge data from MORDOR hydrological network to T-NET Hydrological network.

• TnetMORDOR_computeTg(): To compute or read underground water temperature.

You can add other function if your hydrological model needs it, but these ones will be a minimum to run T-NET correctly

3 - Add an article explaining your hydrological model

Finally, it is best to add a little article with the presentation of your newly added model in order to help other user to understant it

Add the vignette

To create the vignette relatif to your hydrologial model, you can execute the following in the TnetRUI folder:

usethis::use_vignette('TnetRUI_MORDOR',title = "MORDOR hydrological model")

This will create the file where it will be possible to explain how your hydrological model works

Be sure that the file vignette/TnetRUI_MORDOR.Rmd do not exist before using this filename

Add the website article

To add your newly created vignette to the website, you’ll have to add the following code in the _pkgdown.yml file, in the Models menu of the navbar section:

- text: "MORDOR"
  href: articles/TnetRUI_MORDOR.html

It’s possible to update the website by using the following sentence in the terminal (in the TnetRUI folder)

make website

Pushing all modification made in the “public” folder to ForgeINRAE will update the website.