phase_stats: Calculate Parameters of Shrinkage and Expansion Phases
In treenet/treenetproc: Clean, Process and Visualize Dendrometer Data

Description Usage Arguments Details Value Examples

phase_stats calculates the timing, duration, amplitude and the rate of change of shrinkage and expansion phases. In addition, days on which radial change is likely driven by transpiration or temperature are identified.

phase_stats(
  dendro_L2,
  phase_wnd = 8,
  plot_phase = FALSE,
  plot_export = TRUE,
  agg_daily = TRUE,
  tz = "UTC"
)

`dendro_L2`	input `data.frame` containing cleaned `L2` dendrometer data (obtained from functions `proc_dendro_L2` or `corr_dendro_L2`).
`phase_wnd`	numeric, specify the window length (in hours) used to identify local maxima and minima. A shorter window length leads to the identification of more local maxima and minima.
`plot_phase`	logical, specify whether identified phases should be plotted.
`plot_export`	logical, specifies whether the plots are exported as a `PDF` file to the working directory or are plotted in the console.
`agg_daily`	logical, specify whether phase statistics are aggregated by day (`agg_daily = TRUE`) or appended to the `L2` data (`agg_daily = FALSE`).
`tz`	specify the desired time zone. Default is `"UTC"`.

The identification of local maxima and minima in the function phase_stats is inspired by the functionality of phase_def in the package dendrometeR. Overlapping sets of time windows are used to identify local maxima and minima, i.e. maxima or minima that appear in both overlapping time windows and are not only bound to the start or the end of the respective time windows.

The often reported parameter maximum daily shrinkage ('mds') can be extracted from the output parameters. 'mds' is equal to 'shrink_amp' in case 'shrink_dur < 1440' (i.e. the shrinkage is shorter than 24 hours). Example code on how to extract 'mds' can be found in the vignette vignette("Introduction-to-treenetproc", package = "treenetproc").

The following additional variables are returned by phase_stats:

`day`	day on which the respective phase ends (format `%Y-%m-%d`.
`doy`	day of year on which the respective phase ends.
`shrink_start/exp_start`	timestamp of the start of the shrinkage or expansion phase.
`shrink_end/exp_end`	timestamp of the end of the shrinkage or expansion phase.
`shrink_dur/exp_dur`	duration (minutes) of the shrinkage or expansion phase.
`shrink_amp/exp_amp`	amplitude (`µm`) of the shrinkage or expansion phase.
`shrink_slope/exp_slope`	slope (`µm * reso^-1`) of the shrinkage or expansion phase.
`phase_class`	days are classified as `1` if a shrinkage occurs during the day, and as `-1` if there is an expansion during the day. On all other days phase_class is set to NA.

In case data is not aggregated to daily values (agg_daily = FALSE), all columns are appended to the input data. All parameters related to shrinkage or expansion phases are pasted at the timestamp corresponding to the end of the respective phases (shrink_end or exp_end). All other rows are set to NA.

# Subset dataset for example
library(dplyr)
data_L2 <- dendro_data_L2 %>%
   filter(series == "site-1_dendro-2")

phase_stats(dendro_L2 = data_L2, plot_phase = TRUE, plot_export = FALSE)