Nothing
#' Create transfR object
#'
#' Create a transfR object or add new attributes to a transfR object.
#' @name as_transfr
#' @param object object of class \code{transfR}
#' @param st spatio-temporal array of class \code{stars}. Observed discharge must be identified 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 [m^3/s]
#' and RnInv is assumed to be in [mm/h] (or [mm/d] at daily time step).
#' @param uc vector of the streamflow velocities of the catchments. If no unit is provided, \code{uc} is assumed to be in [m/s].
#' @param lagtime vector of the lag times of the catchments. If no unit is provided, \code{lagtime} is assumed to be in [h].
#' @param surface vector of the surfaces of the catchments. If no unit is provided, \code{surface} is assumed to be in [km^2].
#' @param delineation spatial layer of the boundary of the catchments of class \code{sfc_POLYGON}.
#' @param outlet spatial layer of the outlets of the catchments of class \code{sfc_POINT}.
#' @param centroid spatial layer of the centroids of the catchments of class \code{sfc_POINT}.
#' @param uh list of the unit hydrographs of the catchments.
#' @param hl list of hydraulic length objects, one per catchment. Each element must be a \code{stars} object,
#' a numeric \code{matrix} or a numeric vector. For a single catchment, one object can be supplied directly.
#' If no unit is provided, \code{hl} is assumed to be in [m]. See details below.
#' @return An object of class transfR.
#' @details This function creates an object of class \code{transfR} or adds new attributes to an existing \code{transfR} object.
#' It can be used to gather and organise most of the inputs and outputs of the other functions,
#' like streamflow velocities, unit hydrographs, a priori estimates of net rainfall, inversions and simulations for every catchment.
#'
#' This function can be used to organise the two user inputs required for a conventional use of the package, namely \code{st}
#' and \code{hl}. The hydraulic lengths are defined as the flow path length from each pixel to the outlet within
#' the river network \insertCite{Cudennec2004,Aouissi2013}{transfR}. 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 packages can extract them from a digital elevation model,
#' such as GRASS toolkits \insertCite{Jasiewicz2011}{transfR},
#' Whitebox GAT (\insertCite{@see @Lindsay2016;textual}{transfR} or \href{https://github.com/jblindsay/whitebox-tools}{WhiteboxTools}),
#' TauDEM (D. Tarboton, Utah State University)
#' or online services (\insertCite{@see @Squividant2015;textual}{transfR} for catchment delineation in the Brittany French region).
#' @examples
#' data(Oudon)
#' object <- as_transfr(st = Oudon$obs, hl = Oudon$hl)
#' @import sf stars
#' @importFrom units set_units
#' @references
#' \insertRef{Aouissi2013}{transfR}
#'
#' \insertRef{Cudennec2004}{transfR}
#'
#' \insertRef{Jasiewicz2011}{transfR}
#'
#' \insertRef{Lindsay2016}{transfR}
#'
#' \insertRef{Squividant2015}{transfR}
#' @export
as_transfr <- function(object, st, uc, lagtime, surface, delineation, outlet, centroid, uh, hl){
#--Create transfR object
if(missing(object)){
object <- list()
class(object)=c("transfR","list")
}
#--Adding attributes to transfR object
if(!missing(st)){
#--Checking class
if(!inherits(st, "stars")) stop("The class of 'st' must be 'stars'.")
if(!all(st_geometry_type(st) == c("POLYGON"))) stop("The geometry type of 'st' must be POLYGON.")
#--Checking attributes
if(length(names(st))>0&!any(names(st)%in%c("Qobs","RnInv","RnSim"))) stop("No recognised column name was found in 'st'. Provide a 'Qobs', 'RnInv' or 'RnSim' time series.")
# if("Qobs"%in%names(st)) st[[which(names(st)=="Qobs")]] <- units::set_units(st[[which(names(st)=="Qobs")]],"m^3/s")
#--Deducing time step
deltat <- unique(as.numeric(difftime(st_get_dimension_values(st,1)[-1], st_get_dimension_values(st,1)[-dim(st)[1]], units = "mins")))
if(length(deltat)==1){
deltat <- units::set_units(deltat, "min")
object$deltat <- deltat
}else{stop(paste0("Time step must be constant. Detected time steps: ", paste0(deltat, "min", collapse = ", "), "."))}
#--Set up units
if("Qobs"%in%names(st)) st[["Qobs"]] <- units::set_units(st[["Qobs"]],"m^3/s")
if(object$deltat==units::set_units(1,"day")){rn_units <- units::as_units("mm/d")}else{rn_units <- units::as_units("mm/h")}
if("RnInv"%in%names(st)) st[["RnInv"]] <- units::set_units(st[["RnInv"]],rn_units,mode="standard")
object$st <- st
}
#--Checking new attributes
if(!missing(uc)){
if(!(inherits(uc, "numeric")|inherits(uc, "units"))) stop("The class of 'uc' must be numeric or units.")
if(length(uc)!=dim(object$st)[2]) stop(paste0("Length of 'uc' is ",length(uc)," but there are ",dim(object$st)[2]," spatial features."))
uc <- units::set_units(uc,"m/s")
object$uc <- uc
}
if(!missing(lagtime)){
if(!(inherits(lagtime, "numeric")|inherits(lagtime, "units"))) stop("The class of 'lagtime' must be numeric or units.")
if(length(lagtime)!=dim(object$st)[2]) stop(paste0("Length of 'lagtime' is ",length(lagtime)," but there are ",dim(object$st)[2]," spatial features."))
lagtime <- units::set_units(lagtime,"h")
object$lagtime <- lagtime
}
if(!missing(surface)){
if(!(inherits(surface, "numeric")|inherits(surface, "units"))) stop("The class of 'surface' must be numeric or units.")
if(length(surface)!=dim(object$st)[2]) stop(paste0("Length of 'surface' is ",length(surface)," but there are ",dim(object$st)[2]," spatial features."))
surface <- units::set_units(surface,"km2")
object$surface <- surface
}
if(!missing(delineation)){
if(!inherits(delineation, "sfc_POLYGON")) stop("The class of 'delineation' must be sfc_POLYGON")
if(length(delineation)!=dim(object$st)[2]) stop(paste0("Length of 'delineation' is ",length(delineation),", but ",dim(object$st)[2]," spatial features were expected."))
object$delineation <- delineation
}
if(!missing(outlet)){
if(!inherits(outlet, "sfc_POINT")) stop("The class of 'outlet' must be sfc_POINT")
if(length(outlet)!=dim(object$st)[2]) stop(paste0("Length of 'outlet' is ",length(outlet),", but ",dim(object$st)[2]," spatial features were expected."))
object$outlet <- outlet
}
if(!missing(centroid)){
if(!inherits(centroid, "sfc_POINT")) stop("The class of 'centroid' must be sfc_POINT")
if(length(centroid)!=dim(object$st)[2]) stop(paste0("Length of 'centroid' is ",length(centroid),", but ",dim(object$st)[2]," spatial features were expected."))
object$centroid <- centroid
}
if(!missing(uh)){
if(!inherits(uh, "list")) stop("The class of 'uh' must be a list")
if(length(uh)!=dim(object$st)[2]) stop(paste0("Length of 'uh' is ",length(uh)," but there are ",dim(object$st)[2]," spatial features."))
classes <- c("numeric","units")
if(any(!unlist(lapply(uh,class))%in%classes)) stop(paste("Variables contained in the list of 'uh' can only be",paste(classes,collapse=" or ")))
object$uh <- uh
}
if(!missing(hl)){
is_valid_hl <- function(x) inherits(x,"stars") || (is.numeric(x) && (is.matrix(x) || is.null(dim(x))))
if(is_valid_hl(hl)) hl <- list(hl)
if(!inherits(hl, "list")) stop("'hl' must be a list or a single hydraulic length object")
if(length(hl)!=dim(object$st)[2]) stop(paste0("Length of 'hl' is ",length(hl)," but there are ",dim(object$st)[2]," spatial features."))
if(!all(vapply(hl,is_valid_hl,FALSE))) stop("Elements of 'hl' must be stars objects, numeric matrices or numeric vectors")
object$hl <- lapply(hl,function(x){
if(inherits(x,"stars")) x[[1]] <- units::set_units(x[[1]],"m") else x <- units::set_units(x,"m")
x
})
if(any(vapply(object$hl,function(x){
if(inherits(x,"stars")) x <- x[[1]]
any(x < units::set_units(0,"m"),na.rm=TRUE)
},FALSE))) stop("Negative values of 'hl' detected.")
}
return(object)
}
Any scripts or data that you put into this service are public.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.