Calculate the instantaneous rate of green-up.

Usage,
calc_irg(DT, id = "id", year = "yr", scaled = TRUE)

Arguments

DT

data.table of model parameters (output from model_params).

id

id column. default is 'id'. See details.

year

year column name. default is 'yr'.

scaled

boolean indicating if irg should be rescaled between 0-1 within id and year. If TRUE, provide id and year. Default is TRUE.

Value

Extended data.table 'irg' column of instantaneous rate of green-up calculated for each day of the year, for each individual and year.

Details

The DT argument expects a data.table of model estimated parameters for double logistic function of NDVI for each year and individual. Since it is the rate of green-up, model parameters required are only xmidS and scalS.

The scaled argument is used to optionally rescale the IRG result to 0-1, for each year and individual.

The id argument is used to split between sampling units. This may be a point id, polygon id, pixel id, etc. depending on your analysis. This should match the id provided to filtering functions. The formula used is described in Bischoff et al. (2012):

$$IRG = (exp((t + xmidS) / scalS)) / (2 * scalS * (exp(1) ^ ((t + xmidS) / scalS)) + (scalS * (exp(1) ^ ((2 * t) / scalS))) + (scalS * exp(1) ^ ((2 * xmidS) / scalS)))$$

(See the "Getting started with irg vignette" for a better formatted formula.)

See also

Other irg: irg

Examples

# Load data.table
library(data.table)

# Read in example data
ndvi <- fread(system.file("extdata", "ndvi.csv", package = "irg"))

# Filter and scale NDVI time series
filter_ndvi(ndvi)
#>       id   yr DayOfYear  NDVI SummaryQA filtered winter rolled    top
#>    1:  1 2002         3 -1367         3     4099   4099   4099 7443.4
#>    2:  2 2002        14  -304         3     5382   5382   5382 7462.9
#>    3:  3 2002         1   374         2     3702   3702   3702 6709.8
#>    4:  4 2002        15   635         3     5180   5180   5180 7288.1
#>    5:  5 2002         9   685         2     4621   4621   4621 7645.1
#>   ---                                                                
#> 1261:  1 2012       353   151         2     4099   4099   4099 7443.4
#> 1262:  2 2012       356   330         2     5382   5382   5382 7462.9
#> 1263:  3 2012       356   560         2     3702   3702   3702 6709.8
#> 1264:  4 2012       356  1720         2     5180   5180   5180 7288.1
#> 1265:  5 2012       356  2689         2     4621   4621   4621 7645.1
scale_doy(ndvi)
#>       id   yr DayOfYear  NDVI SummaryQA filtered winter rolled    top
#>    1:  1 2002         3 -1367         3     4099   4099   4099 7443.4
#>    2:  2 2002        14  -304         3     5382   5382   5382 7462.9
#>    3:  3 2002         1   374         2     3702   3702   3702 6709.8
#>    4:  4 2002        15   635         3     5180   5180   5180 7288.1
#>    5:  5 2002         9   685         2     4621   4621   4621 7645.1
#>   ---                                                                
#> 1261:  1 2012       353   151         2     4099   4099   4099 7443.4
#> 1262:  2 2012       356   330         2     5382   5382   5382 7462.9
#> 1263:  3 2012       356   560         2     3702   3702   3702 6709.8
#> 1264:  4 2012       356  1720         2     5180   5180   5180 7288.1
#> 1265:  5 2012       356  2689         2     4621   4621   4621 7645.1
#>                 t
#>    1: 0.005479452
#>    2: 0.035616438
#>    3: 0.000000000
#>    4: 0.038356164
#>    5: 0.021917808
#>   ---            
#> 1261: 0.964383562
#> 1262: 0.972602740
#> 1263: 0.972602740
#> 1264: 0.972602740
#> 1265: 0.972602740
scale_ndvi(ndvi)
#>       id   yr DayOfYear  NDVI SummaryQA filtered winter rolled    top
#>    1:  1 2002         3 -1367         3     4099   4099   4099 7443.4
#>    2:  2 2002        14  -304         3     5382   5382   5382 7462.9
#>    3:  3 2002         1   374         2     3702   3702   3702 6709.8
#>    4:  4 2002        15   635         3     5180   5180   5180 7288.1
#>    5:  5 2002         9   685         2     4621   4621   4621 7645.1
#>   ---                                                                
#> 1261:  1 2012       353   151         2     4099   4099   4099 7443.4
#> 1262:  2 2012       356   330         2     5382   5382   5382 7462.9
#> 1263:  3 2012       356   560         2     3702   3702   3702 6709.8
#> 1264:  4 2012       356  1720         2     5180   5180   5180 7288.1
#> 1265:  5 2012       356  2689         2     4621   4621   4621 7645.1
#>                 t scaled
#>    1: 0.005479452      0
#>    2: 0.035616438      0
#>    3: 0.000000000      0
#>    4: 0.038356164      0
#>    5: 0.021917808      0
#>   ---                   
#> 1261: 0.964383562      0
#> 1262: 0.972602740      0
#> 1263: 0.972602740      0
#> 1264: 0.972602740      0
#> 1265: 0.972602740      0

# Guess starting parameters
model_start(ndvi)
#>       id   yr DayOfYear NDVI SummaryQA filtered winter rolled    top         t
#>    1:  2 2003        NA   NA        NA       NA   5382     NA 7462.9        NA
#>    2:  2 2009        NA   NA        NA       NA   5382     NA 7462.9        NA
#>    3:  2 2011        NA   NA        NA       NA   5382     NA 7462.9        NA
#>    4:  2 2011        NA   NA        NA       NA   5382     NA 7462.9        NA
#>    5:  4 2002        61  375         2       NA   5180     NA 7288.1 0.1643836
#>   ---                                                                         
#> 1261:  5 2011       247 7634         0     7634   4621   7727 7645.1 0.6739726
#> 1262:  4 2005       251 7554         0     7554   5180   7554 7288.1 0.6849315
#> 1263:  4 2009       253 7289         0     7289   5180   7289 7288.1 0.6904110
#> 1264:  2 2008       256 7581         0     7581   5382   7581 7462.9 0.6986301
#> 1265:  5 2012       262 7773         1     7773   4621   7905 7645.1 0.7150685
#>       scaled xmidS_start xmidA_start
#>    1:     NA   0.4767123   0.7150685
#>    2:     NA   0.4575342          NA
#>    3:     NA   0.4986301   0.7780822
#>    4:     NA   0.4986301   0.7780822
#>    5:     NA   0.4328767   0.8164384
#>   ---                               
#> 1261:      1   0.4000000   0.7890411
#> 1262:      1   0.4657534   0.7534247
#> 1263:      1   0.4547945   0.7479452
#> 1264:      1   0.4712329   0.8164384
#> 1265:      1   0.3342466          NA

# Double logistic model parameters given starting parameters for nls
mods <- model_params(
  ndvi,
  return = 'models',
  xmidS = 'xmidS_start',
  xmidA = 'xmidA_start',
  scalS = 0.05,
  scalA = 0.01
)

# Fit double logistic curve to NDVI time series
fit <- model_ndvi(mods, observed = FALSE)

# Calculate IRG for each day of the year
calc_irg(fit)
#> Warning: NAs found in DT, IRG will be set to NA.
#> Warning: no non-missing arguments to min; returning Inf
#> Warning: no non-missing arguments to max; returning -Inf
#> Warning: no non-missing arguments to min; returning Inf
#> Warning: no non-missing arguments to min; returning Inf
#> Warning: no non-missing arguments to max; returning -Inf
#> Warning: no non-missing arguments to min; returning Inf
#> Warning: no non-missing arguments to min; returning Inf
#> Warning: no non-missing arguments to max; returning -Inf
#> Warning: no non-missing arguments to min; returning Inf
#> Warning: no non-missing arguments to min; returning Inf
#> Warning: no non-missing arguments to max; returning -Inf
#> Warning: no non-missing arguments to min; returning Inf
#>        id   yr     xmidS     xmidA      scalS      scalA           t
#>     1:  2 2003 0.4964268 0.7941240 0.05571006 0.02009980 0.000000000
#>     2:  2 2003 0.4964268 0.7941240 0.05571006 0.02009980 0.002739726
#>     3:  2 2003 0.4964268 0.7941240 0.05571006 0.02009980 0.005479452
#>     4:  2 2003 0.4964268 0.7941240 0.05571006 0.02009980 0.008219178
#>     5:  2 2003 0.4964268 0.7941240 0.05571006 0.02009980 0.010958904
#>    ---                                                              
#> 20126:  3 2012 0.4041541 0.8097318 0.08376870 0.01252067 0.989041096
#> 20127:  3 2012 0.4041541 0.8097318 0.08376870 0.01252067 0.991780822
#> 20128:  3 2012 0.4041541 0.8097318 0.08376870 0.01252067 0.994520548
#> 20129:  3 2012 0.4041541 0.8097318 0.08376870 0.01252067 0.997260274
#> 20130:  3 2012 0.4041541 0.8097318 0.08376870 0.01252067 1.000000000
#>               fitted          irg
#>     1:  0.0001348922 6.496844e-05
#>     2:  0.0001416908 9.216898e-05
#>     3:  0.0001488321 1.207398e-04
#>     4:  0.0001563332 1.507500e-04
#>     5:  0.0001642123 1.822720e-04
#>    ---                           
#> 20126: -0.0009268256 4.552599e-04
#> 20127: -0.0008971293 3.358220e-04
#> 20128: -0.0008683673 2.202136e-04
#> 20129: -0.0008405135 1.083125e-04
#> 20130: -0.0008135419 0.000000e+00