Skip to contents

Example script

introduction.Rmd

Setup

Loading the library:

There are a few things that need to be set before the functions can be used.

It is important that we can monitor changes made and the reasoning behind them. This package uses the logger package for logging. This will print messages to the console and write them to a file.

By default the logging level is set to INFO. You can also set the scripts to be more verbose by changing the log threshold:

log_threshold (TRACE)

For more information about different logger levels see log_levels.

You also need to point the package to where the seatrack directory is placed in your file system. This variable will be used by many functions contained in this package.

path_to_seatrack <- file.path("a_filepath","SEATRACK - shared")
set_sea_track_folder(path_to_seatrack)
#> INFO [2025-10-08 07:34:38] Sea track folder set to: .
#> INFO [2025-10-08 07:34:38] Sea track folder set to: a_filepath/SEATRACK - shared

Loading data

Once this is set up you can open a partner metadata file. Note that the files shown in this vignette are missing a number of columns present in the real files.

partner_data <- load_partner_metadata("Metadata_SEATRACK_2025-TestColony.xlsx")

This loads the Excel file into R as a list, where each element of the list is different sheet of the Excel file.

names(partner_data)
#> [1] "ENCOUNTER DATA" "LOGGER RETURNS" "RESTART TIMES"
head(partner_data$`LOGGER RETURNS`)
#> # A tibble: 1 × 6
#>   logger_id status     `download / stop_date` `downloaded by` comment        
#>   <chr>     <chr>      <date>                 <chr>           <chr>          
#> 1 L1        Downloaded 2025-01-10             User            Logger returned
#> # ℹ 1 more variable: `stored or sent to?` <chr>

You can then load the master file that you wish to update. This can be done by using the colony name.

master_import <- load_master_import("TestColony")
#> SUCCESS [2025-10-08 07:34:38] Master import file for colony 'TestColony' found at: a_filepath/SEATRACK - shared/Database/Imports_Metadata/imports_TestColony_2025.xlsx

The function returns a list with two elements, data and path. path is the full file path of the loaded. data is a list, where each element is a sheet from the imported master file

names(master_import$data)
#> [1] "METADATA"         "STARTUP_SHUTDOWN"
head(master_import$data$METADATA)
#> # A tibble: 1 × 6
#>   date       ring_number logger_id_deployed logger_id_retrieved colony   comment
#>   <date>     <chr>       <chr>              <lgl>               <chr>    <chr>  
#> 1 2024-01-10 42          L1                 NA                  TestCol… A smal…

Optionally, you can also load or initialise some sheets of nonresponsive loggers. This function takes a vector of file paths and a vector of manufacturers.

nonresponsive_list <- load_nonresponsive(c("lotek_sheet.xlsx", "migrate_sheet.xlsx"), c("Lotek", "MigrateTech"))

Workflow

There are several steps to updating the master import sheet. Firstly checking startup files for missing logger sessions.

master_import_data <- master_import$data
updated_startup <- add_loggers_from_startup(master_import_data$`STARTUP_SHUTDOWN`)

Then appending reported encounter data.

updated_metadata <- append_encounter_data(master_import_data$METADATA, partner_data$`ENCOUNTER DATA`)
#> SUCCESS [2025-10-08 07:34:38] Appended 1 rows to master metadata. New total is 2 rows.

Finally the processing reported logger returns and attempts to update the appropriate session in the master startup sheet, setting download status and dates.

This function also handles loggers that the partner restearts, generating new sessions for them in the master startup sheet.

The function will also update the nonresponsive lists.

updated_sessions <- handle_returned_loggers("TestColony", updated_startup, partner_data$`LOGGER RETURNS`, partner_data$`RESTART TIMES`, nonresponsive_list)
#> SUCCESS [2025-10-08 07:34:38] Found unfinished session for logger ID: L1 2025-01-10
#> SUCCESS [2025-10-08 07:34:38] Unfinished session:
#>   logger_serial_no starttime_gmt intended_species intended_location
#> 1 L1               2024-01-01    bird             TestColony       
#> SUCCESS [2025-10-08 07:34:39] Updated 1 sessions.
#> SUCCESS [2025-10-08 07:34:39] Updated sessions:
#>   logger_serial_no starttime_gmt download_type download_date
#> 1 L1               2024-01-01    Downloaded    2025-01-10

At every stage, the log will report the changes that the functions have made to the master sheet. The log will also report when it is unable to handle some part of the partner supplied metadata. This can help identify areas that need manually fixing in either the partner metadata sheet or the master sheet.

Combined workflow

This workflow can be run using a single function, handle_partner_metadata that takes the colony name and the imported excel files as arguments.

new_sheets <- handle_partner_metadata("TestColony", partner_data, master_import_data)
#> INFO [2025-10-08 07:34:39] Add missing sessions from start up files
#> INFO [2025-10-08 07:34:39] Append encounter data
#> SUCCESS [2025-10-08 07:34:39] Appended 1 rows to master metadata. New total is 2 rows.
#> INFO [2025-10-08 07:34:39] Update sessions from logger returns
#> SUCCESS [2025-10-08 07:34:39] Found unfinished session for logger ID: L1 2025-01-10
#> SUCCESS [2025-10-08 07:34:39] Unfinished session:
#>   logger_serial_no starttime_gmt intended_species intended_location
#> 1 L1               2024-01-01    bird             TestColony       
#> SUCCESS [2025-10-08 07:34:39] Updated 1 sessions.
#> SUCCESS [2025-10-08 07:34:39] Updated sessions:
#>   logger_serial_no starttime_gmt download_type download_date
#> 1 L1               2024-01-01    Downloaded    2025-01-10
new_master_sheets <- new_sheets$master_sheet
new_nonresponsive_list <- new_sheets$nonresponsive_list

Finally, if you are happy with the changes made, you can save the updated master sheet.

save_master_sheet(new_master_sheets, master_import$path)

And the new/modified nonresponsive sheets.

save_nonresponsive(paths, new_nonresponsive_list)