Getting Started with GeoLightViz • GeoLightViz

This tutorial demonstrates the use of GeoLightViz with the data from a European Bee-eater tagged in Germany.

library(GeoLightViz)
library(GeoPressureR)
library(tidyverse)

# Get the path to the extdata directory
extdata_dir <- system.file("extdata", package = "GeoLightViz")

Creating the tag Object

The first step is to load your geolocator data using the tag_create() function from the GeoPressureR package. This function reads raw light measurements and structures them into a standardized format.

Key parameters:

crop_start and crop_end: Define the analysis period, excluding irrelevant data before deployment and after retrieval
assert_pressure = FALSE: Required for light-only geolocators without atmospheric pressure sensors

tag <- tag_create(
  "14OI",
  directory = file.path(extdata_dir, "data/raw-tag/14OI"),
  crop_start = "2015-08-09",
  crop_end = "2016-07-11",
  assert_pressure = FALSE
)

# Detect twilight events
tag <- twilight_create(tag)

# View the tag structure
tag

The resulting tag object contains:

Light data: Cropped to your specified date range
Twilight events: Automatically detected sunrise and sunset times

Launching the Interactive Application

geolightviz(tag)

1. Labeling Twilight Events

Twilight times detected from light measurements can be noisy due to weather conditions, shading, or sensor issues. The main twilight plot provides a tool to help you identify and exclude problematic data points.

How to label:

Click “Start labeling” in the toolbar
Single points: Click individual twilight markers to toggle their status
Batch selection: Draw a rectangle to select multiple points at once

2. Defining Stationary Periods (Staps)

Stationary periods are time intervals when the bird remained at a fixed location.

How to create staps:

Click the “+” icon in the toolbar to enable drawing mode
Draw a rectangle on the light plot to define the time range
Look for patterns: Parallel, smooth twilight lines indicate stable latitude (stationary behavior)

3. Exporting Your Work

You can export both the twilight label (typically stored in data/twilight-label/14OI-labeled.csv) and the staps (typically stored in data/staps/14OI.csv). These files will be used in Step 2 for spatial analysis.

Lauching the app with Likelihood Maps

Using the twilight labels and known locations, GeoLightViz generates likelihood maps showing probable bird positions based on day length patterns.

Loading the twilight labels and known locations

First, load the twilight labels:

tag <- twilight_label_read(
  tag,
  file = file.path(extdata_dir, "data/twilight-label/14OI-labeled.csv")
)

Next, load the stationary periods and add GPS coordinates for known locations

tag$stap <- read.csv(file.path(extdata_dir, "data/staps/14OI.csv")) |>
  mutate(
    known_lon = 11.93128,
    known_lat = 51.3629
  )

Finally, define the geographic extent and resolution for likelihood map calculations (See GeoPressureR:::tag_set_map() for more details):

tag$param$tag_set_map <- list(
  extent = c(-5, 25, -10, 55),
  scale = 5
)

Launching the Enhanced Application

geolightviz(tag)

With the map configuration complete, GeoLightViz now provides additional powerful features:

The map panel now displays: - Likelihood surfaces: Color-coded probability maps based on day length matching - Position markers: Geographic locations for each stationary period - Interactive exploration: Click positions on the map to see corresponding twilight patterns

Manual adjustment: Click on the map to test different position hypotheses
Twilight comparison: Observe how predicted twilight times (lines) match observed data (points)
Maximum likelihood: Use the “ML” button to automatically find the most probable position
Compare twilight distributions between calibrated stationary periods (with known coordinates) and uncalibrated periods
Evaluate quality: Assess how well the sun elevation angle calibration performs across different time periods
Visualize uncertainty: Use the histogram view to examine twilight error distributions