Passer au contenu

Get GPS variables

Source : R/getGPS.R
getGPS.Rd

To improve speed, the alltags view doesn't include GPS-related variables such as gpsLat, gpsLon, or gpsAlt. There is a alltagsGPS view that does include GPS-related variables, but this will take time to load. This function accepts a source and returns the GPS data associated with the hitIDs in the alltags view. Optionally, users can supply a subset of the alltags view to return only GPS data associated with the specific hitIDs present in the subset.

Utilisation

getGPS(src, data = NULL, by = "daily", cutoff = NULL, keepAll = FALSE)

Arguments

src

SQLite connection (result of tagme(XXX) or DBI::dbConnect(RSQLite::SQLite(), "XXX.motus"))

data

SQLite connection or data.frame. Optional subset of the alltags view. Must have ts, batchID and hitID at the minimum.

by

Numeric/Character. Either the time in minutes over which to join GPS locations to hits, or "daily" or "closest". To join GPS locations by daily time blocks or by the closest temporal match (see Details).

cutoff

Numeric. The maximum allowable time in minutes between hit and GPS timestamps when matching hits to GPS with by = 'closest'. Defaults to NULL (no maximum).

keepAll

Logical. Return all hits regardless of whether they have a GPS match? Defaults to FALSE.

Valeur de retour

Data frame linking hitID to gpsLat, gpsLon and gpsAlt. When by = 'daily' or by = 'X', output includes:

  • hitID - the ID associated with the hit

  • gpsLat \ gpsLon \ gpsAlt - the median location calculated from the available GPS points

  • gpsTs_min \ gps_Ts_max - the range of GPS timestamps associated with the GPS points binned

When by = 'closest' or by = 'X', output includes:

  • hitID - the ID associated with the hit

  • gpsID - the ID of the closest GPS point aligned with the hitID

  • gpsLat \ gpsLon \ gpsAlt - the location of the GPS point

  • gpsTs - the timestamp of the GPS point

Détails

There are three different methods for matching GPS data to hitIDs all related to timestamps (ts).

  1. by = X Where X is a duration in minutes. ts is converted to a specific time block of duration X. Median GPS lat/longs for the time block are returned, matching associated hitID time blocks.

  2. by = "daily" (the default). Similar to by = X except the duration is 24hr.

  3. by = "closest" Individual GPS lat/lons are returned, matching the closest hitID timestamp. Use cutoff to specify the maximum allowable time between timestamps (defaults to none).

Exemples


# download and access data from project 176 in sql format
# usename and password are both "motus.sample"
if (FALSE) sql.motus <- tagme(176, new = TRUE, update = TRUE)

# OR use example sql file included in `motus`
sql.motus <- tagme(176, update = FALSE, 
                   dir = system.file("extdata", package = "motus"))

# Match hits to GPS within 24hrs (daily) of each other
my_gps <- getGPS(sql.motus)
my_gps
#> [1] hitID  gpsTs  gpsLat gpsLon gpsAlt
#> <0 lignes> (ou 'row.names' de longueur nulle)

# Note that the sample data doesn't have GPS hits so this will be an 
# empty data frame for project 176.

# Match hits to GPS within 15min of each other
my_gps <- getGPS(sql.motus, by = 15)
my_gps
#> [1] hitID  gpsTs  gpsLat gpsLon gpsAlt
#> <0 lignes> (ou 'row.names' de longueur nulle)

# Match hits to GPS according to the closest timestamp
my_gps <- getGPS(sql.motus, by = "closest")
my_gps
#> [1] hitID  gpsTs  gpsLat gpsLon gpsAlt
#> <0 lignes> (ou 'row.names' de longueur nulle)

# Match hits to GPS according to the closest timestamp, but limit to within
# 20min of each other
my_gps <- getGPS(sql.motus, by = "closest", cutoff = 20)
my_gps
#> [1] hitID  gpsTs  gpsLat gpsLon gpsAlt
#> <0 lignes> (ou 'row.names' de longueur nulle)

# To return all hits, regardless of whether they match a GPS record

my_gps <- getGPS(sql.motus, keepAll = TRUE)
my_gps
#> # A tibble: 188,354 × 4
#>      hitID gpsLat gpsLon gpsAlt
#>    <int64>  <dbl>  <dbl>  <dbl>
#>  1   45107     NA     NA     NA
#>  2   45108     NA     NA     NA
#>  3   45109     NA     NA     NA
#>  4   45110     NA     NA     NA
#>  5   45111     NA     NA     NA
#>  6  199885     NA     NA     NA
#>  7  199886     NA     NA     NA
#>  8  199887     NA     NA     NA
#>  9  199888     NA     NA     NA
#> 10  199889     NA     NA     NA
#> # … with 188,344 more rows

# Alternatively, use the alltagsGPS view:
dplyr::tbl(sql.motus, "alltagsGPS")
#> # Source:   table<alltagsGPS> [?? x 65]
#> # Database: sqlite 3.39.3 [/home/runner/work/_temp/Library/motus/extdata/project-176.motus]
#>     hitID runID batchID          ts tsCor…¹   sig sigsd noise  freq freqsd  slop
#>     <int> <int>   <int>       <dbl>   <dbl> <dbl> <dbl> <dbl> <dbl>  <dbl> <dbl>
#>  1  45107  8886      53 1445858390.  1.45e9    52     0   -96     4      0  1e-4
#>  2  45108  8886      53 1445858429.  1.45e9    54     0   -96     4      0  1e-4
#>  3  45109  8886      53 1445858477.  1.45e9    55     0   -96     4      0  1e-4
#>  4  45110  8886      53 1445858516.  1.45e9    52     0   -96     4      0  1e-4
#>  5  45111  8886      53 1445858564.  1.45e9    49     0   -96     4      0  1e-4
#>  6 199885 23305      64 1445857924.  1.45e9    33     0   -96     4      0  1e-4
#>  7 199886 23305      64 1445857983.  1.45e9    41     0   -96     4      0  1e-4
#>  8 199887 23305      64 1445858041.  1.45e9    29     0   -96     4      0  1e-4
#>  9 199888 23305      64 1445858089.  1.45e9    41     0   -96     4      0  1e-4
#> 10 199889 23305      64 1445858147.  1.45e9    45     0   -96     4      0  1e-4
#> # … with more rows, 54 more variables: burstSlop <dbl>, done <int>,
#> #   motusTagID <int>, ambigID <int>, port <chr>, nodeNum <chr>, runLen <int>,
#> #   motusFilter <dbl>, bootnum <int>, tagProjID <int>, mfgID <chr>,
#> #   tagType <chr>, codeSet <chr>, mfg <chr>, tagModel <chr>, tagLifespan <dbl>,
#> #   nomFreq <dbl>, tagBI <dbl>, pulseLen <dbl>, tagDeployID <int>,
#> #   speciesID <int>, markerNumber <chr>, markerType <chr>,
#> #   tagDeployStart <dbl>, tagDeployEnd <dbl>, tagDepLat <dbl>, …