====== move2 (Movebank) ======

These instructions describe how to use the R package **move2** on the HPC cluster:

+ [[#using-move2-on-interactive-sessions | Interactive sessions]]
+ [[#using-move2-on-slurm-batch-jobs | Slurm batch jobs]]

---
===== Using move2 on interactive sessions =====

On this system, credentials are stored **per R session** using the `keyring` *env* backend (expected behaviour on headless nodes).


=== 0. Start an interactive session ===

```
~$ srun -p ceab --pty bash
```


=== 1. Load the R module ===

```
~$ module load R-bundle-CRAN
```

Start R,

```
~$ R
```

=== 2. Check if move2 is installed (install if needed) ===

Check whether move2 is installed:

```
> library(move2)
```

If not installed (typical on HPCs), install it in your user library:

```
> install.packages("move2", repos = "https://cloud.r-project.org")
```

The package will be installed under ~/R/x86_64-pc-linux-gnu-library/.


=== 3. Load package and store Movebank credentials ===

```
> library(move2)

> movebank_store_credentials(<movebank_user_name>)
```

You will be prompted once for your Movebank password.
Credentials remain valid **only for the current R session**.

A warning about the `env` backend may appear. This is expected on this system.


=== 4. Check available studies ===

List all accessible studies:

```
> movebank_download_study_info()
```

List only studies with download access:

```
> movebank_download_study_info(i_have_download_access = TRUE)
```

Query a specific study by ID:

```
> movebank_download_study_info(id = 2911040)
```

=== 5. Suppress backend warning messages (optional) ===

To avoid repeated warnings about the keyring backend:

```
suppressWarnings(
  movebank_download_study_info()
)
```
**This does not affect functionality.**

=== 6. Download tracking data from a study ===

Resolve the study ID if you just know the name:

```
suppressWarnings(
  study_id <- movebank_get_study_id(
    study_id = "Galapagos Albatrosses"
  )
)
```

Then download data with filters:

```
suppressWarnings(
  data <- movebank_download_study(
    study_id,
    sensor_type_id = "gps",
    timestamp_start = as.POSIXct("2008-08-01 00:00:00"),
    timestamp_end   = as.POSIXct("2008-08-02 00:00:00")
  )
)
```

//data// is returned as a //move2// object and can be processed directly with the package’s tools.


=== 7.Notes and limitations ===

+ Credentials are **session-local** (lost on R session exit)
+ No persistent encrypted keyring is available on this system
+ Warning messages about the //env// backend are normal
+ Authentication happens automatically when calling download functions

===== Using move2 on Slurm batch jobs =====

Because the system is headless, //Movebank credentials// must be provided via //environment variables// (**lost on shell session exit**).

**NEVER hard-code passwords in your R scripts !!**

=== 1. Prepare Movebank credentials ===

Before submitting the job, export your credentials in the shell.
 

```
export MOVEBANK_USER="your_movebank_user_name"
export MOVEBANK_PASSWORD="your_movebank_user_password"
```

These variables are inherited by the Slurm job.


=== 2. Write your R script ===

Example: //myRscript.R//

```
library(move2)

# Get credentials from the env vars and store credentials for this Movebank session
movebank_store_credentials(
  Sys.getenv("MOVEBANK_USER"),
  Sys.getenv("MOVEBANK_PASSWORD")
)
# Check available studies
studies <- suppressWarnings(
  movebank_download_study_info(i_have_download_access = TRUE)
)
# show result
print(studies)

```

=== 3. Write your bash script ===

Example: //run_myRscript.sbatch//

```
#!/bin/bash
#SBATCH --job-name=movebank
#SBATCH --time=01:00:00
#SBATCH --mem=4G
#SBATCH --cpus-per-task=1
#SBATCH --output=myRscript_%j.out
#SBATCH --error=myRscript_%j.err

# load R modules
module load R-bundle-CRAN

# launch R script
Rscript myRscript.R
```

=== 4. Submit the job ===

```
srun_-p ceab run_myRscript.sbatch
```

=== 5. Notes specific to batch execution ===

+ Credentials are lost on shell session exit
+ The //keyring env backend// warning is expected
+ Use //suppressWarnings()// to keep logs clean
+ No explicit authentication function necessary
+ Do not use interactive prompts in batch jobs