assign_season: Filter phenological cycles

In ranghetti/sen2rts: Build and Analyse Sentinel-2 Time Series

Filter phenological cycles

Description

Filter detected cycles basing on dates of begin / end / peak, or limit the number of cycles allowed for any specified season.

Usage

assign_season(
  pheno,
  seasons = NA,
  pop = NULL,
  pop_win = NULL,
  sos_win = NULL,
  eos_win = NULL,
  pop_name = "pop",
  sos_name = "sos",
  eos_name = "eos",
  max_n_cycles = 2,
  rm_unassigned = TRUE
)

Arguments

pheno	Cycle allocation (data table generated by extract_pheno() or cut_cycles()).
seasons	Character vector with the season names to be used.
pop	Vector with the expected dates of cycle peaks (one per season, it must be of the same length of seasons), in the form "mm-dd" (month-day). If provided, it is used to filter cycles among seasons (see argument max_n_cycles).
pop_win	List with the allowed ranges for the dates of cycle peaks (one per season): each element is a two-length character vector with two elements, in the form "mm-dd" (month-day), representing the range of the temporal window (see default value as example) within the corresponding season. The list must be of the same length of seasons. If season is one-length, pop_seasons can be also a two-length vector. Each element of the list can be left to NA in order not to specify any filtering condition.
sos_win	List with the allowed ranges for the dates of start of cycle (see pop_seasons for details about the format).
eos_win	Named list with the allowed ranges for the dates of end of cycle (see pop_seasons for details about the format).
pop_name	Character name of the field in pheno to be used as metric for the date of peak (associated with pop_seasons).
sos_name	Character name of the field in pheno to be used as metric for the date of start of cycle (associated with sos_seasons). Set to NULL in order not to apply.
eos_name	Character name of the field in pheno to be used as metric for the date of end of cycle (associated with pop_seasons). Set to NULL in order not to apply.
max_n_cycles	(optional) Maximum number of cycles to be detected in one season (default: Inf, meaning that all the identified cycles are kept). If pop is provided, the cycles with the corresponding dates of peak closer to the dates set in argument pop (for each seasons) are selected; otherwise, the field weight of the input pheno dataset is considered (cycles with the higher values are selected).
rm_unassigned	(optional) Logical: should cycles which do not match with any season (basing on the settings) be dropped from the output? (Default: TRUE)

Value

The input data table, filtered basing on arguments and with the addition of the field season, containing the name of each season (one among the ones specified in argument seasons) associated to each cycle. If seasons = NA this field is not returned.

Author(s)

Luigi Ranghetti, PhD (2020) [e-mail]

Examples

# Load input data
data("dt_cycles")
data("dt_pheno")
data("ts_filled") # used for plots

# Filter one cycle per year, standard parameters (keep the most relevant cycle)
dt_cycles
dt_cycles_seas <- assign_season(dt_cycles, max_n_cycles = 1)
dt_cycles_seas
plot(ts_filled, pheno = dt_cycles_seas)

# Filter one cycle per year, keep the one with the peak clostest to 1st August
dt_pheno_seas1 <- assign_season(dt_pheno, max_n_cycles = 1, pop = "08-01")
plot(ts_filled, pheno = dt_pheno_seas1)

# Filter cycles with start of season between 1st February and 30th April
dt_pheno_seas2 <- assign_season(
  dt_pheno, 
  sos_win = c("02-01", "04-30"),
)
plot(ts_filled, pheno = dt_pheno_seas2)

# Assign season names: "winter" for winter crops, "summer" for summer crops
# (defining winter crops as crops seeded between October and March,
# summer crops as crops seeded between April and August)
dt_pheno_seas3 <- assign_season(
  dt_pheno, 
  seasons = c("winter", "summer"),
  sos_win = list(c("10-01", "03-31"), c("04-01", "08-31")),
  sos_name = "begin",
  rm_unassigned = FALSE
)
# notice the new column "season"
dt_pheno_seas3

ranghetti/sen2rts documentation built on March 31, 2024, 1:18 a.m.