Title: Terrestrial Water Cycle
Version: 0.0.2
Description: An open-access tool/framework that constitutes the core functions to analyze terrestrial water cycle data across various spatio-temporal scales.
Depends: R (≥ 4.0.0)
License: GPL-3
Encoding: UTF-8
RoxygenNote: 7.3.2
Imports: data.table, doParallel, foreach, lubridate, magrittr, methods, ncdf4, parallel, raster, sf, sp, stats, utils
URL: https://github.com/imarkonis/twc
BugReports: https://github.com/imarkonis/twc/issues
SystemRequirements: PROJ (>= 6, https://proj.org/download.html), GDAL (>= 3, https://gdal.org/download.html), NetCDF(>= 4, https://www.unidata.ucar.edu/software/netcdf/).
Suggests: testthat (≥ 3.0.0)
Config/testthat/edition: 3
NeedsCompilation: no
Packaged: 2025-04-02 14:24:21 UTC; mirovago
Author: Mijael Rodrigo Vargas Godoy ORCID iD [aut, cre], Yannis Markonis ORCID iD [aut]
Maintainer: Mijael Rodrigo Vargas Godoy <mirovago@gmail.com>
Repository: CRAN
Date/Publication: 2025-04-02 15:50:02 UTC

twc: Terrestrial Water Cycle

Description

twc is an R package that that constitutes the core functions to analyze terrestrial water cycle data across various spatio-temporal scales.

Author(s)

Coded by: Mijael Rodrigo Vargas Godoy vargas_godoy@fzp.czu.cz

Conceptual design by: Mijael Rodrigo Vargas Godoy vargas_godoy@fzp.czu.cz and Yannis Markonis markonis@fzp.czu.cz

See Also

Useful links:


Pipe operator

Description

See magrittr::%>% for details.

Usage

lhs %>% rhs

Arguments

lhs

A value or the magrittr placeholder.

rhs

A function call using the magrittr semantics.

Value

The result of calling 'rhs(lhs)'.


Ensure getZ output are dates

Description

Function to fix dates

Usage

aux_date(x)

Arguments

x

output from getZ()

Value

Date


Crop precipitation data sets

Description

The function crop_data crops the data sets using a shapefile mask.

Usage

crop_data(x, y)

## S4 method for signature 'Raster'
crop_data(x, y)

## S4 method for signature 'data.table'
crop_data(x, y)

## S4 method for signature 'character'
crop_data(x, y)

Arguments

x

Raster* object; data.table (see details); filename (character; see details)

y

filename (character). Path to a *.shp file

Details

If 'x' is a data.table, its columns should be named: "lon", "lat", "date", and "value"

If 'x' is a filename, it should point to a *.nc file.

Value

Raster* object; data.table

Examples

## Not run: 
download_data("gldas-vic", tempdir(), timestep = "yearly")
r <- raster::brick(paste0(tempdir(),
"/gldas-vic_tp_mm_land_194801_201412_025_yearly.nc"))
s <- crop_data(r, "cze.shp")

## End(Not run)

Field mean

Description

The function fldmean computes the spatial weighted average for each timestep.

Usage

fldmean(x)

## S4 method for signature 'Raster'
fldmean(x)

## S4 method for signature 'data.table'
fldmean(x)

## S4 method for signature 'character'
fldmean(x)

Arguments

x

Raster* object; data.table (see details); filename (character, see details)

Details

If 'x' is a data.table, its columns should be named: "lon", "lat", "date", and "value"

If 'x' is a filename, it should point to a *.nc file.

Value

data.table

Examples

## Not run: 
download_data("gldas-vic", tempdir(), timestep = "yearly")
r <- raster::brick(paste0(tempdir(),
"/gldas-vic_tp_mm_land_194801_201412_025_yearly.nc"))
s <- fldmean(r)

## End(Not run)

Show data content

Description

The function infoNC displays the specification of the desired file.

Usage

infoNC(x)

## S4 method for signature 'Raster'
infoNC(x)

## S4 method for signature 'character'
infoNC(x)

Arguments

x

Raster* Object; character

Value

character


Multiply by days per month

Description

The function muldpm multiplies the value by days per month.

Usage

muldpm(x)

## S4 method for signature 'Raster'
muldpm(x)

## S4 method for signature 'data.table'
muldpm(x)

## S4 method for signature 'character'
muldpm(x)

Arguments

x

Raster* object; data.table (see details); filename (character, see details)

Details

'x' object with monthly data in [units/day]

If 'x' is a data.table, its columns should be named: "lon", "lat", "date", and "value"

If 'x' is a filename, it should point to a *.nc file.

Value

Raster* object; data.table

Examples

## Not run: 
tavg_brick <- raster::brick('terraclimate_tavg.nc')
pet_od <- pet(method = "od", tavg = tavg_brick)
pet_od <- muldpm(pet_od)

## End(Not run)

Nash–Sutcliffe Efficiency

Description

Function for calculating the Nash–Sutcliffe efficiency.

Usage

nse(x, ref)

Arguments

x

a data.table generated by fldmean

ref

a data.table with data used for evaluation

Value

numeric


Masks data

Description

Function for various masks.

Usage

pRecipe_masks()

Value

data.table


Ensemble representativeness ranking

Description

The function rank_repres ranks the elements of a dataset ensemble in terms of a representativeness metric.

Usage

rank_repres(data, method = "all", ensemble = "median")

Arguments

data

data.table with three variables: dataset, date, value

method

character with seven options: mean, var (variance), slope, kge (Kling–Gupta Efficiency), tss (Taylor Skill Score), kld (Kullback–Leibler Divergence), all (default)

ensemble

character with two options: mean, median (default)

Details

data is a data.table (time, value) method relates to the metric used to estimate the similarity to the ensemble mean/median. Can be mean, variance, correlation, slope, Kling–Gupta efficiency, Taylor skill score, Kullback–Leibler divergence, and all (for returning all of them)

Value

data.table 2-column (dataset, repres_metric) or 8-column (dataset, mean, variance, ...) in case of method = all

Examples

## Not run: 
download_data("gldas-vic", tempdir(), timestep = "yearly")
download_data("gpcc", tempdir(), timestep = "yearly")
download_data("ghcn", tempdir(), timestep = "yearly")
r1 <- raster::brick(paste0(tempdir(),
"/gldas-vic-v2-0_tp_mm_land_194801_201412_025_yearly.nc"))
s1 <- fldmean(r1)
s1$dataset <- "gldas-vic"
r2 <- raster::brick(paste0(tempdir(),
"/gpcc-v2022_tp_mm_land_198201_202012_025_yearly.nc"))
s2 <- fldmean(r2)
s2$dataset <- "gpcc"
r3 <- raster::brick(paste0(tempdir(),
"/ghcn-v2_tp_mm_land_190001_201505_025_yearly.nc"))
s3 <- fldmean(r2)
s3$dataset <- "ghcn"
dt <- rbind(r1, r2, r3)
dr <- rank_repres(dt[year(date) >= 1991 & year(date) <= 2012, .(dataset, date, value)])

## End(Not run)

Spatial aggregation

Description

The function remap aggregates data into a new grid resolution.

Usage

remap(x, y)

## S4 method for signature 'Raster'
remap(x, y)

## S4 method for signature 'data.table'
remap(x, y)

## S4 method for signature 'character'
remap(x, y)

Arguments

x

Raster* object; data.table (see details); filename (character, see details)

y

numeric

Details

If 'x' is a data.table, its columns should be named: "lon", "lat", "date", and "value"

If 'x' is a filename, it should point to a *.nc file.

Value

Raster* object; data.table

Examples

## Not run: 
download_data("gldas-vic", tempdir(), timestep = "yearly")
r <- raster::brick(paste0(tempdir(),
"/gldas-vic_tp_mm_land_194801_201412_025_yearly.nc"))
s <- remap(r, 1)

## End(Not run)

Save .nc file

Description

Function to save data compatible with pRecipe in .nc file

Usage

saveNC(x, file, name = "tp", longname = "Total precipitation", units = "mm")

Arguments

x

Raster* object

file

character

name

character

longname

character

units

character

Value

No return value, called to save a file

Examples

## Not run: 
save_nc(dummie_brick, "gpcp_tp_mm_global_197901_202205_025_monthly.nc")

## End(Not run)

Select Longitude Latitude Box

Description

The function sellonlatbox subsets the data in space within a bounding box.

Usage

sellonlatbox(x, y)

## S4 method for signature 'Raster'
sellonlatbox(x, y)

## S4 method for signature 'data.table'
sellonlatbox(x, y)

## S4 method for signature 'character'
sellonlatbox(x, y)

Arguments

x

Raster* object; data.table (see details); filename (character, see details)

y

numeric. Bounding box in the form: (xmin, xmax, ymin, ymax)

Details

If 'x' is a data.table, its columns should be named: "lon", "lat", "date", and "value"

If 'x' is a filename, it should point to a *.nc file.

Value

Raster* object; data.table


Select Years

Description

The function selyear subsets the data in time within a year range.

Usage

selyear(x, y)

## S4 method for signature 'Raster'
selyear(x, y)

## S4 method for signature 'data.table'
selyear(x, y)

## S4 method for signature 'character'
selyear(x, y)

Arguments

x

Raster* object; data.table (see details); filename (character, see details)

y

numeric. Time range in the form: (start_year, end_year)

Details

If 'x' is a data.table, its columns should be named: "lon", "lat", "date", and "value"

If 'x' is a filename, it should point to a *.nc file.

Value

Raster* object; data.table


Subset data in space and time

Description

The function subset_data subsets the data in space within a bounding box, and/or in time within a year range.

Usage

subset_data(x, box = NULL, yrs = NULL)

## S4 method for signature 'Raster'
subset_data(x, box = NULL, yrs = NULL)

## S4 method for signature 'data.table'
subset_data(x, box = NULL, yrs = NULL)

## S4 method for signature 'character'
subset_data(x, box = NULL, yrs = NULL)

Arguments

x

Raster* object; data.table (see details); filename (character, see details)

box

numeric. Bounding box in the form: (xmin, xmax, ymin, ymax)

yrs

numeric. Time range in the form: (start_year, end_year)

Details

If 'x' is a data.table, its columns should be named: "lon", "lat", "date", and "value"

If 'x' is a filename, it should point to a *.nc file.

If subsetting only in space or time then the arguments must be passed by name. I.e., subset_data(x, box = ...) (space) or subset_data(x, yrs = ...) (time)

Value

Raster* object; data.table

Examples

## Not run: 
download_data("gldas-vic", tempdir(), timestep = "yearly")
r <- raster::brick(paste0(tempdir(),
"/gldas-vic_tp_mm_land_194801_201412_025_yearly.nc"))
sd <- subset_data(r, c(12.24, 18.85, 48.56, 51.12), c(2000, 2010))
ss <- subset_data(r, box = c(12.24, 18.85, 48.56, 51.12))
st <- subset_data(r, yrs = c(2000, 2010))

## End(Not run)

Transform raster into data.table

Description

Function to transform a raster brick into a data.table

Usage

tabular(x)

## S4 method for signature 'Raster'
tabular(x)

## S4 method for signature 'character'
tabular(x)

Arguments

x

Raster* object; filename (character, see details)

Value

data.table

Examples

## Not run: 
download_data("gldas-vic", tempdir(), timestep = "yearly")
r <- raster::brick(paste0(tempdir(),
"/gldas-vic_tp_mm_land_194801_201412_025_yearly.nc"))
s <- tabular(r)

## End(Not run)

Trends

Description

The function trend computes linear slope.

Usage

trend(x)

## S4 method for signature 'Raster'
trend(x)

## S4 method for signature 'data.table'
trend(x)

## S4 method for signature 'character'
trend(x)

Arguments

x

Raster* object; data.table (see details); filename (character, see details)

Details

If 'x' is a data.table, its columns should be named: "lon", "lat", "date", and "value"

If 'x' is a filename, it should point to a *.nc file.

Value

Raster* object; data.table


Yearly <stat>

Description

The function yearstat aggregates the data from monthly to yearly.

Usage

yearstat(x, stat = "sum")

## S4 method for signature 'Raster'
yearstat(x, stat = "sum")

## S4 method for signature 'data.table'
yearstat(x, stat = "sum")

## S4 method for signature 'character'
yearstat(x, stat = "sum")

Arguments

x

Raster* object; data.table (see details); filename (character, see details)

stat

character

Details

If 'x' is a data.table, its columns should be named: "lon", "lat", "date", and "value"

If 'x' is a filename, it should point to a *.nc file.

'stat' is a character string describing the desired aggregation function. Suitable options are:

Value

Raster* object; data.table

Examples

## Not run: 
download_data("gldas-vic", path = tempdir())
r <- raster::brick(paste0(tempdir(),
"/gldas-vic_tp_mm_land_194801_201412_025_monthly.nc"))
s <- yearstat(r, "mean")

## End(Not run)