mergeSites2: Imporved mergeSites function
In slisovski/GeoLight: Analysis of Light Based Geolocator Data

mergeSites2

R Documentation

Imporved mergeSites function

Description

The changeLight functions provides a vector grouping the twilight times into stationary (>0) and movement (0) periods. The mergeSites functions allows to merge these stationary periods in case some consecutive sites were separated by e.g. outliers or strong shading events. In a nutshell, the function estimates a likelihood surface for each stationary period that is based on the siteEstimate principle (e.g. fitting sunrise and sunset times of locations to the recorded sunrise and sunsets and finding the coordinates that results in the best fit). The decision on whether two consecutive sites should be merged together is made by the provided 'distThreshold' and the overlap of the 95 between two consecutive sites needs to be smaller than the 'distThreshold' AND the median locations need to overlap with the credible intervals of the two location estimates to trigger merging of the sites). The function also requires a sun elevation angle. HOWEVER, the angle defining the zero in the log-normal distribution of the twilight error is needed and not the sun elevation for the median twilight error which is needed for the location estimation using the function 'coord'. The function 'getElevation' provides both, the median and the zero sun elevation angle as well as the parameters for the log-normal distribution that also required in the 'mergeSites2' function.

Usage

mergeSites2(
  tFirst,
  tSecond,
  type,
  twl,
  site,
  degElevation,
  distThreshold = 250,
  fixed = NULL,
  alpha = c(2.5, 1),
  method = "gamma",
  mask = "land",
  plot = TRUE
)

Arguments

`tFirst`	vector of sunrise/sunset times (e.g. 2008-12-01 08:30).
`tSecond`	vector of of sunrise/sunset times (e.g. 2008-12-01 17:30).
`type`	vector of either 1 or 2, defining `tFirst` as sunrise or sunset respectively.
`twl`	data.frame containing twilights and at least `tFirst`, `tSecond` and `type`
`site`	a `numerical vector` assigning each row to a particular period. Stationary periods in numerical order and values >0, migration/movement periods 0. This `vector` will be used as the initial state.
`degElevation`	the sun elevation angle (in degrees) that defines twilight (e.g. -6 for "civil twilight"). Either a single value, a `vector` with the same length as `tFirst` or `nrow(x)`.
`distThreshold`	a `numerical` value defining the threshold of the distance under which consecutive sites should be merged (in km).
`fixed`	a logical vector indicating locations that should not be merged.
`alpha`	log-mean and log-sd of the twilight error (see: `getElevation`).
`method`	either, "gamma" or "log-normal". Depending on the error distribution used in `getElevation`.
`mask`	Either 'land' or 'ocean'.
`plot`	`logical`, if TRUE a plot comparing the initial and the final site selection.