Package 'etnservice'

Title: Serve Data from the European Tracking Network
Description: Provides API endpoints to the European Tracking Network. Designed to be used with OpenCPU and the 'etn' package.
Authors: Pieter Huybrechts [aut, cre] (ORCID: <https://orcid.org/0000-0002-6658-6062>), Peter Desmet [aut] (ORCID: <https://orcid.org/0000-0002-8442-8025>), Research Institute for Nature and Forest (INBO) [cph] (ROR: <https://ror.org/00j54wy13>), LifeWatch Belgium [fnd] (https://lifewatch.be)
Maintainer: Pieter Huybrechts <[email protected]>
License: MIT + file LICENSE
Version: 0.7.0.9000
Built: 2026-10-09 10:27:06 UTC
Source: https://github.com/inbo/etnservice

Help Index


Check if the provided credentials are valid.

Description

This function checks if the provided credentials contain a "username" and "password" field, and if both fields are of type character. It also verifies that the credentials object has a length of 2.

Usage

check_credentials(credentials)

Arguments

credentials

A list or data frame containing the credentials to be checked.

Value

TRUE if the credentials are valid, an error otherwise

Examples

## Not run: 
credentials <- list(username = "john_doe", password = "password123")
check_credentials(credentials)
#> [1] TRUE

## End(Not run)

Connect to the ETN database

Description

Connect to the ETN database using username and password.

Usage

connect_to_etn(username, password)

Arguments

username

Character. Username to use for the connection.

password

Character. Password to use for the connection.

Value

ODBC connection to ETN database.

Examples

## Not run: 
# Connect to the ETN database using your rstudio.lifewatch.be username and
# password, and save as the default connection variable "con"
con <- connect_to_etn()

# Connect to the ETN database using non-default username and password
con <- connect_to_etn(username = "my_username", password = "my_password")

## End(Not run)

Retrieve log files/diagnostic information for deployments of acoustic receivers.

Description

This function retrieves log files and diagnostic information for deployments of acoustic receivers from the ETN database. The returned data includes deployment ID, receiver ID, station name, datetime, record type, and log data in JSON format.

Usage

get_acoustic_deployment_logs(
  credentials = list(username = Sys.getenv("ETN_USER"), password = Sys.getenv("ETN_PWD")),
  deployment_id,
  limit = FALSE
)

Arguments

credentials

A list with the username and password to connect to the ETN database.

deployment_id

Integer (vector). One or more deployment identifiers.

limit

Logical. Limit the number of returned records to 100 (useful for testing purposes). Defaults to FALSE.

Value

A tibble with receiver diagnostics data. The data is embedded in a log_data column that is JSON formatted.

Examples

get_acoustic_deployment_logs(deployment_id = 6028)

get_acoustic_deployment_logs(deployment_id = c(53790, 1758), limit = TRUE)

Get acoustic deployment data

Description

Get data for deployments of acoustic receivers, with options to filter results.

Usage

get_acoustic_deployments(
  credentials = list(username = Sys.getenv("ETN_USER"), password = Sys.getenv("ETN_PWD")),
  deployment_id = NULL,
  receiver_id = NULL,
  acoustic_project_code = NULL,
  station_name = NULL,
  open_only = FALSE
)

Arguments

credentials

A list with the username and password to connect to the ETN database.

deployment_id

Integer (vector). One or more deployment identifiers.

receiver_id

Character (vector). One or more receiver identifiers.

acoustic_project_code

Character (vector). One or more acoustic project codes. Case-insensitive.

station_name

Character (vector). One or more deployment station names.

open_only

Logical. Restrict deployments to those that are currently open (i.e. no end date defined). Defaults to FALSE.

Value

A tibble with acoustic deployment data, sorted by acoustic_project_code, station_name and deploy_date_time. See also field definitions.

Examples

# Set credentials
credentials <- list(
   username = Sys.getenv("ETN_USER"),
   password = Sys.getenv("ETN_PWD")
 )

# Get all acoustic deployments
get_acoustic_deployments(credentials)

# Get specific acoustic deployment
get_acoustic_deployments(credentials, deployment_id = 1437)

# Get acoustic deployments for a specific receiver
get_acoustic_deployments(credentials, receiver_id = "VR2W-124070")

# Get open acoustic deployments for a specific receiver
get_acoustic_deployments(credentials, receiver_id = "VR2W-124070", open_only = TRUE)

# Get acoustic deployments for a specific acoustic project
get_acoustic_deployments(credentials, acoustic_project_code = "demer")

# Get acoustic deployments for two specific stations
get_acoustic_deployments(credentials, station_name = c("de-9", "de-10"))

Get acoustic detections data

Description

Get data for acoustic detections, with options to filter results. Use limit to limit the number of returned records.

Usage

get_acoustic_detections(
  credentials = list(username = Sys.getenv("ETN_USER"), password = Sys.getenv("ETN_PWD")),
  start_date = NULL,
  end_date = NULL,
  acoustic_tag_id = NULL,
  animal_project_code = NULL,
  scientific_name = NULL,
  acoustic_project_code = NULL,
  receiver_id = NULL,
  station_name = NULL,
  limit = FALSE
)

Arguments

credentials

A list with the username and password to connect to the ETN database.

start_date

Character. Start date (inclusive) in ISO 8601 format ( yyyy-mm-dd, yyyy-mm or yyyy).

end_date

Character. End date (exclusive) in ISO 8601 format ( yyyy-mm-dd, yyyy-mm or yyyy).

acoustic_tag_id

Character (vector). One or more acoustic tag ids.

animal_project_code

Character (vector). One or more animal project codes. Case-insensitive.

scientific_name

Character (vector). One or more scientific names.

acoustic_project_code

Character (vector). One or more acoustic project codes. Case-insensitive.

receiver_id

Character (vector). One or more receiver identifiers.

station_name

Character (vector). One or more deployment station names.

limit

Logical. Limit the number of returned records to 100 (useful for testing purposes). Defaults to FALSE.

Value

A tibble with acoustic detections data, sorted by acoustic_tag_id and date_time. See also field definitions.

Examples

## Not run: 
# Set default connection variable
con <- connect_to_etn()

# Get limited sample of acoustic detections
get_acoustic_detections(con, limit = TRUE)

# Get all acoustic detections from a specific animal project
get_acoustic_detections(con, animal_project_code = "2014_demer")

# Get 2015 acoustic detections from that animal project
get_acoustic_detections(
  con,
  animal_project_code = "2014_demer",
  start_date = "2015",
  end_date = "2016",
)

# Get April 2015 acoustic detections from that animal project
get_acoustic_detections(
  con,
  animal_project_code = "2014_demer",
  start_date = "2015-04",
  end_date = "2015-05",
)

# Get April 24, 2015 acoustic detections from that animal project
get_acoustic_detections(
  con,
  animal_project_code = "2014_demer",
  start_date = "2015-04-24",
  end_date = "2015-04-25",
)

# Get acoustic detections for a specific tag at two specific stations
get_acoustic_detections(
  con,
  acoustic_tag_id = "A69-1601-16130",
  station_name = c("de-9", "de-10")
)

# Get acoustic detections for a specific species, receiver and acoustic project
get_acoustic_detections(
  con,
  scientific_name = "Rutilus rutilus",
  receiver_id = "VR2W-124070",
  acoustic_project_code = "demer"
)

## End(Not run)

Getting a single page of a multi page acoustic detections query

Description

A view was implemented that returns the next primary key id, this allows for optimized page wise detections querying to the database as no offset needs to be included.

Usage

get_acoustic_detections_page(
  credentials = list(username = Sys.getenv("ETN_USER"), password = Sys.getenv("ETN_PWD")),
  next_id_pk = 0,
  page_size = 1e+05,
  start_date = NULL,
  end_date = NULL,
  tag_serial_number = NULL,
  acoustic_tag_id = NULL,
  animal_project_code = NULL,
  scientific_name = NULL,
  acoustic_project_code = NULL,
  deployment_id = NULL,
  receiver_id = NULL,
  station_name = NULL,
  count = FALSE,
  ...
)

Arguments

credentials

A list with the username and password to connect to the ETN database.

next_id_pk

The next primary key to fetch. All detections have a sequential id, this key allows us to read the view top to bottom, but filter out any records with lower detection_ids the one we've already fetched. By default, start reading at the first detection. Returned records have a detection_id higher than next_id_pk.

page_size

The number of records to retrieve.

start_date

Character. Start date (inclusive) in ISO 8601 format ( yyyy-mm-dd, yyyy-mm or yyyy).

end_date

Character. End date (exclusive) in ISO 8601 format ( yyyy-mm-dd, yyyy-mm or yyyy).

tag_serial_number

Character (vector). One or more tag serial numbers.

acoustic_tag_id

Character (vector). One or more acoustic tag ids.

animal_project_code

Character (vector). One or more animal project codes. Case-insensitive.

scientific_name

Character (vector). One or more scientific names.

acoustic_project_code

Character (vector). One or more acoustic project codes. Case-insensitive.

deployment_id

Character (vector). One or more deployment ids.

receiver_id

Character (vector). One or more receiver identifiers.

station_name

Character (vector). One or more deployment station names.

count

Logical. If set to TRUE a data.frame is returned with a single column: the count of the number of records returned by the query. page_size is ignored.

...

Additional arguments passed to the function. Not used. Handy if extra arguments are passed as a side effect of do.call()

Value

A tibble with acoustic detections data, with length page_size or smaller. Including a column with the primary key of the next detection.


Get acoustic project data

Description

Get data for acoustic projects, with options to filter results.

Usage

get_acoustic_projects(
  credentials = list(username = Sys.getenv("ETN_USER"), password = Sys.getenv("ETN_PWD")),
  acoustic_project_code = NULL
)

Arguments

credentials

A list with the username and password to connect to the ETN database.

acoustic_project_code

Character (vector). One or more acoustic project codes. Case-insensitive.

Value

A tibble with acoustic project data, sorted by project_code. See also field definitions.

Examples

# Set credentials
credentials <- list(
   username = Sys.getenv("ETN_USER"),
   password = Sys.getenv("ETN_PWD")
 )

# Get all acoustic projects
get_acoustic_projects(credentials)

# Get a specific acoustic project
get_acoustic_projects(credentials, acoustic_project_code = "demer")

Get acoustic receiver data

Description

Get data for acoustic receivers, with options to filter results.

Usage

get_acoustic_receivers(
  credentials = list(username = Sys.getenv("ETN_USER"), password = Sys.getenv("ETN_PWD")),
  receiver_id = NULL,
  status = NULL
)

Arguments

credentials

A list with the username and password to connect to the ETN database.

receiver_id

Character (vector). One or more receiver identifiers.

status

Character. One or more statuses, e.g. available or broken.

Value

A tibble with acoustic receiver data, sorted by receiver_id. See also field definitions. Values for owner_organization will only be visible if you are member of the group.

Examples

# Set credentials
credentials <- list(
   username = Sys.getenv("ETN_USER"),
   password = Sys.getenv("ETN_PWD")
 )

# Get all acoustic receivers
get_acoustic_receivers(credentials)

# Get lost and broken acoustic receivers
get_acoustic_receivers(credentials, status = c("lost", "broken"))

# Get a specific acoustic receiver
get_acoustic_receivers(credentials, receiver_id = "VR2W-124070")

Get animal project data

Description

Get data for animal projects, with options to filter results.

Usage

get_animal_projects(
  credentials = list(username = Sys.getenv("ETN_USER"), password = Sys.getenv("ETN_PWD")),
  animal_project_code = NULL
)

Arguments

credentials

A list with the username and password to connect to the ETN database.

animal_project_code

Character (vector). One or more animal project codes. Case-insensitive.

Value

A tibble with animal project data, sorted by project_code. See also field definitions.

Examples

# Set credentials
credentials <- list(
   username = Sys.getenv("ETN_USER"),
   password = Sys.getenv("ETN_PWD")
 )

# Get all animal projects
get_animal_projects(credentials)

# Get a specific animal project
get_animal_projects(credentials, animal_project_code = "2014_demer")

Get animal data

Description

Get data for animals, with options to filter results. Associated tag information is available in columns starting with tag and acoustic_tag_id. If multiple tags are associated with a single animal, the information is comma-separated.

Usage

get_animals(
  credentials = list(username = Sys.getenv("ETN_USER"), password = Sys.getenv("ETN_PWD")),
  animal_id = NULL,
  tag_serial_number = NULL,
  animal_project_code = NULL,
  scientific_name = NULL
)

Arguments

credentials

A list with the username and password to connect to the ETN database.

animal_id

Integer (vector). One or more animal identifiers.

tag_serial_number

Character (vector). One or more tag serial numbers.

animal_project_code

Character (vector). One or more animal project codes. Case-insensitive.

scientific_name

Character (vector). One or more scientific names.

Value

A tibble with animals data, sorted by animal_project_code, release_date_time and tag_serial_number. See also field definitions.

Examples

# Set credentials
credentials <- list(
   username = Sys.getenv("ETN_USER"),
   password = Sys.getenv("ETN_PWD")
 )

# Get all animals
get_animals(credentials)

# Get specific animals
get_animals(credentials, animal_id = 305) # Or string value "305"
get_animals(credentials, animal_id = c(304, 305, 2827))

# Get animals from specific animal project(s)
get_animals(credentials, animal_project_code = "2014_demer")
get_animals(credentials, animal_project_code = c("2014_demer", "2015_dijle"))

# Get animals associated with a specific tag_serial_number
get_animals(credentials, tag_serial_number = "1187450")

# Get animals of specific species (across all projects)
get_animals(credentials, scientific_name = c("Rutilus rutilus", "Silurus glanis"))

# Get animals of a specific species from a specific project
get_animals(credentials, animal_project_code = "2014_demer", scientific_name = "Rutilus rutilus")

Fetch a table with UUID references to archival data files

Description

Archival data is stored in csv files hosted on lifewatch.com. To fetch these we must first query ETN for uuids that are needed to build the paths to read these csv files.

Usage

get_archival_data_uuid(
  credentials = list(username = Sys.getenv("ETN_USER"), password = Sys.getenv("ETN_PWD")),
  tag_serial_number = NULL,
  animal_project_code = NULL,
  animal_id = NULL
)

Arguments

credentials

A list with the username and password to connect to the ETN database.

tag_serial_number

Character (vector). One or more tag serial numbers.

animal_project_code

Character (vector). One or more animal project codes. Case-insensitive.

animal_id

Integer (vector). One or more animal identifiers.

Value

A tibble with a column converted_archival_file_uuid that contains the UUID pointing to the archival data csv file. Other columns are: animal_id, tag_serial_number, and animal_project_code.

Examples

get_archival_data_uuid(tag_serial_number = "22035610")

Get cpod project data

Description

Get data for cpod projects, with options to filter results.

Usage

get_cpod_projects(
  credentials = list(username = Sys.getenv("ETN_USER"), password = Sys.getenv("ETN_PWD")),
  cpod_project_code = NULL
)

Arguments

credentials

A list with the username and password to connect to the ETN database.

cpod_project_code

Character (vector). One or more cpod project codes. Case-insensitive.

Value

A tibble with animal project data, sorted by project_code. See also field definitions.

Examples

# Set credentials
credentials <- list(
   username = Sys.getenv("ETN_USER"),
   password = Sys.getenv("ETN_PWD")
 )

# Get all animal projects
get_cpod_projects(credentials)

# Get a specific animal project
get_cpod_projects(credentials, cpod_project_code = "cpod-lifewatch")

Get tag data

Description

Get data for tags, with options to filter results. Note that there can be multiple records (acoustic_tag_id) per tag device (tag_serial_number).

Usage

get_tags(
  credentials = list(username = Sys.getenv("ETN_USER"), password = Sys.getenv("ETN_PWD")),
  tag_type = NULL,
  tag_subtype = NULL,
  tag_serial_number = NULL,
  acoustic_tag_id = NULL
)

Arguments

credentials

A list with the username and password to connect to the ETN database.

tag_type

Character (vector). acoustic or archival. Some tags are both, find those with acoustic-archival.

tag_subtype

Character (vector). animal, ⁠built-in⁠, range or sentinel.

tag_serial_number

Character (vector). One or more tag serial numbers.

acoustic_tag_id

Character (vector). One or more acoustic tag identifiers, i.e. identifiers found in get_acoustic_detections().

Value

A tibble with tags data, sorted by tag_serial_number. See also field definitions. Values for owner_organization and owner_pi will only be visible if you are member of the group.

Examples

# Set credentials
credentials <- list(
   username = Sys.getenv("ETN_USER"),
   password = Sys.getenv("ETN_PWD")
 )

# Get all tags
get_tags(credentials)

# Get archival tags, including acoustic-archival
get_tags(credentials, tag_type = c("archival", "acoustic-archival"))

# Get tags of specific subtype
get_tags(credentials, tag_subtype = c("built-in", "range"))

# Get specific tags (note that these can return multiple records)
get_tags(credentials, tag_serial_number = "1187450")
get_tags(credentials, acoustic_tag_id = "A69-1601-16130")
get_tags(credentials, acoustic_tag_id = c("A69-1601-16129", "A69-1601-16130"))

Version information about etnservice

Description

Users of the etn package might (probably will) have a local version of etnservice. If there are differences between the version deployed on the API and the version installed locally, this might lead to inconsistent results when switching between local database queries and queries over the API. This function returns version information of the installed version of etnservice, when called over the api, it'll return version information on the version of etnservice deployed via opencpu.

Usage

get_version()

Value

A list with the following elements:

ls

A character vector of the objects in the environment.

version

The version of the etnservice package.

Examples

get_version()

List all available acoustic project codes

Description

List all available acoustic project codes

Usage

list_acoustic_project_codes(
  credentials = list(username = Sys.getenv("ETN_USER"), password = Sys.getenv("ETN_PWD"))
)

Arguments

credentials

A list with the username and password to connect to the ETN database.

Value

A vector of all unique project_code of type = "acoustic" in project.sql.


List all available acoustic tag ids

Description

List all available acoustic tag ids

Usage

list_acoustic_tag_ids(
  credentials = list(username = Sys.getenv("ETN_USER"), password = Sys.getenv("ETN_PWD"))
)

Arguments

credentials

A list with the username and password to connect to the ETN database.

Value

A vector of all unique acoustic_tag_id in acoustic_tag_id.sql.


List all available animal ids

Description

List all available animal ids

Usage

list_animal_ids(
  credentials = list(username = Sys.getenv("ETN_USER"), password = Sys.getenv("ETN_PWD"))
)

Arguments

credentials

A list with the username and password to connect to the ETN database.

Value

A vector of all unique id_pk present in common.animal_release.


List all available animal project codes

Description

List all available animal project codes

Usage

list_animal_project_codes(
  credentials = list(username = Sys.getenv("ETN_USER"), password = Sys.getenv("ETN_PWD"))
)

Arguments

credentials

A list with the username and password to connect to the ETN database.

Value

A vector of all unique project_code of type = "animal" in project.sql.


List all available cpod project codes

Description

List all available cpod project codes

Usage

list_cpod_project_codes(
  credentials = list(username = Sys.getenv("ETN_USER"), password = Sys.getenv("ETN_PWD"))
)

Arguments

credentials

A list with the username and password to connect to the ETN database.

Value

A vector of all unique project_code of type = "cpod" in project.sql.


List all available receiver ids

Description

List all available receiver ids

Usage

list_deployment_ids(
  credentials = list(username = Sys.getenv("ETN_USER"), password = Sys.getenv("ETN_PWD"))
)

Arguments

credentials

A list with the username and password to connect to the ETN database.

Value

A vector of all unique id_pk present in acoustic.deployments.


List all available receiver ids

Description

List all available receiver ids

Usage

list_receiver_ids(
  credentials = list(username = Sys.getenv("ETN_USER"), password = Sys.getenv("ETN_PWD"))
)

Arguments

credentials

A list with the username and password to connect to the ETN database.

Value

A vector of all unique receiver present in acoustic.receivers.


List all available scientific names

Description

List all available scientific names

Usage

list_scientific_names(
  credentials = list(username = Sys.getenv("ETN_USER"), password = Sys.getenv("ETN_PWD"))
)

Arguments

credentials

A list with the username and password to connect to the ETN database.

Value

A vector of all unique scientific_name present in common.animal_release.


List all available station names

Description

List all available station names

Usage

list_station_names(
  credentials = list(username = Sys.getenv("ETN_USER"), password = Sys.getenv("ETN_PWD"))
)

Arguments

credentials

A list with the username and password to connect to the ETN database.

Value

A vector of all unique station_name present in acoustic.deployments.


List all available tag serial numbers

Description

List all available tag serial numbers

Usage

list_tag_serial_numbers(
  credentials = list(username = Sys.getenv("ETN_USER"), password = Sys.getenv("ETN_PWD"))
)

Arguments

credentials

A list with the username and password to connect to the ETN database.

Value

A vector of all unique tag_serial_numbers present in common.tag_device.


Check ETN Database Credentials

Description

Validates user credentials for the ETN database by attempting to establish a connection. Returns TRUE if the credentials are valid and FALSE otherwise.

Usage

validate_login(username, password)

Arguments

username

Character string containing the ETN database username.

password

Character string containing the ETN database password.

Value

Logical TRUE if credentials are valid and the connection is successful, FALSE if authentication fails.

Examples

# Check if credentials are valid
 validate_login("invalid_username", "invalid_password")