Package 'transfR'

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

Help Index


Transfer of Hydrograph from Gauged to Ungauged Catchments

Description

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).

References

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 transfR object

Description

Create a transfR object or add new attributes to a transfR object.

Usage

as_transfr(
  object,
  st,
  uc,
  lagtime,
  surface,
  delineation,
  outlet,
  centroid,
  uh,
  hl
)

Arguments

object

object of class transfR

st

spatio-temporal arrays of class stars. Observed discharge must be described by the column name 'Qobs'. Time should be the first dimension, space the second dimension. If no unit is provided, Qobs is assumed to be in [m3/s] and RnInv is assumed to be in [mm/h] (or [mm/d] at daily time step).

uc

vector of the streamflow velocities of the catchments. If no unit is provided, uc is assumed to be in [m/s].

lagtime

vector of the lag times of the catchments. If no unit is provided, lagtime is assumed to be in [h].

surface

vector of the surfaces of the catchments. If no unit is provided, surface is assumed to be in [km2].

delineation

spatial layer of the boundary of the catchments of class sfc_POLYGON.

outlet

spatial layer of the outlets of the catchments of class sfc_POINT.

centroid

spatial layer of the centroids of the catchments of class sfc_POINT.

uh

list of the unit hydrographs of the catchments.

hl

hydraulic length of class stars, matrix or vector. If no unit is provided, hl is assumed to be in [m]. See details below.

Details

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).

Value

An object of class transfR.

References

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.

Examples

data(Oudon)
object <- as_transfr(st = Oudon$obs, hl = Oudon$hl)

Blavet French river dataset

Description

'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.

Format

'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.

Source

http://www.hydro.eaufrance.fr

https://www6.inrae.fr/ore_agrhys_eng

http://bdtopage.eaufrance.fr

References

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.

Examples

## 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)

Convolution of net rainfall with unit hydrograph

Description

Simulate the discharge by a convolution between the unit hydrograph and the net rainfall.

Usage

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,
  ...
)

Arguments

Rn

net rainfall vector or an object of class transfR

...

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 transfR object

Qcol

name of the space-time attribute for the net rainfall in the transfR object

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 save_donor was TRUE when using mixr

verbose

boolean indicating if information messages should be written to the console

Value

An object of the same class of Rn. If Rn is a transfR object, the same transfR object incremented by the new computed attributes.

Examples

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)

Geographical distance between catchments

Description

Calculate distances between two sets of catchments using their spatial support.

Usage

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, ...)

Arguments

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 parallel is TRUE. If not specified, the number of cores is set to the value of parallel::detectCores()

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"

Details

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).

Value

A matrix of class units with the catchments of x organised in rows and the catchments of y organised in columns.

References

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.

Examples

data(Oudon)
catchments <- st_geometry(Oudon$obs)
hdist(x = catchments[1:2], y = catchments[3:5], gres = 5, method = "rghosh")

Estimate net rainfall by inversion

Description

Estimate net rainfall by inverse modelling, where the model is a convolution between net rainfall and a unit hydrograph in order to simulate discharge.

Usage

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, ...)

Arguments

Qobs

discharge vector or object of class transfR. If no unit is provided, Qobs is assumed to be in [mm/h]

...

further arguments passed to or from other methods

uh

unit hydrograph vector

RnAp

net rainfall a priori. If no unit is provided, RnAp is assumed to be in [mm/h]

deltat

time step of the time series. If no unit is provided, deltat is assumed to be in [min]

Bd

parameter used to maintain a minimum value of standart deviation for low discharge values. If no unit is provided, Bd is assumed to be in [mm/h]

Dd

decorrelation time of discharge errors. If no unit is provided, Dd is assumed to be in [h]

Bp

parameter used to maintain a minimum value of standart deviation for low net rainfall values. If no unit is provided, Bp is assumed to be in [mm/h]

Tp

decorrelation time of net rainfall errors. If no unit is provided, Tp is assumed to be in [h]

parameter equivalent to the coefficient of variation of the discharge measurement error. If no unit is provided, Ad is assumed to be dimensionless

Ap

parameter equivalent to the coefficient of variation of the net rainfall error. If no unit is provided, Ap is assumed to be dimensionless

warmup

length of the warmup period. If no unit is provided, warmup is assumed to be in [days]

cooldown

length of the period removed at the end of the simulation. If no unit is provided, cooldown is assumed to be in [days]

dosplit

boolean, if true the inversion is performed by subperiods of length defined by split

split

length the subperiods if dosplit is true. If no unit is provided, split is assumed to be in [days]

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 parallel is TRUE. If not specified, the number of cores is set to the value of parallel::detectCores()

verbose

boolean indicating if information messages should be written to the console

Details

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".

Value

An object of the same class of Qobs. If Qobs is a transfR object, the same transfR object incremented by the new computed attributes.

References

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.

See Also

rapriori

Examples

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)

Lag time estimation

Description

Estimate the lag time of the catchment.

Usage

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, ...)

Arguments

hl

hydraulic length of class transfR or stars or matrix or vector. If no unit is provided, hl is assumed to be in [m].

...

further arguments passed to or from other methods

uc

streamflow velocity. If no unit is provided, uc is assumed to be in [m/s].

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.

Details

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).

Value

A numeric value of class units, or if hl is a transfR object, the same transfR object incremented by the "lagtime" attribute.

Examples

data(Oudon)
icatch <- 1
lagtime(Oudon$hl[[icatch]], uc = units::set_units(0.5, "m/s"))

Transfer of net rainfall to ungauged catchments

Description

Combine the net rainfall of gauged catchments to simulate the net rainfall of an ungauged catchment.

Usage

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
)

Arguments

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 mdist is not provided. Possible values are "ghosh", "rghosh", "points", "centroids", "combined" as available in the function hdist

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 distance is "combined" (see the function hdist)

weightC

weight given to the distance between centroids if distance is "combined" (see the function hdist)

parallel

logical indicating if the computation should be parallelised

cores

the number of cores to use for parallel execution if parallel is TRUE. If not specified, the number of cores is set to the value of parallel::detectCores()

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 ndonors closest catchments are used

maxdist

maximum distance between a gauged and an ungauged catchment to allow the net rainfall to be transfered. This threshold is applied on the mdist distance matrix. If no units is provided, maxdist is assumed to be in [m].

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 (obs) as if they were ungauged (leave-one-out evaluation)

save_donor

boolean indicating if the net rainfall of each of the ndonors catchments should be stored in the sim object for further analysis. If true, it is adding three new space-time attributes in the sim object called "RnDonor", "Idonor" and "Wdonor" describing the net rainfall, the id and the weight of the donor catchments respectively

verbose

boolean indicating if information messages should be written to the console

Details

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 ii is a weighted average of the net rainfalls of ndonors gauged catchments jj:

Rni=Σj=1ndonorsRnjλjR_n^i =\Sigma_{j=1}^{ndonors} R_n^j \cdot \lambda_j

where λj\lambda_j are defined by an inverse distance weighting function (see weightr).

Value

The sim object incremented by the new computed attributes.

See Also

hdist, weightr

Examples

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 French river dataset

Description

'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.

Format

'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).

Source

http://www.hydro.eaufrance.fr


Plot transfR object

Description

Plot transfR object.

Usage

## 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,
  ...
)

Arguments

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

Examples

data(Oudon)
object <- as_transfr(st = Oudon$obs, hl = Oudon$hl)
plot(object, attribute = "Qobs")

Transfer of observed discharge from gauged catchments to ungauged catchments

Description

Wrap up all the modelling steps into one function for a quick implementation of this R package.

Usage

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
)

Arguments

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 (method argument)

distance

character string describing the method to compute the distance between catchments. See hdist for the available options (method argument)

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 mdist distance matrix. If no units is provided, maxdist is assumed to be in [m]. See mixr for more details

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 (obs) as if they were ungauged (leave-one-out evaluation)

save_donor

boolean indicating if the net rainfall of each of the ndonors catchments should be stored in the sim object for further analysis. If true, it is adding three new space-time attributes in the sim object called "RnDonor", "Idonor" and "Wdonor" describing the net rainfall, the id and the weight of the donor catchments respectively. See mixr for more details

warmup

length of the warmup period. If no unit is provided, warmup is assumed to be in [days]. See inversion for more details

cooldown

length of the period removed at the end of the simulation. If no unit is provided, cooldown is assumed to be in [days]. See inversion for more details

dosplit

boolean, if true the inversion is performed by subperiods of length defined by split. See inversion for more details

split

length the subperiods if dosplit is true. If no unit is provided, split is assumed to be in [days]. See inversion for more details

parallel

logical indicating if the computation should be parallelised

cores

the number of cores to use for parallel execution if parallel is TRUE. If not specified, the number of cores is set to the value of parallel::detectCores()

verbose

boolean indicating if information messages should be written to the console

Details

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.

Value

The sim object incremented by the new computed attributes

See Also

velocity, uh, lagtime, rapriori, inversion, hdist, mixr, convolution

Examples

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)

Net rainfall a priori estimation

Description

A priori estimate of net rainfall as required for the inversion.

Usage

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, ...)

Arguments

Qobs

vector of discharge value or object of class transfR. If no unit is provided, Qobs is assumed to be in [m3/s].

...

further arguments passed to or from other methods

area

drainage area of the catchment. If no unit is provided, area is assumed to be in [km2].

lagtime

lag time value of the catchment. If no unit is provided, lagtime is assumed to be in [h].

deltat

time step of the time series. If no unit is provided, deltat is assumed to be in [min].

verbose

boolean indicating if information messages should be written to the console

Details

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.

Value

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.

Examples

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)

Unit hydrograph estimation

Description

Estimate the unit hydrograph from a sample of hydraulic lengths and a streamflow velocity.

Usage

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, ...)

Arguments

hl

hydraulic length of class stars, matrix, vector or transfR. If no unit is provided, hl is assumed to be in [m].

...

further arguments passed to or from other methods

uc

streamflow velocity. If no unit is provided, uc is assumed to be in [m/s].

deltat

time step of the time series. If no unit is provided, deltat is assumed to be in [min].

verbose

boolean indicating if information messages should be written to the console

Details

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).

Value

A data.frame with vectors of class units, or if hl is a transfR object, the same transfR object incremented by the "uh" attribute.

Examples

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"))

Streamflow velocity estimation

Description

Estimate streamflow velocity in average over the catchment.

Usage

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, ...)

Arguments

hl

hydraulic length of class stars, matrix, vector or transfR. If no unit is provided, hl is assumed to be in [m].

...

further arguments passed to or from other methods

lagtime

lag time of the catchment. If no unit is provided, lagtime is assumed to be in [h].

method

character string describing the method to estimate the velocity. One of "loire2016" (default), "brittany2013" or "lagtime" (see details).

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:

ahlba \cdot hl^b

where a=4.38e4a=4.38e-4 and b=0.69b=0.69 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 a=8.59e4a=8.59e-4 and b=0.61b=0.61 (de Lavenne 2013).

Value

A numeric value of class units, or if hl is a transfR object, the same transfR object incremented by the "uc" attribute.

References

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.

Examples

data(Oudon)
velocity(Oudon$hl[[1]], method = "loire2016")

object <- as_transfr(st = Oudon$obs, hl = Oudon$hl)
object <- velocity(object)
object$uc

Weights of donor catchments

Description

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

Usage

weightr(Rn, distances, ndonors = 5, donors, power = 1, flexible_donor = TRUE)

Arguments

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 ndonors closest catchments are used

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)

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 λ\lambda are estimated by an inverse distance weighting function (de Lavenne et al. 2016):

λi=1dip\lambda_i=\frac{1}{d_i^p}

Σi=1ndonorsλi=1\Sigma_{i=1}^{ndonors}\lambda_i=1

where dd is the distances argument and pp 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.

Value

A matrix with the same dimensions as Rn.

References

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.

See Also

hdist, mixr