Title: | Transfer of Hydrograph from Gauged to Ungauged Catchments |
---|---|
Description: | A geomorphology-based hydrological modelling for transferring streamflow measurements from gauged to ungauged catchments. Inverse modelling enables to estimate net rainfall from streamflow measurements following Boudhraâ et al. (2018) <doi:10.1080/02626667.2018.1425801>. Resulting net rainfall is then estimated on the ungauged catchments by spatial interpolation in order to finally simulate streamflow following de Lavenne et al. (2016) <doi:10.1002/2016WR018716>. |
Authors: | Alban de Lavenne [aut, cre] , Christophe Cudennec [ths] , Tom Loree [ctb], Hervé Squividant [ctb] |
Maintainer: | Alban de Lavenne <[email protected]> |
License: | GPL-2 |
Version: | 1.0.11 |
Built: | 2024-11-25 06:56:38 UTC |
Source: | CRAN |
This R package aims to propose a geomorphology-based hydrological modelling to transfer streamflow measurements from gauged catchments to ungauged catchments, i.e. where there is no station monitoring the streamflow. It follows a runoff-runoff approach, i.e. it directly combines the observed streamflow series available at monitoring stations to estimate the streamflow series anywhere else in the surroundings rivers and without the need to implement a full rainfall-runoff model. The package itself and theoretical aspects of the approach are presented in detail and discussed by de Lavenne et al. (2023).
## — Short description of the modelling approach
The hydrological modelling is based on a description of the hydro-geomorphometry of the river network which can be easily observed for any given outlet. An inversion of this model for a gauged catchment allows the observed streamflow series being deconvoluted in order to estimate an almost scale-independent signal, namely the net rainfall (Boudhraâ et al. 2018). Transferring this estimate of the net rainfall series to a targeted ungauged catchment then allows simulating the streamflow there. The use of streamflow observations from several gauged catchments of the neighbourhood increases the robustness of the simulation (de Lavenne et al. 2016). The methodology has first been implemented on a few catchments in semiarid Tunisia at the event time scale (Boudhraâ et al. 2009), then in dense configurations of neighbouring and nesting catchments in France with mainly temperate oceanic climate (de Lavenne et al. 2015; de Lavenne et al. 2016; de Lavenne and Cudennec 2019) and in snow-influenced Québec, Canada (Ecrepont et al. 2019).
## — Functions and objects
To implement the method, it is advised to explore the following functions in this order:
as_transfr
create a “transfR” database from a “stars” object and morphometric description of the catchments (hydraulic lengths)
velocity
estimates the main model parameter, i.e. the streamflow velocity, from different regionalisation strategies
uh
estimates a simple linear model, i.e. the unit hydrograph, based on the analysis of catchment geomorphology and streamflow velocity
rapriori
provides an a priori on the net rainfall, as needed for the model's inversion
inversion
estimates the net rainfall by an inverse modelling
hdist
computes hydrological distances between catchments, such as the rescaled Ghosh distances
mixr
estimates the net rainfall of one catchment by averaging the net rainfall of neighbouring gauged catchments and according to hydrological distances
convolution
computes the convolution of the net rainfall by the unit hydrograph to estimate streamflow
## — How to get started
This package comes with two datasets (Blavet and Oudon) that contains all the necessary inputs to test the package and perform discharge prediction. Users are advised to check the 'Get started with transfR' vignette (vignette("V01_get_started", package = "transfR")
) that provides a complete implementation of the method with the Oudon dataset. Two additional vignettes are proposed to help the preparation of input data: a spatiotemporal array of observed discharge (vignette("V02_inputs_preparation_stars", package = "transfR")
) and a morphometric description of the catchments (vignette("V03_inputs_preparation_whitebox", package = "transfR")
). In addition, each function comes with different examples.
A detailed description of the modelling approach and the package has been published by de Lavenne et al. (2023): the theoretical aspects of each modelling step are described in more detail, arguments justifying the default values used in the functions are presented, and limitations of the approach are discussed for a consistent implementation of the approach.
For the French region of Brittany, a web service using this package was developed to facilitate the implementation of the method without the need for the user to have programming skills in R or to collect the necessary input data (Dallery et al. 2020).
Boudhraâ H, Cudennec C, Slimani M, Andrieu H (2009). “Hydrograph transposition between basins through a geomorphology-based deconvolution-reconvolution approach.” IAHS publication, 333, 76.
Boudhraâ H, Cudennec C, Andrieu H, Slimani M (2018). “Net rainfall estimation by the inversion of a geomorphology-based transfer function and discharge deconvolution.” Hydrological Sciences Journal, 63(2), 285–301. doi:10.1080/02626667.2018.1425801.
Ecrepont S, Cudennec C, Anctil F, Jaffrézic A (2019). “PUB in Québec: A robust geomorphology-based deconvolution-reconvolution framework for the spatial transposition of hydrographs.” Journal of Hydrology, 570, 378–392. doi:10.1016/j.jhydrol.2018.12.052.
Dallery D, Squividant H, de Lavenne A, Launay J, Cudennec C (2020). “An end-user-friendly hydrological Web Service for hydrograph prediction in ungauged basins.” Hydrological Sciences Journal, 1–9. doi:10.1080/02626667.2020.1797045.
de Lavenne A, Boudhraâ H, Cudennec C (2015). “Streamflow prediction in ungauged basins through geomorphology-based hydrograph transposition.” Hydrology Research, 46(2), 291–302. doi:10.2166/nh.2013.099.
de Lavenne A, Skøien JO, Cudennec C, Curie F, Moatar F (2016). “Transferring measured discharge time series: Large-scale comparison of Top-kriging to geomorphology-based inverse modeling.” Water Resources Research, 52(7), 5555–5576. doi:10.1002/2016WR018716.
de Lavenne A, Cudennec C (2019). “Assessment of freshwater discharge into a coastal bay through multi-basin ensemble hydrological modelling.” Science of The Total Environment, 669, 812 - 820. ISSN 0048-9697, doi:10.1016/j.scitotenv.2019.02.387.
de Lavenne A, Loree T, Squividant H, Cudennec C (2023). “The transfR toolbox for transferring observed streamflow series to ungauged basins based on their hydrogeomorphology.” Environmental Modelling & Software, 159, 105562. ISSN 1364-8152, doi:10.1016/j.envsoft.2022.105562.
Create a transfR object or add new attributes to a transfR object.
as_transfr( object, st, uc, lagtime, surface, delineation, outlet, centroid, uh, hl )
as_transfr( object, st, uc, lagtime, surface, delineation, outlet, centroid, uh, hl )
object |
object of class |
st |
spatio-temporal arrays of class |
uc |
vector of the streamflow velocities of the catchments. If no unit is provided, |
lagtime |
vector of the lag times of the catchments. If no unit is provided, |
surface |
vector of the surfaces of the catchments. If no unit is provided, |
delineation |
spatial layer of the boundary of the catchments of class |
outlet |
spatial layer of the outlets of the catchments of class |
centroid |
spatial layer of the centroids of the catchments of class |
uh |
list of the unit hydrographs of the catchments. |
hl |
hydraulic length of class |
This function creates an object of class transfR
or increment an existing transfR
object
with new attributes. It can be used to gather and organize most of the inputs and outputs of the other functions
like streamflow velocities, unit hydrograph, a priori on net rainfall, inversions and simulations of every catchments.
This function can be used to organise the two user inputs required for a conventional use of the package, namely st
and hl
. The hydraulic lengths are defined as the flow path length from each pixel to the outlet within
the river network (Cudennec et al. 2004; Aouissi et al. 2013). Catchment delineations and hydraulic lengths
need to be prepared beforehand by the user. This package does not provide functions to create them.
However, several GIS software offer possibilities to extract them from a digital elevation model
such as GRASS toolkits (Jasiewicz and Metz 2011),
Whitebox GAT (see Lindsay (2016) or WhiteboxTools),
TauDEM (D. Tarboton, Utah State University)
or online services (see Squividant et al. (2015) for catchment delineation in the Brittany French region).
An object of class transfR.
Aouissi J, Pouget J, Boudhraâ H, Storer G, Cudennec C (2013). “Joint spatial, topological and scaling analysis framework of river-network geomorphometry.” Géomorphologie : relief, processus, environnement, 19(1), 7–16. doi:10.4000/geomorphologie.10082.
Cudennec C, Fouad Y, Gatot IS, Duchesne J (2004). “A geomorphological explanation of the unit hydrograph concept.” Hydrological Processes, 18(4), 603–621. doi:10.1002/hyp.1368.
Jasiewicz J, Metz M (2011). “A new GRASS GIS toolkit for Hortonian analysis of drainage networks.” Computers & Geosciences, 37(8), 1162–1173. doi:10.1016/j.cageo.2011.03.003.
Lindsay JB (2016). “Whitebox GAT: A case study in geomorphometric analysis.” Computers & Geosciences, 95, 75–84. doi:10.1016/j.cageo.2016.07.003.
Squividant H, Bera R, Aurousseau P, Cudennec C (2015). “Online watershed boundary delineation: sharing models through Spatial Data Infrastructures.” Proceedings of the International Association of Hydrological Sciences, 368, 144–149. doi:10.5194/piahs-368-144-2015.
data(Oudon) object <- as_transfr(st = Oudon$obs, hl = Oudon$hl)
data(Oudon) object <- as_transfr(st = Oudon$obs, hl = Oudon$hl)
'Blavet' is a dataset of the Blavet French river in Brittany peninsula and two neighouring rivers (Claie and Coët-Organ). It contains all the necessary inputs to test the package and perform discharge prediction at the outlet of six catchments:
J5613010 Evel at Guénin (316 km²)
J5618310 Fremeur et Guénin (15.1 km²)
J5618320 Fremeur et Pluméliau (5.88 km²)
J5704810 Coët-Organ at Quistinic (47.7 km²)
J8433020 Claie at Saint-Jean-Brévelay (135 km²)
AgrHys Coët-Dan at Naizin (4.9 km²)
Hourly discharge observations of the six catchments are provided for one hydrological year, from 2013-10-01 to 2014-10-01. It has been extracted from the French HYDRO database (http://www.hydro.eaufrance.fr). Discharge observations for the Coët-Dan river is provided by the AgrHys Environment Research Observatories (Fovet et al. 2018) managed by INRAE (https://www6.inrae.fr/ore_agrhys_eng). Catchment delineations and respective maps of hydraulic length have been extracted from a digital elevation model of 100 m resolution.
'Blavet' is a list of three objects:
hl A list of stars objects containing the six rasters maps of hydraulic length.
obs A stars object with two dimensions (time and space, with catchment delineations as spatial support) and one attribute (discharge observations).
network A sf object of the [French TOPAGE river network](https://bdtopage.eaufrance.fr/). It can be downloaded using the Web Feature Service (WFS) "Sandre - Eau France", as shown in the example below.
http://www.hydro.eaufrance.fr
https://www6.inrae.fr/ore_agrhys_eng
http://bdtopage.eaufrance.fr
Fovet O, Ruiz L, Gruau G, Akkal N, Aquilina L, Busnot S, Dupas R, Durand P, Faucheux M, Fauvel Y, Fléchard C, Gilliet N, Grimaldi C, Hamon Y, Jaffrezic A, Jeanneau L, Labasque T, Henaff GL, Mérot P, Molénat J, Petitjean P, Pierson-Wickmann A, Squividant H, Viaud V, Walter C, Gascuel-Odoux C (2018). “AgrHyS: An Observatory of Response Times in Agro-Hydro Systems.” Vadose Zone Journal, 17(1), 180066. doi:10.2136/vzj2018.04.0066.
## Not run: # Working directory wd <- tempdir(check = TRUE) # Define a bbox that will encompass the catchments of the study area blavet_bbox <- st_bbox(c(xmin = -3.3, xmax = -2.7, ymax = 48.11, ymin = 47.77), crs = st_crs(4326)) # Download a French Topage river network within the bbox using the "Sandre - Eau France" WFS download.file(url = paste0("https://services.sandre.eaufrance.fr/geo/topage2019", "?request=GetFeature&service=WFS&version=2.0.0", "&typeName=CoursEau_FXX_Topage2019", "&outputFormat=application/json; paste0(blavet_bbox[c("ymin","xmin","ymax","xmax")], collapse=",")), destfile = file.path(wd,"CoursEau_FXX_Topage2019.geojson")) CoursEau_Topage2019 <- st_read(dsn = file.path(wd,"CoursEau_FXX_Topage2019.geojson"), drivers = "GeoJSON", stringsAsFactors = FALSE, quiet = FALSE, query = "SELECT gid FROM CoursEau_FXX_Topage2019") ## End(Not run)
## Not run: # Working directory wd <- tempdir(check = TRUE) # Define a bbox that will encompass the catchments of the study area blavet_bbox <- st_bbox(c(xmin = -3.3, xmax = -2.7, ymax = 48.11, ymin = 47.77), crs = st_crs(4326)) # Download a French Topage river network within the bbox using the "Sandre - Eau France" WFS download.file(url = paste0("https://services.sandre.eaufrance.fr/geo/topage2019", "?request=GetFeature&service=WFS&version=2.0.0", "&typeName=CoursEau_FXX_Topage2019", "&outputFormat=application/json; paste0(blavet_bbox[c("ymin","xmin","ymax","xmax")], collapse=",")), destfile = file.path(wd,"CoursEau_FXX_Topage2019.geojson")) CoursEau_Topage2019 <- st_read(dsn = file.path(wd,"CoursEau_FXX_Topage2019.geojson"), drivers = "GeoJSON", stringsAsFactors = FALSE, quiet = FALSE, query = "SELECT gid FROM CoursEau_FXX_Topage2019") ## End(Not run)
Simulate the discharge by a convolution between the unit hydrograph and the net rainfall.
convolution(Rn, ...) ## Default S3 method: convolution(Rn, uh, continuous = FALSE, ...) ## S3 method for class 'units' convolution(Rn, uh, ...) ## S3 method for class 'transfR' convolution( Rn, Rcol = "RnSim", Qcol = "Qsim", save_donor = FALSE, verbose = TRUE, ... )
convolution(Rn, ...) ## Default S3 method: convolution(Rn, uh, continuous = FALSE, ...) ## S3 method for class 'units' convolution(Rn, uh, ...) ## S3 method for class 'transfR' convolution( Rn, Rcol = "RnSim", Qcol = "Qsim", save_donor = FALSE, verbose = TRUE, ... )
Rn |
net rainfall vector or an object of class |
... |
further arguments passed to or from other methods |
uh |
unit hydrograph vector |
continuous |
boolean indicating if, when one time step might be influenced by past or future rainfall (according to the time span of the unit hydrograph), no simulated value is provided |
Rcol |
name of the space-time attribute for the discharge simulation in the |
Qcol |
name of the space-time attribute for the net rainfall in the |
save_donor |
boolean indicating if additional discharge simulations should be computed using the
net rainfall of each individual donor catchment instead of just the weighted average net rainfall. This
requires that |
verbose |
boolean indicating if information messages should be written to the console |
An object of the same class of Rn
. If Rn
is a transfR object,
the same transfR object incremented by the new computed attributes.
data(Oudon) icatch <- 1 uc <- velocity(hl = Oudon$hl[[icatch]]) uh <- uh(hl = Oudon$hl[[icatch]], uc = uc, deltat = units::set_units(1,"h"))$prob Rn <- units::set_units(c(1,5,2), "mm/h") Qsim <- convolution(Rn = Rn, uh = uh)
data(Oudon) icatch <- 1 uc <- velocity(hl = Oudon$hl[[icatch]]) uh <- uh(hl = Oudon$hl[[icatch]], uc = uc, deltat = units::set_units(1,"h"))$prob Rn <- units::set_units(c(1,5,2), "mm/h") Qsim <- convolution(Rn = Rn, uh = uh)
Calculate distances between two sets of catchments using their spatial support.
hdist(x, y, ...) ## S3 method for class 'sfc' hdist( x, y, method = "rghosh", gres = 5, ditself = FALSE, maxsample = 25000, proj = NULL, parallel = FALSE, cores = NULL, verbose = TRUE, ... ) ## S3 method for class 'sf' hdist(x, y, ...) ## S3 method for class 'stars' hdist(x, y, ...) ## S3 method for class 'transfR' hdist(x, y, method = "rghosh", weightO = 0.8, weightC = 0.2, ...)
hdist(x, y, ...) ## S3 method for class 'sfc' hdist( x, y, method = "rghosh", gres = 5, ditself = FALSE, maxsample = 25000, proj = NULL, parallel = FALSE, cores = NULL, verbose = TRUE, ... ) ## S3 method for class 'sf' hdist(x, y, ...) ## S3 method for class 'stars' hdist(x, y, ...) ## S3 method for class 'transfR' hdist(x, y, method = "rghosh", weightO = 0.8, weightC = 0.2, ...)
x |
sf, stars or transfR object of the first catchments |
y |
sf, stars or transfR object of the second catchments |
... |
further arguments passed to or from other methods |
method |
the method to use for computing distance. This must be one of "ghosh", "rghosh", "points", "centroids", "combined" |
gres |
resolution of spatial discretisation (number of points by km²) for Ghosh distance |
ditself |
logical value indicating if the distance to itself should be computed. It will add one row and one column in the distance matrix. Only used if method is "ghosh" |
maxsample |
maximum size of sampling points for each catchments during spatial discretisation |
proj |
logical indicating if spatial layer are using a projection. If TRUE, euclidean distance is used. If FALSE, the great-circle distance is used |
parallel |
logical indicating if the computation should be parallelised |
cores |
the number of cores to use for parallel execution if |
verbose |
boolean indicating if information messages should be written to the console |
weightO |
weight given to the distance between outlets if method is "combined" |
weightC |
weight given to the distance between centroids if method is "combined" |
The method
"ghosh" refers to a simplification of the distance defined
by Ghosh (1951) as proposed by Gottschalk (1993); Gottschalk et al. (2011).
The rescaled Ghosh distance (method
"rghosh") is calculted following de Lavenne et al. (2016).
A matrix of class units with the catchments of x
organised in rows
and the catchments of y
organised in columns.
Ghosh B (1951). “Random distances within a rectangle and between two rectangles.” Bull. Calcutta Math. Soc, 43(1), 17–24.
Gottschalk L (1993). “Interpolation of runoff applying objective methods.” Stochastic Hydrology and Hydraulics, 7(4), 269–281. doi:10.1007/BF01581615.
Gottschalk L, Leblois E, Skøien JO (2011). “Distance measures for hydrological data having a support.” J. Hydrol., 402(3-4), 415–421. doi:10.1016/j.jhydrol.2011.03.020.
de Lavenne A, Skøien JO, Cudennec C, Curie F, Moatar F (2016). “Transferring measured discharge time series: Large-scale comparison of Top-kriging to geomorphology-based inverse modeling.” Water Resources Research, 52(7), 5555–5576. doi:10.1002/2016WR018716.
data(Oudon) catchments <- st_geometry(Oudon$obs) hdist(x = catchments[1:2], y = catchments[3:5], gres = 5, method = "rghosh")
data(Oudon) catchments <- st_geometry(Oudon$obs) hdist(x = catchments[1:2], y = catchments[3:5], gres = 5, method = "rghosh")
Estimate net rainfall by inverse modelling, where the model is a convolution between net rainfall and a unit hydrograph in order to simulate discharge.
inversion(Qobs, ...) ## Default S3 method: inversion(Qobs, uh, RnAp, deltat, ...) ## S3 method for class 'units' inversion( Qobs, uh, RnAp, deltat, Bd = 0.01, Dd = 1, Bp = 0.001, Tp = 20, Ad = 0.01, Ap = 0.9, warmup = 10, cooldown = 8, dosplit = TRUE, split = 30, fixedpar = TRUE, parallel = FALSE, cores = NULL, ... ) ## S3 method for class 'transfR' inversion(Qobs, verbose = TRUE, ...)
inversion(Qobs, ...) ## Default S3 method: inversion(Qobs, uh, RnAp, deltat, ...) ## S3 method for class 'units' inversion( Qobs, uh, RnAp, deltat, Bd = 0.01, Dd = 1, Bp = 0.001, Tp = 20, Ad = 0.01, Ap = 0.9, warmup = 10, cooldown = 8, dosplit = TRUE, split = 30, fixedpar = TRUE, parallel = FALSE, cores = NULL, ... ) ## S3 method for class 'transfR' inversion(Qobs, verbose = TRUE, ...)
Qobs |
discharge vector or object of class |
... |
further arguments passed to or from other methods |
uh |
unit hydrograph vector |
RnAp |
net rainfall a priori. If no unit is provided, |
deltat |
time step of the time series. If no unit is provided, |
Bd |
parameter used to maintain a minimum value of standart deviation for low discharge values.
If no unit is provided, |
Dd |
decorrelation time of discharge errors. If no unit is provided, |
Bp |
parameter used to maintain a minimum value of standart deviation for low net rainfall values.
If no unit is provided, |
Tp |
decorrelation time of net rainfall errors. If no unit is provided, |
Ad |
parameter equivalent to the coefficient of variation of the discharge measurement error. If
no unit is provided, |
Ap |
parameter equivalent to the coefficient of variation of the net rainfall error. If no unit
is provided, |
warmup |
length of the warmup period. If no unit is provided, |
cooldown |
length of the period removed at the end of the simulation. If no unit is provided,
|
dosplit |
boolean, if true the inversion is performed by
subperiods of length defined by |
split |
length the subperiods if dosplit is true. If no unit is provided, |
fixedpar |
boolean, if false Ap and Ad are calibrated dynamically according to the coefficient of variation of RnAp and Qobs respectively (see details) |
parallel |
boolean, if true the splitting of the inversion by subperiods is parallelised |
cores |
the number of cores to use for parallel execution if |
verbose |
boolean indicating if information messages should be written to the console |
In a convolution between the unit hydrograph (uh
) and net rainfall that is simulating
streamflow at the outltet (Qobs
), and where net rainfall is the only unknown variable, this function estimates
net rainfall by inversion (Tarantola and Valette 1982; Menke 1989; Boudhraâ et al. 2018). It requires an
a priori on this net rainfall (that could be estimated by the function rapriori), a description
of the errors on the discharge (Ad
, Bd
, Dd
) and on the net rainfall (Ap
,
Bp
, Tp
) that are assumed to be Gaussian and unbiased. Default values of these parameters
are taken from de Lavenne et al. (2016). If fixedpar
is deactivated, Ap
is estimated at 20
of variation of Qobs.
It is recommanded to use warmup
and cooldown
periods in order to reduce the problem of oscillations
created by inversion.
If object
is provided, results are stored as a new space-time attribute in the object
called "RnAp".
An object of the same class of Qobs
. If Qobs
is a transfR object,
the same transfR object incremented by the new computed attributes.
Boudhraâ H, Cudennec C, Andrieu H, Slimani M (2018). “Net rainfall estimation by the inversion of a geomorphology-based transfer function and discharge deconvolution.” Hydrological Sciences Journal, 63(2), 285–301. doi:10.1080/02626667.2018.1425801.
de Lavenne A, Skøien JO, Cudennec C, Curie F, Moatar F (2016). “Transferring measured discharge time series: Large-scale comparison of Top-kriging to geomorphology-based inverse modeling.” Water Resources Research, 52(7), 5555–5576. doi:10.1002/2016WR018716.
Menke W (1989). Geophysical data analysis: discrete inverse theory, volume 45. Academic Press.
Tarantola A, Valette B (1982). “Inverse problems= quest for information.” Journal of Geophysics, 50(3), 150–170.
data(Oudon) icatch <- 1 # Catchment index itime <- 1:1000 # Using the first values for a quicker example Qobs <- Oudon$obs[["Qobs"]][itime,icatch] Qspec <- units::set_units(Qobs/st_area(st_geometry(Oudon$obs)[icatch]), "mm/h") deltat <- units::set_units(1, "h") uc <- velocity(hl = Oudon$hl[[icatch]]) uh <- uh(hl = Oudon$hl[[icatch]], uc = uc, deltat = units::set_units(1,"h"))$prob RnAp <- rapriori(Qobs = Qspec, lagtime = lagtime(hl = Oudon$hl[[icatch]], uc = uc), deltat = deltat) RnInv <- inversion(Qobs = Qspec, RnAp = RnAp, uh = uh, deltat = deltat)
data(Oudon) icatch <- 1 # Catchment index itime <- 1:1000 # Using the first values for a quicker example Qobs <- Oudon$obs[["Qobs"]][itime,icatch] Qspec <- units::set_units(Qobs/st_area(st_geometry(Oudon$obs)[icatch]), "mm/h") deltat <- units::set_units(1, "h") uc <- velocity(hl = Oudon$hl[[icatch]]) uh <- uh(hl = Oudon$hl[[icatch]], uc = uc, deltat = units::set_units(1,"h"))$prob RnAp <- rapriori(Qobs = Qspec, lagtime = lagtime(hl = Oudon$hl[[icatch]], uc = uc), deltat = deltat) RnInv <- inversion(Qobs = Qspec, RnAp = RnAp, uh = uh, deltat = deltat)
Estimate the lag time of the catchment.
lagtime(hl, ...) ## Default S3 method: lagtime(hl, uc, ...) ## S3 method for class 'units' lagtime(hl, uc, method = 1, ...) ## S3 method for class 'stars' lagtime(hl, ...) ## S3 method for class 'transfR' lagtime(hl, verbose = TRUE, ...)
lagtime(hl, ...) ## Default S3 method: lagtime(hl, uc, ...) ## S3 method for class 'units' lagtime(hl, uc, method = 1, ...) ## S3 method for class 'stars' lagtime(hl, ...) ## S3 method for class 'transfR' lagtime(hl, verbose = TRUE, ...)
hl |
hydraulic length of class |
... |
further arguments passed to or from other methods |
uc |
streamflow velocity. If no unit is provided, |
method |
integer describing the method to use for lag time estimation. Possible values: 1 (see details). |
verbose |
boolean indicating if information messages should be written to the console. |
The function estimates the lag time of the catchment. It can be used to estimate one of the
inputs of the function rapriori. If method
is 1, the lag time is estimated
from the ratio of the mean hydraulic length (hl
) and the average streamflow velocity (uc
).
A numeric value of class units, or if hl
is a transfR object,
the same transfR object incremented by the "lagtime" attribute.
data(Oudon) icatch <- 1 lagtime(Oudon$hl[[icatch]], uc = units::set_units(0.5, "m/s"))
data(Oudon) icatch <- 1 lagtime(Oudon$hl[[icatch]], uc = units::set_units(0.5, "m/s"))
Combine the net rainfall of gauged catchments to simulate the net rainfall of an ungauged catchment.
mixr( obs, sim, mdist, distance = "rghosh", gres = 5, weightO = 0.8, weightC = 0.2, parallel = FALSE, cores = NULL, power = 1, ndonors = 5, donors = NULL, maxdist = 50000, flexible_donor = TRUE, cv = FALSE, save_donor = FALSE, verbose = TRUE )
mixr( obs, sim, mdist, distance = "rghosh", gres = 5, weightO = 0.8, weightC = 0.2, parallel = FALSE, cores = NULL, power = 1, ndonors = 5, donors = NULL, maxdist = 50000, flexible_donor = TRUE, cv = FALSE, save_donor = FALSE, verbose = TRUE )
obs |
"transfR" object of the gauged catchments |
sim |
"transfR" object of the ungauged catchments |
mdist |
the distance matrix between gauged and ungauged catchments as computed by the function hdist |
distance |
the method to use for computing distance matrix if |
gres |
resolution of spatial discretisation (number of points by km²) for Ghosh distance (see the function hdist) |
weightO |
weight given to the distance between outlets if |
weightC |
weight given to the distance between centroids if |
parallel |
logical indicating if the computation should be parallelised |
cores |
the number of cores to use for parallel execution if |
power |
exponent applied in the inverse distance weighting strategy as defined by the function weightr |
ndonors |
maximum number of catchments to be used to simulate discharge of an ungauged catchment as defined by the function weightr |
donors |
vector of catchments id from which donors are selected. If empty, the |
maxdist |
maximum distance between a gauged and an ungauged catchment to allow the net rainfall
to be transfered. This threshold is applied on the |
flexible_donor |
boolean indicating if the donor catchments can change during the simulation period according to the availability of discharge observations. See weightr for more details |
cv |
boolean indicating if cross validation evaluation should be done. If true, it will estimate
the net rainfall of every gauged catchments ( |
save_donor |
boolean indicating if the net rainfall of each of the |
verbose |
boolean indicating if information messages should be written to the console |
This function is a wrapper function for hdist and weightr to directly estimate
the net rainfall on a set of ungauged catchments (sim
) from a set of gauged catchments (obs
).
It returns the simulated net rainfall as a new space-time attribute in the sim
object called "RnSim".
The simulated net rainfall of a given ungauged catchment is a weighted average of the net rainfalls
of
ndonors
gauged catchments :
where are defined by an inverse distance weighting function (see weightr).
The sim
object incremented by the new computed attributes.
data(Oudon) object <- as_transfr(st = Oudon$obs, hl = Oudon$hl) object <- velocity(object) object <- uh(object) object <- lagtime(object) object <- rapriori(object) object <- inversion(object, parallel = TRUE, cores = 2) mdist <- hdist(x = object, y = object, method = "rghosh") object <- mixr(obs = object, mdist = mdist, parallel = TRUE, cores=2, cv = TRUE, flexible_donor = TRUE, save_donor = FALSE) object <- convolution(object, save_donor = FALSE) plot(object, i = 1, attribute = c("Qobs", "Qsim"))
data(Oudon) object <- as_transfr(st = Oudon$obs, hl = Oudon$hl) object <- velocity(object) object <- uh(object) object <- lagtime(object) object <- rapriori(object) object <- inversion(object, parallel = TRUE, cores = 2) mdist <- hdist(x = object, y = object, method = "rghosh") object <- mixr(obs = object, mdist = mdist, parallel = TRUE, cores=2, cv = TRUE, flexible_donor = TRUE, save_donor = FALSE) object <- convolution(object, save_donor = FALSE) plot(object, i = 1, attribute = c("Qobs", "Qsim"))
'Oudon' is a dataset of the Oudon French river, part of the wider Loire Catchment. It contains all the necessary inputs to test the package and perform discharge prediction at the outlet of six sub-catchments:
M3771810 Oudon at Châtelais (734 km²)
M3774010 Chéran at la Boissière (85 km²)
M3823010 Verzée at Bourg-d'Iré (205 km²)
M3834030 Argos at Sainte-Gemmes-d'Andigné (153 km²)
M3851810 Oudon at Segré (1310 km²)
M3711810 Oudon at Cossé-le-Vivien (133 km²)
Hourly discharge observations of the six sub-catchments (Oudon French river) are provided from 2019-12-01 to 2020-03-01, and extracted from the French HYDRO database (http://www.hydro.eaufrance.fr). Catchment delineations and respective maps of hydraulic length have been extracted from a digital elevation model of 100 m resolution.
'Oudon' is a list of two objects:
hl A list of stars objects containing the six rasters maps of hydraulic length.
obs A stars object with two dimensions (time and space, with catchment delineations as spatial support) and one attribute (discharge observations).
http://www.hydro.eaufrance.fr
Plot transfR object.
## S3 method for class 'transfR' plot( x, y, i, attribute, main = sprintf("Catchment %i", i), xlab, ylab, format, at, nticks = 5, type = "l", lwd = 2, las = 1, cex.names = 1, col = c("#045a8d", "#fb8072", "#bebada", "#ffffb3", "#8dd3c7"), keeplocal = TRUE, ... )
## S3 method for class 'transfR' plot( x, y, i, attribute, main = sprintf("Catchment %i", i), xlab, ylab, format, at, nticks = 5, type = "l", lwd = 2, las = 1, cex.names = 1, col = c("#045a8d", "#fb8072", "#bebada", "#ffffb3", "#8dd3c7"), keeplocal = TRUE, ... )
x |
transfR object |
y |
ignored |
i |
spatial index to plot |
attribute |
attribute of the transfR object to plot |
main |
a main title for the plot, see also title |
xlab |
a label for the x axis, defaults to a description of x |
ylab |
a label for the y axis, defaults to a description of y |
format |
format for labels of time series on x axis |
at |
a date-time or date object for ticks on x axis |
nticks |
number of ticks on x axis |
type |
1-character string giving the type of plot desired (for details, see plot) |
lwd |
the line width (for details, see par) |
las |
the style of axis labels (for details, see par) |
cex.names |
expansion factor for axis names (for details, see barplot) |
col |
a specification for the default plotting color (for details, see par) |
keeplocal |
boolean to preserve local graphical parameters |
... |
further specifications, see plot |
data(Oudon) object <- as_transfr(st = Oudon$obs, hl = Oudon$hl) plot(object, attribute = "Qobs")
data(Oudon) object <- as_transfr(st = Oudon$obs, hl = Oudon$hl) plot(object, attribute = "Qobs")
Wrap up all the modelling steps into one function for a quick implementation of this R package.
quick_transfr( obs, sim, velocity = "loire2016", distance = "rghosh", gres = 5, weightO = 0.8, weightC = 0.2, power = 1, ndonors = 5, maxdist = 50000, flexible_donor = TRUE, cv = FALSE, save_donor = FALSE, warmup = 10, cooldown = 8, dosplit = TRUE, split = 30, parallel = FALSE, cores = NULL, verbose = TRUE )
quick_transfr( obs, sim, velocity = "loire2016", distance = "rghosh", gres = 5, weightO = 0.8, weightC = 0.2, power = 1, ndonors = 5, maxdist = 50000, flexible_donor = TRUE, cv = FALSE, save_donor = FALSE, warmup = 10, cooldown = 8, dosplit = TRUE, split = 30, parallel = FALSE, cores = NULL, verbose = TRUE )
obs |
"transfR" object of the gauged catchments |
sim |
"transfR" object of the ungauged catchments |
velocity |
character string describing the method to estimate the streamflow velocity.
See velocity for the available options ( |
distance |
character string describing the method to compute the distance between catchments.
See hdist for the available options ( |
gres |
resolution of spatial discretisation (number of points by km²) for Ghosh distance. See hdist for more details |
weightO |
weight given to the distance between outlets if distance method is "combined". See hdist for more details |
weightC |
weight given to the distance between centroids if distance method is "combined". See hdist for more details |
power |
exponent applied in the inverse distance weighting strategy. See weightr for more details |
ndonors |
maximum number of catchments to be used to simulate discharge of an ungauged catchment. See weightr for more details |
maxdist |
maximum distance between a gauged and an ungauged catchment to allow the net rainfall
to be transfered. This threshold is applied on the |
flexible_donor |
boolean indicating if the donor catchments can change during the simulation period according to the availability of discharge observations. See weightr for more details |
cv |
boolean indicating if cross validation evaluation should be done. If true, it will estimate
the net rainfall of every gauged catchments ( |
save_donor |
boolean indicating if the net rainfall of each of the |
warmup |
length of the warmup period. If no unit is provided, |
cooldown |
length of the period removed at the end of the simulation. If no unit is provided,
|
dosplit |
boolean, if true the inversion is performed by
subperiods of length defined by |
split |
length the subperiods if dosplit is true. If no unit is provided, |
parallel |
logical indicating if the computation should be parallelised |
cores |
the number of cores to use for parallel execution if |
verbose |
boolean indicating if information messages should be written to the console |
The function applies sequentially the following functions: velocity, uh, lagtime, rapriori, inversion, hdist, mixr and convolution. Please refer to the help of each of these functions and to transfR-package for a general description of the modelling approach.
The sim
object incremented by the new computed attributes
velocity, uh, lagtime, rapriori, inversion, hdist, mixr, convolution
data(Oudon) obs <- as_transfr(st = Oudon$obs[,,1:3], hl = Oudon$hl[1:3]) #gauged catchments sim <- as_transfr(st = Oudon$obs[,,4:6], hl = Oudon$hl[4:6]) #catchments considered as ungauged sim <- quick_transfr(obs, sim)
data(Oudon) obs <- as_transfr(st = Oudon$obs[,,1:3], hl = Oudon$hl[1:3]) #gauged catchments sim <- as_transfr(st = Oudon$obs[,,4:6], hl = Oudon$hl[4:6]) #catchments considered as ungauged sim <- quick_transfr(obs, sim)
A priori estimate of net rainfall as required for the inversion.
rapriori(Qobs, ...) ## Default S3 method: rapriori(Qobs, area, lagtime, deltat, ...) ## S3 method for class 'units' rapriori(Qobs, area, lagtime, deltat, ...) ## S3 method for class 'transfR' rapriori(Qobs, verbose = TRUE, ...)
rapriori(Qobs, ...) ## Default S3 method: rapriori(Qobs, area, lagtime, deltat, ...) ## S3 method for class 'units' rapriori(Qobs, area, lagtime, deltat, ...) ## S3 method for class 'transfR' rapriori(Qobs, verbose = TRUE, ...)
Qobs |
vector of discharge value or object of class |
... |
further arguments passed to or from other methods |
area |
drainage area of the catchment. If no unit is provided, |
lagtime |
lag time value of the catchment. If no unit is provided, |
deltat |
time step of the time series. If no unit is provided, |
verbose |
boolean indicating if information messages should be written to the console |
The function estimates an a priori of the net rainfall from Qobs. It converts Qobs to specific
discharge and removes the delay caused by transfer time in the river network (given by lagtime
and that could be estimated from the function lagtime). If an object of class transfR
is provided,
area
is estimated from its st
attribute. Results are stored as a new space-time attribute,
called "RnAp", in the transfR
object.
An object of the same class of Qobs
. If Qobs
is a transfR object,
the same transfR object incremented by the new "RnAp" computed attributes.
data(Oudon) icatch <- 1 Qobs <- Oudon$obs[["Qobs"]][,icatch] Qspec <- units::set_units(Qobs/st_area(st_geometry(Oudon$obs)[icatch]), "mm/h") deltat <- units::set_units(1,"h") uc <- velocity(hl = Oudon$hl[[icatch]]) uh <- uh(hl = Oudon$hl[[icatch]], uc = uc, deltat = deltat)$prob RnAp <- rapriori(Qobs = Qspec, lagtime = lagtime(hl = Oudon$hl[[icatch]], uc = uc), deltat = deltat)
data(Oudon) icatch <- 1 Qobs <- Oudon$obs[["Qobs"]][,icatch] Qspec <- units::set_units(Qobs/st_area(st_geometry(Oudon$obs)[icatch]), "mm/h") deltat <- units::set_units(1,"h") uc <- velocity(hl = Oudon$hl[[icatch]]) uh <- uh(hl = Oudon$hl[[icatch]], uc = uc, deltat = deltat)$prob RnAp <- rapriori(Qobs = Qspec, lagtime = lagtime(hl = Oudon$hl[[icatch]], uc = uc), deltat = deltat)
Estimate the unit hydrograph from a sample of hydraulic lengths and a streamflow velocity.
uh(hl, ...) ## Default S3 method: uh(hl, uc, deltat, ...) ## S3 method for class 'units' uh(hl, uc, deltat, ...) ## S3 method for class 'stars' uh(hl, ...) ## S3 method for class 'transfR' uh(hl, verbose = TRUE, ...)
uh(hl, ...) ## Default S3 method: uh(hl, uc, deltat, ...) ## S3 method for class 'units' uh(hl, uc, deltat, ...) ## S3 method for class 'stars' uh(hl, ...) ## S3 method for class 'transfR' uh(hl, verbose = TRUE, ...)
hl |
hydraulic length of class |
... |
further arguments passed to or from other methods |
uc |
streamflow velocity. If no unit is provided, |
deltat |
time step of the time series. If no unit is provided, |
verbose |
boolean indicating if information messages should be written to the console |
The function estimates the unit hydrograph from geomorphometric information.
A travel time to the outlet is estimated by assuming an average streamflow velocity (uc
)
within the river network and by applying uc
over the sample of hydraulic lengths (hl
).
The unit hydrograph is the probability distribution of this travel time to the outlet
given at each time step (deltat
).
A data.frame with vectors of class units, or if hl
is a transfR object,
the same transfR object incremented by the "uh" attribute.
data(Oudon) uh1 <- uh(hl=Oudon$hl[[1]], uc=units::set_units(0.5,"m/s"), deltat=units::set_units(1,"h")) plot(units::set_units(uh1$max_time,"h"), cumsum(uh1$prob), type = "b", xlab = "Travel~time", ylab = "Probability~of~non-exceedance") object <- as_transfr(st = Oudon$obs, hl = Oudon$hl) object <- velocity(object) object <- uh(object) plot(object, i = 1, attribute = c("uh"))
data(Oudon) uh1 <- uh(hl=Oudon$hl[[1]], uc=units::set_units(0.5,"m/s"), deltat=units::set_units(1,"h")) plot(units::set_units(uh1$max_time,"h"), cumsum(uh1$prob), type = "b", xlab = "Travel~time", ylab = "Probability~of~non-exceedance") object <- as_transfr(st = Oudon$obs, hl = Oudon$hl) object <- velocity(object) object <- uh(object) plot(object, i = 1, attribute = c("uh"))
Estimate streamflow velocity in average over the catchment.
velocity(hl, ...) ## Default S3 method: velocity(hl, lagtime, method = "loire2016", ...) ## S3 method for class 'units' velocity(hl, lagtime = NULL, method = "loire2016", ...) ## S3 method for class 'stars' velocity(hl, ...) ## S3 method for class 'transfR' velocity(hl, ...)
velocity(hl, ...) ## Default S3 method: velocity(hl, lagtime, method = "loire2016", ...) ## S3 method for class 'units' velocity(hl, lagtime = NULL, method = "loire2016", ...) ## S3 method for class 'stars' velocity(hl, ...) ## S3 method for class 'transfR' velocity(hl, ...)
hl |
hydraulic length of class |
... |
further arguments passed to or from other methods |
lagtime |
lag time of the catchment. If no unit is provided, |
method |
character string describing the method to estimate the velocity. One of "loire2016" (default), "brittany2013" or "lagtime" (see details). |
Estimate the average streamflow velocity of the catchment from three different approaches. Method "lagtime" estimates the velocity from the ratio between the mean hydraulic length and the lag time of the catchment. Method "loire2016" estimates the velocity from a regression based on hydraulic length only:
where and
have been calibrated over the Loire river basin (de Lavenne et al. 2016).
Method "brittany2013" used a similar regression calibrated for the French Brittany region where
and
(de Lavenne 2013).
A numeric value of class units, or if hl
is a transfR object,
the same transfR object incremented by the "uc" attribute.
de Lavenne A (2013). Modélisation hydrologique à base géomorphologique de bassins versants non jaugés par régionalisation et transposition d'hydrogramme. Ph.D. thesis, Agrocampus-Ouest Rennes. https://hal.inrae.fr/tel-02810356.
de Lavenne A, Skøien JO, Cudennec C, Curie F, Moatar F (2016). “Transferring measured discharge time series: Large-scale comparison of Top-kriging to geomorphology-based inverse modeling.” Water Resources Research, 52(7), 5555–5576. doi:10.1002/2016WR018716.
data(Oudon) velocity(Oudon$hl[[1]], method = "loire2016") object <- as_transfr(st = Oudon$obs, hl = Oudon$hl) object <- velocity(object) object$uc
data(Oudon) velocity(Oudon$hl[[1]], method = "loire2016") object <- as_transfr(st = Oudon$obs, hl = Oudon$hl) object <- velocity(object) object$uc
Estimate the weighting applied at each time step and to each gauged catchment (donors) for the calculation of the average net rainfall of an ungauged catchment
weightr(Rn, distances, ndonors = 5, donors, power = 1, flexible_donor = TRUE)
weightr(Rn, distances, ndonors = 5, donors, power = 1, flexible_donor = TRUE)
Rn |
net rainfall matrix of donor catchments (rows for time index, and columns for donors index) |
distances |
vector of the distances to each donor catchment (see hdist) |
ndonors |
maximum number of donor catchments to use |
donors |
vector of catchments id from which donors are selected. If empty, the |
power |
exponent applied in the inverse distance weighting function (see details) |
flexible_donor |
boolean indicating if the donor catchments can change during the simulation period according to the availability of discharge observations (see details) |
This function returns a matrix of weights for each time steps (rows) and each gauged catchments
(columns) for the calculation of the average net rainfall of an ungauged catchment (see mixr).
The weights are estimated by an inverse distance weighting function (de Lavenne et al. 2016):
where is the
distances
argument and is the
power
argument. The weights are rescaled
so the sum is equal to 1.
Two strategies to handle missing data in the Rn
matrix are possible.
If flexible_donor
is TRUE, donors catchments are redefined at each time steps, and are chosen among
the ones that are effectively gauged at this given time step. This aims to keep a constant number of donor
catchments throughout the simulation period.
If flexible_donor
is FALSE, the donor catchments are chosen once within all the gauged catchments,
regardless of missing data and remain the same throughout the entire simulation period. This stability of
donor catchments might however leads to a reduced number of donors (below ndonors
) during periods
of missing data.
A matrix with the same dimensions as Rn
.
de Lavenne A, Skøien JO, Cudennec C, Curie F, Moatar F (2016). “Transferring measured discharge time series: Large-scale comparison of Top-kriging to geomorphology-based inverse modeling.” Water Resources Research, 52(7), 5555–5576. doi:10.1002/2016WR018716.