Title:	Working with 'Sapfluxnet' Project Data
Version:	0.1.4
Description:	Access, modify, aggregate and plot data from the 'Sapfluxnet' project (http://sapfluxnet.creaf.cat), the first global database of sap flow measurements.
Depends:	R (≥ 3.5.0)
License:	MIT + file LICENSE
Encoding:	UTF-8
LazyData:	true
Imports:	assertthat, dplyr, furrr, ggplot2, glue, lubridate, magrittr, methods, purrr, rlang, stats, stringr, tibble, tidyr
RoxygenNote:	7.2.3
Collate:	'data.R' 'getters.R' 'helpers.R' 'imports.R' 'metrics.R' 'sfn_data_classes.R' 'sfn_data_generics.R' 'sfn_data_methods.R' 'sfn_dplyr.R' 'visualizations.R'
Suggests:	future, knitr, remotes, rmarkdown, testthat, xtable
Config/testthat/edition:	3
Config/testthat/parallel:	true
VignetteBuilder:	knitr
URL:	https://github.com/sapfluxnet/sapfluxnetr
BugReports:	https://github.com/sapfluxnet/sapfluxnetr/issues
NeedsCompilation:	no
Packaged:	2023-01-25 15:10:46 UTC; malditobarbudo
Author:	Victor Granda [aut, cre], Rafael Poyatos [aut], Victor Flo [aut], Jacob Nelson [ctb], Sapfluxnet Core Team [cph]
Maintainer:	Victor Granda <victorgrandagarcia@gmail.com>
Repository:	CRAN
Date/Publication:	2023-01-25 15:30:02 UTC

Reexporting the pipe operator

Description

Imported from magrittr package

Examples

# piping sites
ARG_TRE %>% daily_metrics()

accumulated function

Description

sum for summarise_all aware of POSIX objects

Usage

.accumulated_posix_aware(variable, na.rm = FALSE)

Arguments

Value

the sum for any other variables, but the first for POSIXct variables

Examples

sapfluxnetr:::.accumulated_posix_aware(c(50,20))
sapfluxnetr:::.accumulated_posix_aware(c(Sys.time(), Sys.time() -1))

test for character period

Description

test for character period

Usage

.assert_that_period_is_valid(period)

Arguments

Value

TRUE if is valid, informative error if not.

Examples

sapfluxnetr:::.assert_that_period_is_valid('1 day') # TRUE
# not run
# sapfluxnetr:::.assert_that_period_is_valid('1day') # error

.collapse_timestamp helper

Description

Util to collapse the TIMESTAMP using lubridate::*_date functions

Usage

.collapse_timestamp(timestamp, ..., period, side = "start")

Value

A vector of the same length as TIMESTAMP, with the collapsed timestamp with the same tz as the original one.

Period

Periods accepted are in the "number period" format, as in floor_date or a custom function name without quotes:

• hours (exs. "1 hour", "12 hours")

• days (exs. "1 day", "3 days")

• weeks (exs. "1 week", "4 weeks")

• months (exs. "1 month", "6 months")

• years (exs. "1 year", "7 years")

• Also a custom function can be supplied, one that transforms the TIMESTAMP variable to the collapsed timestamp desired. See sfn_metrics for details

Side

Side indicates if using floor_date (side = "start) or ceiling_date (side = 'end'). Ceiling dates is not trivial, see ceiling_date for information on how the date will be ceiled.

Examples

arg_tre_timestamp <- get_timestamp(ARG_TRE)
sapfluxnetr:::.collapse_timestamp(
  arg_tre_timestamp, period = "1 day", side = 'start'
)

helper to return all environmental variable names

Description

helper to return all environmental variable names

Usage

.env_vars_names()

Value

a character vector with env vars names

Examples

sapfluxnetr:::.env_vars_names()

helper function to generate the fixed metrics

Description

generates a call to list to capture the fixed metrics in a quosure lambda style

Usage

.fixed_metrics_funs(probs, centroid)

Arguments

Metrics

Calculated metrics are as follow:

• mean: Mean value for the selected period

• sd: Standard deviation for the selected period

• coverage: Percentage of coverage as the percentage of no NAs in the expected length of the period, stated by the site timestep

• q*: q95 by default. Quantile value for the selected period. Quantiles to calculate are stated in the probs argument

• accumulated: Accumulated value on the selected period

• centroid: daily centroid value in the selected period, calculated only if centroid argument is TRUE

Examples

sapfluxnetr:::.fixed_metrics_funs(0.95, FALSE)
sapfluxnetr:::.fixed_metrics_funs(c(0.05, 0.95), TRUE)

helper function to flag the mutated data in sfn_mutate and sfn_mutate_at

Description

This function will add the "USER_MODF" flag to the data point flags

Usage

.flag(x)

Arguments

Value

A vector of the same length than x with the variable flags modified

Examples

sapfluxnetr:::.flag('')
sapfluxnetr:::.flag('OUT_WARNING')

Metadata variables architecture

Description

This function returns a nested list with the metadata, the variable and the values, description , units and type for it use in describe_variable, sfn_vars_to_filter and sfn_values_for

Usage

.metadata_architecture()

Value

a list with the metadata architecture

Examples

sapfluxnetr:::.metadata_architecture()

Period custom function

Description

nightly period custom function, to use with nightly_metrics

Usage

.nightly_daily_cf(timestamp, night_data, int_start)

Arguments

Details

This function will be supplied as "period" argument to summarise_by_period when daily nightly metrics are requested.

Value

a vector of the same length as TIMESTAMP with the collapsed values.

.parse_period

Description

Util to parse the period supplied to the function call to create the collapsed timestamp

Usage

.parse_period(period)

Arguments

Value

a list, with the freq value as numeric and the period value as character

Examples

sapfluxnetr:::.parse_period('1 day')

transform period to minutes

Description

helper for data_coverage

Usage

.period_to_minutes(period, timestamp, timestep, ...)

Arguments

Details

This function converts the period supplied into minutes to use it in the coverage calculation.

Value

An integer with the period value in minutes

Examples

# daily period, expected 1440 minutes
sapfluxnetr:::.period_to_minutes('1 day')

# Using a custom function, we need timestamp and timestep
sapfluxnetr:::.period_to_minutes(
  lubridate::as_date, get_timestamp(ARG_TRE), 30
)

.sapflow_tidy helper

Description

This helper is in charge of putting in shape the sapflow metrics, creating the pl_code column.

Usage

.sapflow_tidy(data)

Arguments

Timezones dictionary

Description

Transforms timezone ISO code to character vector compatible with lubridate and POSIXct

Usage

.timezone_dic(tz)

Arguments

Details

GMT time zones are used, as they are day saving light time (DST) agnostic, and in that way the DST can setted if the metadata says so. GMT are sign exchanged to be compatible with ISO.

Value

A character vector with the timezone code compatible with lubridate and as.POSIXct

Write metadata cache file to disk

Description

Load all sites, read the metadata and write it to disk to cache the info for easy and fast access

Usage

.write_metadata_cache(folder, .dry = FALSE)

Arguments

Details

Load all data in memory to collect metadata info can be resource limiting. For easy and quick access to metadata, this function stores an .RData file in the specified folder along the data with all the metadata preloaded.

Value

A list of tibbles with the five metadata classes (site, stand, species, plant and environmental)

Examples

# Let's access the data in "folder". This typically is the folder where the
# sapflow data at the desired unit level is (i.e. "RData/plant"), but in this
# example we will create a temporal folder with some data to test the function
folder <- tempdir()
save(ARG_TRE, file = file.path(folder, 'ARG_TRE.RData'))
save(ARG_MAZ, file = file.path(folder, 'ARG_MAZ.RData'))

# lets create the metadata cache file
sapfluxnetr:::.write_metadata_cache(folder, .dry = FALSE)#' 
file.exists(file.path(folder, '.metadata_cache.RData')) # TRUE

ARG_MAZ sapfluxnet site

Description

Example site for package usage demonstration based on ARG_MAZ

Usage

ARG_MAZ

Format

An sfn_data class object with the data and metadata for ARG_MAZ site

Examples

data('ARG_MAZ', package = 'sapfluxnetr')
ARG_MAZ

ARG_TRE sapfluxnet site

Description

Example site for package usage demonstration based on ARG_TRE

Usage

ARG_TRE

Format

An sfn_data class object with the data and metadata for ARG_TRE site

Examples

data('ARG_TRE', package = 'sapfluxnetr')
ARG_TRE

AUS_CAN_ST2_MIX sapfluxnet site

Description

Example site for package usage demonstration based on AUS_CAN_ST2_MIX

Usage

AUS_CAN_ST2_MIX

Format

An sfn_data class object with the data and metadata for AUS_CAN_ST2_MIX site

Examples

data('AUS_CAN_ST2_MIX', package = 'sapfluxnetr')
AUS_CAN_ST2_MIX

as_sfn_data_multi helper

Description

Convert any list of sfn_data objects in a sfn_data_multi object

Usage

as_sfn_data_multi(x)

Arguments

Value

A sfn_data_multi object

Examples

sites_list <- list(ARG_TRE, ARG_MAZ)
sapfluxnetr:::as_sfn_data_multi(sites_list)

data coverage

Description

helper for sfn_metrics

Usage

data_coverage(x, timestep, period_minutes)

Arguments

Details

This helper function calculates the coverage percentage in a vector, and is designed to be used inside a dplyr summarise statement. It calculates the coverage as the percentage of no NAs in the expected length of the summarising period stated by the timestep.

Value

a single value (numeric) with the percentage of coverage for that variable

Examples

# data for one day, 60 minutes timestep (24 values) with a 75% of coberture
x <- rep(c(1,2,3,NA), 6)
data_coverage(x, 60, 1440) # 75

Detailed description of metadata variables

Description

describe_md_variable prints in console a detailed description for the requested variable. Useful to know which values to filter or in which units the variables are.

Usage

describe_md_variable(variable)

Arguments

Value

Nothing, prints information to console

Examples

# info about the method used to measure sapflow (pl_sens_meth)
describe_md_variable('pl_sens_meth')

Diurnal centroid calculation

Description

Calculate the diurnal centroid for sapflow variables

Usage

diurnal_centroid(variable)

Arguments

Details

The code for this function has been kindly provided by Jacob Nelson in python (see https://github.com/jnelson18/FluxnetTools/blob/master/FileS3.py) and has been translated to a tidy data philosophy in R to be used inside a summarise statement.

Value

A numeric value with the diurnal centroid value (0 to 24 h)

Diurnal centroid algorithm

Given a continuous subdaily sapflow values at regular intervals V = {x_1, ..., x_n} to obtain the diurnal centroid each value is multiplied by its interval index and summed up and divided by the sum of the values for the day and finally the value is normalized to 24h:

\sum {x_1 * 1, x_2 * 2, ... , x_n * n} / \sum {x_1, x_2, ... , x_n} * (24/n)

With even values for all the intervals (i.e. 100 for all), centroid converges to 12h at more than 1000 intervals per day. With only 48 (half hourly measurements) centroid converges to 12.25h and with 24 intervals (hourly measurements) centroid converges to 12.5h. So, using diurnal centroid value in half hourly datasets or above can have a considerable error associated.

Author(s)

Jacob Nelson & Víctor Granda

Examples

# dplyr
library(dplyr)

# check convergence to 12h:
diurnal_centroid(rep(1, 1000)) # 12.012 h
diurnal_centroid(rep(10000, 1000)) # 12.012 h, variable scale not affects calculation

# sapflow diurnal centroid
data('ARG_TRE', package = 'sapfluxnetr')

sfn_metrics(
  ARG_TRE,
  period = '1 day',
  .funs = list(~ diurnal_centroid(.),
               ~ data_coverage(., timestep, period_minutes)),
  solar = FALSE,
  interval = 'general'
)

Filter the sites by metadata variable values

Description

filter_sites_by_md function takes logical expressions for the metadata variables (i.e. pl_sens_meth == 'HR'), and list the sites that met the criteria from those supplied

Usage

filter_sites_by_md(sites, metadata, ..., .join = c("and", "or"))

Arguments

Details

.join argument indicates how sites must be filtered between metadata classes. 'and' indicates only sites meeting all conditions for all metadata classes are returned. 'or' indicates all sites meeting any condition between classes are returned. For two or more filters of the same metadata class, they are combined as 'and'.

Value

A character vector with the sites fulfilling the premises

Examples

# Let's access the data in "folder". This typically is the folder where the
# sapflow data at the desired unit level is (i.e. "RData/plant"), but in this
# example we will create a temporal folder with some data to test the function
folder <- tempdir()
save(ARG_TRE, file = file.path(folder, 'ARG_TRE.RData'))
save(ARG_MAZ, file = file.path(folder, 'ARG_MAZ.RData'))
save(AUS_CAN_ST2_MIX, file = file.path(folder, 'AUS_CAN_ST2_MIX.RData'))

# we need the metadata and the site names
metadata <- read_sfn_metadata(folder = folder, .write_cache = TRUE)
sites <- sfn_sites_in_folder(folder)

# Filter by Heat Ratio method
filter_sites_by_md(
  pl_sens_meth == 'HR', sites = sites, metadata = metadata
)

# Both, Heat Ratio and Heat Dissipation
filter_sites_by_md(
  pl_sens_meth %in% c('HR', 'HD'),
  sites = sites, metadata = metadata
)

# more complex, Heat Ratio method AND Woodland/Shrubland biome
filter_sites_by_md(
  pl_sens_meth == 'HR',
  si_biome == 'Woodland/Shrubland',
  sites = sites, metadata = metadata,
  .join = 'and' # default
)

# join = 'or' returns sites that meet any condition
filter_sites_by_md(
  pl_sens_meth == 'HR',
  si_biome == 'Woodland/Shrubland',
  sites = sites, metadata = metadata,
  .join = 'or'
)

get the timezone of the site

Description

Obtain the site timezone from a sfn_data/sfn_data_multi object

Usage

get_timezone(sfn_data)

Arguments

Value

a character with the site timezone

Examples

# timezone of ARG_TRE site
get_timezone(ARG_TRE)

Initialize method for sfn_data

Description

Initialize an sfn_data object

Usage

## S4 method for signature 'sfn_data'
initialize(
  .Object,
  sapf_data,
  env_data,
  sapf_flags,
  env_flags,
  si_code,
  timestamp,
  solar_timestamp,
  site_md,
  stand_md,
  species_md,
  plant_md,
  env_md
)

Arguments

Initialize method for sfn_data multi

Description

Initialize an sfn_data_multi object

Usage

## S4 method for signature 'sfn_data_multi'
initialize(.Object, ...)

Arguments

Complete metrics wrappers

Description

This set of functions returns a complete set of statistics for a site (using sfn_data) or several sites (using sfn_data_multi)

Usage

daily_metrics(
  sfn_data,
  solar = TRUE,
  probs = c(0.95),
  tidy = FALSE,
  metadata = NULL,
  ...
)

monthly_metrics(
  sfn_data,
  solar = TRUE,
  probs = c(0.95),
  tidy = FALSE,
  metadata = NULL,
  ...
)

nightly_metrics(
  sfn_data,
  period = c("1 day", "1 month"),
  solar = TRUE,
  int_start = 20,
  int_end = 6,
  probs = c(0.95),
  tidy = FALSE,
  metadata = NULL,
  ...
)

daylight_metrics(
  sfn_data,
  period = c("1 day", "1 month"),
  solar = TRUE,
  int_start = 6,
  int_end = 20,
  probs = c(0.95),
  tidy = FALSE,
  metadata = NULL,
  ...
)

predawn_metrics(
  sfn_data,
  period = c("1 day", "1 month"),
  solar = TRUE,
  int_start = 4,
  int_end = 6,
  probs = c(0.95),
  tidy = FALSE,
  metadata = NULL,
  ...
)

midday_metrics(
  sfn_data,
  period = c("1 day", "1 month"),
  solar = TRUE,
  int_start = 11,
  int_end = 13,
  probs = c(0.95),
  tidy = FALSE,
  metadata = NULL,
  ...
)

Arguments

Details

*_metrics functions are wrappers for sfn_metrics with a set of fixed arguments.

*_metrics functions return all or some of the following statistics:

• mean: mean of variable (tree or environmental variable) for the given period. NAs are removed

• sd: standard deviation of the variable for the given period. NAs are removed

• coverage: Data coverage percentage (percentage of measures without NAs)

• q_XX: 0.XX quantile value for the period

• centroid: Diurnal centroid value (hours passed until the half of the summed daily value was reached). Only returned for sapflow measures when period is '1 day'

• accumulated: Accumulated values for precipitation only

Value

If tidy is TRUE, a tibble with the metrics for sapflow and environmental data, with all the metadata included. If tidy is FALSE (default), a list of tibbles with the calculated metrics.

daily_metrics

daily_metrics summarise daily data for all hours in the day

monthly_metrics

monthly_metrics summarise monthly data for all hours in the day.

nightly_metrics

nightly_metrics will return the metrics for night periods, summarised daily or monthly

Night for daily period starts in DOY x and ends in DOY x+1 (i.e. if night_start = 20, night_end = 6 values for the night starting at 2018-03-28 20:00:00 and ending at 2018-03-29 06:00:00 are summarised).

Night for monthly period summarises all night periods in the month, that includes from 00:00:00 of the first month night to 23:59:59 of the last month night.

daylight_metrics

daylight_metrics will return the metrics for daylight periods, summarised daily or monthly. Daylight interval is selected by start and end hours.

predawn_metrics

predawn_metrics will always return the metrics for predawn period, summarised daily or monthly. Predawn interval is selected by start and end hours.

Predawn metrics did not return the centroid metric.

midday_metrics

midday_metrics will always return the metrics for midday period, summarised daily or monthly. midday interval is selected by start and end hours.

Midday metrics did not return the centroid metric.

See Also

Other metrics: sfn_metrics()

Examples

## daily_metrics
# data load
data('ARG_TRE', package = 'sapfluxnetr')
data('sfn_metadata_ex', package = 'sapfluxnetr')

# non tidy raw metrics (default)
ARG_TRE_raw_daily <- daily_metrics(ARG_TRE)
str(ARG_TRE_raw_daily)


# tidy daily metrics
ARG_TRE_daily <- daily_metrics(
  ARG_TRE, tidy = TRUE, metadata = sfn_metadata_ex
)
ARG_TRE_daily


## monthly_metrics
# data load
data('ARG_TRE', package = 'sapfluxnetr')
data('sfn_metadata_ex', package = 'sapfluxnetr')

# non tidy raw metrics (default)
ARG_TRE_raw_monthly <- monthly_metrics(ARG_TRE)
str(ARG_TRE_raw_monthly)


# tidy monthly metrics
ARG_TRE_monthly <- monthly_metrics(
  ARG_TRE, tidy = TRUE, metadata = sfn_metadata_ex
)
ARG_TRE_monthly



## nightly_metrics
# data load
data('AUS_CAN_ST2_MIX', package = 'sapfluxnetr')

# non tidy daily night metrics (default)
AUS_CAN_ST2_MIX_night <- nightly_metrics(AUS_CAN_ST2_MIX)

str(AUS_CAN_ST2_MIX_night)
AUS_CAN_ST2_MIX_night[['sapf']]
AUS_CAN_ST2_MIX_night[['env']]

# change the night interval
AUS_CAN_ST2_MIX_night_short <- nightly_metrics(
  AUS_CAN_ST2_MIX, int_start = 21, int_end = 4 # night starting and ending hour
)
AUS_CAN_ST2_MIX_night_short[['env']]

# tidy nightly metrics
data('sfn_metadata_ex', package = 'sapfluxnetr')
AUS_CAN_ST2_MIX_night_tidy <- nightly_metrics(
  AUS_CAN_ST2_MIX,
  tidy = TRUE, metadata = sfn_metadata_ex
)
AUS_CAN_ST2_MIX_night_tidy



## daylight_metrics
# data load
data('AUS_CAN_ST2_MIX', package = 'sapfluxnetr')

# non tidy daily daylight metrics (default)
AUS_CAN_ST2_MIX_daylight <- daylight_metrics(AUS_CAN_ST2_MIX)

str(AUS_CAN_ST2_MIX_daylight)
AUS_CAN_ST2_MIX_daylight[['sapf']]
AUS_CAN_ST2_MIX_daylight[['env']]

# change the daylight interval
AUS_CAN_ST2_MIX_daylight_short <- daylight_metrics(
  AUS_CAN_ST2_MIX, int_start = 8, int_end = 18 # night starting and ending hour
)
AUS_CAN_ST2_MIX_daylight_short[['env']]

# tidy daylight metrics
data('sfn_metadata_ex', package = 'sapfluxnetr')
AUS_CAN_ST2_MIX_daylight_tidy <- daylight_metrics(
  AUS_CAN_ST2_MIX,
  tidy = TRUE, metadata = sfn_metadata_ex
)
AUS_CAN_ST2_MIX_daylight_tidy



## predawn_metrics
# data load
data('AUS_CAN_ST2_MIX', package = 'sapfluxnetr')

# non tidy daily predawn metrics (default)
AUS_CAN_ST2_MIX_predawn <- predawn_metrics(AUS_CAN_ST2_MIX)

str(AUS_CAN_ST2_MIX_predawn)
AUS_CAN_ST2_MIX_predawn[['sapf']]
AUS_CAN_ST2_MIX_predawn[['env']]

# change the predawn interval
AUS_CAN_ST2_MIX_predawn_short <- predawn_metrics(
  AUS_CAN_ST2_MIX, int_start = 8, int_end = 18 # night starting and ending hour
)
AUS_CAN_ST2_MIX_predawn_short[['env']]

# tidy daylight metrics
data('sfn_metadata_ex', package = 'sapfluxnetr')
AUS_CAN_ST2_MIX_predawn_tidy <- predawn_metrics(
  AUS_CAN_ST2_MIX,
  tidy = TRUE, metadata = sfn_metadata_ex
)
AUS_CAN_ST2_MIX_predawn_tidy



## midday_metrics
# data load
data('AUS_CAN_ST2_MIX', package = 'sapfluxnetr')

# non tidy daily midday metrics (default)
AUS_CAN_ST2_MIX_midday <- midday_metrics(AUS_CAN_ST2_MIX)

str(AUS_CAN_ST2_MIX_midday)
AUS_CAN_ST2_MIX_midday[['sapf']]
AUS_CAN_ST2_MIX_midday[['env']]

# change the midday interval
AUS_CAN_ST2_MIX_midday_short <- midday_metrics(
  AUS_CAN_ST2_MIX, int_start = 8, int_end = 18 # night starting and ending hour
)
AUS_CAN_ST2_MIX_midday_short[['env']]

# tidy daylight metrics
data('sfn_metadata_ex', package = 'sapfluxnetr')
AUS_CAN_ST2_MIX_midday_tidy <- midday_metrics(
  AUS_CAN_ST2_MIX,
  tidy = TRUE, metadata = sfn_metadata_ex
)
AUS_CAN_ST2_MIX_midday_tidy

Build a tidy data frame from the metrics results nested list

Description

Transform the nested list of metrics in a tidy tibble where each observation has its own row

Usage

metrics_tidyfier(
  metrics_res,
  metadata,
  interval = c("general", "predawn", "midday", "night", "daylight")
)

Arguments

Value

a tibble with the following columns:

• TIMESTAMP: POSIXct vector with the date-time of the observation

• si_code: Character vector with the site codes

• pl_code: Character vector with the plant codes

• sapflow_*: Variables containing the different metrics for the sapflow measurements (i.e. sapflow_mean, sapflow_q_95)

• ta_*; rh_*; vpd_*; ...: Variables containing the different metrics for environmental variables (i.e. ta_mean, ta_q_95)

• pl_*: plant metadata variables (i.e. pl_sapw_area, pl_sens_meth)

• si_*: site metadata variables (i.e. si_biome, si_contact_firstname)

• st_*: stand metadata variables (i.e. st_aspect, st_lai)

• sp_*: species metadata variables (i.e. sp_basal_area_perc)

• env_*: environmental metadata variables (i.e. env_timezone)

Examples

# data
multi_sfn <- sfn_data_multi(ARG_TRE, ARG_MAZ, AUS_CAN_ST2_MIX)
data('sfn_metadata_ex', package = 'sapfluxnetr')

# metrics
multi_metrics <- daily_metrics(multi_sfn)

# tidyfing
multi_tidy <- metrics_tidyfier(
  multi_metrics, sfn_metadata_ex, interval = 'general'
)
multi_tidy

# A really easier way of doing the same
multi_tidy_easy <- daily_metrics(multi_sfn, tidy = TRUE, metadata = sfn_metadata_ex)

Normalized diurnal centroid calculation

Description

Calculate the normalized diurnal centroid for sapflow variables

Usage

norm_diurnal_centroid(sapf_var, rad_var)

Arguments

Details

The code for this function has been kindly provided by Jacob Nelson in python (see https://github.com/jnelson18/FluxnetTools/blob/master/FileS3.py) and has been translated to a tidy data philosophy in R to be used inside a summarise statement.

Value

A numeric value with the normalized diurnal centroid value

Normalized diurnal centroid algorithm

This function calculates the diurnal centroid of sapflow measures relative to the diurnal centroid of incoming radiation (in any units). For that the incoming radiation diurnal centroid is substracted from the sapflow diurnal centroid:

Sapf_cent - IncomingRad_cent

Author(s)

Jacob Nelson & Víctor Granda

Read sfn_data from disk

Description

Given a site code and a route, read_sfn_data will return the selected sfn_data object

Usage

read_sfn_data(site_codes, folder = ".")

Arguments

Value

If site_codes is a vector of length 1, an sfn_data object with the selected site data. If site_codes is a vector of length > 1, then a sfn_data_multi object containing all selected sites.

Examples

# Let's access the data in "folder". This typically is the folder where the
# sapflow data at the desired unit level is (i.e. "RData/plant"), but in this
# example we will create a temporal folder with some data to test the function
folder <- tempdir()
save(ARG_TRE, file = file.path(folder, 'ARG_TRE.RData'))
save(ARG_MAZ, file = file.path(folder, 'ARG_MAZ.RData'))

# now we read a single site
ARG_TRE_test <- read_sfn_data('ARG_TRE', folder)
ARG_TRE_test

# or we can read multiple sites at once
multi_sfn <- read_sfn_data(
  c('ARG_TRE', 'ARG_MAZ'), folder
)
multi_sfn

Read and combine all metadata

Description

Read metadata from all sites in folder and write it to disk to cache the info for easy and fast access

Usage

read_sfn_metadata(folder = ".", .write_cache = FALSE)

Arguments

Details

Load all data in memory to collect metadata info can be resource limiting. For easy and quick access to metadata, this function stores an .RData file in the specified folder along the data with all the metadata preloaded. Also it return it as an object to use in filtering and selecting sites.

Value

A list of tibbles with the five metadata classes (site, stand, species, plant and environmental)

Examples

# Let's access the data in "folder". This typically is the folder where the
# sapflow data at the desired unit level is (i.e. "RData/plant"), but in this
# example we will create a temporal folder with some data to test the function
folder <- tempdir()
save(ARG_TRE, file = file.path(folder, 'ARG_TRE.RData'))
save(ARG_MAZ, file = file.path(folder, 'ARG_MAZ.RData'))

# create and load the metadata. The first time we use .write_cache = TRUE,
# to ensure creating a file containing the metadata for speed the process
# for the next times
read_sfn_metadata(
  folder = folder, .write_cache = TRUE
)
# a cached copy must have been written to "folder"
file.exists(paste0(folder, '.metadata_cache.RData')) # TRUE

# after that, we only need to especify the folder
sites_metadata <- read_sfn_metadata(folder = folder) # quicker than before
sites_metadata

S4 class for sapfluxnet site data

Description

Main class for storing sapfluxnet project site data and metadata

Details

This class allows to store all the data and metadata for a sapfluxnet site in one single object, to easily work with it. See vignette('sfn-data-classes', package = 'sapfluxnetr') for more info.

Slots

sapf_data

A data frame with the sapf data

env_data

A data frame with the env data

sapf_flags

A data frame with the same dimensions of sapf_data with the flag info for each tree/TIMESTAMP combination

env_flags

A data frame with the same dimensions of env_data with the flag info for each env_var/TIMESTAMP combination

si_code

A character vector of length one indicating the site code

timestamp

A POSIXct vector of length nrow(sapf_data) with the timestamp

solar_timestamp

A POSIXct vector of length nrow(sapf_data) with the solar timestamp

site_md

A data frame containing the site metadata

stand_md

A data frame containing the stand metadata

species_md

A data frame containing the species metadata

plant_md

A data frame containing the plant metadata

env_md

A data frame containing the env metadata

S4 class for sapfluxnet multi-site data

Description

Multi sfn data class, derived from list

Details

This class inherits from list, but modified to contain sfn_data objects as elements. This will allow to work with several sites at the same time obtaining results for all of them combined or individually as elements of the resulting list (with lapply or purrr::map)

Validity method for sfn_data_multi class

Description

Validation checks for generating sfn_data_multi class objects

Details

This method is used internally to ensure the correctness of the sfn_data_multi object. Basically ensures that the object returned is a list of sfn_data class objects

Validity method for sfn_data class

Description

Validation checks for generating sfn_data class objects

Details

This method is used internally when creating and/or modifying sfn_data class objects to ensure that the object returned is correct in terms of content classes and dimensions (i.e. sapflow data and environmental data has the same length)

Filter sfn_data by variable/s value

Description

Port of filter for sfn_data and sfn_data_multi objects

Usage

sfn_filter(sfn_data, ..., solar = FALSE)

Arguments

Details

'sfn_filter' will remove the rows not matching the logical expression/s provided. So, it will remove cases and will create TIMESTAMP gaps, so its use is not recommended except in the case of filtering by TIMESTAMP (i.e. to set several sites (sfn_data_multi) in the same time frame). For other scenarios (removing extreme environmental conditions values or strange sapflow measures patterns) see sfn_mutate and sfn_mutate_at

Value

For sfn_data objects, a filtered sfn_data or NULL if no data meet the criteria. For sfn_data_multi another sfn_data_multi with the sites filtered, and an empty sfn_data_multi if any sites met the criteria

Examples

library(dplyr)
library(lubridate)

# data
data('ARG_TRE', package = 'sapfluxnetr')

# by timestamp
foo_timestamp <- get_timestamp(ARG_TRE)

foo_timestamp_trimmed <- foo_timestamp[1:100]

sfn_filter(
  ARG_TRE,
  TIMESTAMP %in% foo_timestamp_trimmed
)

# by wind speed value
ws_threshold <- 25

sfn_filter(
  ARG_TRE,
  ws <= ws_threshold
)

## multi
data('ARG_MAZ', package = 'sapfluxnetr')
multi_sfn <- sfn_data_multi(ARG_TRE, ARG_MAZ)

# by timestamp
sfn_filter(
  multi_sfn,
  between(day(TIMESTAMP), 18, 22)
)

# by wind speed value
sfn_filter(
  multi_sfn,
  ws <= ws_threshold
)

sfn_data custom get generics

Description

Generics for getting the info in the slots of SfnData

Usage

get_sapf_data(object, ...)

get_env_data(object, ...)

get_sapf_flags(object, ...)

get_env_flags(object, ...)

get_timestamp(object, ...)

get_solar_timestamp(object, ...)

get_si_code(object, ...)

get_site_md(object, ...)

get_stand_md(object, ...)

get_species_md(object, ...)

get_plant_md(object, ...)

get_env_md(object, ...)

Arguments

Details

see sfn_get_methods for detailed info about using the get methods in sfn_data class objects and sfn_multi_get_methods for detailed info about using the get methods in sfn_data_multi class objects.

sfn_data get methods

Description

Methods to get the data and metadata from the sfn_data class slots

Usage

## S4 method for signature 'sfn_data'
get_sapf_data(object, solar = FALSE)

## S4 method for signature 'sfn_data'
get_env_data(object, solar = FALSE)

## S4 method for signature 'sfn_data'
get_sapf_flags(object, solar = FALSE)

## S4 method for signature 'sfn_data'
get_env_flags(object, solar = FALSE)

## S4 method for signature 'sfn_data'
get_timestamp(object)

## S4 method for signature 'sfn_data'
get_solar_timestamp(object)

## S4 method for signature 'sfn_data'
get_si_code(object)

## S4 method for signature 'sfn_data'
get_site_md(object)

## S4 method for signature 'sfn_data'
get_stand_md(object)

## S4 method for signature 'sfn_data'
get_species_md(object)

## S4 method for signature 'sfn_data'
get_plant_md(object)

## S4 method for signature 'sfn_data'
get_env_md(object)

Arguments

Details

get_sapf_data and get_env_data methods retrieve sapflow or environmental tibbles to create a functional dataset to work with.

get_sapf_flags and get_env_flags methods retrieve sapflow or environmental flags as tibbles.

get_timestamp and get_solar_timestamp methods retrieve only the timestamp as POSIXct vector.

get_si_code method retrieve a character vector with length(timestamp) containing the site code.

get_site_md, get_stand_md, get_species_md, get_plant_md and get_env_md methods retrieve the corresponding metadata.

Examples

library(dplyr)

data('ARG_TRE', package = 'sapfluxnetr')
sapf_data <- get_sapf_data(ARG_TRE, solar = TRUE)
env_data_no_solar <- get_env_data(ARG_TRE, solar = FALSE)
plant_md <- get_plant_md(ARG_TRE)

# dplyr pipe to get the mean dbh for a site
ARG_TRE %>%
  get_plant_md() %>%
  summarise(dbh_mean = mean(pl_dbh, na.rm = TRUE)) %>%
  pull(dbh_mean)

sfn_metadata cache file for example data (ARG_MAZ, ARG_TRE and AUS_CAN_ST2_MIX)

Description

Example metadata cache file content for package usage demonstration

Usage

sfn_metadata_ex

Format

A list with five elements, each of one a metadata type.

Examples

data('sfn_metadata_ex', package = 'sapfluxnetr')
sfn_metadata_ex

Metrics summary function

Description

Generate metrics from a site/s data for the period indicated

Usage

sfn_metrics(
  sfn_data,
  period,
  .funs,
  solar,
  interval = c("general", "predawn", "midday", "night", "daylight"),
  int_start = NULL,
  int_end = NULL,
  ...
)

Arguments

Value

For sfn_data objects, a list of tbl_df objects with the following structure:

• $sapf: metrics for the sapflow data

• $env: metrics for the environmental data

For sfn_data_multi objects, a list of lists of tbl_df objects with the metrics for each site:

• $SITE_CODE

  • $sapf: metrics for the sapflow data

  • $env: metrics for the environmental data

• $NEXT_SITE_CODE...

Period

period argument is used by internal function .collapse_timestamp and it can be stated in two ways:

• frequency period format: "3 hours", "1 day", "7 days", "1 month"

• As a custom function. This will be the name of a function, without quotes, that accepts as the first argument the timestamp to collapse. The result of the function must be a vector of collapsed TIMESTAMPs of the same length than the original TIMESTAMP which will be used to group by and summarise the data. Additional arguments to this function, if needed, can be passed in the ... argument.

.collapse_timestamp also accepts the side argument to collapse by the starting timestamp or the ending timestamp of each group. This can be supplied in the ... argument.

.funs

.funs argument uses the same method as the .funs argument in the summarise_all function of dplyr package. Basically it accepts a list of function calls generated by list(). If you want to pass on a custom function you can specify it here. See details in summarise_by_period for more complex summarising functions declaration.

Interval

Previously to the metrics summary, data can be filtered by an special interval (i.e. predawn or nightly). This filtering can be specified with the interval argument as this:

• "general" (default). No special interval is used, and metrics are performed with all the data.

• "predawn". Data is filtered for predawn interval. In this case int_start and int_end must be specified as 24h value

• "midday". Data is filtered for midday interval. In this case int_start and int_end must be specified as 24h value

• "night". Data is filtered for night interval. In this case int_start and int_end must be specified as 24h value

• "daylight". Data is filtered for daylight interval. In this case int_start and int_end must be specified as 24h value

See Also

Other metrics: metrics

Examples

library(dplyr)

### general metrics
## sfn_data
data('ARG_TRE', package = 'sapfluxnetr')
ARG_TRE_metrics <- sfn_metrics(
  ARG_TRE,
  period = '7 days',
  .funs = list(~ mean(., na.rm = TRUE), ~ sd(., na.rm = TRUE), ~ n()),
  solar = FALSE,
  interval = 'general'
)

str(ARG_TRE_metrics)
ARG_TRE_metrics[['sapf']]
ARG_TRE_metrics[['env']]

## sfn_data_multi

data('ARG_MAZ', package = 'sapfluxnetr')
data('AUS_CAN_ST2_MIX', package = 'sapfluxnetr')
multi_sfn <- sfn_data_multi(ARG_TRE, ARG_MAZ, AUS_CAN_ST2_MIX)

multi_metrics <- sfn_metrics(
  multi_sfn,
  period = '7 days',
  .funs = list(~ mean(., na.rm = TRUE), ~ sd(., na.rm = TRUE), ~ n()),
  solar = FALSE,
  interval = 'general'
)

str(multi_metrics)

multi_metrics[['ARG_TRE']][['sapf']]


### midday metrics
ARG_TRE_midday <- sfn_metrics(
  ARG_TRE,
  period = '1 day',
  .funs = list(~ mean(., na.rm = TRUE), ~ sd(., na.rm = TRUE), ~ n()),
  solar = TRUE,
  interval = 'midday', int_start = 11, int_end = 13
)

str(ARG_TRE_midday)
ARG_TRE_midday[['sapf']]

sfn_data_multi get methods

Description

Methods to get the data and metadata from the sfn_data class slots

Usage

## S4 method for signature 'sfn_data_multi'
get_sapf_data(object, solar = FALSE)

## S4 method for signature 'sfn_data_multi'
get_env_data(object, solar = FALSE)

## S4 method for signature 'sfn_data_multi'
get_sapf_flags(object, solar = FALSE)

## S4 method for signature 'sfn_data_multi'
get_env_flags(object, solar = FALSE)

## S4 method for signature 'sfn_data_multi'
get_timestamp(object)

## S4 method for signature 'sfn_data_multi'
get_solar_timestamp(object)

## S4 method for signature 'sfn_data_multi'
get_si_code(object)

## S4 method for signature 'sfn_data_multi'
get_site_md(object, collapse = FALSE)

## S4 method for signature 'sfn_data_multi'
get_stand_md(object, collapse = FALSE)

## S4 method for signature 'sfn_data_multi'
get_species_md(object, collapse = FALSE)

## S4 method for signature 'sfn_data_multi'
get_plant_md(object, collapse = FALSE)

## S4 method for signature 'sfn_data_multi'
get_env_md(object, collapse = FALSE)

Arguments

Details

get_sapf_data and get_env_data methods retrieve sapflow or environmental tibbles from the sfn_data objects contained in the sfn_data_multi and return them in a list.

get_sapf_flags and get_env_flags methods retrieve sapflow or environmental flags tibbles from the sfn_data objects contained in the sfn_data_multi and return them in a list.

get_timestamp and get_solar_timestamp methods retrieve only the timestamps as POSIXct vectors and return them as a list (each element corresponding to a site in the sfn_data_multi object).

get_si_code method retrieve a character vector with length(timestamp) containing the site code for each site, returning them as a list.

get_site_md, get_stand_md, get_species_md, get_plant_md and get_env_md methods retrieve the corresponding metadata objects for each site returning them as a list, unless collapse is TRUE, then the list collapses to a tibble.

Examples

library(dplyr)

Mutate variables by function

Description

Port of mutate for sfn_data and sfn_data_multi objects

Usage

sfn_mutate(sfn_data, ..., solar = FALSE)

Arguments

Details

'sfn_mutate' function will maintain the same number of rows before and after the modification, so it is well suited to modify variables without creating TIMESTAMP gaps (i.e. to change variable units). For mutating groups of variables at the same time see sfn_mutate_at.

Value

For sfn_data objects, a mutated sfn_data. For sfn_data_multi another sfn_data_multi with the sites mutated

Sapflow and environmental variables

'sfn_mutate' internally joins the sapflow and environmental datasets by the TIMESTAMP, so it is possible to mutate variables conditionally between sapflow and environmental measures (i.e. mutate sapflow when wind is high or radiation is zero). Due to this, at the moment any new variable is dropped when building the final results, so this is ONLY intended to mutate existing variables without changing the names.

Examples

library(dplyr)
library(lubridate)

# data
data('ARG_TRE', package = 'sapfluxnetr')

# transform to NAs any wind value above 25
ws_threshold <- 25
sfn_mutate(ARG_TRE, ws = if_else(ws > 25, NA_real_, ws))

## multi
data(ARG_MAZ, package = 'sapfluxnetr')
data(AUS_CAN_ST2_MIX, package = 'sapfluxnetr')
multi_sfn <- sfn_data_multi(ARG_TRE, ARG_MAZ, AUS_CAN_ST2_MIX)

multi_sfn_mutated <- sfn_mutate(
  multi_sfn, ws = if_else(ws > 25, NA_real_, ws)
)

multi_sfn_mutated[['ARG_TRE']]

Mutate selected columns by function

Description

Port of mutate_at for sfn_data and sfn_data_multi objects

Usage

sfn_mutate_at(sfn_data, .vars, .funs, ..., solar = FALSE)

Arguments

Details

'sfn_mutate_at' function will maintain the same number of rows before and after the modification, so it is well suited to modify variables without creating TIMESTAMP gaps (i.e. to change variable units). For mutating individual variables see sfn_mutate.

Value

For sfn_data objects, a mutated sfn_data. For sfn_data_multi another sfn_data_multi with the sites mutated

Examples

library(dplyr)
library(lubridate)

# data
data('ARG_TRE', package = 'sapfluxnetr')

# transform to NAs any sapflow value occured with wind speed above 25
ws_threshold <- 25
# get the names of the variables to mutate (tree names)
vars_to_mutate <- names(get_sapf_data(ARG_TRE)[,-1]) # no TIMESTAMP

sfn_mutate_at(
  ARG_TRE,
  .vars = vars(one_of(vars_to_mutate)),
  .funs = list(
    ~ case_when(
      ws > ws_threshold ~ NA_real_,
      TRUE ~ .
    )
  )
)

## multi
data(ARG_MAZ, package = 'sapfluxnetr')
data(AUS_CAN_ST2_MIX, package = 'sapfluxnetr')
multi_sfn <- sfn_data_multi(ARG_TRE, ARG_MAZ, AUS_CAN_ST2_MIX)

## in multi it's better to discard the variables to not mutate:
vars_to_not_mutate <- names(get_env_data(ARG_TRE)) # all the environmental

multi_sfn_mutated <- sfn_mutate_at(
  multi_sfn,
  .vars = vars(-one_of(vars_to_not_mutate)), # we use -
  .funs = list(
    ~ case_when(
      ws > ws_threshold ~ NA_real_,
      TRUE ~ .
    )
  )
)

multi_sfn_mutated[['ARG_TRE']]

plot method for sfn_data class

Description

Plot the desired data from a site object

Usage

sfn_plot(
  sfn_data,
  type = c("sapf", "env", "ta", "rh", "vpd", "ppfd_in", "netrad", "sw_in", "ext_rad",
    "ws", "precip", "swc_shallow", "swc_deep"),
  formula_env = NULL,
  solar = TRUE,
  ...
)

Arguments

Value

A ggplot object that can be called to see the plot. If input is an sfn_data_multi object, a list with the plots

ggplot plotting system

plot is a base R function which uses the base R plotting system to show the plot. We prefer the ggplot plotting system, which allow for storing the plots in objects and can be subjected to further modifications. This allow the package users to generate rather simple plots that can be fine tuned afterwards to the user taste. Generating a plot method for the sfn_data class returning a ggplot object is not desired (it change the way plot works and can be misleading about the plot general usage). So, instead, we offer this function, sfn_plot.

Type

type argument controls what is going to be plotted. It accepts the following:

• "sapf": It will plot sapflow data vs. TIMESTAMP

• "env": It will plot environmental variables vs. TIMESTMAP

• "ta", "rh", "vpd", "ppfd_in", "netrad", "sw_in", "ext_rad", "ws", "precip", "swc_shallow" and "swc_deep": They will plot the corresponding variable vs. TIMESTAMP

Formula

formula argument can be used to select an environmental variable to plot versus all the sapflow measurements. Any environmental variable is allowed, if it exist in the site provided.

Geometry

By default sfn_plot generates plots using geom_point geometry, except in the case of type = "ws" and type = "precip" where geom_col is used. These geometries can be modified with the ... argument.

Examples

library(ggplot2)

# data
data('ARG_TRE', package = 'sapfluxnetr')

# plotting directly
sfn_plot(ARG_TRE, type = 'sapf')

# this could be noisy, you can facet by "Tree" (for sapflow) or by
# "Variable" (for environmental data):
sfn_plot(ARG_TRE, type = 'sapf') +
  facet_wrap(~ Tree)

sfn_plot(ARG_TRE, type = 'env') +
  facet_wrap(~ Variable, scales = 'free_y')

# saving and modifying:
env_plot <- sfn_plot(ARG_TRE, type = 'env', solar = FALSE) +
  facet_wrap(~ Variable, scales = 'free_y')
env_plot + labs(title = 'Environmental variables facet plot')

# formula
sfn_plot(ARG_TRE, formula_env = ~ vpd)

sfn_data replacement generics

Description

Generic functions for replacement functions for sfn_data

Usage

get_sapf_data(object) <- value

get_env_data(object) <- value

get_sapf_flags(object) <- value

get_env_flags(object) <- value

get_timestamp(object) <- value

get_solar_timestamp(object) <- value

get_si_code(object) <- value

get_site_md(object) <- value

get_stand_md(object) <- value

get_species_md(object) <- value

get_plant_md(object) <- value

get_env_md(object) <- value

Arguments

Details

see sfn_replacement_methods for more info about using the replacement methods in sfn_data objects

sfn_data replacement methods

Description

Methods to replace the data and metadata from the sfn_data class slots

Usage

## S4 replacement method for signature 'sfn_data'
get_sapf_data(object) <- value

## S4 replacement method for signature 'sfn_data'
get_env_data(object) <- value

## S4 replacement method for signature 'sfn_data'
get_sapf_flags(object) <- value

## S4 replacement method for signature 'sfn_data'
get_env_flags(object) <- value

## S4 replacement method for signature 'sfn_data'
get_timestamp(object) <- value

## S4 replacement method for signature 'sfn_data'
get_solar_timestamp(object) <- value

## S4 replacement method for signature 'sfn_data'
get_si_code(object) <- value

## S4 replacement method for signature 'sfn_data'
get_site_md(object) <- value

## S4 replacement method for signature 'sfn_data'
get_stand_md(object) <- value

## S4 replacement method for signature 'sfn_data'
get_species_md(object) <- value

## S4 replacement method for signature 'sfn_data'
get_plant_md(object) <- value

## S4 replacement method for signature 'sfn_data'
get_env_md(object) <- value

Arguments

Details

The replacement object must be a valid object for that slot:

• For get_sapf_data, get_env_data, get_sapf_flags and get_env_flags a data.frame or tibble without the TIMESTAMP variable

• For get_*_md a data.frame or tibble

• For get_timestamp and get_solar_timestamp a POSIXct vector of length == nrow(sapf/env_data)

• For get_si_code a character vector

Validity is automatically checked before modifying the sfn_data object, and an error is raised if not valid

Examples

# preparation
data('ARG_TRE', package = 'sapfluxnetr')
sapf_data <- get_sapf_data(ARG_TRE, solar = TRUE)

# modifying the slot data
sapf_data[1:10, 2] <- NA

# replacement. Remember, the sfn_data slot does not contain a TIMESTAMP
# variable, it must be removed
get_sapf_data(ARG_TRE) <- sapf_data[,-1]

list available sites in a db folder

Description

Retrieves the site codes in the specified folder

Usage

sfn_sites_in_folder(folder = ".")

Arguments

Details

If folder

Value

A character vector with the site codes present in the folder, an error if the folder is not valid or does not contain any site data file.

Examples

# Let's access the data in "folder". This typically is the folder where the
# sapflow data at the desired unit level is (i.e. "RData/plant"), but in this
# example we will create a temporal folder with some data to test the function
folder <- tempdir()
save(ARG_TRE, file = file.path(folder, 'ARG_TRE.RData'))
save(ARG_MAZ, file = file.path(folder, 'ARG_MAZ.RData'))
save(AUS_CAN_ST2_MIX, file = file.path(folder, 'AUS_EUC_ST2_MIX.RData'))

# lets see the sites
sites <- sfn_sites_in_folder(folder)

List all variables that can be used to filter sites

Description

sfn_vars_to_filter() returns a list with the variables for each kind of metadata that can be used to select and filter sites

Usage

sfn_vars_to_filter()

Value

A list with five elements, site_md, stand_md, species_md, plant_md and env_md

Examples

# all variables
sfn_vars_to_filter()

# by some metadata
sfn_vars_to_filter()$site_md

Show method for sfn_data

Description

print a summary for sfn_data objects

Usage

## S4 method for signature 'sfn_data'
show(object)

Arguments

Show method for sfn_data_multi

Description

print a summary for sfn_data_multi objects

Usage

## S4 method for signature 'sfn_data_multi'
show(object)

Arguments

Summaries by period

Description

This function collapse the TIMESTAMP to the desired period (day, month...) by setting the same value to all timestamps within the period. This modified TIMESTAMP is used to group by and summarise the data.

Usage

summarise_by_period(data, period, .funs, ...)

Arguments

Details

This function uses internally .collapse_timestamp and summarise_all. Arguments to control these functions can be passed as '...'. Arguments for each function are spliced and applied when needed. Be advised that all arguments passed to the summarise_all function will be applied to all the summarising functions used, so it will fail if any of that functions does not accept that argument. To complex function-argument relationships, indicate each summary function call within the .funs argument as explained here summarise_all:

# This will fail beacuse na.rm argument will be also passed to the n function,
# which does not accept any argument:
summarise_by_period(
  data = get_sapf_data(ARG_TRE),
  period = '7 days',
  .funs = list(mean, sd, n()),
  na.rm = TRUE
)

# to solve this is better to use the .funs argument:
summarise_by_period(
  data = get_sapf_data(ARG_TRE),
  period = '7 days',
  .funs = list(~ mean(., na.rm = TRUE), ~ sd(., na.rm = TRUE), ~ n())
)

Value

A 'tbl_df' object with the metrics results. The names of the columns indicate the original variable (tree or environmental variable) and the metric calculated (i.e. 'vpd_mean'), separated by underscore

TIMESTAMP_coll

Previously to the collapsing step, a temporal variable called TIMESTAMP_coll is created to be able to catch the real timestamp when some events happens, for example to use the min_time function. If your custom summarise function needs to get the time at which some event happens, use TIMESTAMP_coll instead of TIMESTAMP for that:

    min_time <- function(x, time) {
      time[which.min(x)]
    }

    summarise_by_period(
      data = get_sapf_data(ARG_TRE),
      period = '1 day',
      .funs = list(~ min_time(., time = TIMESTAMP_coll)) # Not TIMESTAMP
    )
  

Examples

library(dplyr)

# data
data('ARG_TRE', package = 'sapfluxnetr')

# simple summary
summarise_by_period(
  data = get_sapf_data(ARG_TRE),
  period = '7 days',
  .funs = list(~ mean(., na.rm = TRUE), ~ sd(., na.rm = TRUE), ~ n())
)

time at maximum/minimum

Description

helpers for sfn_metrics

Usage

max_time(x, time)

min_time(x, time)

Arguments

Details

These helper functions return the TIMESTAMP value at which the maximum value for other variable occurs. It is designed to be used inside a dplyr summarise statement.

Value

a single value (POSIXct) with the TIMESTAMP value.

Functions

• max_time(): helper for sfn_metrics

• min_time(): helper for sfn_metrics

Examples

library(dplyr)
storms %>%
  group_by(year) %>%
  summarise(wind_max = max(wind),
            hour_at_max = sapfluxnetr:::max_time(wind, time = hour),
            wind_min = min(wind),
            hour_at_min = sapfluxnetr:::min_time(wind, time = hour))