---
title: "Getting Started with glscalibrator"
author: "glscalibrator authors"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting Started with glscalibrator}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  eval = FALSE
)
```

## Introduction

Global Location Sensors (GLS) are widely used to track animal movements over long periods.
However, processing GLS data has traditionally been a manual, time-consuming process requiring:

1. Manual identification of calibration periods
2. Custom scripting for each study
3. Individual processing of each device
4. Manual quality control

`glscalibrator` automates this entire workflow, allowing you to process entire datasets with a single command.

## Installation

```{r install}
# Install from GitHub
# install.packages("devtools")
devtools::install_github("fabbiologia/glscalibrator")

# Load the package
library(glscalibrator)
```

## Basic Workflow

### 1. Organize Your Data

For this vignette we'll rely on the bundled example data that ships with the
package, but the same structure applies to your own deployments. The examples
live in:

```r
system.file("extdata", package = "glscalibrator")
```

### 2. Run Batch Calibration

The main function `calibrate_gls_batch()` handles everything:

```{r batch}
results <- calibrate_gls_batch(
  data_dir = system.file("extdata", package = "glscalibrator"),
  output_dir = "data/processed/calibration",
  colony_lat = 27.85178,    # Your colony latitude
  colony_lon = -115.17390,  # Your colony longitude
  light_threshold = 2,      # Light threshold in lux
  verbose = TRUE
)
```

### 3. Check Results

```{r results}
# Summary statistics for all birds
print(results$summary)

# Processing log (successes and failures)
print(results$processing_log)

# Access individual bird positions
bird_data <- results$results$BW154_05Jul24_225805
head(bird_data)
```

## What Gets Created

After running `calibrate_gls_batch()`, you'll have:

### Data Files

- `GLSmergedata.csv` - Combined data for all birds in standard format
- `all_birds_calibrated.csv` - All positions with metadata
- `calibration_summary.csv` - Summary statistics
- `[bird_id]_calibrated.csv` - Individual bird positions
- `[bird_id]_GLSmergedata.csv` - Individual bird in standard format

### Figures

- `all_tracks_combined.png` - Map with all bird tracks
- `[bird_id]_track.png` - Individual bird track map
- `[bird_id]_calibration.png` - Calibration diagnostics

## Advanced Features

### Excluding Equinox Periods

Light-based geolocation is unreliable near equinoxes. You can exclude these periods:

```{r equinox}
# Define equinox exclusion windows
equinoxes <- list(
  c("2024-08-24", "2024-10-23"),  # Autumn
  c("2024-02-19", "2024-04-19"),  # Spring
  c("2023-08-24", "2023-10-23")   # Previous year
)

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
)
```

### Customizing Thresholds

```{r custom}
results <- calibrate_gls_batch(
  data_dir = "data/raw/birds",
  output_dir = "data/processed/calibration",
  colony_lat = 27.85,
  colony_lon = -115.17,
  light_threshold = 3,      # Higher threshold
  min_positions = 20,       # Require more positions
  create_plots = FALSE      # Skip plot generation
)

# metadata table is also exported for programmatic access
glscalibrator_example_metadata
```

## Step-by-Step Processing

If you need more control, you can use the individual functions:

### 1. Read Light Data

```{r read}
light_data <- read_lux_file(gls_example("W086"))
head(light_data)
```

### 2. Auto-Detect Calibration Period

```{r calib}
calib_period <- auto_detect_calibration(
  light_data,
  colony_lat = 27.85178,
  colony_lon = -115.17390,
  threshold = 2
)

print(calib_period)
# $start
# [1] "2024-07-05 22:58:05 UTC"
# $end
# [1] "2024-07-07 22:58:05 UTC"
# $twilights
# [1] 5
```

### 3. Detect Twilights

```{r twilights}
twilights <- detect_twilights(light_data, threshold = 2)
head(twilights)
```

### 4. Filter Twilights

```{r filter}
twilights_clean <- filter_twilights(
  twilights,
  light_data = light_data,
  threshold = 2,
  strict = TRUE
)
```

### 5. Estimate the Sun Elevation

```{r sun-elev}
calib_result <- estimate_sun_elevation(
  twilight = twilights_clean$Twilight,
  rise = twilights_clean$Rise,
  lon = -115.17390,
  lat = 27.85178
)

zenith <- calib_result["z1"]
print(paste("Zenith angle:", round(zenith, 2), "degrees"))
```

## Understanding the Output

### Calibration Summary

```{r summary}
# Example calibration_summary.csv structure:
# bird_id              zenith  sun_elevation  n_twilights_calib  n_positions  hemisphere_check
# BW154_05Jul24_225805  98.74       -8.74              5              143     CORRECT (Western)
# BW157_05Jul24_231215  98.39       -8.39              5              274     CORRECT (Western)
```

Key columns:
- `zenith`: Calculated sun elevation angle for this device
- `n_twilights_calib`: Twilights used for calibration
- `n_positions`: Final number of position estimates
- `hemisphere_check`: Quality control (should match your study area)

### Position Data

```{r positions}
# Example [bird_id]_calibrated.csv structure:
# bird_id    datetime            date        Longitude  Latitude  zenith  method
# BW154      2024-07-08 05:30:00 2024-07-08  -115.2     27.9      98.74   threshold_crossing_internal_gamma
```

## Quality Control

The package performs automatic quality checks:

1. **Twilight Filtering**
   - Removes twilights < 1 hour apart
   - Filters unusual intervals (not ~12 or ~24 hours)
   - Checks light quality around transitions

2. **Position Filtering**
   - Removes impossible coordinates (outside reasonable bounds)
   - Excludes equinox periods if specified
   - Validates hemisphere

3. **Hemisphere Check**
   - Verifies positions are in expected hemisphere
   - Reports in summary for manual review

### Reviewing Quality

```{r quality}
# Check calibration diagnostics
# Look at [bird_id]_calibration.png files

# Check hemisphere in summary
summary <- read.csv("data/processed/calibration/data/calibration_summary.csv")
table(summary$hemisphere_check)

# Review failed birds
failed <- results$processing_log[
  sapply(results$processing_log, function(x) x$status == "FAILED")
]
print(failed)
```

## Troubleshooting

### No twilights detected

- Check if light threshold is appropriate (try 1-5 lux)
- Verify .lux file format is correct
- Ensure device was recording properly

### Wrong hemisphere

- Check colony coordinates (lon/lat order)
- Review individual track plots
- May indicate device malfunction

### Too few positions

- Check if equinox exclusions are too broad
- Review calibration period (might be at wrong location)
- Verify deployment duration

## Next Steps

- Combine with environmental data
- Perform movement analysis
- Create publication-quality figures
- Integrate with other tracking data

## Further Reading

- [SGAT documentation](https://github.com/SWotherspoon/SGAT)
- [GeoLight manual](https://geolocationmanual.vogelwarte.ch/GeoLight.html)
- Light-level geolocation user's guide (Lisovski et al. 2020)

## Getting Help

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