mixr: Transfer of net rainfall to ungauged catchments

In transfR: Transfer of Hydrograph from Gauged to Ungauged Catchments

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,
  msim = NULL,
  distance = "rghosh",
  gres = 5,
  weightO = 0.8,
  weightC = 0.2,
  similarity,
  similarity_obs,
  mdist_obs,
  FUN = "invKGE",
  symmetrize = mean,
  parallel = FALSE,
  cores = NULL,
  power = c(1, 0.5),
  ndonors = 5,
  donors = NULL,
  maxdist = 50000,
  min_ndonors = 3,
  flexible_donor = TRUE,
  two_steps = FALSE,
  cv = FALSE,
  save_donor = FALSE,
  save_model = FALSE,
  verbose = TRUE,
  ...
)

Arguments

obs	"transfR" object of the gauged catchments
sim	"transfR" object of the ungauged catchments
mdist	the geographical distance matrix between gauged and ungauged catchments, as computed by the function hdist, used for donor selection
msim	the similarity matrix of net rainfall time series for gauged catchments, as computed by rsimilarity. It serves as the target variable in a multivariate model that predicts this similarity at ungauged locations using several predictors (see the similarity argument) and optimizes the donors' weighting strategy. Thus, msim is required only if similarity and similarity_obs are lists containing several predictors
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^2) 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)
similarity	a hydrological similarity matrix between gauged and ungauged catchments used for donor weighting (1/mdist^power[1] is used if not provided). Gauged catchments should be in rows, ungauged catchments in columns. Several predictors of hydrological similarity can be provided in a list of matrices in order to be used by a multivariate model for predicting similarity between a gauged and an ungauged catchment (see predictors of the rsimilarity_model function).
similarity_obs	list of square matrices of hydrological similarity predictors between gauged catchments in order to train a multivariate model for predicting similarity (msim). Similar to similarity but between gauged catchments only. similarity will be used instead of similarity_obs if cv is TRUE
mdist_obs	the geographical distance matrix among gauged catchments, computed by the function hdist, used for training a first model of hydrological similarity
FUN	either a function or a character string specifying the name of a predifined function to quantify the similarity of two net rainfall time series. See rsimilarity for more details
symmetrize	a function to combine FUN(Rn[,i],Rn[,j]) and FUN(Rn[,j],Rn[,i]) into one similarity value (typically if FUN=KGE, KGE(Rn[,i],Rn[,j])!=KGE(Rn[,j],Rn[,i])). Default is mean
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	exponents. The first vector value is used in the inverse distance weighting strategy (as defined by the function weightr) and the second vector value is used during computation of Rn similarities (as defined by the function rsimilarity_model)
ndonors	maximum number of catchments to be used to simulate discharge of an ungauged catchment as defined by the function weightr
donors	list of vectors indicating the catchment IDs from which donors are selected for each ungauged catchments. 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 transferred. This threshold is applied on the mdist distance matrix. If no units is provided, maxdist is assumed to be in [m].
min_ndonors	minimum number of gauged catchments to start using rsimilarity_model to build a similarity model of Rn time series for the weighting strategy. So this argument is only used when similarity is a list of matrices. It cannot be less than 3. If less than min_ndonors donors are found inverse distance weighting is applied using mdist
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
two_steps	boolean indicating if a first model of hydrological similarity should be built first on geographical distances. Residuals of this first model will be predicted from predictors provided by similarity and similarity_obs in a second model (see first_model of rsimilarity_model)
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
save_model	boolean indicating whether additional results of the local similarity model should be saved. If true, then a list of data frames of observed and simulated similarities among gauged catchments neighbouring each ungauged catchment will be available in the "model_training" attribute of the output
verbose	boolean indicating if information messages should be written to the console
...	other arguments to be passed to rsimilarity_model if similarity is a list of matrices

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

R_n^i =\Sigma_{j=1}^{ndonors} R_n^j \cdot \lambda_j

where \lambda_j are defined by an inverse distance weighting function (see weightr). If similarity is a list of predictors of hydrological similarity, then \lambda_j are provided by rsimilarity_model.

Value

The sim object incremented by the new computed attributes.

See Also

hdist, weightr, rsimilarity_model, rsimilarity

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

transfR documentation built on April 4, 2025, 2:41 a.m.