Skip to contents

Create stationary periods from twilight midpoints

Source: R/tag_stap_daily.R
tag_stap_daily.Rd

Construct stationary periods from labelled sunrise and sunset times. Each boundary is the midpoint of an assumed movement period: night midpoints when movement occurs at night, or day midpoints when movement occurs during the day. The resulting stap intervals therefore cover the periods between successive movements. If a stap_long is provided (as a data.frame or a CSV path), its intervals are kept as-is and the remaining gaps are filled using twilight midpoints.

Usage

tag_stap_daily(
  tag,
  stap_long = NULL,
  movement_period = "night",
  max_twl_gap = 23.5,
  quiet = FALSE,
  twl_grouping = lifecycle::deprecated(),
  stap0 = lifecycle::deprecated()
)

Arguments

tag

a GeoPressureR tag object with twilight.

stap_long

optional long stationary periods, supplied as a stap data.frame with columns start and end, a CSV path with those columns (POSIXct-compatible strings), or a tag id resolved by read_stap().

movement_period

When the bird is assumed to be moving: "night" (default) assumes the bird is moving during the night, so sunrise-to-sunset twilights are combined into the same stationary period, while "day" assumes the bird is moving during the day, so sunset-to-sunrise twilights are combined into the same stationary period.

max_twl_gap

maximum allowed gap between consecutive twilights (in hours) before erroring, indicating missing twilights.

quiet

logical to hide messages.

twl_grouping

[Deprecated] Renamed to movement_period.

stap0

[Deprecated] Renamed to stap_long.

Value

Updated tag with a twilight-based stap and optional stap0. The stap includes a logical column stap0 set to TRUE when intervals come from the provided stap0 input.

See also

Other tag: print.tag(), read_stap(), tag_create(), tag_set_map()

Examples

# Create and label the sunrise and sunset times used to define periods.
withr::with_dir(system.file("extdata", package = "GeoPressureR"), {
  tag <- tag_create("18LX", quiet = TRUE) |>
    twilight_create() |>
    twilight_label_read()

  # Assume the bird moves at night. Preserve the long stationary periods
  # stored in data/stap-label/18LX.csv, while filling the remaining time
  # with daily periods bounded by night midpoints.
  tag <- tag_stap_daily(
    tag,
    stap_long = tag$param$id,
    movement_period = "night"
  )
})

head(tag$stap)
#>   stap_id               start                 end stap0
#> 1       1 2017-07-27 22:55:00 2017-08-08 23:20:00  TRUE