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. TNET_readMODEL (for exemple TNET_readJ2K() or TNET_readEROS()) will read the raw data of the model on the hydrographic network of the model and put it in a NetCDF file, where TNET_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 execute T-NET, you can only use TNET_computeQ() function to read the file with the discharge of all your river segments.
Hydraulic data are computed using discharge data. TNET_computeHydraulic() is made to compute the hydraulic data with discharge data as a simplification. If your model already compute width, depth and travel time, you can use TNET_computeHydraulic() 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 exemple 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 `TNET_readMORDOR` function

If you need to read raw files from modor before dispatching them on TNET hydrographic network, you will nee to create a function TNET_readMORDOR (just like TNET_readJ2K() or TNET_readEROS() functions).

3 - Modify all `compute` functions

You will need to modify the followings function in order to add the hydrological model MORDOR:

In all those functions, you’ll need to add the following case in order to specify the code to use for the new hydrological model (example for TNET_computeQ())

if (hydro_model == 'MORDOR') {
  results_file <- computeQ_MORDOR(...)
}

and create just bellow the function computeQ_MORDOR with the computation needed. The function needs to return the file created by TNETutils_createNetCDF().

4 - Add the execution squeleton in `TNET_prepareSim()`

You can add a condition in the TNET_prepareSim() in order to be sure that all function will be executed in the good order

#This example is fictionnal

if (hydro_model == 'MORDOR') {
  #Read MORDOR files
  TNET_readMORDOR(...)
  
  #Dispatch discharge on TNET hydrographique network
  TNET_computeQ(hydro_model = 'MORDOR',...)
  
  #Read hydraulique data from MORDOR
  TNET_computeHydraulic(hydro_model = 'MORDOR',...)
  
  #compute underground lateral discharge
  TNET_computeQlatSout(hydro_model = 'MORDOR',...)
  
}

5 - 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_7',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_7.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 Articles menu of the navbar section:

- text: "MORDOR"
  href: articles/TnetRUI_7.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 ForgeMIA will update the website.

Introduction

NetCDF files

Philosopy behind TnetRUI

1 - Create the file colnames_MORDOR.txt

Column explanation

column col_mandatory

column colname_shape

column created_by

column needed_by

column Explanation