Skip to content

Home

Jump to bottom
Pratik Gupte edited this page Dec 19, 2019 · 1 revision

Welcome to the watlasUtils wiki!

Main functions

Shiny application

Package functionality is demonstrated by the inbuilt shiny application, which is started by the function runTweakApp. The app runs locally, and accepts data of the kind that can be found in the tests/testthat/testdata folder of the cloned repository. NB: This folder is not available when installing using devtools as shown above.

The application visualises the effect of tweaking the important parameters used in the main functions. The app takes two input files (for historical reasons; this is liable to change):

  1. Revisit data: A dataframe of recurse analysis, or must include, in addition to X, Y and time columns, a residence time column named resTime, id, and tidalcycle.
  2. Tidal data: A dataframe output of tidal cycle finding analysis, or must include, in addition to X, Y and time columns, a tidaltime column named tidaltime; also id, and tidalcycle for merging.

These two files are merged together during operation. Operation begins on clicking the Run button.

Residence point inference

WATLAS sometimes has difficulty tracking birds on the mudflats, but not in flight, leading to missing data between flight trajectories. The funcInferResidence fills in gaps which satisfy certain parameters with aritifical (inferred) localisations:

  1. The duration of the missing data is greater than the threshold infPatchTimeDiff.
  2. The distance between the start and end points of the missing-data phase is less than infPatchSpatDiff.

The inferred localisations all have an X and Y coordinate value that is the mean of the start and end points of the missing data phase. The time assigned to each point is from a linear sequence with an interval of 3s, starting from the last location before the missing data phase. The residence time assigned to them is the minimum required to be considered a residence point (see next function). All inferred points are clearly marked 'inferred' in the resulting data frame.

Path classification

Individual trajectories are classified by funcClassifyPath into residence or travelling points depending on the residence time resTimeLimit calculated using the recurse package (Bracis et al. 2018) -- ideally, this is based in the biology of the tracked animal. The travelling points are removed, and the residence points returned in a data frame.

Residence patch construction

The individual trajectory retaining only the presumed residence points is clustered into groups based on spatial and temporal proximity using funcGetResPatch. Summary statistics on these 'residence patches' form the major output of this package.

The procedure adopted here is as follows:

  1. The distance between consecutive locations is calculated, and compared against 2 * bufferSize, which has a default value of 10m [^1]. Points within 20m of the previous point are clustered together.

  2. The function counts the number of locations in each of these preliminary clusters, and removes entire clusters which have fewer than minFixes locations.

  3. The first, last, and mean value of time, X coordinate, Y coordinate, and residence time of each of the clusters is counted. These are used to assess spatio-temporal independence between successive clusters as follows:

    1. The time between the last timestamp of cluster N and the first timestamp of N+1 is compared against tempIndepLim [^2].
    2. The distance between the last position of cluster N and the first position of N+1 is compared against spatIndepLim [^2].
    3. The absolute difference in mean residence times between N and N+1 is compared against restIndepLim.
    4. If any of the three comparisons satisfies a greater-than predicate, the clusters are considered independent.
    5. If not, cluster N+1 is merged with N.

  4. These merged clusters are called residence patches, and the first, last, and mean of each of the following are calculated: time, X coordinate, Y coordinate, time since high tide, and residence time.

  5. Spatial metrics are added in the form of the distance in the patch (the distance between successive points classified into a residence patch), and the displacement in a patch (the linear distance between the first and last coordinates), and distance between patches for successive patches only.

  6. Quality metrics are added: the number of locations, duration, and proportion of fixes in a patch.

  7. The patches are converted into sf based spatial polygons by constructing and dissolving buffers of bufferSize around each point. From these, patch area and circularity measures are added. The Polsby-Popper metric of roundness (Polsby and Popper. 1991) is used: 4 * pi * patch area / patch perimeter squared. A perfect circle would have a value of 1.0 using this method.

  8. A column for patch type is added, indicating whether the patch consists only of empirical real points, inferred points, or mixed points.

  9. Finally, patches with a mean time since high tide outside the tidal limits specified in tideLims are removed, the remaining patches are renumbered, and the resulting sf object is returned.

Auxiliary functions

Getting residence patch data

The sf class object generated above can be stripped of the underlying point locations using funcGetPatchData, or conversely, the spatial object can be removed to return the component points with associated patch summary data.

Fast functions for patch distances

There are three functions that are used in the main methods that implement fast distance calculations, with the caveat that Euclidean space is assumed. These are funcDistance for distances between consecutive points, funcBwPatchDistance for distances between any two points, and typically used for between patch distances, and funcPatchTraj to convert the linear path between patches (last point of N to first point of N+1) into sf MULTILINESTRING objects for mapping.

Footnotes

[^1]: The distance of the first point from the previous point is considered unknown, and assigned Inf for calculation. 2 * bufferSize is the maximum distance possible between the centres of two circles for buffers of radius bufferSize m around them to just touch.

[^2]: As before, the first cluster's time and spatial difference to the cluster prior is unknown and set to Inf.

Clone this wiki locally