Find flecks

Detects and characterizes "flecks" in a time series of irradiances.

Usage

find_flecks(
  time,
  var,
  zero.lim = 5e-04,
  minTime = 0,
  minAmp = 0,
  minPdiff = 0,
  asymmetry = 1/4,
  trimCV = 0.05,
  asmMethod = c("mean", "max", "rm"),
  bounds = c(0, 1),
  timeSplit = 10,
  shadeflecks = FALSE,
  time.digits = 3,
  var.digits = 2,
  verbose = TRUE
)

Arguments

time

numeric Vector of times from the time-series (x-axis).

var

numeric Vector of observations from the time-series (y-axis).

zero.lim

numeric Limit for multiplication, only values higher than zero.lim are kept (removes noise and prevents recording zeroes when time-series is flat.).

minTime

numeric Flecks found with duration below minTime will be discarded. Keep at 0 to keep all flecks.

minAmp

numeric Flecks found with amplitude below minAmp will be discarded. Keep at 0 to keep all flecks.

minPdiff

numeric Flecks found with a percent difference between peak and baseline that is below minPdiff will be discarded. Keep at 0 to keep all flecks.

asymmetry

numeric Threshold value to qualify fleck as asymeric. Asymetry happens when the baseline have large difference in their value.

trimCV

Control trimming threshold. Fleck baselines are trimmed iteratively based on the coefficient of variation between two points at each baseline side.

asmMethod

character One of "mean", "max", "rm". Decides what to do with asymetric flecks "mean" averages the two baselines, "max" keeps the largest baseline, "rm" discard the asymetric fleck.

bounds

numeric vector of length 2 For relative amplitude calculations, normalize between 0 and 1 by default.

timeSplit

integer Increase time-series data frequency by linear interpolation. A value of 10 usually guarantee accuracy.

shadeflecks

logical If true, run the function in shadefleck mode instead of in the default sunfleck mode, i.e., the function will find troughs instead of peaks in the data.

time.digits, var.digits

integer Argument passed to parameter digits in internal calls to round() for time and var values.

verbose

logical If TRUE, provides more information while running.

Details

A sunfleck is characterized by an increase followed by a decrease in irradiance. As a first step zero crossings of the derivative are located using the same code as in find_zeros(). In a second step, flecks are searched and once found, are checked for asymmetry between baselines. If found, tries to extend baseline a bit. If still asymmetric, behaviour is as defined by asmMethod. Then fleck is compared againts criteria given by minTime, minAmp and minPdiff. If passed, the baselines are trimmed. Conditions are checked once more, and trimming is reversed if conditions are not passed any more. In the last step overlapping flecks are removed and the time interval between successive flecks is computed. Finally, the fleck properties are returned in a data frame.

References

Durand M, Matule B, Burgess AJ, Robson TM. 2021. Sunfleck properties from time series of fluctuating light. Agricultural and Forest Meteorology 308-309, 108554. doi:10.1016/j.agrformet.2021.108554