Preparation of input data: creation of a stars object

The hardware and bandwidth for this mirror is donated by METANET, the Webhosting and Full Service-Cloud Provider.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]metanet.ch.

Alban de Lavenne

2023-10-02

Any time series in the transfR package is supposed to be georeferenced. In order to use your discharge observations in transfR, two inputs are thus required: the discharge time series and a georeferenced vector layer describing the location of this gauged catchments. These two attributes will be merged into one R object of class stars. This vignette provides some guidance to create this object from common input formats.

For the sake of the example, we will create a shapefile and a text file from the ‘Oudon’ example dataset provided with the transfR package:

library(transfR)
data(Oudon)

wd <- tempdir(check = TRUE)
st_write(st_sf(ID = paste0("ID", 1:6), geom = st_geometry(Oudon$obs)), 
         dsn = file.path(wd, "catchments.shp"), delete_layer = TRUE)
write.table(data.frame(DateTime = format(st_get_dimension_values(Oudon$obs,1),
                                         "%Y-%m-%d %H:%M:%S"), 
                       ID1 = Oudon$obs$Qobs[,1], 
                       ID2 = Oudon$obs$Qobs[,2], 
                       ID3 = Oudon$obs$Qobs[,3], 
                       ID4 = Oudon$obs$Qobs[,4], 
                       ID5 = Oudon$obs$Qobs[,5], 
                       ID6 = Oudon$obs$Qobs[,6]), 
            file = file.path(wd, "discharge.txt"), 
            col.names = TRUE, row.names = FALSE, sep = ";", quote = FALSE)

1. Reading a vector layer with sf

The spacial vector layer describes the location of the catchments. It could be the catchments delineation, outlet or centroid. However, catchment delineation allows a better assessment of the distances between them (de Lavenne et al. 2016). It is advised to use the sf package to load this layer.

library(sf)
catchments <- st_read(file.path(wd, "catchments.shp"), "catchments", stringsAsFactors = FALSE)
obs_sf <- catchments[1:5,] # Gauged catchments
sim_sf <- catchments[6,]   # Ungauged catchments

2. Reading a data frame of time series

It is advised to provide the units of your discharge time series using the units package.

library(units)
Q <- read.table(file.path(wd, "discharge.txt"), header = TRUE, sep = ";", 
                colClasses = c("character", rep("numeric", 6)))
Qmatrix  <- as.matrix(Q[,-1])
Qmatrix  <- set_units(Qmatrix, "m^3/s")

3. Creating a stars object

These time series and the spacial vector layer are merged into one stars object. Make sure that both are organised in the same order. The stars object will have two dimensions (time and space) and one attribute (discharge observation) for gauged catchments. The ungauged catchments will have the same dimensions but no attribute for the moment.

library(stars)
Qmatrix  <- Qmatrix[,obs_sf$ID] #to have the same order as in the spacial data layer
obs_st   <- st_as_stars(list(Qobs = Qmatrix), 
                            dimensions = st_dimensions(time = as.POSIXct(Q$DateTime, tz="UTC"), 
                                                       space = obs_sf$geometry))
sim_st   <- st_as_stars(dimensions = st_dimensions(time = as.POSIXct(Q$DateTime, tz="UTC"), 
                                                       space = sim_sf$geometry))

4. Creating a transfr object

These stars objects can finally be used to create objects of class transfR by using the function as_transfr() (argument st) and perform simulations.

obs <- as_transfr(st = obs_st, hl = Oudon$hl[1:5])
sim <- as_transfr(st = sim_st, hl = Oudon$hl[6])

A transfer of hydrograph from the gauged catchments to the ungauged catchments can then quickly be implemented using the quick_transfr() function.

sim <- quick_transfr(obs, sim, parallel = TRUE, cores = 2)

The simulated time series will be available in its stars object as new attributes.

sim$st
#> stars object with 2 dimensions and 2 attributes
#> attribute(s):
#>                    Min.    1st Qu.     Median      Mean   3rd Qu.       Max.
#> RnSim [mm/h] 0.02816396 0.05254076 0.07866921 0.1007728 0.1221585  0.3406501
#> Qsim [m^3/s] 1.15369209 1.93774673 2.92630993 3.7211282 4.5184092 11.9112466
#>              NA's
#> RnSim [mm/h]  444
#> Qsim [m^3/s]  466
#> dimension(s):
#>       from   to         offset   delta                refsys point
#> time     1 2185 2019-12-01 UTC 1 hours               POSIXct FALSE
#> space    1    1             NA      NA RGF93 v1 / Lambert-93 FALSE
#>                               values
#> time                            NULL
#> space POLYGON ((404349 6766262, 4...

References

de Lavenne, A., J. O. Skøien, C. Cudennec, F. Curie, and F. Moatar. 2016. “Transferring Measured Discharge Time Series: Large-Scale Comparison of Top-Kriging to Geomorphology-Based Inverse Modeling.” Water Resources Research 52 (7): 5555–76. https://doi.org/10.1002/2016WR018716.

These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.