Create Candidate Relative-Time Windows — make

Generates windows relative to a reference date. Negative offsets are before the reference date, zero is the reference date, and positive offsets are after the reference date. Use fixed-width windows for the classic window-pane scan, where one exposure duration slides through the relative-time range. Use variable-width windows when you also want to scan alternative exposure durations.

Usage

make_windows(
  min_offset = -30,
  max_offset = -1,
  width = 5,
  slide_by = 1,
  type = c("fixed", "variable"),
  reference_col = NULL
)

Arguments

min_offset: Minimum relative-time offset included in the grid.
max_offset: Maximum relative-time offset included in the grid.
width: Window duration in relative-time units. For example, with min_offset = -5, max_offset = 0, and width = 5, the window is labeled window_m05_z00 and covers the five relative-time units ending at the reference date. Use one value for a fixed-duration scan, such as width = 5. Use several values for a variable-duration scan, such as width = 2:4 or width = c(2, 4, 6).
slide_by: Number of relative-time units used when sliding the window start. A value of 1 creates consecutive starts; a value of 2 skips every other possible start.
type: Window-generation strategy. "fixed" creates one sliding window width. "variable" creates windows from all values in width. If width has more than one value, type is treated as "variable".
reference_col: Optional name of the reference timestamp column, such as "assessment_time" or "planting_time". This is stored as metadata on the returned window grid and used by window_pane() when its own reference_col argument is NULL.

Value

A data frame with relative_start, relative_end, width, and label.

Details

make_windows() does not place windows on calendar dates by itself. It defines the relative-time grid. If reference_col is supplied, that column name is stored with the grid so window_pane() can later place the windows relative to each row's site-specific reference date.

Examples

make_windows(min_offset = -7, max_offset = -1, width = 5)
#>   relative_start relative_end width          label
#> 1             -7           -2     5 window_m07_m02
#> 2             -6           -1     5 window_m06_m01

make_windows(min_offset = -21, max_offset = -1, width = 5, slide_by = 3)
#>   relative_start relative_end width          label
#> 1            -21          -16     5 window_m21_m16
#> 2            -18          -13     5 window_m18_m13
#> 3            -15          -10     5 window_m15_m10
#> 4            -12           -7     5 window_m12_m07
#> 5             -9           -4     5 window_m09_m04
#> 6             -6           -1     5 window_m06_m01

make_windows(min_offset = -7, max_offset = -1, width = 5, reference_col = "planting_time")
#>   relative_start relative_end width          label
#> 1             -7           -2     5 window_m07_m02
#> 2             -6           -1     5 window_m06_m01

make_windows(
  min_offset = -5,
  max_offset = 5,
  width = c(2, 4, 6),
  slide_by = 2
)
#>    relative_start relative_end width          label
#> 1              -5           -3     2 window_m05_m03
#> 2              -5           -1     4 window_m05_m01
#> 3              -5            1     6 window_m05_p01
#> 4              -3           -1     2 window_m03_m01
#> 5              -3            1     4 window_m03_p01
#> 6              -3            3     6 window_m03_p03
#> 7              -1            1     2 window_m01_p01
#> 8              -1            3     4 window_m01_p03
#> 9              -1            5     6 window_m01_p05
#> 10              1            3     2 window_p01_p03
#> 11              1            5     4 window_p01_p05
#> 12              3            5     2 window_p03_p05