calc_metrics: Easy function for calculating all polar meatrics.

In bjornbrooks/PolarMetrics: Functions for analyzing seasonal patterns in environmental variables

Description

A basic, but fast function for calculating all polar metrics from arrays or xts objects.

Usage

calc_metrics(input, t = NULL, yr_type, spc, lcut, hcut, return_vecs, sin_cos)

Arguments

input	Either a vector of values or a 1-column xts object indexed with time stamps. If input is an xts object then omit argument t. Else if input is a vector of values then t should be set to a corresponding vector of time values.
t	An optional vector of time values (e.g., days) corresponding to the input vector sampling points. Do not use this argument if input is an xts object.
yr_type	Argument specifying either 'cal_yr' for output (of timing variables) given in days starting from Jan. 1, or 'rot_yr' for output in days starting from the average seasonal minimum.
spc	Integer value specifying the number of samples per cycle (measurements per year) in input.
lcut	Numeric value in the range [0,0.5] passed to window_idx function. Indicates the percentile to truncate from the first half of each cycle. For example, 0.15 will result in remove the interval corresponding to [0%,15%] representing a window that begins after the 15th-percentile is crossed.
hcut	Numeric value in the range (0.5,1] passed to window_idx function. Indicates the percentile to truncate from the last half of each cycle. For example, 0.85 will result in remove the interval corresponding to [85%,100%] representing a window that begins after the 85th-percentile is crossed.
return_vecs	logical argument specifying whether or not to include all of the horizontal and vertical component vectors in output.
sin_cos	logical argument. If TRUE then each timing metric (es, ms, etc.) is returned as its sine and cosine components, es is returned as es_sin and es_cos.

Details

calc_metrics runs through the entire polar transformation process and conveniently outputs the final polar metrics for all years included in the input.

Value

Returns a list with all of the derived polar metrics (e.g., early season, mid season, etc.). Timing variables in output can be returned relative to the standard calendar year or rotated to a relative year using yr_type argument. Sine and cosine components can also be returned instead of days since start using sin_cos argument. The optional argument return_vecs can be used to add the actual vecturs used in deriving the polar metrics to the returned list. This will also return the overall average (all years) statistics of the resultant vector (rv) and its opposite the anti-vector (av). Table below indicates the variable components of each object within the returned list. metrics (data frame): year, es (or es_sin, es_cos), # Early ssn DOY ems (or ems_sin, ems_cos), # Early-mid ssn DOY ms (or ms_sin, ms_cos), # Mid ssn DOY lms (or lms_sin, lms_cos), # Late-mid ssn DOY ls (or ls_sin, ls_cos), # Late ssn DOY s_intv, # Season length(days) s_avg, # Avg data val in ssn s_sd, # StDev of data dur ssn s_mag, # Mag of avg vec in ssn ems_mag, # Mag early-mid ssn vec lms_mag, # Mag late-mid ssn vec a_avg # Avg data val of yr component_vectors (data frame): VX, VY # Hrz, vert vec comp. average_vectors (data frame): rv_idx, rv_ang, # Resultant vector rv_doy, rv_mag, # attributes av_idx, av_ang, av_doy # Anti-vector attr.

Author(s)

Bjorn J. Brooks, Danny C. Lee, William W. Hargrove, Lars Y. Pomara

References

Brooks, B.J., Lee, D.C., Desai, A.R., Pomara, L.Y., Hargrove, W.W. (2017). Quantifying seasonal patterns in disparate environmental variables using the PolarMetrics R package.

Examples

library(PolarMetrics)
library(xts)
input <- xts(mndvi$fef, as.Date(mndvi$date))
### Calculate polar measures relative to calendar year
calc_metrics(input, yr_type='cal_yr', spc=46, lcut=0.15, hcut=0.8,
             return_vecs=FALSE, sin_cos=FALSE)
### Calculate as above and return sine, cosine components of timing metrics
calc_metrics(input, yr_type='cal_yr', spc=46, lcut=0.15, hcut=0.8,
             return_vecs=FALSE, sin_cos=TRUE)
### Calculate & return the average vectors for the entire time series
calc_metrics(input, yr_type='cal_yr', spc=46, lcut=0.15, hcut=0.8,
             return_vecs=TRUE, sin_cos=FALSE)$avg_vectors
### Calculate & return the horizontal and vertical vector components
head(calc_metrics(input, yr_type='cal_yr', spc=46, lcut=0.15, hcut=0.8,
             return_vecs=TRUE, sin_cos=FALSE)$vectors)

bjornbrooks/PolarMetrics documentation built on Dec. 22, 2020, 1:42 a.m.