library(move2)
The credentials of the user are stored using the keyring
package. With the following command a user can be added to the keyring. Run this line once, it will store your credentials in keyring. After that every time you load move2
and execute a download function from movebank, these functions will retrieve your credentials from keyring.
movebank_store_credentials("myUserName", "myPassword")
movebank_remove_credentials()
#> There is 1 key removed from the keyring.
The keyring
package can use several mechanisms to store credentials, these are called backends. Some of these backends are operating system dependent, others are more general. Some of the operating systems dependent backends have the advantage that they do not require providing credentials when opening a new R session.
The move2
package uses the default backend as is returned by keyring::default_backend()
, this function thus shows the backend move2
is using. If you want to change the default you can use the keyring_backend
option, for more details see the documentation in the keyring package.
macOS and Windows generally do not require entering an extra password for keyring. The default in Linux is often the file
backend which can be confusing as it creates an encrypted file with credentials that need a password to unlock. In this case a separate password for the keyring file has to be entered for each new R session before the movebank password can be accessed. To avoid having to enter each time a keyring password the Secret Service API can be used by installing the libsecret
library. (Debian/Ubuntu: libsecret-1-dev
; Recent RedHat, Fedora and CentOS systems: libsecret-devel
)
key_name
If you have multiple user accounts on movebank, the easiest way is to give each of them a key name with the argument key_name
. For the most used account also the default option can be used. The movebank_store_credentials()
only has to be executed once for each account. After that the credentials will be retrieved from keyring.
## store credentials for the most used account.
movebank_store_credentials("myUserName", "myPassword")
## store credentials for another movebank account
movebank_store_credentials("myUserName_2", "myPassword_2", key_name = "myOtherAccount")
When you want to download from Movebank using your default movebank account, nothing has to be specified before the download functions. If you want to download from Movebank with another account, than you should execute the line below, specifying the key name of the account to use, before the download functions are executed.
options("move2_movebank_key_name" = "myOtherAccount")
If in one script/Rsession you are using several accounts, to use the credentials of the default account execute the line below:
options("move2_movebank_key_name" = "movebank")
To check which accounts are stored in keyring:
::key_list()
keyring# service username
# 1 movebank myUserName
# 2 myOtherAccount myUserName_2
The service
column corresponds to the names provided in key_name
. The account entered without a key name (the default) will be called movebank
. Note that the key names have to be unique, if there are several usernames with the same key name (service), it will cause an error.
To deleted credentials from keyring:
## for the default account
movebank_remove_credentials()
#> There is 1 key removed from the keyring.
## for an account with a key name
movebank_remove_credentials(key_name = "myOtherAccount")
#> There is 1 key removed from the keyring.
Next we can check if the keys are successfully removed:
::key_list() keyring
library(dplyr, quietly = TRUE)
Using the movebank_retrieve
function it is possible to directly access the API, here all studies with a creative commons 0 license are returned. These are a good candidate for exploration and testing
movebank_retrieve(entity_type = "study", license_type = "CC_0") |>
select(id, name, number_of_deployed_locations) |>
filter(!is.na(number_of_deployed_locations))
#> # A tibble: 286 × 3
#> id name number_of_deployed_l…¹
#> <int64> <fct> [count]
#> 1 1169957016 spectacledEider_USGS_ASC_argos 61299
#> 2 1199929756 Spatial ecology of urban copperheads 2031
#> 3 1605798640 O_BALGZAND - Eurasian oystercatchers (Haem… 165891
#> 4 1605803389 O_AMELAND - Eurasian oystercatchers (Haema… 216108
#> 5 1605797471 O_ASSEN - Eurasian oystercatchers (Haemato… 20152
#> 6 1605799506 O_SCHIERMONNIKOOG - Eurasian oystercatcher… 602380
#> 7 1605802367 O_VLIELAND - Eurasian oystercatchers (Haem… 4908942
#> 8 294524920 Black Kites at the Strait of Gibraltar (da… 77228
#> 9 1402467516 Black kites of different age and sex show … 231193
#> 10 7249090 Peregrine Falcon, High Arctic Institute, n… 3004
#> # ℹ 276 more rows
#> # ℹ abbreviated name: ¹number_of_deployed_locations
A more quick way to retrieve the information is the following (the selection is performed on movebank and not all data is downloaded):
movebank_download_study_info(license_type = "CC_0")
By default all attributes are downloaded:
movebank_download_study(2911040, sensor_type_id = "gps")
#> A <move2> object containing 28 tracks consisting of:
#> Simple feature collection with 16414 features and 18 fields (with 386 geometries empty)
#> Geometry type: POINT
#> Dimension: XY
#> Bounding box: xmin: -91.3732 ymin: -12.79464 xmax: -77.51874 ymax: 0.1821983
#> Geodetic CRS: WGS 84
#> # A tibble: 16,414 × 19
#> sensor_type_id individual_local_identifier eobs_battery_voltage
#> <int64> <fct> [mV]
#> 1 653 4264-84830852 3686
#> 2 653 4264-84830852 3701
#> 3 653 4264-84830852 3701
#> 4 653 4264-84830852 3691
#> 5 653 4264-84830852 3691
#> # ℹ 16,409 more rows
#> # ℹ 16 more variables: eobs_fix_battery_voltage [mV],
#> # eobs_horizontal_accuracy_estimate [m], eobs_key_bin_checksum <int64>,
#> # eobs_speed_accuracy_estimate [m/s], eobs_start_timestamp <dttm>,
#> # eobs_status <ord>, eobs_temperature [°C], eobs_type_of_fix <fct>,
#> # eobs_used_time_to_get_fix [s], ground_speed [m/s], heading [°],
#> # height_above_ellipsoid [m], timestamp <dttm>, visible <lgl>, …
#> First 5 track features:
#> # A tibble: 28 × 52
#> deployment_id tag_id individual_id animal_life_stage attachment_type
#> <int64> <int64> <int64> <fct> <fct>
#> 1 2911170 2911124 2911090 adult tape
#> 2 2911150 2911126 2911091 adult tape
#> 3 2911167 2911127 2911092 adult tape
#> 4 2911168 2911129 2911093 adult tape
#> 5 2911178 2911132 2911094 adult tape
#> # ℹ 23 more rows
#> # ℹ 47 more variables: deployment_comments <chr>, deploy_on_timestamp <dttm>,
#> # duty_cycle <chr>, deployment_local_identifier <fct>,
#> # manipulation_type <fct>, study_site <chr>, tag_readout_method <fct>,
#> # sensor_type_ids <chr>, capture_location <POINT [°]>,
#> # deploy_on_location <POINT [°]>, deploy_off_location <POINT [°]>,
#> # individual_comments <chr>, individual_local_identifier <fct>, …
For speed of download you might want to add the argument attributes = NULL
as it reduces the columns to download to the bare minimum. Note still all individual attributes are downloaded as this does not take much time.
movebank_download_study(1259686571, sensor_type_id = "gps", attributes = NULL)
#> ℹ In total 280266 records were omitted as they were not deployed (the
#> `deployment_id` was `NA`).
#> A <move2> object containing 91 tracks consisting of:
#> Simple feature collection with 724489 features and 2 fields
#> Geometry type: POINT
#> Dimension: XY
#> Bounding box: xmin: -9.097052 ymin: 34.82506 xmax: 10.34339 ymax: 52.64934
#> Geodetic CRS: WGS 84
#> # A tibble: 724,489 × 3
#> deployment_id timestamp geometry
#> <int64> <dttm> <POINT [°]>
#> 1 2362121740 2020-07-10 18:03:10 (3.173287 51.34489)
#> 2 2362121740 2020-07-10 18:23:35 (3.173358 51.3447)
#> 3 2362121740 2020-07-10 18:43:11 (3.173287 51.34484)
#> 4 2362121740 2020-07-10 19:03:15 (3.173215 51.34494)
#> 5 2362121740 2020-07-10 19:23:35 (3.17341 51.3448)
#> # ℹ 724,484 more rows
#> First 5 track features:
#> # A tibble: 91 × 56
#> deployment_id tag_id individual_id alt_project_id animal_life_stage
#> <int64> <int64> <int64> <fct> <fct>
#> 1 2290929058 1266480715 1267592251 LBBG_JUVENILE juvenile
#> 2 2362121575 1266480370 1267592250 LBBG_JUVENILE juvenile
#> 3 1480807803 1266480978 1267592246 LBBG_JUVENILE juvenile
#> 4 2362121690 1260704800 1267592247 LBBG_JUVENILE juvenile
#> 5 2362121491 1266480586 1267592248 LBBG_JUVENILE juvenile
#> # ℹ 86 more rows
#> # ℹ 51 more variables: animal_mass [g], attachment_type <fct>,
#> # deployment_comments <chr>, deploy_off_timestamp <dttm>,
#> # deploy_on_timestamp <dttm>, deployment_end_type <fct>,
#> # manipulation_type <fct>, study_site <chr>, tag_readout_method <fct>,
#> # sensor_type_ids <chr>, capture_location <POINT [°]>,
#> # deploy_on_location <POINT [°]>, deploy_off_location <POINT [°]>, …
If only specific attributes want to be download you can state them in the argument attributes
. The available attributes vary between studies and sensors. You can retrieve the list of available attributes for a specific sensor in given study. Note that only one sensor at a time can be stated.
movebank_retrieve(
entity_type = "study_attribute",
study_id = 2911040,
sensor_type_id = "gps"
$short_name
)#> [1] "eobs_battery_voltage" "eobs_fix_battery_voltage"
#> [3] "eobs_horizontal_accuracy_estimate" "eobs_key_bin_checksum"
#> [5] "eobs_speed_accuracy_estimate" "eobs_start_timestamp"
#> [7] "eobs_status" "eobs_temperature"
#> [9] "eobs_type_of_fix" "eobs_used_time_to_get_fix"
#> [11] "ground_speed" "heading"
#> [13] "height_above_ellipsoid" "location_lat"
#> [15] "location_long" "timestamp"
#> [17] "update_ts" "visible"
movebank_download_study(
study_id = 2911040,
sensor_type_id = "gps",
attributes = c(
"height_above_ellipsoid",
"eobs_temperature"
)
)#> A <move2> object containing 28 tracks consisting of:
#> Simple feature collection with 16414 features and 4 fields (with 386 geometries empty)
#> Geometry type: POINT
#> Dimension: XY
#> Bounding box: xmin: -91.3732 ymin: -12.79464 xmax: -77.51874 ymax: 0.1821983
#> Geodetic CRS: WGS 84
#> # A tibble: 16,414 × 5
#> height_above_ellipsoid eobs_temperature deployment_id timestamp
#> [m] [°C] <int64> <dttm>
#> 1 16.5 12 9472219 2008-05-31 13:30:02
#> 2 12.6 19 9472219 2008-05-31 15:00:44
#> 3 17.4 24 9472219 2008-05-31 16:30:39
#> 4 24.8 18 9472219 2008-05-31 18:00:49
#> 5 19 22 9472219 2008-05-31 19:30:18
#> # ℹ 16,409 more rows
#> # ℹ 1 more variable: geometry <POINT [°]>
#> First 5 track features:
#> # A tibble: 28 × 52
#> deployment_id tag_id individual_id animal_life_stage attachment_type
#> <int64> <int64> <int64> <fct> <fct>
#> 1 2911170 2911124 2911090 adult tape
#> 2 2911150 2911126 2911091 adult tape
#> 3 2911167 2911127 2911092 adult tape
#> 4 2911168 2911129 2911093 adult tape
#> 5 2911178 2911132 2911094 adult tape
#> # ℹ 23 more rows
#> # ℹ 47 more variables: deployment_comments <chr>, deploy_on_timestamp <dttm>,
#> # duty_cycle <chr>, deployment_local_identifier <fct>,
#> # manipulation_type <fct>, study_site <chr>, tag_readout_method <fct>,
#> # sensor_type_ids <chr>, capture_location <POINT [°]>,
#> # deploy_on_location <POINT [°]>, deploy_off_location <POINT [°]>,
#> # individual_comments <chr>, individual_local_identifier <fct>, …
Only load gps records:
movebank_download_study(1259686571, sensor_type_id = 653)
#> ℹ In total 280266 records were omitted as they were not deployed (the
#> `deployment_id` was `NA`).
#> A <move2> object containing 91 tracks consisting of:
#> Simple feature collection with 724489 features and 25 fields
#> Geometry type: POINT
#> Dimension: XY
#> Bounding box: xmin: -9.097052 ymin: 34.82506 xmax: 10.34339 ymax: 52.64934
#> Geodetic CRS: WGS 84
#> # A tibble: 724,489 × 26
#> sensor_type_id individual_local_identi…¹ acceleration_raw_x acceleration_raw_y
#> <int64> <fct> <dbl> <dbl>
#> 1 653 L930055 228 315
#> 2 653 L930055 -127 177
#> 3 653 L930055 61 -169
#> 4 653 L930055 64 216
#> 5 653 L930055 116 227
#> # ℹ 724,484 more rows
#> # ℹ abbreviated name: ¹individual_local_identifier
#> # ℹ 22 more variables: acceleration_raw_z <dbl>, barometric_height [m],
#> # battery_charge_percent [%], battery_charging_current [mA],
#> # external_temperature [°C], gps_hdop [1], gps_satellite_count [count],
#> # gps_time_to_fix [s], ground_speed [m/s], heading [°], height_above_msl [m],
#> # import_marked_outlier <lgl>, light_level <dbl>, …
#> First 5 track features:
#> # A tibble: 91 × 56
#> deployment_id tag_id individual_id alt_project_id animal_life_stage
#> <int64> <int64> <int64> <fct> <fct>
#> 1 2290929058 1266480715 1267592251 LBBG_JUVENILE juvenile
#> 2 2362121575 1266480370 1267592250 LBBG_JUVENILE juvenile
#> 3 1480807803 1266480978 1267592246 LBBG_JUVENILE juvenile
#> 4 2362121690 1260704800 1267592247 LBBG_JUVENILE juvenile
#> 5 2362121491 1266480586 1267592248 LBBG_JUVENILE juvenile
#> # ℹ 86 more rows
#> # ℹ 51 more variables: animal_mass [g], attachment_type <fct>,
#> # deployment_comments <chr>, deploy_off_timestamp <dttm>,
#> # deploy_on_timestamp <dttm>, deployment_end_type <fct>,
#> # manipulation_type <fct>, study_site <chr>, tag_readout_method <fct>,
#> # sensor_type_ids <chr>, capture_location <POINT [°]>,
#> # deploy_on_location <POINT [°]>, deploy_off_location <POINT [°]>, …
Note that the sensor_type_id
can either be specified either of an integer
or character
with respectively the id or name of the sensor. In some cases additional data is added is downloaded if a specific sensor is selected. For example the column eobs_acceleration_raw
:
movebank_download_study(2911040, sensor_type_id = "acceleration")
#> Warning in min(cc[[1]], na.rm = TRUE): no non-missing arguments to min;
#> returning Inf
#> Warning in min(cc[[2]], na.rm = TRUE): no non-missing arguments to min;
#> returning Inf
#> Warning in max(cc[[1]], na.rm = TRUE): no non-missing arguments to max;
#> returning -Inf
#> Warning in max(cc[[2]], na.rm = TRUE): no non-missing arguments to max;
#> returning -Inf
#> A <move2> object containing 28 tracks consisting of:
#> Simple feature collection with 98515 features and 10 fields (with 98515 geometries empty)
#> Geometry type: POINT
#> Dimension: XY
#> Bounding box: xmin: NA ymin: NA xmax: NA ymax: NA
#> Geodetic CRS: WGS 84
#> # A tibble: 98,515 × 11
#> sensor_type_id individual_local_identifier eobs_acceleration_axes
#> <int64> <fct> <fct>
#> 1 2365683 4264-84830852 XY
#> 2 2365683 4264-84830852 XY
#> 3 2365683 4264-84830852 XY
#> 4 2365683 4264-84830852 XY
#> 5 2365683 4264-84830852 XY
#> # ℹ 98,510 more rows
#> # ℹ 8 more variables: eobs_acceleration_sampling_frequency_per_axis [Hz],
#> # eobs_accelerations_raw <chr>, eobs_key_bin_checksum <int64>,
#> # eobs_start_timestamp <dttm>, timestamp <dttm>, visible <lgl>,
#> # event_id <int64>, geometry <POINT [°]>
#> First 5 track features:
#> # A tibble: 28 × 52
#> deployment_id tag_id individual_id animal_life_stage attachment_type
#> <int64> <int64> <int64> <fct> <fct>
#> 1 2911170 2911124 2911090 adult tape
#> 2 2911150 2911126 2911091 adult tape
#> 3 2911167 2911127 2911092 adult tape
#> 4 2911168 2911129 2911093 adult tape
#> 5 2911178 2911132 2911094 adult tape
#> # ℹ 23 more rows
#> # ℹ 47 more variables: deployment_comments <chr>, deploy_on_timestamp <dttm>,
#> # duty_cycle <chr>, deployment_local_identifier <fct>,
#> # manipulation_type <fct>, study_site <chr>, tag_readout_method <fct>,
#> # sensor_type_ids <chr>, capture_location <POINT [°]>,
#> # deploy_on_location <POINT [°]>, deploy_off_location <POINT [°]>,
#> # individual_comments <chr>, individual_local_identifier <fct>, …
The following list of sensors is available:
movebank_retrieve(
entity_type = "tag_type",
attributes = c("external_id", "id")
)#> # A tibble: 18 × 2
#> external_id id
#> <chr> <int64>
#> 1 bird-ring 397
#> 2 gps 653
#> 3 radio-transmitter 673
#> 4 argos-doppler-shift 82798
#> 5 natural-mark 2365682
#> 6 acceleration 2365683
#> 7 solar-geolocator 3886361
#> 8 accessory-measurements 7842954
#> 9 solar-geolocator-raw 9301403
#> 10 barometer 77740391
#> 11 magnetometer 77740402
#> 12 orientation 819073350
#> 13 solar-geolocator-twilight 914097241
#> 14 acoustic-telemetry 1239574236
#> 15 gyroscope 1297673380
#> 16 heart-rate 2206221896
#> 17 sigfox-geolocation 2299894820
#> 18 proximity 2645090675
Alternatively more informative names can be used for some arguments. For example you can use a character
string to identify a study or a timestamp as a POSIXct
:
movebank_download_study("LBBG_JUVENILE",
sensor_type_id = "gps",
timestamp_start = as.POSIXct("2021-02-03 00:00:00"),
timestamp_end = as.POSIXct("2021-03-03 00:00:00")
)#> ℹ In total 7001 records were omitted as they were not deployed (the
#> `deployment_id` was `NA`).
#> A <move2> object containing 6 tracks consisting of:
#> Simple feature collection with 8763 features and 25 fields
#> Geometry type: POINT
#> Dimension: XY
#> Bounding box: xmin: -7.169092 ymin: 35.18931 xmax: 3.229445 ymax: 49.06081
#> Geodetic CRS: WGS 84
#> # A tibble: 8,763 × 26
#> sensor_type_id individual_local_identi…¹ acceleration_raw_x acceleration_raw_y
#> <int64> <fct> <dbl> <dbl>
#> 1 653 L930074 313 -18
#> 2 653 L930074 308 -18
#> 3 653 L930074 310 -18
#> 4 653 L930074 314 -17
#> 5 653 L930074 312 -18
#> # ℹ 8,758 more rows
#> # ℹ abbreviated name: ¹individual_local_identifier
#> # ℹ 22 more variables: acceleration_raw_z <dbl>, barometric_height [m],
#> # battery_charge_percent [%], battery_charging_current [mA],
#> # external_temperature [°C], gps_hdop [1], gps_satellite_count [count],
#> # gps_time_to_fix [s], ground_speed [m/s], heading [°], height_above_msl [m],
#> # import_marked_outlier <lgl>, light_level <dbl>, …
#> First 5 track features:
#> # A tibble: 6 × 56
#> deployment_id tag_id individual_id alt_project_id animal_life_stage
#> <int64> <int64> <int64> <fct> <fct>
#> 1 2362121739 1260704751 1266821308 LBBG_JUVENILE juvenile
#> 2 2362121733 1260704817 1266821320 LBBG_JUVENILE juvenile
#> 3 2362121558 1260704811 1266821327 LBBG_JUVENILE juvenile
#> 4 1266821469 1266481002 1266821333 LBBG_JUVENILE juvenile
#> 5 1266821467 1260704940 1266821331 LBBG_JUVENILE juvenile
#> # ℹ 1 more row
#> # ℹ 51 more variables: animal_mass [g], attachment_type <fct>,
#> # deployment_comments <chr>, deploy_off_timestamp <dttm>,
#> # deploy_on_timestamp <dttm>, deployment_end_type <fct>,
#> # manipulation_type <fct>, study_site <chr>, tag_readout_method <fct>,
#> # sensor_type_ids <chr>, capture_location <POINT [°]>,
#> # deploy_on_location <POINT [°]>, deploy_off_location <POINT [°]>, …
If you are interested in the deployment information you can use the movebank_download_deployment
function.
movebank_download_deployment("Galapagos Albatrosses")
#> # A tibble: 28 × 26
#> deployment_id tag_id individual_id animal_life_stage attachment_type
#> <int64> <int64> <int64> <fct> <fct>
#> 1 2911170 2911124 2911090 adult tape
#> 2 2911150 2911126 2911091 adult tape
#> 3 2911167 2911127 2911092 adult tape
#> 4 2911168 2911129 2911093 adult tape
#> 5 2911178 2911132 2911094 adult tape
#> 6 2911163 2911133 2911095 adult tape
#> 7 9472225 2911114 2911061 adult tape
#> 8 9472224 2911120 2911062 adult tape
#> 9 9472223 2911121 2911086 adult tape
#> 10 9472222 2911134 2911065 adult tape
#> # ℹ 18 more rows
#> # ℹ 21 more variables: deployment_comments <chr>, deploy_on_timestamp <dttm>,
#> # duty_cycle <chr>, deployment_local_identifier <fct>,
#> # manipulation_type <fct>, study_site <chr>, tag_readout_method <fct>,
#> # sensor_type_ids <chr>, capture_location <POINT [°]>,
#> # deploy_on_location <POINT [°]>, deploy_off_location <POINT [°]>,
#> # individual_comments <chr>, individual_local_identifier <fct>, …
For specific request it might be useful to directly retrieve information from the movebank api. The movebank_retrieve
function provides this functionality. The first argument is the entity type you would like to retrieve information for (e.g. tag
or event
). Other arguments make it possible to select, a study id is always required. For more details how to use the api see the documentation.
One common reason to use this options is to retrieve undeployed locations. In some cases a set of locations is collected before the tag attached to the animal for quality control or error measurements. The example below shows how all records for a specific tag can be retrieved. Filtering for locations where the deployment_id
is NA
, returns those locations that were collected while the tag was not deployed. The timestamp_start
and timestamp_end
might be good argument to filter down the data even more in the call to movebank_retrieve
.
movebank_retrieve("event",
study_id = 1259686571,
tag_local_identifier = "193967", attributes = "all"
%>%
) filter(is.na(deployment_id))
#> # A tibble: 57 × 33
#> individual_id deployment_id tag_id study_id sensor_type_id
#> <int64> <int64> <int64> <int64> <int64>
#> 1 NA NA 1266480679 1259686571 653
#> 2 NA NA 1266480679 1259686571 653
#> 3 NA NA 1266480679 1259686571 653
#> 4 NA NA 1266480679 1259686571 653
#> 5 NA NA 1266480679 1259686571 653
#> 6 NA NA 1266480679 1259686571 653
#> 7 NA NA 1266480679 1259686571 653
#> 8 NA NA 1266480679 1259686571 653
#> 9 NA NA 1266480679 1259686571 653
#> 10 NA NA 1266480679 1259686571 653
#> # ℹ 47 more rows
#> # ℹ 28 more variables: individual_local_identifier <fct>,
#> # tag_local_identifier <fct>, individual_taxon_canonical_name <fct>,
#> # acceleration_raw_x <dbl>, acceleration_raw_y <dbl>,
#> # acceleration_raw_z <dbl>, barometric_height [m],
#> # battery_charge_percent [%], battery_charging_current [mA],
#> # external_temperature [°C], gps_hdop [1], gps_satellite_count [count], …