Growing season division

Source: R/season.R, R/season_mov.R

Divide growing seasons according to rough fitting (rFUN) result .

For season, rough fitting is applied for whole. For season_mov rough fitting is applied in every year, during which maxExtendMonth is extended.

season(
  INPUT,
  rFUN,
  wFUN,
  iters = 2,
  wmin = 0.1,
  lambda,
  nf = 3,
  frame = floor(INPUT$nptperyear/5) * 2 + 1,
  minpeakdistance,
  ypeak_min = 0.1,
  r_max = 0.2,
  r_min = 0.05,
  rtrough_max = 0.6,
  MaxPeaksPerYear = 2,
  MaxTroughsPerYear = 3,
  calendarYear = FALSE,
  IsPlot = FALSE,
  plotdat = INPUT,
  adj.param = TRUE,
  rm.closed = TRUE,
  is.continuous = TRUE,
  .check_season = TRUE,
  ...
)

season_mov(
  INPUT,
  rFUN,
  wFUN,
  iters = 2,
  wmin = 0.1,
  .lambda_vcurve = FALSE,
  lambda = NULL,
  nf = 3,
  frame = floor(INPUT$nptperyear/5) * 2 + 1,
  maxExtendMonth = 12,
  calendarYear = FALSE,
  r_min = 0.05,
  rtrough_max = 0.6,
  ...,
  len_min = 45,
  len_max = 650,
  .check_season = TRUE,
  years.run = NULL,
  IsPlot = FALSE,
  show.legend = TRUE,
  plotdat = INPUT,
  titlestr = ""
)

stat_season(INPUT, brks)

Arguments

INPUT

A list object with the elements of t, y, w, Tn (optional) and ylu, returned by check_input().
rFUN

Rough curve fitting function, can be one of smooth_wSG(), smooth_wWHIT() and smooth_wHANTS().
wFUN

weights updating function, can be one of wTSM(), wChen(), wBisquare() and wSELF().
iters

How many times curve fitting is implemented.
wmin

Double, minimum weigth (i.e. weight of snow, ice and cloud).
lambda

The smoothing parameter of smooth_wWHIT(). For season_mov(), if lambda is NULL, init_lambda() will be used. Generally, it was set as 10000, 15, and 5 for daily, 8-day and 16-day inputs respectively.
nf

The parameter of smooth_wHANTS(), number of frequencies to be considered above the zero frequency.
frame

The parameter of smooth_wSG(), moving window size. Suggested by TIMESAT, default frame = floor(nptperyear/7)*2 + 1.
minpeakdistance

Numberic, in the unit of points (default as nptperyear/12). The minimum distance of two peaks. If the distance of two maximum extreme value less than minpeakdistance, only the real maximum value will be left.
ypeak_min

y_peak >= ypeak_min
r_max

Similar as r_min, The maximum threshold should be greater than r_max.
r_min

Threshold is defined as the difference of peak value with trough value. There are two threshold (left and right). The minimum threshold should be greater than r_min.
rtrough_max

ytrough <= rtrough_max*A, A is the amplitude of y.
MaxPeaksPerYear

This parameter is used to adjust lambda in iterations. If PeaksPerYear > MaxPeaksPerYear, then lambda = lambda*2.
MaxTroughsPerYear

This parameter is used to adjust lambda in iterations. If TroughsPerYear > MaxTroughsPerYear, then lambda = lambda*2.
calendarYear

If true, only one static calendar growing season will be returned.
IsPlot

Boolean
plotdat

(optional) A list or data.table, with t, y and w. Only if IsPlot=TRUE, plot_input() will be used to plot. Known that y and w in INPUT have been changed, we suggest using the original data.table.
adj.param

Adjust rough curve fitting function parameters automatically, if too many or to less peak and trough values.
rm.closed

boolean. Whether check the two closest peaks (or troughs).
is.continuous

boolean. Whether the input is continuous? This parameter is for fluxsite site-year data.
.check_season

not used (only for debug)
...

For season_mov(), Other parameters passed to season(); For season(), other parameters passed to findpeaks().
.lambda_vcurve

Boolean. Whether to optimize Whittaker's parameter lambda by V-curve theory? This parameter only works when lambda not provided.
maxExtendMonth

Previous and subsequent maxExtendMonth data were added for every year curve fitting.
len_min, len_max

the minimum and maximum length (in the unit of days) of growing season
years.run

Numeric vector. Which years to run? If not specified, it is all years.
show.legend

boolean
titlestr

string for title
brks

A list object returned by season or season_mov.

Value

  • fit: A data.table of Rough fitting result, with the columns of (t, y, witer1, ..., witerN, ziter1, ..., ziterN).

  • dt: A data.table of Growing season dividing information, with the columns of (beg, peak, end, y_beg, y_peak, y_end, len, year, season, flag).

Details

Before dividing growing season, INPUT should be added a year in head and tail first by add_HeadTail.

Finally, use findpeaks() to get local maximum and local minimum values. Two local minimum define a growing season. If two local minimum(maximum) are too closed, then only the smaller(biger) is left.

References

  1. Kong, D., Zhang, Y., Wang, D., Chen, J., & Gu, X. (2020). Photoperiod Explains the Asynchronization Between Vegetation Carbon Phenology and Vegetation Greenness Phenology. Journal of Geophysical Research: Biogeosciences, 125(8), e2020JG005636. https://doi.org/10.1029/2020JG005636

  2. Kong, D., Zhang, Y., Gu, X., & Wang, D. (2019). A robust method for reconstructing global MODIS EVI time series on the Google Earth Engine. ISPRS Journal of Photogrammetry and Remote Sensing, 155, 13-24.

See also

findpeaks().

Examples

library(phenofit)

#> Error in library(phenofit): there is no package called ‘phenofit’
data("MOD13A1")

#> Warning: data set ‘MOD13A1’ not found

df <- tidy_MOD13(MOD13A1$dt)

#> Error in tidy_MOD13(MOD13A1$dt): object 'MOD13A1' not found
st <- MOD13A1$st

#> Error in eval(expr, envir, enclos): object 'MOD13A1' not found

date_start <- as.Date('2013-01-01')
date_end   <- as.Date('2016-12-31')

sitename <- 'CA-NS6' # df$site[1]
d     <- df[site == sitename & (date >= date_start & date <= date_end), ]

#> Error in eval(expr, envir, enclos): object 'site' not found
sp    <- st[site == sitename, ]

#> Error in eval(expr, envir, enclos): object 'st' not found
south <- sp$lat < 0

#> Error in eval(expr, envir, enclos): object 'sp' not found
nptperyear <- 23

# global parameter
IsPlot = TRUE
print  = FALSE
ypeak_min  = 0.05
wFUN = wTSM

# add one year in head and tail
# d     <- add_HeadTail(d, south = south, nptperyear = nptperyear) 
INPUT    <- check_input(d$t, d$y, d$w, QC_flag = d$QC_flag,
     nptperyear = nptperyear, south = south, 
     maxgap = nptperyear/4, alpha = 0.02, wmin = 0.2)

#> Error in check_input(d$t, d$y, d$w, QC_flag = d$QC_flag, nptperyear = nptperyear,     south = south, maxgap = nptperyear/4, alpha = 0.02, wmin = 0.2): object 'd' not found
# all year as a whole
brks  <- season(INPUT,
    rFUN = smooth_wWHIT, wFUN = wFUN,
    lambda = 10,
    plotdat = d, IsPlot = IsPlot, IsPlot.OnlyBad = FALSE)

#> Error in season(INPUT, rFUN = smooth_wWHIT, wFUN = wFUN, lambda = 10,     plotdat = d, IsPlot = IsPlot, IsPlot.OnlyBad = FALSE): object 'INPUT' not found
# curve fitting by year
brks2 <- season_mov(INPUT,
    rFUN = smooth_wWHIT, wFUN = wFUN,
    lambda = 10,
    plotdat = d, IsPlot = IsPlot, IsPlot.OnlyBad = FALSE)

#> Error in season_mov(INPUT, rFUN = smooth_wWHIT, wFUN = wFUN, lambda = 10,     plotdat = d, IsPlot = IsPlot, IsPlot.OnlyBad = FALSE): object 'INPUT' not found