SABERPRO - Semi-Analytical Bayesian Estimate Retrieval

A semi-analytically coupled elastic and inelastic scattering resolved aquatic radiative transfer model for retrieving posterior distributions of Optically Significant Constituents (OSCs), water depth, benthic reflectance and phyotplankton fluorescence indicators from remote sensing reflectance (Rrs).

Creator: Soham Mukherjee
Initial packaging: Raphael Mabit
Maintenance and feature integration: Soham Mukherjee

---

Mathematical and physics-based formulation

Please refer to the publication:

A Semi-Analytical Bayesian Estimate Retrieval (SABER) algorithm for the inversion of Remote Sensing Reflectance in optically deep and shallow waters
https://doi.org/10.1002/lom3.70004

---

Code structure

This package follows the recommendations of https://r-pkgs.org/ and the tidyverse style guide.

The code is written with a functional approach:

• fct_* files — low-level computations that call compiled C functions in src/
• utils_* files — higher-level, more generic utilities

The central piece is the objective_factory() function, which stitches together any forward model with any objective/likelihood function (including user-defined ones).

Forward models, input preparers, and objective functions are stored in registries (see registry.R): .input_preparer_registry, .forward_model_registry, .objective_function_registry.

---

Installation

System requirements

Platform	Requirements
R	≥ 3.5.0
Windows	Rtools matching your R version
Linux (Ubuntu/Debian)	build-essential, gfortran, cmake, libnlopt-dev, pkg-config
macOS	Xcode Command Line Tools, pkg-config (via Homebrew)

On Ubuntu/Debian, install system dependencies in one step:

sudo apt install build-essential gfortran cmake libnlopt-dev pkg-config \
                 libssl-dev libcurl4-openssl-dev libxml2-dev

Install from GitHub

# Install devtools if needed
if (!require("devtools")) install.packages("devtools")

# Install SABERPRO
devtools::install_github("homas01123/SABERPRO", dependencies = TRUE)

Verify installation

library(SABERPRO)

# List registered forward models and objective functions
list_forward_models()
list_objective_functions()

Optional: radcalnet_oc downwelling irradiance

SABERPRO uses Gregg & Carder (1990) by default for downwelling irradiance calculation in SICF modeling. A more extensive, VRTE driven precise model for downwelling irraidnace is also available, preferrable for very high spectral resolution observations, considering the gap-filling in at SICF emission wavelengths.

Each user needs a local radcalnet_oc clone and a virtual environment located inside that clone. Do not install into the system Python. The commands and bin/python paths below are for Linux/macOS; on Windows use the equivalent Scripts/python.exe virtualenv path.

cd /path/to/workspace
git clone https://github.com/homas01123/radcalnet_oc.git
cd radcalnet_oc
python3 -m venv .rcnet_venv
.rcnet_venv/bin/python -m pip install --upgrade pip
.rcnet_venv/bin/python -m pip install -e .

The expected layout is:

/path/to/workspace/radcalnet_oc/
  .rcnet_venv/
  radcalnet_oc/bridge.py

Next, in R prior to atetempt to use radcalnet-oc in a session, first onfigure reticulate before loading SABERPRO or making any Python call. The explicit source-path step is MANDATORY to enable radcalnet driven irradiance calculation.

rcnet_venv <- "/path/to/workspace/radcalnet_oc/.rcnet_venv"
rcnet_python <- file.path(rcnet_venv, "bin", "python")

Sys.setenv(
  RCNET_OC_VENV = rcnet_venv,
  RETICULATE_PYTHON = rcnet_python
)

library(reticulate)
print(reticulate::py_config()$python)

rcnet_root <- dirname(normalizePath(rcnet_venv, mustWork = TRUE))
reticulate::py_run_string(sprintf(
  "import importlib, sys\np = %s\nif p not in sys.path:\n    sys.path.insert(0, p)\nimportlib.invalidate_caches()\n",
  shQuote(rcnet_root)
))
reticulate::import("radcalnet_oc.bridge", delay_load = FALSE)

devtools::load_all("/path/to/workspace/saber_pro")

For a persistent local configuration, add these user-specific lines to ~/.Renviron and restart R:

RCNET_OC_VENV=/path/to/workspace/radcalnet_oc/.rcnet_venv
RETICULATE_PYTHON=/path/to/workspace/radcalnet_oc/.rcnet_venv/bin/python

---

Running the code

See the forward_inverse_basics vignette for a detailed introduction to forward and inverse modelling with SABERPRO.

---

Troubleshooting

Windows: Ensure Rtools is installed and on the system PATH.

Linux: If compilation fails with errors about missing math functions (cos, exp, etc.), ensure gfortran and libnlopt-dev are installed (see system requirements above).

General: If you see Error: no benthic classes loaded, call select_benthic_classes() before make_inversion_params().