sapfluxnetr package offers a very flexible but powerful API based on the tidyverse packages to aggregate and summarise the site/s data in the form of the sfn_metrics function. All the metrics family of functions (?metrics) make use of the sfn_metrics funcion under the hood. If you want full control to the statistics returned and aggregation periods, we recommend you to use this API. This vignette will show you how.

Pre-fixed summarising functions

  1. daily_metrics
  2. monthly_metrics
  3. predawn_metrics
  4. midday_metrics
  5. nightly_metrics
  6. daylight_metrics

See each function help for a detailed description and examples of use.

Custom summarising functions

daily_metrics and related functions return a complete set of metrics ready for use, but if you want simpler metrics and/or different metrics you can supply your own summarising functions using the .funs argument.
The correct way of especifying the functions are as described in the summarise_all help (help(dplyr::summarise_all)), function names, quosure style lambda functions or a list of either form. We recommend a list of quosure style lamda functions, as is easier to add the corresponding arguments for each function:

# libraries
library(sapfluxnetr)
#> Registered S3 methods overwritten by 'ggplot2':
#>   method         from 
#>   [.quosures     rlang
#>   c.quosures     rlang
#>   print.quosures rlang
library(dplyr)
#> 
#> Attaching package: 'dplyr'
#> The following objects are masked from 'package:stats':
#> 
#>     filter, lag
#> The following objects are masked from 'package:base':
#> 
#>     intersect, setdiff, setequal, union

### only mean and sd at a daily scale
# data
data('ARG_TRE', package = 'sapfluxnetr')

# summarising funs (built with quosure style lambdas list)
custom_funs <- list(mean = ~ mean(., na.rm = TRUE), std_dev = ~ sd(., na.rm = TRUE))

# metrics
foo_simpler_metrics <- sfn_metrics(
  ARG_TRE,
  period = '1 day',
  .funs = custom_funs,
  solar = TRUE,
  interval = 'general'
)
#> [1] "Crunching data for ARG_TRE. In large datasets this could take a while"
#> [1] "General data for ARG_TRE"

foo_simpler_metrics[['sapf']]
#> # A tibble: 14 x 9
#>    TIMESTAMP           ARG_TRE_Nan_Jt_… ARG_TRE_Nan_Jt_… ARG_TRE_Nan_Jt_…
#>    <dttm>                         <dbl>            <dbl>            <dbl>
#>  1 2009-11-17 00:00:00             308.             173.             303.
#>  2 2009-11-18 00:00:00             507.             376.             432.
#>  3 2009-11-19 00:00:00             541.             380.             391.
#>  4 2009-11-20 00:00:00             330.             218.             272.
#>  5 2009-11-21 00:00:00             338.             219.             278.
#>  6 2009-11-22 00:00:00             384.             243.             310.
#>  7 2009-11-23 00:00:00             492.             300.             390.
#>  8 2009-11-24 00:00:00             573.             389.             497.
#>  9 2009-11-25 00:00:00             601.             400.             484.
#> 10 2009-11-26 00:00:00             502.             360.             450.
#> 11 2009-11-27 00:00:00             544.             411.             506.
#> 12 2009-11-28 00:00:00             573.             451.             589.
#> 13 2009-11-29 00:00:00             371.             285.             357.
#> 14 2009-11-30 00:00:00             386.             293.             381.
#> # … with 5 more variables: ARG_TRE_Nan_Jt_4_mean <dbl>,
#> #   ARG_TRE_Nan_Jt_1_std_dev <dbl>, ARG_TRE_Nan_Jt_2_std_dev <dbl>,
#> #   ARG_TRE_Nan_Jt_3_std_dev <dbl>, ARG_TRE_Nan_Jt_4_std_dev <dbl>

When supplying only one function to .funs, names of variables are not changed to contain the metric name at the end, as the summary function returns the same columns as the original data

Custom aggregation periods

period argument in sfn_metrics is passed to .collapse_timestamp function, and so, it can use the same input:

  • “frequency period” format, where frequency is a number and period is an interval as character (i.e. “1 year”, “7 days”)
  • A custom function name (without quotes). This way you can build irregular or custom periods. This function first argument must always be the timestamp to be collapsed, and can have other arguments that will be supplied in the dots (...) argument of sfn_metrics. Also, this function always must return a vector of timestamps of the same length as the original timestamp.
    For example, if you want to summarise by quarters we can use the quarter function from the lubridate package:

Extra parameters

sfn_metrics has a ... parameter intended to supply additional parameters to the internal functions used:

  1. .collapse_timestamp accepts the following extra arguments:

    • side
      “start” by default in the sfn_metrics implementation
  2. dplyr::summarise_all accepts extra arguments intended to be applied to the summarising functions provided (to all, so they all must have the argument provided or an error will be raised). That’s the reason because we recommend to use the list way, as the arguments are specified for the individual functions.

For example, if we want the TIMESTAMPs after aggregation to show the end of the period instead the begining (default) we can do the following:

If it is compared with the foo_simpler_metrics calculated before, now the period is identified in the TIMESTAMP by the ending of the period (daily in this case).

When supplying custom functions as “period” argument, the default coverage statistic is not reliable as there is no way of knowing beforehand the period/s in minutes.

Temporary columns helpers

The internal aggregation process in sfn_metrics generates some transitory columns which can be used in the summarising functions:

TIMESTAMP_coll

When aggregating by the declared period (i.e. "daily"), the TIMESTAMP column collapses to the period start/end value (meaning that all the TIMESTAMP values for the same day becomes identical).
This makes impossible to use any summarise functions that obtain the time of the day at which one event happens (i.e. time of the day at which the maximum sap flow occurs) because all TIMESTAMP values are identical. For that kind of summarising functions, a transitory column called TIMESTAMP_coll is created. So in this case we can create a function that takes de variable values for the day, the TIMESTAMP_coll values for the day and return the TIMESTAMP at which the max sap flow occurs and use it with sfn_metrics:

max_time <- function(x, time) {
  
  # x: vector of values for a day
  # time: TIMESTAMP for the day 

  # if all the values in x are NAs (a daily summmarise of no measures day for
  # example) this will return a length 0 POSIXct vector, which will crash
  # dplyr summarise step. So, check if all NA and if true return NA as POSIXct
  if(all(is.na(x))) {
    return(as.POSIXct(NA, tz = attr(time, 'tz'), origin = lubridate::origin))
  } else {
    time[which.max(x)]
  }
}

custom_funs <- list(max = ~ max(., na.rm = TRUE), ~ max_time(., TIMESTAMP_coll))

max_time_metrics <- sfn_metrics(
  ARG_TRE,
  period = '1 day',
  .funs = custom_funs,
  solar = TRUE,
  interval = 'general'
)
#> [1] "Crunching data for ARG_TRE. In large datasets this could take a while"
#> [1] "General data for ARG_TRE"

max_time_metrics[['sapf']]
#> # A tibble: 14 x 9
#>    TIMESTAMP           ARG_TRE_Nan_Jt_… ARG_TRE_Nan_Jt_… ARG_TRE_Nan_Jt_…
#>    <dttm>                         <dbl>            <dbl>            <dbl>
#>  1 2009-11-17 00:00:00             322.             190.             313.
#>  2 2009-11-18 00:00:00             778.             715.             679.
#>  3 2009-11-19 00:00:00            1015.             694.             633.
#>  4 2009-11-20 00:00:00             648.             401.             442.
#>  5 2009-11-21 00:00:00             664.             406.             539.
#>  6 2009-11-22 00:00:00             812.             564.             816.
#>  7 2009-11-23 00:00:00            1085.             676.             935.
#>  8 2009-11-24 00:00:00             992.             736.            1115.
#>  9 2009-11-25 00:00:00             976.             646.             951.
#> 10 2009-11-26 00:00:00             932.             766.            1087.
#> 11 2009-11-27 00:00:00             862.             704.             921.
#> 12 2009-11-28 00:00:00             845.             763.            1165.
#> 13 2009-11-29 00:00:00             714.             747.             701.
#> 14 2009-11-30 00:00:00             875.             646.             919.
#> # … with 5 more variables: ARG_TRE_Nan_Jt_4_max <dbl>,
#> #   ARG_TRE_Nan_Jt_1_max_time <dttm>, ARG_TRE_Nan_Jt_2_max_time <dttm>,
#> #   ARG_TRE_Nan_Jt_3_max_time <dttm>, ARG_TRE_Nan_Jt_4_max_time <dttm>