Estimate one location per stationary period from twilight times

For each stationary period (stap_id) with usable twilight events, estimate a single longitude, latitude, and effective zenith angle by minimizing the squared spherical distance to the corresponding iso-zenith small circles.

Each twilight defines a small circle on the Earth: the set of locations at a fixed angular distance (zenith angle) from the subsolar point at that time. The fitted location is the point that is, in a least-squares sense, closest to all those circles simultaneously.

For a stationary period with twilight-specific subsolar points s_i, the fitted longitude lon, latitude lat, and zenith angle z minimize

mean_i ( d((lon, lat), s_i) - z )^2 + P_prior(z)

where d((lon, lat), s_i) is the great-circle angular distance from the candidate location to the subsolar point at twilight i. The first term is the mean squared residual to the iso-zenith small circles, normalized by the number of twilight events so its influence does not depend on sample size.

P_prior(z) is an optional Gaussian penalty on the fitted zenith angle:

1/2 * ((z - mu) / sigma)^2

where mu = zenith_prior_mean and sigma = zenith_prior_sd. This acts as a prior on the effective zenith angle while leaving longitude and latitude driven by the twilight geometry.

Usage

geolight_fit_location(
  tag,
  fitted_location_duration = Inf,
  extent = NULL,
  zenith_bounds = c(70, 110),
  zenith_prior_mean = 93,
  zenith_prior_sd = 1.3,
  zenith_prior_penalty_weight = 1e-04,
  compute_known = FALSE,
  quiet = FALSE
)

Arguments

tag

A GeoPressureR tag object containing tag$twilight and tag$stap.

fitted_location_duration

Minimum duration (in days) of stationary period(s) eligible to be used as a fitted location from twilight times. Default is Inf (disabled).

extent

Numeric vector c(W, E, S, N) in degrees (longitude west/east, latitude south/north).

zenith_bounds

Numeric vector of length 2 giving zenith bounds (degrees).

zenith_prior_mean

Gaussian prior mean for fitted zenith angle (degrees).

zenith_prior_sd

Gaussian prior standard deviation for fitted zenith angle (degrees).

zenith_prior_penalty_weight

Weight controlling how strongly automatically fitted locations are pulled toward zenith_prior_mean. This only affects fitted locations; known locations are still used directly when compute_known = FALSE.

compute_known

Logical; if FALSE, known stationary periods are copied from tag$stap (rather than being estimated).

quiet

Logical; if TRUE, suppress informative messages.

Value

A path data.frame derived from tag$stap with added columns: lon, lat, zenith. Rows where fitting was not possible remain NA.

See also

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

Examples

withr::with_dir(system.file("extdata", package = "GeoPressureR"), {
  tag <- tag_create("18LX", quiet = TRUE) |>
    tag_label(quiet = TRUE) |>
    twilight_create() |>
    twilight_label_read()
})
tag <- tag_stap_daily(tag, quiet = TRUE)
path <- geolight_fit_location(tag, fitted_location_duration = 5, quiet = TRUE)