Repository files navigation

An R package for fully automated calibration and analysis of Global Location Sensor (GLS) data from seabirds and other wildlife.glscalibrator streamlines the traditionally manual and time-consuming process of GLS data analysis by auto-discovering devices, detecting calibration periods, and batch processing multiple individuals.

• Fully Automated Workflow: Process entire datasets with a single command
• Auto-Discovery: Automatically finds all GLS devices in your directory structure
• Intelligent Calibration: Auto-detects calibration periods from the first days of deployment
• Batch Processing: Handles multiple individuals without manual intervention
• Quality Control: Automated hemisphere checks, twilight filtering, and diagnostic plots
• Standardized Outputs: Produces consistent data formats (GLSmergedata.csv) and visualizations
• Built on Proven Methods: Implements NOAA-style solar geometry to replicate the classic threshold workflow without archived dependencies

Install from GitHub (this will pull the CRAN dependencies automatically):

if (!requireNamespace("remotes",quietly=TRUE)) install.packages("remotes")remotes::install_github("fabbiologia/glscalibrator")

library(glscalibrator)# Process all GLS devices in a directoryresults<- calibrate_gls_batch(data_dir= system.file("extdata",package="glscalibrator"),output_dir="data/processed/calibration",colony_lat=27.85178,# Colony latitudecolony_lon=-115.17390# Colony longitude)# Check summaryprint(results$summary)# Access individual bird resultsbird_positions<-results$results$BW154_05Jul24_225805

Traditional GLS analysis requires:

1. Manual identification of each bird's data file
2. Manual selection of calibration period
3. Custom scripting for twilight detection
4. Individual processing of each bird
5. Manual creation of output formats and plots

glscalibrator automates all of this:

# Traditional approach (hours of work)# Read file → Find calibration dates → Detect twilights →# Filter twilights → Calibrate → Calculate positions →# Create plots → Repeat for each bird → Combine outputs# glscalibrator approach (one command)results<- calibrate_gls_batch(data_dir,output_dir,colony_lat,colony_lon)

output_dir/├── data/│   ├── GLSmergedata.csv              # Combined data (standard format)│   ├── all_birds_calibrated.csv     # Combined positions│   ├── calibration_summary.csv      # Summary statistics│   ├── BW154_calibrated.csv         # Individual bird data│   └── BW154_GLSmergedata.csv       # Individual bird (standard format)└── figures/    ├── all_tracks_combined.png      # All tracks on one map    ├── BW154_track.png              # Individual track    └── BW154_calibration.png        # Calibration diagnostics

# Define equinox exclusion periodsequinoxes<-list(  c("2024-08-24","2024-10-23"),# Autumn equinox  c("2024-02-19","2024-04-19")# Spring equinox)results<- calibrate_gls_batch(data_dir="data/raw/birds",output_dir="data/processed/calibration",colony_lat=27.85,colony_lon=-115.17,exclude_equinoxes=equinoxes)

# Read light data bundled with the packagelight_data<- read_lux_file(gls_example("W086"))# Auto-detect calibration periodcalib<- auto_detect_calibration(light_data,colony_lat=27.85,colony_lon=-115.17)# Detect twilightstwilights<- detect_twilights(light_data,threshold=2)# Filter twilightstwilights_clean<- filter_twilights(twilights,light_data,threshold=2)

The package implements a proven workflow:

1. Twilight Detection: Threshold-crossing method (light > 2 lux = day)
2. Auto-Calibration: Searches first 1-5 days for stable period at colony
3. Gamma Calibration: Learns an optimal sun elevation directly from calibration twilights (algorithm inspired by TwGeos)
4. Position Estimation: Applies NOAA solar geometry to derive coordinates from twilight pairs
5. Quality Filtering:
   • Removes twilights < 1 hour apart
   • Filters unusual intervals (not ~12 or ~24 hours)
   • Checks light quality around transitions
   • Validates hemisphere (Western vs Eastern)
   • Excludes equinox periods

glscalibrator ships with three.lux files ininst/extdata/ that power thedocumentation, tests, and vignettes. You can explore them programmatically:

# List available example datasets and their metadataglscalibrator_example_metadata# Retrieve the path to a specific filew086_path<- gls_example("W086")# See summary informationlist_gls_examples()

Use these datasets in tutorials, automated tests, or live demonstrations withoutneeding external files. They are also summarised ininst/extdata/README.md forquick human-readable reference.

• dplyr /magrittr /lubridate /stringr – Data manipulation utilities
• maps – Basemap rendering for diagnostic plots
• Base R packagesstats,graphics,grDevices,utils
• Historical inspiration fromTwGeos,GeoLight, andSGAT algorithms (no runtime dependency)

Run the automated test suite to verify the installation:

testthat::test_local("tests")

The bundled synthetic dataset (gls_example("synthetic")) underpins most unittests, while real bird deployments offer higher-volume scenarios for manual QA.

If you useglscalibrator in your research, please cite.

Contributions are welcome! Please feel free to submit a Pull Request.

MIT License - see LICENSE file for details

Built on the excellent work of:

• SGAT package authors
• GeoLight andTwGeos developers
• The seabird tracking community

For issues and questions:

• GitHub Issues:https://github.com/fabbiologia/glscalibrator/issues
• Email:favoretto.fabio@gmail.com