seatrackGLS

contact re. GLS data processing: vegard.brathen@nina.no

This vignette provide a setup for how to process data from one or multiple geolocators with seatrackGLS. The function require supporting information about the geolocator and to specify some settings for filters.

Note that seatrackGLS use a threshold method to achieve locations from light data which require a correctly assigned sun angle in order to estimate reliable latitudes. Hence, seatrackGLS should be run twice on the data;first, with a “best guess” sun angle and last, with a subjectively assigned calibrated sun angle. ‘sun_plots’ can be used to assign sun angles. “sun_angle_start” and “sun_angle_end” can be left blank for the initial run of the script. The script will use a sun angle of -3.5 when left blank.See descriptions for how to do this in Bråthen et al. (2021) Also note that the function is built for processing one tracked non-breeding season at a time.

One sun angle can be assigned to each non-breeding season, or one to the beginning and one to the end, with a linear gradient then created between these two.

In this example, information is loaded from a table where each row represents a tracked non-breeding season.

• luxfile = required, specify how to read in light data
• save_sun_plots.dir = where to save plots for sun angle - calibration. If NA or NULL, no plots are produced
• save_filter_plots.dir = where to save plots of filtering effects. If NA or NULL, no plots are produced
• speed = required, flight speed (km/h)
• boundary.box = required, distribution limits (c(lonW,lonE,latS,latN)) PS! lons as 0-360 deg if crossing the 180 meridian (otherwise -180 to 180)
• coast_to_land = required, kilometers individual is allowed to fly inland. Inf = infinite.
• coast_to_sea = required, kilometers individual is allowed to fly ofshore Inf = infinite.
• loess_filter_k = required, number of interquartile ranges for identifying and filtering twilights
• months_breeding = approximate of months with regular presence at breeding location. Aid filtering during breeding
• man_equinox_periods = equinox period specifying by day and month. Override by ‘aut_equinox_periods’ set as TRUE
• aut_equinox_periods = equinox period automatically set based on approximate latitudes before and after equinox
• midnightsun_removal = helps removing errornous positions while breeding under the midnight sun
• add_summer_pos = extra positions estimated using a higher threshold at each side of summer
• noonfilter = twilight filtered based on corresponding noon/midnight
• daylengthfilter = twilight filtered based on corresponding day length/night length
• split_years = for convenience, tracks can be split up in yearly sections (e.g. summer 2015 to summer 2016)
• year_tracked = for convenience, corresponding metadata gets added and linked by yearly sections
• sun_angle_start = assigned during sun angle calibrations. Default is currently -3.5 (based on seatrack average)
• sun_angle_end = assigned during sun angle calibrations if drift in sun angles
• light_threshold = required, which light-level mark a twilight event (dawn and dusk)
• logger_id = for convenience, logger id can be added to the positional dataset
• logger_model = for convenience, logger model can be added to the positional dataset
• ring_number = for convenience, bird id can be added to the positional dataset
• species = for convenience, species name can be added to the positional dataset
• colony = for convenience, breeding location can be addded as name to the positional dataset
• col_lon = required, breeding longitude is used by several filters
• col_lat = required, breeding latitude is used by several filters
• date_deployed = required, limit the light-level data to time on the bird
• date_retrieved = required, limit the light-level data to time on the bird
• age_deployed = for convenience, birds’ age can be added to the positional dataset

# Load seatrackGLS
devtools::load_all(".")
library(seatrackGLS)
# Load example data
metadata <- read.csv(system.file("exdata", "metadata.csv", package = "seatrackGLS"))

i=1
for(i in 1:nrow(metadata)){
#---------------------- run seatrackGLS ---------------

locations <- seatrackGLS(luxfile                     = system.file("exdata", metadata$file_name[i], package = "seatrackGLS"), 
                           save_sun_plots.dir          = NULL,                 #if NA or NULL, no plots are produced
                           save_filter_plots.dir       = NULL,                 #if NA or NULL, no plots are produced
                           speed                       = 60,                 
                           boundary.box                = c(-95,90,30,88),   
                           coast_to_land               =100,
                           coast_to_sea                =Inf,
                           loess_filter_k              = 6,                  
                           months_breeding             = c(4,5,6,7,8),     
                           man_equinox_periods         = c("02-22","04-01","09-12","10-18"),
                           aut_equinox_periods         = TRUE, 
                           midnightsun_removal         = TRUE,              
                           add_summer_pos              = TRUE,          
                           noonfilter                  = TRUE,
                           daylengthfilter             = TRUE,
                           split_years                 = c("05-31","06-01"),
                           year_tracked                = metadata$year_tracked[i],    
                           sun_angle_start             = metadata$sun_angle_start[i], #default is -3.5
                           sun_angle_end               = metadata$sun_angle_end[i],   
                           light_threshold             = metadata$light_threshold[i], 
                           logger_id                   = metadata$logger_id[i],
                           logger_model                = metadata$logger_model[i],
                           ring_number                 = metadata$ring_number[i],
                           species                     = metadata$species[i],
                           colony                      = metadata$colony[i],         
                           col_lon                     = metadata$col_lon[i],         
                           col_lat                     = metadata$col_lat[i],         
                           date_deployed               = metadata$date_deployed[i],
                           date_retrieved              = metadata$date_retrieved[i],
                           age_deployed                = metadata$age_deployed[i])

  positions<-locations$tracks
  filter_effects<-locations$`number of datapoints removed or retained`
  twilights_before_locfiltering<-locations$`cleaned twilights with no positional filtering`
  
  if(i==1){
  positions_combined<-positions
  filter_effects_combined<-filter_effects
  twilights_before_locfiltering_combined<-twilights_before_locfiltering}
  
  if(i!=1){
    positions_combined<-rbind(positions_combined,positions)
    filter_effects_combined<-rbind(filter_effects_combined,filter_effects)
    twilights_before_locfiltering_combined<-rbind(twilights_before_locfiltering_combined,twilights_before_locfiltering)}
  
}

Map positions

plot_a_map(positions_combined[positions_combined$year_tracked%in%unique(positions_combined$year_tracked)[1],])

  positions_combined %>%
    dplyr::mutate(month = month(date_time)) %>%
    sf::st_as_sf(coords = c('lon', 'lat'), crs = 4326) ->
  mylocs 


  track <- mylocs %>%
  summarise(do_union = FALSE) %>%
  st_cast("LINESTRING")


  worldmap <- ggplot2::map_data('world')
  
  ggplot() +
   geom_polygon(data = worldmap, aes(x = long, y = lat, group = group)) +
   geom_sf(data = track,colour="grey80") + #line
   geom_sf(data =  mylocs[mylocs$eqfilter==1 & mylocs$light_threshold>11,], aes(),colour= "orange", size = 1)+ #increased light trhesholds
   geom_sf(data =  mylocs[mylocs$eqfilter==0,], aes(),pch=21,fill= "white", size = 1)+ #equinox
   geom_sf(data =  mylocs[mylocs$eqfilter==1 & mylocs$light_threshold<=11,], aes(colour = year_tracked), size = 1) +
   coord_sf(xlim = c(min(mylocs$lon[mylocs$eqfilter==1]),max(mylocs$lon[mylocs$eqfilter==1])), 
            ylim = c(min(mylocs$lat[mylocs$eqfilter==1]),max(mylocs$lat[mylocs$eqfilter==1]))) +
   theme_light() + theme(legend.position="bottom")+
   ggtitle(unique(mylocs$ring_number))

Explore data

Number of positions from one breeding season to the next:

    positions_combined %>%
    dplyr::group_by(colony, year_tracked) %>%
    dplyr::summarise(n_positions = n_distinct(lat))

## `summarise()` has grouped output by 'colony'. You can override using the
## `.groups` argument.

## # A tibble: 2 × 3
## # Groups:   colony [1]
##   colony  year_tracked n_positions
##   <chr>   <chr>              <int>
## 1 Sklinna 2015_16              600
## 2 Sklinna 2016_17              541

Number of positions from one breeding season to the next, excluding the equinox affected latitudes:

    positions_combined[positions_combined$eqfilter==1,] %>%
    dplyr::group_by(colony, year_tracked) %>%
    dplyr::summarise(n_positions = n_distinct(lat))

## `summarise()` has grouped output by 'colony'. You can override using the
## `.groups` argument.

## # A tibble: 2 × 3
## # Groups:   colony [1]
##   colony  year_tracked n_positions
##   <chr>   <chr>              <int>
## 1 Sklinna 2015_16              458
## 2 Sklinna 2016_17              384

Number of high-threshold locations generated for between spring and autumn equinox:

    positions_combined[positions_combined$light_threshold>11,] %>%
    dplyr::group_by(colony, year_tracked) %>%
    dplyr::summarise(n_positions = n_distinct(lat))

## `summarise()` has grouped output by 'colony'. You can override using the
## `.groups` argument.

## # A tibble: 2 × 3
## # Groups:   colony [1]
##   colony  year_tracked n_positions
##   <chr>   <chr>              <int>
## 1 Sklinna 2015_16               18
## 2 Sklinna 2016_17               50

Filter effects

as.data.frame(t(filter_effects_combined))

##                                           V1                  V2
## logger_yeartracked       C411_mk4083_2015_16 C411_mk4083_2016_17
## nrow_twilightCalc                        678                 647
## removed_twilight_cleanup                  17                  76
## moved_twilights                           22                  18
## daylengthfilter                           26                  33
## noonfilter                                10                  16
## removed_speed                              5                   0
## removed_boundbox                          17                   3
## removed_argos                              0                   0
## removed_loess                              0                   0
## removed_midnight_sun                      44                  59

Twilights only filtered up to the point of “removed_speed” (see Filter effects) meaning filtering has only been based on twilights alone:

head(twilights_before_locfiltering)

##                   tFirst             tSecond type  logger_yeartracked
## 1100 2016-06-05 23:24:10 2016-06-09 00:24:56    1 C411_mk4083_2016_17
## 610  2016-07-05 22:21:18 2016-07-06 00:26:19    2 C411_mk4083_2016_17
## 710  2016-07-08 22:31:21 2016-07-09 00:55:03    2 C411_mk4083_2016_17
## 810  2016-07-09 00:55:03 2016-07-12 22:31:24    1 C411_mk4083_2016_17
## 910  2016-07-12 22:31:24 2016-07-13 00:30:24    2 C411_mk4083_2016_17
## 1010 2016-07-15 22:06:26 2016-07-16 00:30:26    2 C411_mk4083_2016_17
##      ring_number
## 1100     6211704
## 610      6211704
## 710      6211704
## 810      6211704
## 910      6211704
## 1010     6211704

A brief description of each column in the positional data file

• Date_time = date and time of the calculated position in GMT (DD.MM.YYYY HH:MM)
  
• logger_id = specific logger ID for each GLS logger (e.g N032).
  
• logger_model = GLS logger model (e.g c65, mk4083 etc)
• year_tracked = ‘year_tracked’ specify the tracking period from one breeding
  season to the next (e.g.’2013_14’).
• session_id = unique for each time a logger was deployed
• individ_id = unique for each individual
• year_deployed = year of deployment
• year_retrieved = year of retrieval
• species = english name of the species (e.g ‘Black-legged kittiwake’)
• colony = name of the colony the logger was deployed and retrieved in.
  Colony name can often cover multiple breeding locations when in close proximity.
• col_lon = longitude of the colony.
  
• col_lat = latitude of the colony.
• lon_raw = longitude calculated from time (GMT) of noon or midnight and date
• lat_raw = latitude calculated from the length of day or night and date.
• lon and lat= first averaging consecutive noon-midnight or midnight-noon
  lon_raws and lat_raws, then a two point moving average on subsequent coordinates using spherical trigonometry.
• eqfilter = this filter identifies fixed periods where the latitudes are
  assumed to be unreliable during equinox (1 = reliable/outside fixed equinox period, 0 = unreliable/inside equinox).
• tfirst = time of first sun event (DD.MM.YYYY HH:MM) used for calculating
  positions
• tsecond = time of second sun event (DD.MM.YYYY HH:MM) used for calculating
  positions
• twl_type = identify whether ‘tfirst’ is sunrise (1) or sunset (2)
• sun = the suns angle to the horizon used to calculated the positions from
  twilight events.
• light_threshold = selected threshold that defines a sunset/sunrise
• script_version = script version
• analyzer = name of person that run scripts and perform the sun elevation
  angle calibration
• data_responsible = name of data responsible