telemetry_api.RmdIn order to start interacting with the API server, you must first establish a session using a pre-established set of login credentials (Username and Password). It is best practice to avoid storing these in files which are easily shared with others either directly or indirectly (e.g. an accidental git commit). Please note, this includes .Rhistory files (which store console commands). Therefore, you want to use the password in a way that defines it without ever printing it in your script or R console.
A simple way to enact this is to stored login credentials in a file that is separate from the analysis script, and is ignored by git in a .gitignore file:
## Defines api_url, usr, and pwd
source("api_credentials.R", echo = FALSE)Using these, we can establish a session,
library(telemetry)
my_session = start_session(usr, pwd, api_url)The returned object stores all the information about the session that was just established, including the user who started the session, the URL of the database server, the time the session was started (as the session will timeout after some time), a curl handle for the session, and a unique token for the server to identify the session. This object is then passed into subsequent functions, simplifying the process of interacting with the server.
To download the data associated with an individual user, we use the
download_data() function. This takes a session object
created above, as well as a region and speciesID to download data for.
It will download a SQLite3 database which is a subset of that the user
has access to. By default, this is stored in a temporary file (which is
deleted when the user’s computer is restarted), but we can also specifiy
a location to keep a persistent copy:
download_data(my_session, region = 1, speciesID = 1, db_file = "my.db")This stores the database in the file called my.db in the
current working directory.
Both speciesID and region are optional. If
both are omitted, the entire dataset the user has access to will be
returned.
Of note when selecting by species: Only tags that are registered in the database will have a species associated with them. This means that a query by species ID will return only registered tags.
We can extract data from this database with the function
extract_data()
tele_data = extract_data("my.db")This creates a new environment (a list like object), which contains all of the tables from the specified database file.
tele_data$Tags ## a data.frame of the Tags tableAlternatively, we can assign the tables directly into our Global environment, but this is potentially dangerous - it will overwrite any existing objects with similar names as the tables in the database. Only do this if you are sure you don’t have objects in your environment with the same names, or do not mind losing those objects.
extract_data("my.db", env = .GlobalEnv) # Potentially dangerous!!When we want to see what the available entries for a certain category
are, e.g. species ID, we use the list_db_entry() function.
This function takes the name of the entry category, and returns a
data.frame of the respective entries. It requires an active
session.
list_db_entry("species", session = my_session)Once we are done with our interactions with the database, we should
close out our session. We can do this with
end_session()
end_session(my_session)