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.
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_nameIf 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.
If in one script/Rsession you are using several accounts, to use the credentials of the default account execute the line below:
To check which accounts are stored in keyring:
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:
Here you can check if the movebank service is
successfully removed.
Using the function movebank_download_study_info it is
possible to download information for all studies, for all studies that
have certain property or for a single study. Any column of the table can
be used to download only the information of the studies that comply with
the selected property. This table contains all the information that can
be seen on the “Study page” on the Movebank webpage, plus additional
information about download rights and ownership.
NOTE: due to incorrect timestamps in some Movebank studies, the
function movebank_download_study_info() sometimes returns a
Warning message as the one in the example below. You can ignore
this (see issue #17).
movebank_download_study_info()
#> Warning: `vroom()` finds reading problems with the movebank specification.
#> ℹ This might relate to the returned data not fitting the expectation of the
#> movebank data format specified in the package.
#> ℹ For retrieving the specific problem you can enable `global_entrace` using
#> `rlang::global_entrace()` then run the command and use
#> `rlang::last_warnings()[[1]]$problems` to retrieve the problems.
#> ℹ The requested url can then be retrieved with: `rlang::last_warnings()[[1]]$url`
#> ℹ Alternatively in some cases you might be able to retrieve the problems calling
#> `vroom::problems()` on the result of the function call that produced the warning.
#> # A tibble: 7,425 × 31
#> acknowledgements citation go_public_date grants_used has_quota i_am_owner
#> <chr> <chr> <dttm> <chr> <lgl> <lgl>
#> 1 <NA> <NA> NA <NA> TRUE FALSE
#> 2 <NA> <NA> NA <NA> TRUE FALSE
#> 3 "Supported by the … <NA> NA <NA> TRUE FALSE
#> 4 <NA> <NA> NA <NA> TRUE FALSE
#> 5 "Graduate students… MCKINNO… NA "Natural Scienc… TRUE FALSE
#> 6 <NA> <NA> NA <NA> TRUE FALSE
#> 7 "Universidad Estat… <NA> NA "Comisión Feder… TRUE FALSE
#> 8 <NA> <NA> NA <NA> TRUE FALSE
#> 9 <NA> <NA> NA <NA> TRUE FALSE
#> 10 <NA> <NA> NA <NA> TRUE FALSE
#> # ℹ 7,415 more rows
#> # ℹ 25 more variables: id <int64>, is_test <lgl>, license_terms <chr>,
#> # license_type <fct>, name <fct>, …The function movebank_download_deployment downloads a
table with the associated information to individuals, tags and
deployments. This table reassembles the “Reference Data” table that can
be downloaded from the Movebank webpage.
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>, …With the function movebank_download_study the complete
study from Movebank can be downloaded. There are many options to
download a subset of the complete study. The study_id can
either be specified either as an integer or
character with respectively the id or name of the
study.
To get the study ID of a Movebank study use
movebank_get_study_id
movebank_download_study_info(study_id = 2911040)$sensor_type_ids
#> [1] "GPS,Acceleration"
movebank_download_study(
study_id = 2911040,
sensor_type_id = c("gps", "acceleration")
)
#> A <move2> with `track_id_column` "individual_local_identifier" and `time_column`
#> "timestamp"
#> Containing 28 tracks lasting on average 37.1 days in a
#> Simple feature collection with 114929 features and 21 fields (with 98901 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: 114,929 × 22
#> sensor_type_id individual_local_iden…¹ eobs_battery_voltage eobs_fix_battery_vol…²
#> <int64> <fct> [mV] [mV]
#> 1 653 4264-84830852 3686 3437
#> 2 653 4264-84830852 3701 3452
#> 3 653 4264-84830852 3701 3482
#> 4 653 4264-84830852 3691 3476
#> 5 653 4264-84830852 3691 3541
#> # ℹ 114,924 more rows
#> # ℹ abbreviated names: ¹individual_local_identifier, ²eobs_fix_battery_voltage
#> # ℹ 18 more variables: eobs_horizontal_accuracy_estimate [m],
#> # eobs_key_bin_checksum <int64>, eobs_speed_accuracy_estimate [m/s],
#> # eobs_start_timestamp <dttm>, eobs_status <ord>, …
#> 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>, …movebank_download_study(
study_id = "Galapagos Albatrosses",
sensor_type_id = "gps",
individual_local_identifier = "unbanded-160"
)
#> A <move2> with `track_id_column` "individual_local_identifier" and `time_column`
#> "timestamp"
#> Containing 1 track lasting 13.3 days in a
#> Simple feature collection with 213 features and 18 fields (with 4 geometries empty)
#> Geometry type: POINT
#> Dimension: XY
#> Bounding box: xmin: -81.20167 ymin: -1.829105 xmax: -80.93177 ymax: -1.11206
#> Geodetic CRS: WGS 84
#> # A tibble: 213 × 19
#> sensor_type_id individual_local_iden…¹ eobs_battery_voltage eobs_fix_battery_vol…²
#> <int64> <fct> [mV] [mV]
#> 1 653 unbanded-160 3754 3496
#> 2 653 unbanded-160 3701 3530
#> 3 653 unbanded-160 3754 3505
#> 4 653 unbanded-160 3759 3535
#> 5 653 unbanded-160 3732 3515
#> # ℹ 208 more rows
#> # ℹ abbreviated names: ¹individual_local_identifier, ²eobs_fix_battery_voltage
#> # ℹ 15 more variables: eobs_horizontal_accuracy_estimate [m],
#> # eobs_key_bin_checksum <int64>, eobs_speed_accuracy_estimate [m/s],
#> # eobs_start_timestamp <dttm>, eobs_status <ord>, …
#> Track features:
#> # A tibble: 1 × 52
#> deployment_id tag_id individual_id animal_life_stage attachment_type
#> <int64> <int64> <int64> <fct> <fct>
#> 1 2911163 2911133 2911095 adult tape
#> # ℹ 47 more variables: deployment_comments <chr>, deploy_on_timestamp <dttm>,
#> # duty_cycle <chr>, deployment_local_identifier <fct>, manipulation_type <fct>, …movebank_download_study(
study_id = 2911040,
sensor_type_id = "gps",
individual_local_identifier = c("1094-1094", "1103-1103")
)
#> A <move2> with `track_id_column` "individual_local_identifier" and `time_column`
#> "timestamp"
#> Containing 2 tracks lasting on average 10.3 days in a
#> Simple feature collection with 289 features and 18 fields (with 59 geometries empty)
#> Geometry type: POINT
#> Dimension: XY
#> Bounding box: xmin: -89.96382 ymin: -1.502011 xmax: -89.59216 ymax: -0.7981921
#> Geodetic CRS: WGS 84
#> # A tibble: 289 × 19
#> sensor_type_id individual_local_iden…¹ eobs_battery_voltage eobs_fix_battery_vol…²
#> <int64> <fct> [mV] [mV]
#> 1 653 1103-1103 3671 3444
#> 2 653 1103-1103 3615 3437
#> 3 653 1103-1103 3662 3476
#> 4 653 1103-1103 3662 3471
#> 5 653 1103-1103 3662 3452
#> # ℹ 284 more rows
#> # ℹ abbreviated names: ¹individual_local_identifier, ²eobs_fix_battery_voltage
#> # ℹ 15 more variables: eobs_horizontal_accuracy_estimate [m],
#> # eobs_key_bin_checksum <int64>, eobs_speed_accuracy_estimate [m/s],
#> # eobs_start_timestamp <dttm>, eobs_status <ord>, …
#> Track features:
#> # A tibble: 2 × 52
#> deployment_id tag_id individual_id animal_life_stage attachment_type
#> <int64> <int64> <int64> <fct> <fct>
#> 1 9472225 2911114 2911061 adult tape
#> 2 9472212 2911119 2911080 adult tape
#> # ℹ 47 more variables: deployment_comments <chr>, deploy_on_timestamp <dttm>,
#> # duty_cycle <chr>, deployment_local_identifier <fct>, manipulation_type <fct>, …## it is also possible to use the numerical identifiers
movebank_download_study(
study_id = 2911040,
sensor_type_id = "gps",
individual_id = c(2911086, 2911065)
)movebank_download_study(2911040,
sensor_type_id = "acceleration",
individual_local_identifier = "1094-1094"
)
#> A <move2> with `track_id_column` "individual_local_identifier" and `time_column`
#> "timestamp"
#> Containing 1 track lasting 3.05 days in a
#> Simple feature collection with 291 features and 10 fields (with 291 geometries empty)
#> Geometry type: POINT
#> Dimension: XY
#> Bounding box: xmin: NA ymin: NA xmax: NA ymax: NA
#> Geodetic CRS: WGS 84
#> # A tibble: 291 × 11
#> sensor_type_id individual_local_identifier eobs_acceleration_axes
#> <int64> <fct> <fct>
#> 1 2365683 1094-1094 XY
#> 2 2365683 1094-1094 XY
#> 3 2365683 1094-1094 XY
#> 4 2365683 1094-1094 XY
#> 5 2365683 1094-1094 XY
#> # ℹ 286 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>, …
#> Track features:
#> # A tibble: 1 × 52
#> deployment_id tag_id individual_id animal_life_stage attachment_type
#> <int64> <int64> <int64> <fct> <fct>
#> 1 9472212 2911119 2911080 adult tape
#> # ℹ 47 more variables: deployment_comments <chr>, deploy_on_timestamp <dttm>,
#> # duty_cycle <chr>, deployment_local_identifier <fct>, manipulation_type <fct>, …Note that the sensor_type_id can either be specified
either as an integer or character with
respectively the ‘id’ or ‘external_id’ of the sensor. Here is how you
get the correspondence table of sensor name and id:
movebank_retrieve(entity_type = "tag_type")
#> # A tibble: 23 × 5
#> description external_id id is_location_sensor name
#> <chr> <chr> <int64> <lgl> <fct>
#> 1 <NA> bird-ring 397 TRUE Bird Ring
#> 2 <NA> gps 653 TRUE GPS
#> 3 <NA> radio-transmitter 673 TRUE Radio Transmitter
#> 4 <NA> argos-doppler-shift 82798 TRUE Argos Doppler Shi…
#> 5 <NA> natural-mark 2365682 TRUE Natural Mark
#> 6 <NA> acceleration 2365683 FALSE Acceleration
#> 7 <NA> solar-geolocator 3886361 TRUE Solar Geolocator
#> 8 <NA> accessory-measurements 7842954 FALSE Accessory Measure…
#> 9 <NA> solar-geolocator-raw 9301403 FALSE Solar Geolocator …
#> 10 <NA> barometer 77740391 FALSE Barometer
#> # ℹ 13 more rowstimestamp_* arguments can either be formatted as a
POSIXct timestamp, Date or a character string
(e.g. "20080604133046000"(yyyyMMddHHmmssSSS)). The
timestamp_* arguments can also be used separately.movebank_download_study(2911040,
sensor_type_id = "gps",
timestamp_start = as.POSIXct("2008-08-01 00:00:00"),
timestamp_end = as.POSIXct("2008-08-02 00:00:00")
)
#> A <move2> with `track_id_column` "individual_local_identifier" and `time_column`
#> "timestamp"
#> Containing 9 tracks lasting on average 22.5 hours in a
#> Simple feature collection with 144 features and 18 fields (with 6 geometries empty)
#> Geometry type: POINT
#> Dimension: XY
#> Bounding box: xmin: -90.0103 ymin: -5.571548 xmax: -80.94916 ymax: -0.6785461
#> Geodetic CRS: WGS 84
#> # A tibble: 144 × 19
#> sensor_type_id individual_local_iden…¹ eobs_battery_voltage eobs_fix_battery_vol…²
#> <int64> <fct> [mV] [mV]
#> 1 653 4266-84831108 3754 3505
#> 2 653 4266-84831108 3754 3508
#> 3 653 4266-84831108 3754 3576
#> 4 653 4266-84831108 3759 3520
#> 5 653 4266-84831108 3759 3593
#> # ℹ 139 more rows
#> # ℹ abbreviated names: ¹individual_local_identifier, ²eobs_fix_battery_voltage
#> # ℹ 15 more variables: eobs_horizontal_accuracy_estimate [m],
#> # eobs_key_bin_checksum <int64>, eobs_speed_accuracy_estimate [m/s],
#> # eobs_start_timestamp <dttm>, eobs_status <ord>, …
#> First 5 track features:
#> # A tibble: 9 × 52
#> deployment_id tag_id individual_id animal_life_stage attachment_type
#> <int64> <int64> <int64> <fct> <fct>
#> 1 2911150 2911126 2911091 adult tape
#> 2 2911167 2911127 2911092 adult tape
#> 3 2911168 2911129 2911093 adult tape
#> 4 2911178 2911132 2911094 adult tape
#> 5 9472222 2911134 2911065 adult tape
#> # ℹ 4 more rows
#> # ℹ 47 more variables: deployment_comments <chr>, deploy_on_timestamp <dttm>,
#> # duty_cycle <chr>, deployment_local_identifier <fct>, manipulation_type <fct>, …attributes = NULL can be used as it reduces the
columns to download to the bare minimum. All individual attributes are
downloaded as this does not take much time. Note that this option should
only be used when downloading location data (by specifying the sensor),
as only timestamps, location and track id is downloaded.movebank_download_study(1259686571, sensor_type_id = 653, attributes = NULL)
#> ℹ In total 302834 records were omitted as they were not deployed (the
#> `deployment_id` was `NA`).
#> A <move2> with `track_id_column` "deployment_id" and `time_column` "timestamp"
#> Containing 92 tracks lasting on average 163 days in a
#> Simple feature collection with 917018 features and 3 fields
#> Geometry type: POINT
#> Dimension: XY
#> Bounding box: xmin: -9.097052 ymin: 34.82506 xmax: 10.34339 ymax: 53.40649
#> Geodetic CRS: WGS 84
#> # A tibble: 917,018 × 4
#> deployment_id timestamp visible geometry
#> <int64> <dttm> <lgl> <POINT [°]>
#> 1 3029108353 2021-08-19 21:16:35 TRUE (2.84631 51.19662)
#> 2 3029108353 2021-08-20 09:16:35 TRUE (2.846492 51.19654)
#> 3 3029108353 2021-08-20 21:16:29 TRUE (2.847637 51.20317)
#> 4 3029108353 2021-08-21 09:16:35 TRUE (2.849055 51.20314)
#> 5 3029108353 2021-08-21 21:16:35 TRUE (2.846533 51.2034)
#> # ℹ 917,013 more rows
#> First 5 track features:
#> # A tibble: 92 × 56
#> deployment_id tag_id individual_id alt_project_id animal_life_stage animal_mass
#> <int64> <int64> <int64> <fct> <fct> [g]
#> 1 3029108356 3e9 3029107890 LBBG_JUVENILE juvenile 693
#> 2 3029108353 3e9 3029107816 LBBG_JUVENILE juvenile NA
#> 3 3029108347 3e9 3029107819 LBBG_JUVENILE juvenile 883
#> 4 3029108346 3e9 3029107822 LBBG_JUVENILE juvenile 726
#> 5 3029108345 3e9 3029107891 LBBG_JUVENILE juvenile 816
#> # ℹ 87 more rows
#> # ℹ 50 more variables: attachment_type <fct>, deployment_comments <chr>,
#> # deploy_off_timestamp <dttm>, deploy_on_timestamp <dttm>,
#> # deployment_end_type <fct>, …## get all attributes available for a specific study and sensor
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> with `track_id_column` "deployment_id" and `time_column` "timestamp"
#> Containing 28 tracks lasting on average 37.1 days in a
#> Simple feature collection with 16414 features and 5 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 × 6
#> height_above_ellipsoid eobs_temperature deployment_id timestamp visible
#> [m] [°C] <int64> <dttm> <lgl>
#> 1 16.5 12 9472219 2008-05-31 13:30:02 TRUE
#> 2 12.6 19 9472219 2008-05-31 15:00:44 TRUE
#> 3 17.4 24 9472219 2008-05-31 16:30:39 TRUE
#> 4 24.8 18 9472219 2008-05-31 18:00:49 TRUE
#> 5 19 22 9472219 2008-05-31 19:30:18 TRUE
#> # ℹ 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>, …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). A study id is always required and other
arguments make it possible to select. 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. By
omitting the argument tag_local_identifier the entire study
can downloaded. With the argument sensor_type_id the
sensors can be specified.
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 individual_local_ide…¹
#> <int64> <int64> <int6> <int64> <int64> <fct>
#> 1 NA NA 3e9 1e9 653 <NA>
#> 2 NA NA 3e9 1e9 653 <NA>
#> 3 NA NA 3e9 1e9 653 <NA>
#> 4 NA NA 3e9 1e9 653 <NA>
#> 5 NA NA 3e9 1e9 653 <NA>
#> 6 NA NA 3e9 1e9 653 <NA>
#> 7 NA NA 3e9 1e9 653 <NA>
#> 8 NA NA 3e9 1e9 653 <NA>
#> 9 NA NA 3e9 1e9 653 <NA>
#> 10 NA NA 3e9 1e9 653 <NA>
#> # ℹ 47 more rows
#> # ℹ abbreviated name: ¹individual_local_identifier
#> # ℹ 27 more variables: tag_local_identifier <fct>,
#> # individual_taxon_canonical_name <fct>, acceleration_raw_x <dbl>,
#> # acceleration_raw_y <dbl>, acceleration_raw_z <dbl>, …