AlienDetective

Species of maritime fauna all over the world are known to travel great distances accross oceans and seas. The goal of this workflow is to detect these species by calculating sea distances (traveling around land) and geodesic distances (shortest route) from sample locations to the occurrence data gathered from GBIF. This workflow focuses specifically on occurrence data within Europe.

Folder overview

doc/

Contains both source (.Rmd) and rendered (.html) documentation files for the newest versions of AlienDetective.R and functions.R.
Please refer to these documents for detailed explanation of the scripts.

The documentation for the older scripts (1_Calculation_sea_distances.Rmd, 2_Visualisation_distribution and 1_Preparation.Rmd) is also available (as .Rmd only), but is not updated to the scripts.

data/

Contains the input files required for running the main script AlienDetective.R..

Required files:

• Species_Location_NIS.csv: Contains a Specieslist column with the species names. Other columns correspond to sample location names, where 0 means the species is absent and 1 means it is present at that location.
• Coordinates_NIS.csv: Contains sample location names (matching those in Species_location_NIS.csv) along with their latitude and longitude coordinates.

Generated files:

These files are created by the script if they are not already present in the Input folder. Once generated, they are saved in the Input folder for reuse in future runs.

• rasterized_land_polygons.rds: Rasterized world map.
• cost_matrix.rds: Matrix indicating the cost values for land and sea cells.

‼️Important: If any parameters related to generating the above files are changed, please delete the existing files in the Input folder so they can be regenerated with updated parameters.

src/

Contains the newest versions of AlienDetective.R and functions.R:

• AlienDetective.R: Main script for calculating distances and generating output plots.
• functions.R: Helper functions used by AlienDetective.R

⚠️ Warning: Running AlienDetective.R computationally intensive, especially when processing many species or species with large GBIF datasets. Running it on a server is recommended.
See the documentation for explanation how to set up the parallel background.

Besides the above mentioned scripts, are also older scripts available:

• 1.Calculations.R and 1_Calculation_sea_distances_2025.R: Early ( no longer functioning) versions of AlienDetective.R.
• Compile_presence_absence_matrix.R: Prepares presence/absence data in the required format.

output/

Results generated by AlienDetective.R are saved here.
For each species, a folder is created containing:

• CSV files with calculated sea and geodesic distances from GBIF occurrences to sample locations.
• Plots visualising the distribution and distances.

---

Note about map

The map does not include inland freshwater bodies, and the coastline may not be fully accurate. To handle points located inside bays, canals, or near coastlines, coordinates are adjusted to the nearest sea cell when necessary. The adjusted coordinates and the moved distance (km) are saved in the output csv file.
Due to movement limits, points that are located far inland may return NA of Inf for distance values. If such points need to be included, you can increase the maximum radius in the move_to_sea function to suit your needs.