Type:	Package
Title:	Automated Calibration and Analysis of 'GLS' (Global Location Sensor) Data
Version:	0.1.0
Maintainer:	Fabio Favoretto <favoretto.fabio@gmail.com>
Description:	Provides a fully automated workflow for calibrating and analyzing light-level geolocation ('GLS') data from seabirds and other wildlife. The 'glscalibrator' package auto-discovers birds from directory structures, automatically detects calibration periods from the first days of deployment, processes multiple individuals in batch mode, and generates standardized outputs including position estimates, diagnostic plots, and quality control metrics. Implements the established threshold workflow internally, following the methods described in 'SGAT' (Wotherspoon et al. (2016) https://github.com/SWotherspoon/SGAT), 'GeoLight' (Lisovski et al. (2012) <doi:10.1111/j.2041-210X.2012.00185.x>), and 'TwGeos' (Lisovski et al. (2019) https://github.com/slisovski/TwGeos).
License:	MIT + file LICENSE
Encoding:	UTF-8
RoxygenNote:	7.3.3
Depends:	R (≥ 4.1.0)
Imports:	magrittr, maps, dplyr, lubridate, stringr, utils, grDevices, graphics, stats
Suggests:	knitr, rmarkdown, testthat (≥ 3.0.0)
VignetteBuilder:	knitr
URL:	https://github.com/fabbiologia/glscalibrator
BugReports:	https://github.com/fabbiologia/glscalibrator/issues
Language:	en-US
NeedsCompilation:	no
Packaged:	2025-11-24 15:28:27 UTC; aburtolab
Author:	Fabio Favoretto [aut, cre], Cecilia Soldatini [aut]
Repository:	CRAN
Date/Publication:	2025-11-27 19:50:02 UTC

Automatically Detect Calibration Period

Description

Automatically detects a suitable calibration period from the beginning of the light data. This assumes the bird was at a known location (typically the colony) at the start of deployment.

Usage

auto_detect_calibration(
  light_data,
  colony_lat,
  colony_lon,
  threshold = 2,
  min_twilights = 2
)

Arguments

Details

The function tries calibration periods of different lengths (2, 3, 1, 4, 5 days) and returns the first period that yields sufficient twilights with both sunrise and sunset events.

Value

A list with:

Examples

example_file <- gls_example("W086")
light_data <- read_lux_file(example_file)
calib <- auto_detect_calibration(light_data,
                                  colony_lat = 27.85,
                                  colony_lon = -115.17,
                                  threshold = 2,
                                  min_twilights = 4)
print(calib)

Batch Calibration of Multiple GLS Devices

Description

Main function for automated batch processing of GLS data. Auto-discovers all birds in a directory, detects calibration periods, performs an internal gamma-style sun elevation calibration, and generates standardized outputs.

Usage

calibrate_gls_batch(
  data_dir,
  output_dir,
  colony_lat,
  colony_lon,
  light_threshold = 2,
  exclude_equinoxes = NULL,
  min_positions = 10,
  create_plots = TRUE,
  verbose = TRUE
)

Arguments

Details

This function implements a complete automated workflow:

1. Auto-discovers .lux files in the data directory

2. For each bird:

   • Reads light data

   • Auto-detects calibration period

   • Detects and filters twilights

   • Learns a sun elevation angle directly from the calibration data

   • Calculates positions using threshold method

   • Generates diagnostic plots

3. Combines results into standardized formats

4. Creates summary statistics and quality control metrics

Value

A list containing:

Examples

example_dir <- file.path(tempdir(), "gls_example_data")
dir.create(example_dir, showWarnings = FALSE)
file.copy(
  system.file("extdata/W086_24May17_215116.lux", package = "glscalibrator"),
  file.path(example_dir, "W086_24May17_215116.lux"),
  overwrite = TRUE
)

results <- calibrate_gls_batch(
  data_dir = example_dir,
  output_dir = file.path(tempdir(), "gls_example_output"),
  colony_lat = 27.85178,
  colony_lon = -115.17390,
  min_positions = 1,
  create_plots = FALSE,
  verbose = FALSE
)

equinoxes <- list(
  c("2024-08-24", "2024-10-23"),
  c("2024-02-19", "2024-04-19")
)
results_filtered <- calibrate_gls_batch(
  data_dir = example_dir,
  output_dir = file.path(tempdir(), "gls_example_output"),
  colony_lat = 27.85,
  colony_lon = -115.17,
  exclude_equinoxes = equinoxes,
  min_positions = 1,
  create_plots = FALSE,
  verbose = FALSE
)

Convert to GLSmerge Format

Description

Converts calibrated position data to the standard GLSmerge format used by many researchers and analysis tools.

Usage

convert_to_glsmerge(results, bird_id, zenith)

Arguments

Value

data.frame in GLSmerge format

Detect Twilight Times from Light Data

Description

Detects sunrise and sunset times from light intensity data using a threshold-crossing method. This is a proven, simple approach that identifies transitions between day and night.

Usage

detect_twilights(light_data, threshold = 2)

Arguments

Value

A data.frame with columns:

Examples

# Detect twilights from example data
example_file <- gls_example("W086")
light_data <- read_lux_file(example_file)
twilights <- detect_twilights(light_data, threshold = 2)
head(twilights)

Estimate the sun elevation angle for a known site

Description

Uses observed calibration twilights at a known location to learn the sun elevation angle required by the threshold method. The calculation minimizes the median absolute difference between observed and predicted twilights using the NOAA solar equations.

Usage

estimate_sun_elevation(twilight, rise, lon, lat, interval = c(-12, 2))

Arguments

Value

Named numeric vector containing the inferred zenith angle ('z1'), the sun elevation ('degElevation'), and the objective value.

Filter and Clean Twilight Data

Description

Applies quality filters to twilight data to remove spurious detections caused by shading, logger malfunction, or other artifacts.

Usage

filter_twilights(twilights, light_data = NULL, threshold = 2, strict = TRUE)

Arguments

Details

Filters applied:

• Remove twilights too close together (< 1-2 hours)

• Remove twilights with unusual intervals (far from 12 or 24 hours)

• Optionally check light quality around twilight (if light_data provided)

Value

A filtered data.frame of twilights

Examples

# Filter twilights from example data
example_file <- gls_example("W086")
light_data <- read_lux_file(example_file)
twilights <- detect_twilights(light_data, threshold = 2)
twilights_clean <- filter_twilights(twilights, light_data, threshold = 2)
nrow(twilights_clean)

Get Path to Example Data

Description

Helper function to get the path to example .lux files included with the package. Three example files are available and their metadata is exposed via glscalibrator_example_metadata.

Usage

gls_example(which = "all")

Arguments

Value

Character vector of file path(s) to example data

Examples

# Inspect available example datasets
list_gls_examples()

# Read the bundled W086 seabird deployment
light_data <- read_lux_file(gls_example("W086"))

# Run calibration on the synthetic dataset (quick demo)
synt_path <- gls_example("synthetic")
synthetic_data <- read_lux_file(synt_path)
twl <- detect_twilights(synthetic_data, threshold = 2)

Metadata for the bundled GLS example datasets

Description

The package ships with three light-level geolocation (.lux) files that are used throughout the documentation, vignettes, and tests. This metadata table records their origin and recommended use so that analysts can reference the contents programmatically.

Named character vector of the filenames stored in inst/extdata/, keyed by the identifiers recognised by gls_example().

Usage

glscalibrator_example_metadata

glscalibrator_example_files

Format

A data frame with 3 rows and 7 variables:

name

Short identifier used by gls_example()

file

Filename stored under inst/extdata/

type

"real" or "synthetic" dataset

description

Summary of the dataset contents

duration_days

Approximate deployment duration represented

size_kb

Approximate file size in kilobytes

notes

Additional guidance for analysis and demonstrations

A data frame (tibble) with metadata for each example dataset.

Named character vector. Use with system.file("extdata", ...).

Details

All files are plain-text .lux exports that can be read directly with read_lux_file(). Real datasets were collected from tropical seabirds breeding near 27.85°N, 115.17°W and are approved for demonstration and teaching purposes. The synthetic dataset contains idealised sunrise/sunset curves for rapid testing.

See Also

gls_example(), list_gls_examples()

List Available Example Datasets

Description

Shows information about example datasets included with the package.

Usage

list_gls_examples()

Value

A data.frame with columns: name, file, type, description, duration_days, size_kb, notes

Examples

list_gls_examples()

Plot Calibration Diagnostics

Description

Creates diagnostic plots showing light data and detected twilights during the calibration period.

Usage

plot_calibration(light_data, twilights, threshold, bird_id, output_dir)

Arguments

Value

NULL (creates PNG file)

Plot Bird Track

Description

Creates a map showing the estimated movement track of a bird

Usage

plot_track(
  results,
  colony_lat,
  colony_lon,
  bird_id,
  output_dir,
  hemisphere = ""
)

Arguments

Value

NULL (creates PNG file)

Process a Single Bird

Description

Internal function to process a single GLS device

Usage

process_single_bird(
  lux_file,
  bird_id,
  colony_lat,
  colony_lon,
  light_threshold,
  exclude_equinoxes,
  output_dir,
  fig_dir,
  verbose
)

Read Light Data from .lux Files

Description

Reads and parses light intensity data from .lux files generated by geolocation loggers. Handles various formats and automatically detects the start of data.

Usage

read_lux_file(file_path)

Arguments

Value

A data.frame with columns:

Examples

# Read example data included with package
example_file <- gls_example("W086")
light_data <- read_lux_file(example_file)
head(light_data)

Solar geometry helpers used internally by glscalibrator

Description

These functions implement the NOAA solar algorithms to replace the archived GeoLight/TwGeos functionality with native code that keeps the package on CRAN-friendly dependencies.