sfn_metrics: Metrics summary function

View source: R/metrics.R

sfn_metricsR Documentation

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

sfn_data

sfn_data or sfn_data_multi object to obtain the metrics from

period

Time period to aggregate data by. See period section for an explanation about the periods ('3 hours', '1 day', '1 month', '1 year', ...)

.funs

List of function calls to summarise the data by, see .funs section for more details.

solar

Logical indicating if the solarTIMESTAMP must be used instead of the site local TIMESTAMP. Default to TRUE (use solarTIMESTAMP).

interval

Character vector indicating if the metrics must be filtered by an special hour interval. See Interval section in details.

int_start

Integer value indicating the starting hour of the special interval in 24h format. See Interval section in details.

int_end

Integer value indicating the ending hour of the special interval in 24h format. See Interval section in details.

...

optional arguments to pass to methods used (i.e. .collapse_timestamp or summarise funs extra 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']]


sapfluxnetr documentation built on Feb. 16, 2023, 7:52 p.m.