Package 'motus'

Description

Download or resume a download of the activity table in an existing Motus database. Batch activity refers to the number of hits detected during a given batch. Batches with large numbers of hits may indicate interference and thus unreliable hits.

Usage

activity(src, resume = FALSE)

Arguments

Details

This function is automatically run by the tagme() function with resume = TRUE.

If an activity table doesn't exist, it will be created prior to downloading. If there is an existing activity table, this will update the records.

Examples

# Download sample project 176 to .motus database (username/password are "motus.sample")
## Not run: sql_motus <- tagme(176, new = TRUE)

# Or use example data base in memory
sql_motus <- tagmeSample()
   
# Access 'activity' table
library(dplyr)
a <- tbl(sql_motus, "activity")
  
# If interrupted and you want to resume
## Not run: my_tags <- activity(sql_motus, resume = TRUE)

Description

Download or resume a download of the activityAll table in an existing Motus database. Batch activity refers to the number of hits detected during a given batch. Batches with large numbers of hits may indicate interference and thus unreliable hits.

Usage

activityAll(src, resume = FALSE)

Arguments

Examples

# Download sample project 176 to .motus database (username/password are "motus.sample")
## Not run: sql_motus <- tagme(176, new = TRUE)

# Or use example data base in memory
sql_motus <- tagmeSample()
  
# Get all activity
## Not run: sql_motus <- activityAll(sql_motus)

# Access 'activityAll' table
library(dplyr)
a <- tbl(sql_motus, "activityAll")
  
# If interrupted and you want to resume
## Not run: sql_motus <- activityAll(sql_motus, resume = TRUE)

Description

Verifies the version of the package against the admInfo table of a .motus file. Those should match if the updateMotusDb() function has been properly applied by the tagme() function.

Usage

checkVersion(src)

Arguments

Description

A detections is "ambiguous" if the motus tag finder could not tell which of several tags was detected, because they all produce the same signal and were active at the same time. The motus tag finder uses tag deployment and lifetime metadata to decide what tags to seek when, and notices when it can't distinguish between two or more of them. Detections of such tags during these periods of overlap are assigned a negative motus tag ID that represents from 2 to 6 possible real motus tags. The ambiguities might be real (i.e. two or more tags transmitting the same signal and active at the same time), or due to errors in tag registration or deployment metadata.

Usage

clarify(src, id, from, to, all.mine = FALSE)

Arguments

Details

This function serves two purposes:

• called with only a database, it reports the numbers of ambiguous detections and what they could represent.

• called with id, it lets you claim some of the ambiguities as your own tag, so that in subsequent processing, they will appear to be yours.

This function does not (yet?) report your claim to motus.org

WARNING: you cannot undo a claim within a copy of the database. If unsure, copy the .motus file first, then run clarify on only one copy.

If both from and to are missing, then all detections of ambiguous tag(s) id are claimed.

Parameters id, from, and to are recycled to the length of the longest item.

When you claim an ambiguous tag T for a period, any runs of T which overlap that period at all are claimed entirely, even if they extend beyond the period; i.e. runs are not split.

Value

With no parameters, returns a summary data frame of ambiguous tag detections

Examples

## Not run: 
s <- tagme(57)         # get the tag database for project 57
clarify(s)             # report on the ambiguous tag detections in s
clarify(all.mine = TRUE) # claim all ambiguous tag detections as mine
clarify(id = -57)      # claim all detections of ambiguous tag -57 as mine

clarify(id = c(-72, -88, -91), from = "2017-01-02", to = "2017-05-06")
# claim all detections of ambiguous tags -72, -88, and -91 from
#   January 2 through May 6, 2017, as mine

## End(Not run)

Description

Create a new filter records that can be applied to runs

Usage

createRunsFilter(src, filterName, motusProjID = NA, descr = NA, update = FALSE)

Arguments

Value

an integer filterID

Description

Deletes a filter by name or project ID.

Usage

deleteRunsFilter(src, filterName, motusProjID = NA, clearOnly = FALSE)

Arguments

Value

the integer filterID of the filter deleted

Description

Deprecated batches are removed from the online database but not from local data files. This function fetches a list of deprecated batches (stored in the 'deprecated' table), and, optionally, removes these batches from all tables that reference batchIDs

Usage

deprecateBatches(src, fetchOnly = FALSE, ask = TRUE)

Arguments

Examples

# Download sample project 176 to .motus database (username/password are "motus.sample")
## Not run: 
sql_motus <- tagme(176, new = TRUE)
  
# Access 'deprecated' table using tbl() from dplyr
library(dplyr)
tbl(sql_motus, "deprecated")

# See that there are deprecated batches in the data
filter(tbl(sql_motus, "alltags"), batchID == 6000)

# Fetch deprecated batches
deprecateBatches(sql_motus, fetchOnly = TRUE)

# Remove deprecated batches (will ask for confirmation unless ask = FALSE)
deprecateBatches(sql_motus, ask = FALSE)

# See that there are NO more deprecated batches in the data
filter(tbl(sql_motus, "alltags"), batchID == 6000)

## End(Not run)

Description

The activity table is used to identify batches with too much noise. Depending on the value of return these are filtered out, returned, or identified in the alltags view with the column probability. No changes to the database are made.

Usage

filterByActivity(
  src,
  return = "good",
  view = "alltags",
  minLen = 3,
  maxLen = 5,
  maxRuns = 100,
  ratio = 0.85
)

Arguments

Details

Runs are identified by the following:

• All runs with a length >= maxLen are GOOD

• All runs with a length <= minLen are BAD

• Runs with a length between minLen and maxLen are BAD IF both of the following is true:

  • belong to a batch where the number of runs is >= maxRuns

  • the ratio of runs with a length of 2 to the number of runs total is >= ratio

Value

tbl_SQLiteConnection

Examples

# Download sample project 176 to .motus database (username/password are "motus.sample")
## Not run: sql_motus <- tagme(176, new = TRUE)

# Or use example data base in memory
sql_motus <- tagmeSample()

tbl_good <- filterByActivity(sql_motus)
tbl_bad <- filterByActivity(sql_motus, return = "bad")
tbl_all <- filterByActivity(sql_motus, return = "all")

Description

Return the projects and receivers which are accessible by the given credentials

Usage

getAccess()

Examples

## Not run: 
getAccess()

## End(Not run)

Description

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.

Usage

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

Arguments

Details

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

Value

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

Examples

# Download sample project 176 to .motus database (username/password are "motus.sample")
## Not run: sql_motus <- tagme(176, new = TRUE)

# Or use example data base in memory
sql_motus <- tagmeSample()

# Match hits to GPS within 24hrs (daily) of each other
my_gps <- getGPS(sql_motus)
my_gps

# 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

# Match hits to GPS according to the closest timestamp
my_gps <- getGPS(sql_motus, by = "closest")
my_gps

# 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

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

my_gps <- getGPS(sql_motus, keepAll = TRUE)
my_gps

# Alternatively, use the alltagsGPS view:
dplyr::tbl(sql_motus, "alltagsGPS")

Description

Receiver database files have names like "SG-1234BBBK06EA.motus" or "Lotek-12345.motus", and project database files have names like "project-52.motus".

Usage

getMotusDBSrc(
  recv = NULL,
  proj = NULL,
  create = FALSE,
  dbDir = motus_vars$dbDir
)

Arguments

Value

a src_sqlite for the receiver; if the receiver is new, this database will be empty, but have the correct schema.

Description

Specifically the runID and motusTagID, ambigID and tsBegin to tsEnd (timestamp) range of runs, filtered by optional parameters. The match.partial parameter (default = TRUE) determines how timestamp filtering works. When match.partial is FALSE, runID's are only included when both tsBegin and tsEnd falls between ts.min and ts.max (only includes runs when they entirely contained in the specified range). When match.partial is TRUE, runID's are returned whenever the run partially matches the specified period.

Usage

getRuns(
  src,
  ts.min = NA,
  ts.max = NA,
  match.partial = TRUE,
  motusTagID = c(),
  ambigID = c()
)

Arguments

Value

a dataframe containing the runID, the motusTagID and the ambigID (if applicable) of runs

Description

Returns a dataframe of the runsFilters records matching a filter name (and optionally a project ID) stored in the local database.

Usage

getRunsFilters(src, filterName, motusProjID = NA)

Arguments

Value

a database connection to src

Description

Download or resume a download of the gpsAll table in an existing Motus database. Batch activity refers to the number of hits detected during a given batch. Batches with large numbers of hits may indicate interference and thus unreliable hits.

Usage

gpsAll(src, resume = TRUE)

Arguments

Examples

# Download sample project 176 to .motus database (username/password are "motus.sample")
## Not run: sql_motus <- tagme(176, new = TRUE)

# Or use example data base in memory
sql_motus <- tagmeSample()
  
# Get all GPS points
## Not run: sql_motus <- gpsAll(sql_motus)

# Access 'gpsAll' table
library(dplyr)
g <- tbl(sql_motus, "gpsAll")
  
# gpsAll resumes a previous download by default
# If you want to delete this original data and do a fresh download, 
# use resume = FALSE
## Not run: sql_motus <- gpsAll(sql_motus, resume = FALSE)

Description

Returns a dataframe of the filters stored in the local database.

Usage

listRunsFilters(src)

Arguments

Value

a dataframe

Description

Updates the entire metadata for receivers and tags from Motus server. Contrary to tagme(), this function retrieves the entire set of metadata for tags and receivers, and not only those pertinent to the detections in your local file.

Usage

metadata(src, projectIDs = NULL, replace = TRUE, delete = FALSE)

Arguments

See Also

tagme() provides an option to update only the metadata relevant to a specific project or receiver file.

Examples

# Download sample project 176 to .motus database (username/password are "motus.sample")
## Not run: sql_motus <- tagme(176, new = TRUE)

# Or use example data base in memory
sql_motus <- tagmeSample()
                   
# Add extended metadata to your file
## Not run: metadata(sql_motus)
  
# Access different metadata tables
library(dplyr)
tbl(sql_motus, "species")
tbl(sql_motus, "projs")
tbl(sql_motus, "tagDeps")
# Etc.

Description

motus is an R package for retrieving telemetry data from the Motus Wildlife Tracking System https://motus.org.

Details

For a detailed walk-though and instructions check out the walk-throughs and articles!

Commonly used functions:

1. Download telemetry data

   • tagme()

   • tellme()

   • metadata()

   • checkVersion()

2. Create data filters

   • listRunsFilters()

   • getRunsFilters()

   • createRunsFilter()

   • writeRunsFilter()

   • deleteRunsFilter()

3. Summarize data

   • tagSum()

   • tagSumSite()

   • simSiteDet()

   • siteSum()

   • siteSumDaily()

   • siteTrans()

4. Plot data

   • plotAllTagsCoord()

   • plotAllTagsSite()

   • plotDailySiteSum()

   • plotRouteMap()

   • plotSite()

   • plotSiteSig()

   • plotTagSig()

5. Sunrises and sets

   • sunRiseSet()

   • timeToSunriset()

References

Motus Wildlife Tracking System https://motus.org

Description

Any requests to the motus data server after calling this function will require re-entering a username and password.

Usage

motusLogout()

Details

This function just resets these items to NULL:

• motus_vars$authToken

• motus_vars$userLogin

• motus_vars$userPassword

Due to their active bindings, subsequent calls to any functions that need them will prompt for a login.

Value

TRUE.

Description

Download or resume a download of the 'nodeData' table in an existing Motus database. nodeData contains information regarding the 'health' of portable node units.

Usage

nodeData(src, resume = FALSE)

Arguments

Details

This function is automatically run by the tagme() function with resume = TRUE.

If an nodeData table doesn't exist, it will be created prior to downloading. If there is an existing nodeData table, this will update the records.

Note that only records for CTT tags will have the possibility of nodeData.

Node metadata is found in the nodeDeps table, updated along with other metadata.

Examples

# Download sample project 176 to .motus database (username/password are "motus.sample")
## Not run: sql_motus <- tagme(176, new = TRUE)

# Or use example data base in memory
sql_motus <- tagmeSample()
  
# Access `nodeData` table
library(dplyr)
a <- tbl(sql_motus, "nodeData")
  
# If you just want to download `nodeData`
## Not run: my_tags <- nodeData(sql_motus)

Description

Plot latitude/longitude vs time (UTC rounded to the hour) for each tag using motus detection data. Coordinate is by default taken from a receivers deployment latitude in metadata.

Usage

plotAllTagsCoord(
  data,
  coordinate = "recvDeployLat",
  ts = "ts",
  tagsPerPanel = 5
)

Arguments

Examples

# Download sample project 176 to .motus database (username/password are "motus.sample")
## Not run: sql_motus <- tagme(176, new = TRUE)

# Or use example data base in memory
sql_motus <- tagmeSample()
                   
# convert sql file "sql_motus" to a tbl called "tbl_alltags"                
library(dplyr)
tbl_alltags <- tbl(sql_motus, "alltags") 

# convert the tbl "tbl_alltags" to a data.frame called "df_alltags"
df_alltags <- tbl_alltags %>% 
  collect() %>% 
  as.data.frame()

# Plot tbl file tbl_alltags with default GPS latitude data and 5 tags per panel
plotAllTagsCoord(tbl_alltags)

# Plot an sql file tbl_alltags with 10 tags per panel
plotAllTagsCoord(tbl_alltags, tagsPerPanel = 10)

# Plot dataframe df_alltags using receiver deployment latitudes with default
# 5 tags per panel
plotAllTagsCoord(df_alltags, coordinate = "recvDeployLat")

# Plot dataframe df_alltags using LONGITUDES and 10 tags per panel
# But only works if non-NA "gpsLon"!
## Not run: plotAllTagsCoord(df_alltags, coordinate = "gpsLon", tagsPerPanel = 10)

# Plot dataframe df_alltags using lat for select motus tagIDs
plotAllTagsCoord(filter(df_alltags, motusTagID %in% c(19129, 16011, 17357)), 
                 tagsPerPanel = 1)

Description

Plot deployment (ordered by latitude) vs time (UTC) for each tag

Usage

plotAllTagsSite(data, coordinate = "recvDeployLat", tagsPerPanel = 5)

Arguments

Examples

# Download sample project 176 to .motus database (username/password are "motus.sample")
## Not run: sql_motus <- tagme(176, new = TRUE)

# Or use example data base in memory
sql_motus <- tagmeSample()

# convert sql file "sql_motus" to a tbl called "tbl_alltags"
library(dplyr)
tbl_alltags <- tbl(sql_motus, "alltags") 

# convert the tbl "tbl_alltags" to a data.frame called "df_alltags"
df_alltags <- tbl_alltags %>% 
  collect() %>% 
  as.data.frame() 

# Plot detections of dataframe df_alltags by site ordered by latitude, with
# default 5 tags per panel
plotAllTagsSite(df_alltags)

# Plot detections of dataframe df_alltags by site ordered by latitude, with
# 10 tags per panel
plotAllTagsSite(df_alltags, tagsPerPanel = 10)

# Plot detections of tbl file tbl_alltags by site ordered by receiver
# deployment latitude
plotAllTagsSite(tbl_alltags, coordinate = "recvDeployLon")

# Plot tbl file tbl_alltags using 3 tags per panel for species Red Knot
plotAllTagsSite(filter(tbl_alltags, speciesEN == "Red Knot"), tagsPerPanel = 3)

Description

Plots total number of detections across all tags, and total number of tags detected per day for a specified site. Depends on siteSumDaily().

Usage

plotDailySiteSum(data, recvDeployName)

Arguments

Examples

# Download sample project 176 to .motus database (username/password are "motus.sample")
## Not run: sql_motus <- tagme(176, new = TRUE)

# Or use example data base in memory
sql_motus <- tagmeSample()

# convert sql file "sql_motus" to a tbl called "tbl_alltags"
library(dplyr)
tbl_alltags <- tbl(sql_motus, "alltagsGPS") 

# convert the tbl "tbl_alltags" to a data.frame called "df_alltags"
df_alltags <- tbl_alltags %>% 
  collect() %>% 
  as.data.frame() 

# Plot of all tag detections at site Longridge using dataframe df_alltags
plotDailySiteSum(df_alltags, recvDeployName = "Longridge")

# Plot of all tag detections at site Niapiskau using tbl file tbl_alltags
plotDailySiteSum(df_alltags, recvDeployName = "Niapiskau")

Description

Google map of routes of Motus tag detections coloured by ID. User defines a date range to show points for receivers that were operational at some point during the date range.

Usage

plotRouteMap(
  src,
  maptype = "osm",
  zoom = NULL,
  start_date = NULL,
  end_date = NULL,
  lim_lat = NULL,
  lim_lon = NULL,
  data,
  lat,
  lon,
  recvStart,
  recvEnd
)

Arguments

Details

By default this function uses OSM maps (Open Street Map). OSM and many other map tiles are released under specific licences, which generally require that you give attribution at a minimum. See OSM for more details on their tiles, but remember to check what other groups require if you use their tiles.

Examples

# Download sample project 176 to .motus database (username/password are "motus.sample")
## Not run: sql_motus <- tagme(176, new = TRUE)

# Or use example data base in memory
sql_motus <- tagmeSample()

# Plot route map of all detection data, with "osm" maptype, and receivers
# active between 2016-01-01 and 2017-01-01
plotRouteMap(sql_motus, start_date = "2016-01-01", end_date = "2016-12-31")

Description

Plot tag ID vs time for all tags detected by site, coloured by antenna bearing. Input is expected to be a data frame, database table, or database. The data must contain "ts", "antBearing", "fullID", "recvDeployName", "recvDeployLat", "recvDeployLon", and optionally "gpsLat" and "gpsLon". If GPS lat/lon are included, they will be used rather than recvDeployLat/Lon. These data are generally contained in the alltags or the alltagsGPS views. If a motus database is submitted, the alltagsGPS view will be used.

Usage

plotSite(df_src, sitename = NULL, ncol = NULL, nrow = NULL, data)

Arguments

Examples

# Download sample project 176 to .motus database (username/password are "motus.sample")
## Not run: sql_motus <- tagme(176, new = TRUE)

# Or use example data base in memory
sql_motus <- tagmeSample()

# convert sql file "sql_motus" to a tbl called "tbl_alltags"
library(dplyr)
tbl_alltags <- tbl(sql_motus, "alltagsGPS") 

# Plot all sites within file for tbl file tbl_alltags
plotSite(tbl_alltags)

# Plot only detections at a specific site; Piskwamish
plotSite(tbl_alltags, sitename = "Piskwamish")

# For more custom filtering, convert the tbl "tbl_alltags" to a data.frame called "df_alltags"
df_alltags <- collect(tbl_alltags)

# Plot only detections for specified tags for data.frame df_alltags
plotSite(filter(df_alltags, motusTagID %in% c(16047, 16037, 16039)))

Description

Plot signal strength vs time for all tags detected at a specified site, coloured by antenna

Usage

plotSiteSig(data, recvDeployName)

Arguments

Examples

# Download sample project 176 to .motus database (username/password are "motus.sample")
## Not run: sql_motus <- tagme(176, new = TRUE)

# Or use example data base in memory
sql_motus <- tagmeSample()

# convert sql file "sql_motus" to a tbl called "tbl_alltags"
library(dplyr)
tbl_alltags <- tbl(sql_motus, "alltags") 

# convert the tbl "tbl_alltags" to a data.frame called "df_alltags"
df_alltags <- tbl_alltags %>% 
  collect() %>% 
  as.data.frame()

# Plot all tags for site Piskwamish
plotSiteSig(tbl_alltags, recvDeployName = "Piskwamish")

# Plot select tags for site Piskwamish 
plotSiteSig(filter(df_alltags, motusTagID %in% c(16037, 16039, 16035)), 
  recvDeployName = "Netitishi")

Description

Plot signal strength vs time for specified tag, faceted by site (ordered by latitude) and coloured by antenna

Usage

plotTagSig(data, motusTagID)

Arguments

Examples

# Download sample project 176 to .motus database (username/password are "motus.sample")
## Not run: sql_motus <- tagme(176, new = TRUE)

# Or use example data base in memory
sql_motus <- tagmeSample()

# convert sql file "sql_motus" to a tbl called "tbl_alltags"
library(dplyr)
tbl_alltags <- tbl(sql_motus, "alltagsGPS") 

# convert the tbl "tbl_alltags" to a data.frame called "df_alltags"
df_alltags <- tbl_alltags %>% 
  collect() %>% 
  as.data.frame()

# Plot signal strength of a specified tag using dataframe df_alltags
plotTagSig(df_alltags, motusTagID = 16047)

# Plot signal strength of a specified tag using tbl file tbl_alltags
plotTagSig(tbl_alltags, motusTagID = 16035)

Description

Converts a data frame with a list of lat/lons to a spatial data frame with MULTILINES defining paths by tag id. Useful for plotting with ggplot2::geom_sf(). Will silently remove single points.

Usage

points2Path(df, by = "fullID", lat = "recvDeployLat", lon = "recvDeployLon")

Arguments

Value

Spatial data frame with MULTILINE paths

Description

Creates a dataframe consisting of detections of tags that are detected at two or more receiver at the same time.

Usage

simSiteDet(data)

Arguments

Examples

# Download sample project 176 to .motus database (username/password are "motus.sample")
## Not run: sql_motus <- tagme(176, new = TRUE)

# Or use example data base in memory
sql_motus <- tagmeSample()

# convert sql file "sql_motus" to a tbl called "tbl_alltags"
library(dplyr)
tbl_alltags <- tbl(sql_motus, "alltags") 

# convert the tbl "tbl_alltags" to a data.frame called "df_alltags"
df_alltags <- tbl_alltags %>% 
  collect() %>% 
  as.data.frame()

# To get a data.frame of just simultaneous detections from a tbl file
# tbl_alltags
simSites <- simSiteDet(tbl_alltags)

# To get a data.frame of just simultaneous detections from a dataframe
# df_alltags
simSites <- simSiteDet(df_alltags)

Description

Creates a summary of the first and last detection at a site, the length of time between first and last detection, the number of tags, and the total number of detections at a site. Plots total number of detections across all tags, and total number of tags detected at each site.

Usage

siteSum(data, units = "hours")

Arguments

Value

a data.frame with these columns:

• site: site

• first_ts: time of first detection at specified site

• last_ts: time of last detection at specified site

• tot_ts: total amount of time between first and last detection at specified site, output in specified unit (defaults to "hours")

• num.tags: total number of unique tags detected at specified site

• num.det: total number of tag detections at specified site

Examples

# Download sample project 176 to .motus database (username/password are "motus.sample")
## Not run: sql_motus <- tagme(176, new = TRUE)

# Or use example data base in memory
sql_motus <- tagmeSample()

# convert sql file "sql_motus" to a tbl called "tbl_alltags"
library(dplyr)
tbl_alltags <- tbl(sql_motus, "alltagsGPS") 

# convert the tbl "tbl_alltags" to a data.frame called "df_alltags"
df_alltags <- tbl_alltags %>% 
  collect() %>% 
  as.data.frame() 

# Create site summaries for all sites within detection data with time in
# default hours using data.frame df_alltags
site_summary <- siteSum(tbl_alltags)

# Create site summaries for only select sites with time in minutes
sub <- filter(df_alltags, recvDeployName %in% 
                c("Niapiskau", "Netitishi", "Old Cur", "Washkaugou"))
site_summary <- siteSum(sub, units = "mins")

# Create site summaries for only a select species, Red Knot
site_summary <- siteSum(filter(df_alltags, speciesEN == "Red Knot"))

Description

Creates a summary of the first and last daily detection at a site, the length of time between first and last detection, the number of tags, and the total number of detections at a site for each day. Same as siteSum(), but daily by site.

Usage

siteSumDaily(data, units = "hours")

Arguments

Value

a data.frame with these columns:

• recvDeployName: site name of deployment

• date: date that is being summarized

• first_ts: time of first detection on specified "date" at "recvDeployName"

• last_ts: time of last detection on specified "date" at "recvDeployName"

• tot_ts: total amount of time between first and last detection at "recvDeployName" on "date, output in specified unit (defaults to "hours")

• num.tags: total number of unique tags detected at "recvDeployName", on "date"

• num.det: total number of detections at "recvDeployName", on "date"

Examples

# Download sample project 176 to .motus database (username/password are "motus.sample")
## Not run: sql_motus <- tagme(176, new = TRUE)

# Or use example data base in memory
sql_motus <- tagmeSample()

# convert sql file "sql_motus" to a tbl called "tbl_alltags"
library(dplyr)
tbl_alltags <- tbl(sql_motus, "alltagsGPS")

# convert the tbl "tbl_alltags" to a data.frame called "df_alltags"
df_alltags <- tbl_alltags %>% 
  collect() %>% 
  as.data.frame() 

# Create site summaries for all sites within detection data with time in
# minutes using tbl file tbl_alltags
daily_site_summary <- siteSumDaily(tbl_alltags, units = "mins")

# Create site summaries for only select sites with time in minutes using tbl
# file tbl_alltags
sub <- filter(tbl_alltags, recvDeployName %in% c("Niapiskau", "Netitishi", 
                                                 "Old Cut", "Washkaugou"))
daily_site_summary <- siteSumDaily(sub, units = "mins")

# Create site summaries for only a select species, Red Knot, with default
# time in hours using data frame df_alltags
daily_site_summary <- siteSumDaily(filter(df_alltags,
                                          speciesEN == "Red Knot"))

Description

Creates a dataframe of transitions between sites; detections are ordered by detection time, then "transitions" are identified as the period between the final detection at site x (possible "departure"), and the first detection (possible "arrival") at site y (ordered chronologically). Each row contains the last detection time and lat/lon of site x, first detection time and lat/lon of site y, distance between the site pair, time between detections, rate of movement between detections, and bearing between site pairs.

Usage

siteTrans(data, latCoord = "recvDeployLat", lonCoord = "recvDeployLon")

Arguments

Value

a data.frame with these columns:

• fullID: fullID of Motus registered tag

• ts.x: time of last detection of tag at site.x ("departure" time)

• lat.x: latitude of site.x

• lon.x: longitude of site.x

• site.x: first site in transition pair (the "departure" site)

• ts.y: time of first detection of tag at site.y ("arrival" time)

• lat.y: latitude of site.y

• lon.y: longitude of site.y

• site.y: second site in transition pair (the "departure" site)

• tot_ts: length of time between ts.x and ts.y (in seconds)

• dist: total straight line distance between site.x and site.y (in metres), see sensorgnome::latLonDist() for details

• rate: overall rate of movement (tot_ts/dist), in metres/second

• bearing: bearing between first and last detection sites, see bearing function in geosphere package for more details

Examples

# Download sample project 176 to .motus database (username/password are "motus.sample")
## Not run: sql_motus <- tagme(176, new = TRUE)

# Or use example data base in memory
sql_motus <- tagmeSample()

# convert sql file "sql_motus" to a tbl called "tbl_alltags"
library(dplyr)
tbl_alltags <- tbl(sql_motus, "alltagsGPS") 
 
## convert the tbl "tbl_alltags" to a data.frame called "df_alltags"
 df_alltags <- tbl_alltags %>%
   collect() %>%
   as.data.frame()

# View all site transitions for all detection data from tbl file tbl_alltags
transitions <- siteTrans(tbl_alltags)

# View site transitions for only tag 16037 from data.frame df_alltags using
# gpsLat/gpsLon
transitions <- siteTrans(filter(df_alltags, motusTagID == 16037),
                           latCoord = "gpsLat", lonCoord = "gpsLon")

Description

Sets, resets or returns the "motus.timeout" global option used by all API access functions (including tagme()). If timeout is a number and reset is FALSE, the API timeout is set to timeout number of seconds. If reset is TRUE, the API timeout is reset to the default of 120 seconds. If no timeout is defined and reset = FALSE, the current value of the timeout is returned.

Usage

srvTimeout(timeout, reset = FALSE)

Arguments

Details

By default the timeout is 120s, which generally should give the server sufficient time to prepare the data without having the user wait for too long if the API is unavailable. However, some projects take unusually long to compile the data, so a longer timeout may be warranted in those situations. This is equivalent to options(motus.timeout = timeout)

Value

Nothing. Or, if timeout is missing and reset = FALSE, the current timeout value.

Examples

srvTimeout()   # get the timeout value
srvTimeout(5)  # set the timeout value
srvTimeout()   # get the timeout value

## Not run: 
# No problem with default timeouts
t <- tagme(176, new = TRUE)

# But setting the timeout too short results in a server timeout
srvTimeout(0.001)
t <- tagme(176, new = TRUE)

## End(Not run)

Description

Create and add sunrise and sunset columns to tag data. Can take a motus database table, but will always return a collected data frame. Requires data containing at least latitude, longitude, and time.

Usage

sunRiseSet(
  df_src,
  lat = "recvDeployLat",
  lon = "recvDeployLon",
  ts = "ts",
  data
)

Arguments

Details

Note that this will always return the sunrise and sunset of the local date. For example, 2023-01-01 04:00:00 in Central North American time is 2023-01-01 in UTC, but 2023-01-01 20:00:00 is actually the following date in UTC. Because Motus timestamps are UTC, times are first converted to their local time zone time using the lat/lon coordinates before extracting the date. Thus:

• A UTC timestamp of 1672624800 for Winnipeg, Canada is 2023-01-02 02:00:00 UTC and 2023-01-01 20:00:00 local time

• Therefore sunRiseSet() calculates the sunrise/sunset times for 2023-01-01 (not for 2023-01-02)

• These sunrise/sunset times are returned in UTC: 2023-01-01 14:27:50 UTC and 2023-01-01 22:38:30 UTC

• Note that the UTC timestamp 2023-01-02 02:00:00 is later than the sunset time of 2023-01-01 22:38:30 UTC. This makes sense, as we know that the timestamp is ~8pm local time, well after sunset in the winter for that date.

Value

Original data (as a flat data frame), with the following additional columns:

• sunrise - Time of sunrise in UTC for that row's date and location

• sunset - Time of sunset in UTC for that row's date and location

Examples

# Download sample project 176 to .motus database (username/password are "motus.sample")
## Not run: sql_motus <- tagme(176, new = TRUE)

# Or use example data base in memory
sql_motus <- tagmeSample()

# For SQLite Data base-----------------------------------------------
sun <- sunRiseSet(sql_motus)

# For specific SQLite table/view ------------------------------------
library(dplyr)
tbl_alltagsGPS <- tbl(sql_motus, "alltagsGPS") 
sun <- sunRiseSet(tbl_alltagsGPS)

# For a flattened data frame ----------------------------------------
df_alltagsGPS <- collect(tbl_alltagsGPS)
sun <- sunRiseSet(df_alltagsGPS)

# Using alternate lat/lons ------------------------------------------
# Get sunrise and sunset information from tbl_alltags using gps lat/lon
# Note this will only work if there are non-NA values in gpsLat/gpsLon
## Not run: sun <- sunRiseSet(tbl_alltagsGPS, lat = "gpsLat", lon = "gpsLon")

Description

This is the main motus function for accessing and updating your data. This function downloads motus data to a local SQLite data base in the name of project-XXX.motus or RECIVER_NAME.motus. If you are having trouble with a particular data base timing out on downloads, see srvTimeout() for options.

Usage

tagme(
  projRecv,
  update = TRUE,
  new = FALSE,
  dir = getwd(),
  countOnly = FALSE,
  forceMeta = FALSE,
  rename = FALSE,
  skipActivity = FALSE,
  skipNodes = FALSE,
  skipDeprecated = FALSE
)

Arguments

Value

a SQLite Connection for the (possibly updated) database, or a data frame of counts if countOnly = TRUE.

See Also

tellme(), which is a synonym for tagme(..., countOnly = TRUE)

Examples

## Not run: 

# Create and update a local tag database for motus project 14 in the
# current directory

t <- tagme(14, new = TRUE)

# Update and open the local tag database for motus project 14;
# it must already exist and be in the current directory

t <- tagme(14)

# Update and open the local tag database for a receiver;
# it must already exist and be in the current directory

t <- tagme("SG-1234BBBK4567")

# Open the local tag database for a receiver, without
# updating it

t <- tagme("SG-1234BBBK4567", update = FALSE)

# Open the local tag database for a receiver, but
# tell 'tagme' that it is in a specific directory

t <- tagme("SG-1234BBBK4567", dir = "Projects/gulls")

# Update all existing project and receiver databases in the current working
# directory

tagme()

## End(Not run)

Description

For running examples and testing out motus functionality, it can be useful to work with sample data set. You can download the most up-to-date copy of this data yourself (to ⁠project-176.motus⁠) with the username and password both "motus.sample".

Usage

tagmeSample(db = "project-176.motus")

Arguments

Details

sql_motus <- tagme(176, new = TRUE)

Or you can use this helper function to grab an in-memory copy bundled in this package.

Value

In memory version of the sample database.

Examples

# Explore the sample data
tags <- tagmeSample()
dplyr::tbl(tags, "activity")
dplyr::tbl(tags, "alltags")

Description

Creates a summary for each tag of it's first and last detection time (ts), first and last detection site, length of time between first and last detection, straight line distance between first and last detection site, rate of movement, and bearing. Lat/lons are taken from gpsLat/gpsLon, or if missing, from recvDeployLat/recvDeployLon. Bearing is calculated using the geosphere::bearing() function.

Usage

tagSum(df_src, data)

Arguments

Value

A flat data frame with the following for each tag:

• fullID - fullID of Motus registered tag

• first_ts - Time (ts) of first detection

• last_ts - Time (ts) of last detection

• first_site - First detection site (recvDeployName)

• last_site - Last detection site (recvDeployName)

• recvLat.x - Latitude of first detection site (gpsLat or recvDeployLat)

• recvLon.x - Longitude of first detection site (gpsLon or recvDeployLon)

• recvLat.y - Latitude of last detection site (gpsLat or recvDeployLat)

• recvLon.y - Longitude of last detection site (gpsLon or recvDeployLon)

• tot_ts - Time between first and last detection (in seconds)

• dist - Straight line distance between first and last detection site (in metres)

• rate - Overall rate of movement (tot_ts/dist), in metres/second

• bearing - Bearing between first and last detection sites

• num_det - Number of detections summarized

Examples

# Download sample project 176 to .motus database (username/password are "motus.sample")
## Not run: sql_motus <- tagme(176, new = TRUE)

# Or use example data base in memory
sql_motus <- tagmeSample()

# Summarize tags
tag_summary <- tagSum(sql_motus)

# For specific SQLite table/view (needs gpsLat/gpsLon) --------------
library(dplyr)
tbl_alltagsGPS <- tbl(sql_motus, "alltagsGPS") 
tag_summary <- tagSum(tbl_alltagsGPS)

# For a flattened data frame ----------------------------------------
df_alltagsGPS <- collect(tbl_alltagsGPS)
tag_summary <- tagSum(df_alltagsGPS)

# Can be filtered, e.g., for only a few tags
tag_summary <- tagSum(filter(tbl_alltagsGPS, motusTagID %in% c(16047, 16037, 16039)))

Description

Creates a summary for each tag of it's first and last detection time at each site, length of time between first and last detection of each site, and total number of detections at each site.

Usage

tagSumSite(data, units = "hours")

Arguments

Examples

# Download sample project 176 to .motus database (username/password are "motus.sample")
## Not run: sql_motus <- tagme(176, new = TRUE)

# Or use example data base in memory
sql_motus <- tagmeSample()

# convert sql file "sql_motus" to a tbl called "tbl_alltags"
library(dplyr)
tbl_alltags <- tbl(sql_motus, "alltagsGPS") 

# convert the tbl "tbl_alltags" to a data.frame called "df_alltags"
df_alltags <- tbl_alltags  %>% 
  collect() %>% 
  as.data.frame() 

# Create tag summaries for all tags within detection data with time in
# minutes with tbl file tbl_alltags
tag_site_summary <- tagSumSite(tbl_alltags, units = "mins")

# Create tag summaries for only select tags with time in default hours with
# data.frame df_alltags
tag_site_summary <- tagSumSite(filter(df_alltags, 
                                      motusTagID %in% c(16047, 16037, 16039)))

# Create tag summaries for only a select species with data.frame df_alltags
tag_site_summary <- tagSumSite(filter(df_alltags, speciesEN == "Red Knot"))

Description

"new" means data not already in your local database.

Usage

tellme(projRecv, new = FALSE, dir = getwd())

Arguments

Value

a named list with these items:

• numBatches: number of batches having data for your database

• numRuns: number of runs of tags detections with new data

• numHits: number of new detections

• numGPS: number of new GPS fixes covering the new detections

• numBytes: estimated size of download, in bytes. This is an estimate of the uncompressed size, but data are gz-compressed for transfer, so the number of bytes you have to download is typically going to be smaller than this number by a factor of 2 or more.

Note

if you specify new = TRUE and the database does not already exist, it will be created (but empty).

Description

Create and add columns for time to and time since sunrise/sunset to tag data. Can take a motus database table, but will always return a collected data frame. Requires data containing at least latitude, longitude, and time.

Usage

timeToSunriset(
  df_src,
  lat = "recvDeployLat",
  lon = "recvDeployLon",
  ts = "ts",
  units = "hours",
  data
)

Arguments

Details

Uses sunRiseSet() to perform sunrise/sunset calculates, see ?sunRiseSet for details regarding how local dates are assessed from UTC timestamps.

Value

Original data (as a flat data frame), with the following additional columns:

• sunrise - Time of sunrise in UTC for that row's date and location

• sunset - Time of sunset in UTC for that row's date and location

• ts_to_set - Time to next sunset, in units

• ts_since_set - Time to previous sunset, in units

• ts_to_rise - Time to next sunrise after, in units

• ts_since_rise - Time to previous sunrise, in units

Examples

# Download sample project 176 to .motus database (username/password are "motus.sample")
## Not run: sql_motus <- tagme(176, new = TRUE)

# Or use example data base in memory
sql_motus <- tagmeSample()

# Get sunrise and sunset information for alltags view with units in minutes
sunrise <- timeToSunriset(sql_motus, units = "mins")

Description

Write to the local database the probabilities associated with runs for a filter

Usage

writeRunsFilter(
  src,
  filterName,
  motusProjID = NA,
  df,
  overwrite = TRUE,
  delete = FALSE
)

Arguments

Value

database connection refering to the filter created