Package 'etn'

Description

Reads an example dataset, formatted as a Frictionless Data Package.

Usage

example_dataset(dataset = "2014_demer")

Arguments

Value

Frictionless data package.

2014_demer

⁠2014_demer⁠ is a river acoustic telemetry dataset. It contains 66 tagged animals across four species. Over 235,000 detections were observed between 2014 and 2019 by acoustic receivers deployed in Belgian rivers. Data are deposited at https://doi.org/10.14284/432.

The dataset was included in the package with:

get_package(animal_project_code = "2014_demer") |>
  write_package("inst/extdata/2014_demer")

After which the detections.csv file was compressed and its path manually updated in datapackage.json.

Examples

example_dataset()

Description

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

Usage

get_acoustic_deployments(
  connection,
  deployment_id = NULL,
  receiver_id = NULL,
  acoustic_project_code = NULL,
  station_name = NULL,
  open_only = FALSE
)

Arguments

Value

A tibble with acoustic deployment data, sorted by acoustic_project_code, station_name and deploy_date_time.

See Also

Other access functions: get_acoustic_detections(), get_acoustic_projects(), get_acoustic_receivers(), get_animal_projects(), get_animals(), get_cpod_projects(), get_package(), get_tags()

Examples

# Get all acoustic deployments
get_acoustic_deployments()

# Get specific acoustic deployment
get_acoustic_deployments(deployment_id = 1437)

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

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

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

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

Description

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

Usage

get_acoustic_detections(
  connection,
  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,
  receiver_id = NULL,
  station_name = NULL,
  limit = FALSE,
  progress = TRUE
)

Arguments

Value

A tibble with acoustic detections data, sorted by acoustic_tag_id and date_time.

See Also

Other access functions: get_acoustic_deployments(), get_acoustic_projects(), get_acoustic_receivers(), get_animal_projects(), get_animals(), get_cpod_projects(), get_package(), get_tags()

Examples

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

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

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

# Get April 2015 acoustic detections from that animal project
get_acoustic_detections(
  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(
  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(
  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(
  scientific_name = "Rutilus rutilus",
  receiver_id = "VR2W-124070",
  acoustic_project_code = "demer"
)

Description

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

Usage

get_acoustic_projects(
  connection,
  acoustic_project_code = NULL,
  citation = FALSE
)

Arguments

Value

A tibble with acoustic project data, sorted by project_code.

See Also

Other access functions: get_acoustic_deployments(), get_acoustic_detections(), get_acoustic_receivers(), get_animal_projects(), get_animals(), get_cpod_projects(), get_package(), get_tags()

Examples

# Get all acoustic projects
get_acoustic_projects()

# Get a specific acoustic project with citation
get_acoustic_projects(acoustic_project_code = "demer", citation = TRUE)

Description

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

Usage

get_acoustic_receivers(connection, receiver_id = NULL, status = NULL)

Arguments

Value

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

See Also

Other access functions: get_acoustic_deployments(), get_acoustic_detections(), get_acoustic_projects(), get_animal_projects(), get_animals(), get_cpod_projects(), get_package(), get_tags()

Examples

# Get all acoustic receivers
get_acoustic_receivers()

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

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

Description

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

Usage

get_animal_projects(connection, animal_project_code = NULL, citation = FALSE)

Arguments

Value

A tibble with animal project data, sorted by project_code.

See Also

Other access functions: get_acoustic_deployments(), get_acoustic_detections(), get_acoustic_projects(), get_acoustic_receivers(), get_animals(), get_cpod_projects(), get_package(), get_tags()

Examples

# Get all animal projects
get_animal_projects()

# Get a specific animal project with citation
get_animal_projects(animal_project_code = "2014_demer", citation = TRUE)

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(
  connection,
  animal_id = NULL,
  tag_serial_number = NULL,
  animal_project_code = NULL,
  scientific_name = NULL
)

Arguments

Value

A tibble with animals data, sorted by animal_project_code, release_date_time and tag_serial_number.

See Also

Other access functions: get_acoustic_deployments(), get_acoustic_detections(), get_acoustic_projects(), get_acoustic_receivers(), get_animal_projects(), get_cpod_projects(), get_package(), get_tags()

Examples

# Get all animals
get_animals()

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

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

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

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

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

Description

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

Usage

get_cpod_projects(connection, cpod_project_code = NULL, citation = FALSE)

Arguments

Value

A tibble with animal project data, sorted by project_code.

See Also

Other access functions: get_acoustic_deployments(), get_acoustic_detections(), get_acoustic_projects(), get_acoustic_receivers(), get_animal_projects(), get_animals(), get_package(), get_tags()

Examples

# Get all animal projects
get_cpod_projects()

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

Description

Gets all data related to an animal project as a Data Package.

Usage

get_package(animal_project_code)

Arguments

Value

A Data Package object. Write it to disk with write_package().

Included resources

The Data Package will contain and describe the following resources:

• animals: Animals related to an animal_project_code, as returned by get_animals().

• tags: Tags associated with the selected animals, as returned by get_tags().

• detections: Acoustic detections for the selected animals, as returned by get_acoustic_detections().

• deployments: Acoustic deployments for the acoustic_project_code(s) found in detections, as returned by get_acoustic_deployments(), but excluding deployments that started after the last detection. This allows you to see when and where receivers were deployed, even if these did not detect the selected animals.

• receivers: Acoustic receivers for the selected deployments, as returned by get_acoustic_receivers().

• references: References for ETN, the R package, the animal project and acoustic projects that returned detections. It is recommended to cite these when using the dataset.

Data quality

The data are downloaded from the ETN database as is, i.e. no quality or consistency checks are performed. Verifying the data before publication is therefore recommended. You can validate the technical consistency of your Data Package using Frictionless Framework with:

pip install frictionless
frictionless validate datapackage.json

See Also

Other access functions: get_acoustic_deployments(), get_acoustic_detections(), get_acoustic_projects(), get_acoustic_receivers(), get_animal_projects(), get_animals(), get_cpod_projects(), get_tags()

Examples

# Get a Data Package for a project
(package <- get_package(animal_project_code = "2014_demer"))

# Read a resource
read_resource(package, "animals")

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(
  connection,
  tag_type = NULL,
  tag_subtype = NULL,
  tag_serial_number = NULL,
  acoustic_tag_id = NULL
)

Arguments

Value

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

See Also

Other access functions: get_acoustic_deployments(), get_acoustic_detections(), get_acoustic_projects(), get_acoustic_receivers(), get_animal_projects(), get_animals(), get_cpod_projects(), get_package()

Examples

# Get all tags
get_tags()

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

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

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

Description

List all available acoustic project codes

Usage

list_acoustic_project_codes(connection)

Arguments

Value

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

See Also

Other list functions: list_acoustic_tag_ids(), list_animal_ids(), list_animal_project_codes(), list_cpod_project_codes(), list_deployment_ids(), list_receiver_ids(), list_scientific_names(), list_station_names(), list_tag_serial_numbers(), list_values()

Examples

list_acoustic_project_codes()

Description

List all available acoustic tag ids

Usage

list_acoustic_tag_ids(connection)

Arguments

Value

A vector of all unique acoustic_tag_id values that are available.

See Also

Other list functions: list_acoustic_project_codes(), list_animal_ids(), list_animal_project_codes(), list_cpod_project_codes(), list_deployment_ids(), list_receiver_ids(), list_scientific_names(), list_station_names(), list_tag_serial_numbers(), list_values()

Examples

list_acoustic_tag_ids()

Description

List all available animal ids

Usage

list_animal_ids(connection)

Arguments

Value

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

See Also

Other list functions: list_acoustic_project_codes(), list_acoustic_tag_ids(), list_animal_project_codes(), list_cpod_project_codes(), list_deployment_ids(), list_receiver_ids(), list_scientific_names(), list_station_names(), list_tag_serial_numbers(), list_values()

Examples

list_animal_ids()

Description

List all available animal project codes

Usage

list_animal_project_codes(connection)

Arguments

Value

A vector of all unique project_code of type = "animal" that are available.

See Also

Other list functions: list_acoustic_project_codes(), list_acoustic_tag_ids(), list_animal_ids(), list_cpod_project_codes(), list_deployment_ids(), list_receiver_ids(), list_scientific_names(), list_station_names(), list_tag_serial_numbers(), list_values()

Examples

list_animal_project_codes()

Description

List all available cpod project codes

Usage

list_cpod_project_codes(connection)

Arguments

Value

A vector of all unique project_code of type = "cpod" that are available.

See Also

Other list functions: list_acoustic_project_codes(), list_acoustic_tag_ids(), list_animal_ids(), list_animal_project_codes(), list_deployment_ids(), list_receiver_ids(), list_scientific_names(), list_station_names(), list_tag_serial_numbers(), list_values()

Examples

list_cpod_project_codes()

Description

List all available receiver ids

Usage

list_deployment_ids(connection)

Arguments

Value

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

See Also

Other list functions: list_acoustic_project_codes(), list_acoustic_tag_ids(), list_animal_ids(), list_animal_project_codes(), list_cpod_project_codes(), list_receiver_ids(), list_scientific_names(), list_station_names(), list_tag_serial_numbers(), list_values()

Examples

list_deployment_ids()

Description

List all available receiver ids

Usage

list_receiver_ids(connection)

Arguments

Value

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

See Also

Other list functions: list_acoustic_project_codes(), list_acoustic_tag_ids(), list_animal_ids(), list_animal_project_codes(), list_cpod_project_codes(), list_deployment_ids(), list_scientific_names(), list_station_names(), list_tag_serial_numbers(), list_values()

Examples

list_receiver_ids()

Description

List all available scientific names

Usage

list_scientific_names(connection)

Arguments

Value

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

See Also

Other list functions: list_acoustic_project_codes(), list_acoustic_tag_ids(), list_animal_ids(), list_animal_project_codes(), list_cpod_project_codes(), list_deployment_ids(), list_receiver_ids(), list_station_names(), list_tag_serial_numbers(), list_values()

Examples

list_scientific_names()

Description

List all available station names

Usage

list_station_names(connection)

Arguments

Value

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

See Also

Other list functions: list_acoustic_project_codes(), list_acoustic_tag_ids(), list_animal_ids(), list_animal_project_codes(), list_cpod_project_codes(), list_deployment_ids(), list_receiver_ids(), list_scientific_names(), list_tag_serial_numbers(), list_values()

Examples

list_station_names()

Description

List all available tag serial numbers

Usage

list_tag_serial_numbers(connection)

Arguments

Value

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

See Also

Other list functions: list_acoustic_project_codes(), list_acoustic_tag_ids(), list_animal_ids(), list_animal_project_codes(), list_cpod_project_codes(), list_deployment_ids(), list_receiver_ids(), list_scientific_names(), list_station_names(), list_values()

Examples

list_tag_serial_numbers()

Description

Get a vector with all unique values found in a given column of a data.frame. Concatenated values (⁠A,B⁠) in the column can be returned as single values (A and B).

Usage

list_values(.data, column, split = ",")

Arguments

Value

A vector of the same type as the given column.

See Also

Other list functions: list_acoustic_project_codes(), list_acoustic_tag_ids(), list_animal_ids(), list_animal_project_codes(), list_cpod_project_codes(), list_deployment_ids(), list_receiver_ids(), list_scientific_names(), list_station_names(), list_tag_serial_numbers()

Examples

# List unique scientific_name from a dataframe containing animal information
df <- get_animals(animal_project_code = "2014_demer")
list_values(df, "scientific_name")

# Or using pipe and unquoted column name
df |> list_values(scientific_name)

# Or using column position
df |> list_values(8)

# tag_serial_number can contain comma-separated values
df <- get_animals(animal_id = 5841)
df$tag_serial_number

# list_values() will split those and return unique values
list_values(df, tag_serial_number)

# Another expression can be defined to split values (here ".")
list_values(df, tag_serial_number, split = "\\.")

Description

Read a Data Package descriptor file (datapackage.json)

Usage

read_package(file = "datapackage.json")

Arguments

See Also

Other frictionless functions: read_resource(), write_package()

Description

Read data from a Data Resource into a tibble data frame

Usage

read_resource(package, resource_name, col_select = NULL)

Arguments

See Also

Other frictionless functions: read_package(), write_package()

Description

Transforms a Data Package with European Tracking Network (ETN) data to a Darwin Core Archive.

Usage

write_dwc(
  package,
  directory,
  dataset_id = package$id,
  dataset_name = NULL,
  license = c("CC-BY-4.0", "CC0-1.0"),
  rights_holder = NULL
)

Arguments

Details

The resulting files can be uploaded to an IPT for publication to GBIF and/or OBIS. A corresponding eml.xml metadata file is not created.

Value

CSV and meta.xml files written to disk. And invisibly, a list of data frames with the transformed data.

Transformation details

This function follows recommendations discussed and created by Peter Desmet, Jonas Mortelmans, Jonathan Pye, John Wieczorek and others and transforms data to:

• An Occurrence core.

• An Extended Measurement Or Facts extension

• A meta.xml file.

Key features of the Darwin Core transformation:

• Deployments (animal+tag associations) are parent events, with capture, surgery, release, recapture (human observations) and acoustic detections (machine observations) as child events. No information about the parent event is provided other than its ID, meaning that data can be expressed in an Occurrence Core with one row per observation and parentEventID shared by all occurrences in a deployment.

• The release event often contains metadata about the animal (sex, life stage, comments) and deployment as a whole. Sex, life stage and weight are (additionally) provided in an Extended Measurement Or Facts extension, where values are mapped to a controlled vocabulary recommended by OBIS.

• Acoustic detections are downsampled to the first detection per hour, to reduce the size of high-frequency data. The coordinateUncertaintyInMeters is set to 1000 m to account for imprecise receiver location and acoustic detection range. Duplicate detections (same animal, tag and timestamp) are excluded. It is possible for a deployment to contain no detections, e.g. if the tag malfunctioned right after deployment.

• Parameters or metadata are used to set the following record-level terms:

  • dwc:datasetID: dataset_id, defaulting to package$id.

  • dwc:datasetName: dataset_name.

  • dcterms:license: license.

  • dcterms:rightsHolder: rights_holder.

Examples

package <- example_dataset()
write_dwc(
  package,
  directory = "my_directory",
  dataset_name = paste(
    "2014_DEMER - Acoustic telemetry data for four fish species in the",
    "Demer river (Belgium)"
  ),
  license = "CC0-1.0",
  rights_holder = "INBO"
)

# Clean up (don't do this if you want to keep your files)
unlink("my_directory", recursive = TRUE)

Description

Write a Data Package to disk

Usage

write_package(package, directory, compress = FALSE)

Arguments

See Also

Other frictionless functions: read_package(), read_resource()