Compute likelihood map from twilight

This function estimates a likelihood map for each stationary period based on twilight data. The function performs the following steps:

1. Perform a calibration on the known stationary period. See below for details

2. Compute a likelihood map for each twilight using the calibration.

3. Combine the likelihood maps of all twilights belonging to the same stationary periods with a log-linear pooling. See GeoPressureManual | Probability aggregation for more information on probability aggregation using log-linear pooling.

Usage

geolight_map(
  tag,
  twl_calib_adjust = 1.4,
  fitted_location_duration = Inf,
  twl_llp = function(n) log(n)/n,
  compute_known = FALSE,
  keep_twl = FALSE,
  quiet = FALSE
)

geolight_map_aggregate(
  tag,
  compute_known = FALSE,
  twl_llp = function(n) log(n)/n,
  keep_twl = FALSE,
  quiet = FALSE
)

geolight_map_calibrate(
  tag,
  twl_calib_adjust = 1.4,
  fitted_location_duration = Inf,
  quiet = FALSE
)

geolight_map_likelihood(tag, compute_known = FALSE, quiet = FALSE)

Arguments

tag

a GeoPressureR tag object.

twl_calib_adjust

smoothing parameter for the kernel density (see stats::density()).

fitted_location_duration

Minimum duration (in days) of stationary period(s) eligible to be used as an automatic (fitted) calibration site estimated from twilight times. If enabled (finite duration), the longest eligible stationary period is selected and its location is estimated from twilight times, then used like a known location for calibration. Default is Inf (disabled).

twl_llp

log-linear pooling aggregation weight.

compute_known

logical defining if the map(s) for known stationary period should be estimated based on twilight or hard defined by the known location stap$known_l**

keep_twl

logical defining if the likelihood map of each twilight is retained.

quiet

logical to hide messages about the progress

Value

a tag with the likelihood of light as tag$map_light

Calibration

Calibration can be based on:

• a known location for at least one stationary period (set via tag_set_map(known = ...)), and/or

• an automatically fitted calibration location (enabled via fitted_location_duration).

When fitted_location_duration is finite, the longest eligible stationary period is selected and its location is estimated from twilight times, then used like a known location for calibration.

Instead of calibrating the twilight errors in terms of duration, we directly model the zenith angle error. We use a kernel distribution to fit the zenith angle during the known stationary period(s). The twl_calib_adjust parameter allows to manually adjust how smooth you want the fit of the zenith angle to be. Because the zenith angle error model is fitted with data from the calibration site only, and we are using it for all locations of the bird’s journey, it is safer to assume a broader/smoother distribution.

See also

Other geolight: geolight_fit_location(), geolight_solar(), plot_twl_calib(), twilight_create(), twilight_label_read(), twilight_label_write()

Other geolight: geolight_fit_location(), geolight_solar(), plot_twl_calib(), twilight_create(), twilight_label_read(), twilight_label_write()

Other geolight: geolight_fit_location(), geolight_solar(), plot_twl_calib(), twilight_create(), twilight_label_read(), twilight_label_write()

Other geolight: geolight_fit_location(), geolight_solar(), plot_twl_calib(), twilight_create(), twilight_label_read(), twilight_label_write()

Examples

withr::with_dir(system.file("extdata", package = "GeoPressureR"), {
  # Read geolocator data and set map parameters
  tag <- tag_create("18LX", quiet = TRUE) |>
    tag_label(quiet = TRUE) |>
    tag_set_map(
      extent = c(-16, 23, 0, 50),
      scale = 10,
      known = data.frame(
        stap_id = 1,
        known_lon = 17.05,
        known_lat = 48.9
      )
    ) |>
    twilight_create() |>
    twilight_label_read()
})

# Visualize twilights
plot(tag, type = "twilight")


# Calibrate twilight to zenith angle and visualize
tag <- geolight_map_calibrate(tag)
#> ℹ Calibrate zenith angle
#> ✔ Calibrate zenith angle [11ms]
#> 
plot_twl_calib(tag)


# Compute likelihood for each twilight and visualize
tag <- geolight_map_likelihood(tag)
#> ℹ Compute twilight likelihood maps
#> ✔ Compute twilight likelihood maps [1s]
#> 
plot(tag, type = "map_light_twl")


# Aggregate twilights to stationary periods and visualize
tag <- geolight_map_aggregate(tag, quiet = TRUE)
plot(tag, type = "map_light")