Type:	Package
Title:	User-Friendly 'shiny' App for Bayesian Species Distribution Models
Version:	1.2.2
Description:	A user-friendly 'shiny' application for Bayesian machine learning analysis of marine species distributions. GLOSSA (Global Ocean Species Spatio-temporal Analysis) uses Bayesian Additive Regression Trees (BART; Chipman, George, and McCulloch (2010) <doi:10.1214/09-AOAS285>) to model species distributions with intuitive workflows for data upload, processing, model fitting, and result visualization. It supports presence-absence and presence-only data (with pseudo-absence generation), spatial thinning, cross-validation, and scenario-based projections. GLOSSA is designed to facilitate ecological research by providing easy-to-use tools for analyzing and visualizing marine species distributions across different spatial and temporal scales.
License:	GPL-3
URL:	https://github.com/iMARES-group/glossa, https://iMARES-group.github.io/glossa/
BugReports:	https://github.com/iMARES-group/glossa/issues
Depends:	bs4Dash, R (≥ 4.1.0), shiny
Imports:	automap, blockCV, dbarts, dplyr, DT, GeoThinneR, ggplot2, htmltools, leaflet, markdown, mcp, pROC, sf, shinyWidgets, sparkline, svglite, terra, tidyterra, waiter, zip
Suggests:	jsonlite, knitr, matrixStats, rmarkdown, testthat (≥ 3.0.0), tidyr, tidyverse
Config/testthat/edition:	3
Encoding:	UTF-8
Language:	en-US
RoxygenNote:	7.3.2
NeedsCompilation:	no
Packaged:	2025-07-15 10:57:36 UTC; jorge
Author:	Jorge Mestre-Tomás [aut, cre], Alba Fuster-Alonso [aut]
Maintainer:	Jorge Mestre-Tomás <jorge.mestre.tomas@csic.es>
Repository:	CRAN
Date/Publication:	2025-07-15 16:00:02 UTC

Enlarge/Buffer a Polygon

Description

This function enlarges a polygon by applying a buffer.

Usage

buffer_polygon(polygon, buffer_distance)

Arguments

Value

An sf object representing the buffered polygon.

Clean Coordinates of Presence/Absence Data

Description

This function cleans coordinates of presence/absence data by removing NA coordinates, rounding coordinates if specified, removing duplicated points, and removing points outside specified spatial polygon boundaries.

Usage

clean_coordinates(
  df,
  study_area,
  overlapping = FALSE,
  thinning_method = NULL,
  thinning_value = NULL,
  coords = c("decimalLongitude", "decimalLatitude"),
  by_timestamp = TRUE,
  seed = NULL
)

Arguments

Details

This function takes a data frame containing presence/absence data with longitude and latitude coordinates, a spatial polygon representing boundaries within which to keep points, and parameters for rounding coordinates and handling duplicated points. It returns a cleaned data frame with valid coordinates within the specified boundaries.

Value

A cleaned data frame containing presence/absence data with valid coordinates.

Continuous Boyce Index (CBI) with weighting

Description

This function is a copy from the 'contBoyce()' function from the 'enmSdm' R package. This function calculates the continuous Boyce index (CBI), a measure of model accuracy for presence-only test data. This version uses multiple, overlapping windows, in contrast to link{contBoyce2x}, which covers each point by at most two windows.

Usage

contBoyce(
  pres,
  contrast,
  presWeight = rep(1, length(pres)),
  contrastWeight = rep(1, length(contrast)),
  numBins = 101,
  binWidth = 0.1,
  autoWindow = TRUE,
  method = "spearman",
  dropZeros = TRUE,
  na.rm = FALSE,
  ...
)

Arguments

Details

CBI is the Spearman rank correlation coefficient between the proportion of sites in each prediction class and the expected proportion of predictions in each prediction class based on the proportion of the landscape that is in that class. The index ranges from -1 to 1. Values >0 indicate the model's output is positively correlated with the true probability of presence. Values <0 indicate it is negatively correlated with the true probability of presence.

Value

Numeric value.

Note

This function is directly copied from the 'enmSdm' package.

References

Boyce, M.S., Vernier, P.R., Nielsen, S.E., and Schmiegelow, F.K.A. 2002. Evaluating resource selection functions. Ecological Modeling 157:281-300. doi:10.1016/S0304-3800(02)00200-4

Hirzel, A.H., Le Lay, G., Helfer, V., Randon, C., and Guisan, A. 2006. Evaluating the ability of habitat suitability models to predict species presences. Ecological Modeling 199:142-152. doi:10.1016/j.ecolmodel.2006.05.017

Create Geographic Coordinate Layers

Description

Generates raster layers for longitude and latitude from given raster data, applies optional scaling, and restricts the output to a specified spatial mask.

Usage

create_coords_layer(layers, study_area = NULL, scale_layers = FALSE)

Arguments

Value

Raster stack with layers lon and lat.

Cross-validation for BART model

Description

This function performs cross-validation for a Bayesian Additive Regression Trees (BART) model using presence-absence data and environmental covariate layers. It calculates various performance metrics for model evaluation.

Usage

cross_validate_model(data, folds, predictor_cols = NULL, seed = NULL)

Arguments

Value

A list with:

metrics

A data frame containing the true positives (TP), false positives (FP), false negatives (FN), true negatives (TN), and various performance metrics including precision (PREC), sensitivity (SEN), specificity (SPC), false discovery rate (FDR), negative predictive value (NPV), false negative rate (FNR), false positive rate (FPR), F-score, accuracy (ACC), balanced accuracy (BA), and true skill statistic (TSS) for each fold.

predictions

Data frame with observed, predicted, probability, and fold assignment per test instance.

Create a Download Action Button

Description

This function generates a download action button that triggers the download of a file when clicked.

Usage

downloadActionButton(
  outputId,
  label = "Download",
  icon = NULL,
  width = NULL,
  status = NULL,
  outline = FALSE,
  ...
)

Arguments

Value

Returns a download action button with the specified parameters.

Evaluation metrics for model predictions

Description

Computes a set of performance metrics (e.g., AUC, TSS, CBI) based on observed and predicted values.

Usage

evaluation_metrics(df, na.rm = TRUE, method = "spearman")

Arguments

Value

A named list or data.frame with evaluation metrics.

Server Logic for Export Plot Functionality

Description

Sets up server-side functionality for exporting plots, including creating a modal dialog for user input on export preferences (height, width, format) and processing the download.

Usage

export_plot_server(id, exported_plot)

Value

No return value, this function is used for its side effects within a Shiny app.

Create UI for Export Plot Button

Description

This function generates a UI element (action button) for exporting plots. The button is styled to be minimalistic, featuring only a download icon.

Usage

export_plot_ui(id)

Value

Returns an actionButton for use in a Shiny UI that triggers plot export modal when clicked.

Extract Non-NA Covariate Values

Description

This function extracts covariate values for species occurrences, excluding NA values.

Usage

extract_noNA_cov_values(data, covariate_layers, predictor_variables)

Arguments

Details

This function extracts covariate values for each species occurrence location from the provided covariate layers. It returns a data frame containing species occurrence data with covariate values, excluding any NA values.

Value

A data frame containing species occurrence data with covariate values, excluding NA values.

Server-side Logic for Custom File Input

Description

Processes the file input from the UI component created by file_input_area_ui and provides access to the uploaded file data.

Usage

file_input_area_server(id)

Value

A reactive expression that returns a data frame containing information about the uploaded files, or NULL if no files have been uploaded.

Custom File Input UI

Description

Creates a customized file input area in a Shiny application. The file input is designed to be visually distinct and supports features such as multiple file selection and file type restrictions.

Usage

file_input_area_ui(
  id,
  label = "Input text: ",
  multiple = FALSE,
  accept = NULL,
  width = NULL,
  button_label = "Browse...",
  icon_name = NULL
)

Value

A Shiny UI object that can be added to a Shiny application.

Fit a BART Model Using Environmental Covariate Layers

Description

This function fits a Bayesian Additive Regression Trees (BART) model using presence/absence data and environmental covariate layers.

Usage

fit_bart_model(y, x, seed = NULL, ...)

Arguments

Value

A BART model object.

Generate cross-validation folds

Description

Creates cross-validation fold assignments for presence-absence or presence-only data, supporting three types of strategies: k-fold, spatial blocks (through blockCV R package), and temporal blocks.

Usage

generate_cv_folds(
  data,
  method = "k-fold",
  block_method = "predictors_autocorrelation",
  block_size = NULL,
  k = 10,
  predictor_raster = NULL,
  model_residuals = NULL,
  coords = c("decimalLongitude", "decimalLatitude")
)

Arguments

Value

A list with the following elements:

folds

A vector of fold assignments (one per row in 'data').

method

The CV method used.

block_method

The spatial block size method (if applicable).

block_size

The estimated or manual block size (in meters), if spatial blocks were used.

Generate Pseudo-Absences Using Buffer-Out Strategy

Description

This function generates pseudo-absences outside a buffer around presence points but within the convex hull of those points. This prevents spatial overlap while preserving geographic realism.

Usage

generate_pa_buffer_out(
  presences,
  raster_stack,
  predictor_variables,
  coords = c("decimalLongitude", "decimalLatitude"),
  pa_buffer_distance = 0.5,
  ratio = 1,
  attempts = 100,
  seed = NULL
)

Arguments

Value

A data frame of pseudo-absences with coordinates, timestamp, 'pa = 0', and covariate values.

Generate Random Pseudo-Absences

Description

This function generates pseudo-absence points randomly across the study area (random background), optionally applying spatial thinning to match presence filtering strategy.

Usage

generate_pa_random(
  presences,
  study_area,
  raster_stack,
  predictor_variables,
  coords = c("decimalLongitude", "decimalLatitude"),
  ratio = 1,
  attempts = 100,
  seed = NULL
)

Arguments

Value

Data frame containing pseudo-absence points with coordinates, timestamp, pa = 0, and covariates.

Generate Pseudo-Absences Using Target-Group Background

Description

Generate Pseudo-Absences Using Target-Group Background

Usage

generate_pa_target_group(
  presences,
  target_group_points,
  study_area,
  raster_stack,
  predictor_variables,
  coords = c("decimalLongitude", "decimalLatitude"),
  ratio = 1,
  attempts = 100,
  seed = NULL
)

Arguments

Value

Data frame containing pseudo-absence points with coordinates, timestamp, pa = 0, and covariates.

Generate Prediction Plot

Description

This function generates a plot based on prediction raster layers and presence/absence points.

Usage

generate_prediction_plot(
  prediction_layer,
  pa_points,
  legend_label,
  non_study_area_mask,
  coords
)

Arguments

Value

Returns a ggplot object representing the world prediction plot.

Generate Pseudo-Absence Points Using Different Methods Based on Presence Points, Covariates, and Study Area Polygon

Description

Wrapper function for pseudo-absence generation methods, such as background random points, target-group, and using buffer area.

Usage

generate_pseudo_absences(
  method = c("random", "target_group", "buffer_out"),
  presences,
  raster_stack,
  predictor_variables,
  study_area = NULL,
  target_group_points = NULL,
  coords = c("decimalLongitude", "decimalLatitude"),
  pa_buffer_distance = 0.5,
  ratio = 1,
  attempts = 100,
  seed = NULL
)

Arguments

Value

A data frame of pseudo-absence points (pa = 0) with covariates.

Compute specificity and sensitivity

Description

Compute specificity and sensitivity

Usage

getFprTpr(actuals, predictedScores, threshold = 0.5)

Arguments

Details

This function was obtained from the InformationValue R package (https://github.com/selva86/InformationValue).

Value

A list with two elements: fpr (false positive rate) and tpr (true positive rate).

Get Covariate Names

Description

This function extracts the names of covariates from a ZIP file containing covariate layers.

Usage

get_covariate_names(file_path)

Arguments

Details

This function extracts the names of covariates from a ZIP file containing covariate layers.

Value

A character vector containing the names of covariates.

Main Analysis Function for GLOSSA Package

Description

This function wraps all the analysis that the GLOSSA package performs. It processes presence-absence data, environmental covariates, and performs species distribution modeling and projections under past and future scenarios.

Usage

glossa_analysis(
  pa_data = NULL,
  fit_layers = NULL,
  proj_files = NULL,
  study_area_poly = NULL,
  predictor_variables = NULL,
  thinning_method = NULL,
  thinning_value = NULL,
  scale_layers = FALSE,
  buffer = NULL,
  native_range = NULL,
  suitable_habitat = NULL,
  other_analysis = NULL,
  model_args = list(),
  cv_methods = NULL,
  cv_folds = 5,
  cv_block_source = "residuals_autocorrelation",
  cv_block_size = NULL,
  pseudoabsence_method = "random",
  pa_ratio = 1,
  target_group_points = NULL,
  pa_buffer_distance = NULL,
  seed = NA,
  waiter = NULL
)

Arguments

Value

A list containing structured outputs from each major section of the analysis, including model data, projections, variable importance scores, and habitat suitability assessments.

Export Glossa Model Results

Description

This function exports various types of Glossa model results, including native range predictions, suitable habitat predictions, model data, variable importance, functional response results, and presence/absence probability cutoffs. It generates raster files for prediction results, TSV files for model data and variable importance, and TSV files for functional response results. Additionally, it creates a TSV file for presence/absence probability cutoffs if provided.

Usage

glossa_export(
  species = NULL,
  models = NULL,
  layer_results = NULL,
  fields = NULL,
  model_data = FALSE,
  model_summary = FALSE,
  fr = FALSE,
  prob_cut = FALSE,
  varimp = FALSE,
  cross_val = FALSE,
  layer_format = "tif",
  projections_results = NULL,
  presence_absence_list = NULL,
  other_results = NULL,
  pa_cutoff = NULL,
  config_snapshot = NULL
)

Arguments

Value

A character vector of file paths for the exported files or directories.

Invert a Polygon

Description

This function inverts a polygon by calculating the difference between the bounding box and the polygon.

Usage

invert_polygon(polygon, bbox = NULL)

Arguments

Value

An sf object representing the inverted polygon.

Apply Polygon Mask to Raster Layers

Description

This function crops and extends raster layers to a study area extent (bbox) defined by longitude and latitude then applies a mask based on a provided spatial polygon to remove areas outside the polygon.

Usage

layer_mask(layers, study_area)

Arguments

Value

A 'SpatRaster' object representing the masked raster layers.

Misclassification Error

Description

Misclassification Error

Usage

misClassError(actuals, predictedScores, threshold = 0.5)

Arguments

Details

This function was obtained from the InformationValue R package (https://github.com/selva86/InformationValue).

Value

The misclassification error, which tells what proportion of predicted direction did not match with the actuals.

Compute the optimal probability cutoff score

Description

Compute the optimal probability cutoff score

Usage

optimalCutoff(
  actuals,
  predictedScores,
  optimiseFor = "misclasserror",
  returnDiagnostics = FALSE
)

Arguments

Details

This function was obtained from the InformationValue R package (https://github.com/selva86/InformationValue).

Value

The optimal probability score cutoff that maximises a given criterion. If 'returnDiagnostics' is TRUE, then the following items are returned in a list:

Optimal Cutoff for Presence-Absence Prediction

Description

This function calculates the optimal cutoff for presence-absence prediction using a BART model.

Usage

pa_optimal_cutoff(y, x, model, seed = NULL)

Arguments

Value

The optimal cutoff value for presence-absence prediction.

Plot cross-validation fold assignments

Description

Plot cross-validation fold assignments

Usage

plot_cv_folds_points(data, polygon = NULL)

Arguments

Value

A ggplot object showing point color-coded by cv fold and shaped by presence/absence.

Plot cross-validation metrics

Description

This function generates a cross-validation radial plot based on evaluation metrics.

Usage

plot_cv_metrics(data)

Arguments

Value

Returns a ggplot object representing the cross-validation plot.

Make Predictions Using a BART Model

Description

This function makes predictions using a Bayesian Additive Regression Trees (BART) model on a stack of environmental covariates ('SpatRaster').

Usage

predict_bart(bart_model, layers, cutoff = NULL)

Arguments

Value

A SpatRaster containing the mean, median, standard deviation, and quantiles of the posterior predictive distribution, as well as a potential presences layer if cutoff is provided.

Read and Validate Extent Polygon

Description

This function reads and validates a polygon file containing the extent. It checks if the file has the correct format and extracts the geometry.

Usage

read_extent_polygon(file_path, show_modal = FALSE)

Arguments

Value

A spatial object representing the extent if the file is valid, NULL otherwise.

Load Covariate Layers from ZIP Files

Description

This function loads covariate layers from a ZIP file, verifies their spatial characteristics, and returns them as a list of raster layers.

Usage

read_layers_zip(
  file_path,
  extend = TRUE,
  first_layer = FALSE,
  show_modal = FALSE
)

Arguments

Value

A list containing raster layers for each covariate.

Read and validate presences/absences CSV file

Description

This function reads and validates a CSV file containing presences and absences data for species occurrences. It checks if the file has the expected columns and formats.

Usage

read_presences_absences_csv(
  file_path,
  file_name = NULL,
  show_modal = FALSE,
  timestamp_mapping = NULL,
  coords = c("decimalLongitude", "decimalLatitude"),
  sep = "\t",
  dec = "."
)

Arguments

Value

A data frame with the validated data if the file has the expected columns and formats, NULL otherwise.

Remove Duplicated Points from a Dataframe

Description

This function removes duplicated points from a dataframe based on specified coordinate columns.

Usage

remove_duplicate_points(df, coords = c("decimalLongitude", "decimalLatitude"))

Arguments

Value

A dataframe without duplicated points.

Remove Points Inside or Outside a Polygon

Description

This function removes points from a dataframe based on their location relative to a specified polygon.

Usage

remove_points_polygon(
  df,
  polygon,
  overlapping = FALSE,
  coords = c("decimalLongitude", "decimalLatitude")
)

Arguments

Value

A dataframe containing the filtered points.

Calculate Response Curve Using BART Model

Description

This function calculates the response curve (functional responses) using a Bayesian Additive Regression Trees (BART) model.

Usage

response_curve_bart(bart_model, data, predictor_names)

Arguments

Value

A list containing a data frame for each independent variable with mean, 2.5th percentile, 97.5th percentile, and corresponding values of the variables.

Run GLOSSA Shiny App

Description

This function launches the GLOSSA Shiny web application.

Usage

run_glossa(
  request_size_mb = 2000,
  launch.browser = TRUE,
  port = getOption("shiny.port"),
  clear_global_env = FALSE
)

Arguments

Details

The GLOSSA Shiny app provides an interactive interface for users to access GLOSSA functionalities.

Value

No return value, called to launch the GLOSSA app.

Note

Use 'clear_global_env = TRUE' cautiously, as it removes all objects from your R environment after the app exits.

Examples

if(interactive()) {
run_glossa()
run_glossa(clear_global_env = TRUE)  # clears all global objects
}

Calculate the sensitivity for a given logit model

Description

Calculate the sensitivity for a given logit model

Usage

sensitivity(actuals, predictedScores, threshold = 0.5)

Arguments

Details

This function was obtained from the InformationValue R package (https://github.com/selva86/InformationValue).

Value

The sensitivity of the given binary response actuals and predicted probability scores, which is, the number of observations with the event AND predicted to have the event divided by the number of observations with the event.

Create a Sparkline Value Box

Description

This function creates a custom value box with a sparkline plot embedded in it.

Usage

sparkvalueBox(
  title,
  sparkline_data,
  description,
  type = "line",
  box_color = "white",
  width = 4,
  elevation = 0,
  ...
)

Arguments

Value

Returns a custom value box with the specified parameters.

Calculate the specificity for a given logit model

Description

Calculate the specificity for a given logit model

Usage

specificity(actuals, predictedScores, threshold = 0.5)

Arguments

Details

This function was obtained from the InformationValue R package (https://github.com/selva86/InformationValue).

Value

The specificity of the given binary response actuals and predicted probability scores, which is, the number of observations without the event AND predicted to not have the event divided by the number of observations without the event.

Validate Fit and Projection Layers

Description

This function validates fit and projection layers by checking their covariates.

Usage

validate_fit_projection_layers(
  fit_layers_path,
  proj_layers_path,
  show_modal = FALSE
)

Arguments

Value

TRUE if the layers pass validation criteria, FALSE otherwise.

Validate Layers Zip

Description

This function validates a ZIP file containing environmental layers. It checks if the layers have the same number of files, CRS (Coordinate Reference System), and resolution.

Usage

validate_layers_zip(file_path, timestamp_mapping = NULL, show_modal = FALSE)

Arguments

Value

TRUE if the layers pass validation criteria, FALSE otherwise.

Validate Match Between Presence/Absence Files and Fit Layers

Description

This function validates whether the time periods of the presence/absence data match the environmental layers.

Usage

validate_pa_fit_time(pa_data, fit_layers_path, show_modal = FALSE)

Arguments

Value

TRUE if the timestamps match the fit layers, FALSE otherwise.

Variable Importance in BART Model

Description

This function computes the variable importance scores for a fitted BART (Bayesian Additive Regression Trees) model using a permutation-based approach. It measures the impact of each predictor variable on the model's performance by permuting the values of that variable and evaluating the change in performance (F-score is the performance metric).

Usage

variable_importance(bart_model, y, x, cutoff = 0, n_repeats = 10, seed = NULL)

Arguments

Value

A data frame where each column corresponds to a predictor variable, and each row contains the variable importance scores across permutations.

Calculate Youden's index

Description

Calculate Youden's index

Usage

youdensIndex(actuals, predictedScores, threshold = 0.5)

Arguments

Details

This function was obtained from the InformationValue R package (https://github.com/selva86/InformationValue).

Value

The youdensIndex of the given binary response actuals and predicted probability scores, which is calculated as Sensitivity + Specificity - 1