Preparation of input data: creation of a stars object

Alban de Lavenne

2026-07-24

All time series in the transfR package must be georeferenced. To use discharge observations in transfR, two inputs are therefore required: the discharge time series and a georeferenced vector layer describing the locations of the gauged catchments. These two inputs are merged into one R object of class stars. This vignette provides guidance on creating 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 spatial vector layer describes the locations of the catchments. It can contain catchment delineations, outlets or centroids. However, catchment delineations allow a better assessment of the distances between catchments (de Lavenne et al. 2016). The sf package can be used 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

The units of the discharge time series should be provided 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 spatial 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 spatial 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 then be used to create objects of class transfR with the as_transfr() function (argument st) and to perform simulations.

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

Hydrographs can then be transferred from the gauged catchments to the ungauged catchments using the quick_transfr() function.

sim <- quick_transfr(obs, sim)

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. NAs
#> RnSim [mm/h] 0.02794408 0.0521163 0.07829075 0.1004202 0.121308  0.3537189 444
#> Qsim [m^3/s] 1.14390830 1.9207286 2.91719974 3.7085267 4.487043 12.2550280 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.