Package {WISP.data}

Title:	Management and Analysis of WISPstation Hyperspectral Data
Version:	1.0.0
Description:	Automate the acquisition, quality control, analysis, and visualization of spectral data collected by the 'WISPstation' fixed spectroradiometer.
License:	GPL (≥ 3)
URL:	https://github.com/oggioniale/WISP.data, https://oggioniale.github.io/WISP.data/
BugReports:	https://github.com/oggioniale/WISP.data/issues
Encoding:	UTF-8
Language:	en-GB
Depends:	R (≥ 4.1.0)
VignetteBuilder:	knitr
Suggests:	knitr, rmarkdown, markdown, testthat (≥ 3.0.0), httptest2, curl
Imports:	dplyr, ggplot2, httr2, lifecycle, lubridate, plotly, purrr, readr, rlang, shiny, shinyjs, stats, stringr, tibble, tidyr, tidyselect, units, utils, viridis
Config/testthat/edition:	3
Config/roxygen2/version:	8.1.0
RoxygenNote:	7.3.3
NeedsCompilation:	no
Packaged:	2026-09-18 13:35:50 UTC; nicol
Author:	Alessandro Oggioni [aut, cre, fnd], Nicola Ghirardi [aut]
Maintainer:	Alessandro Oggioni <alessandro.oggioni@cnr.it>
Repository:	CRAN
Date/Publication:	2026-09-29 13:30:32 UTC

WISP.data: Management and Analysis of WISPstation Hyperspectral Data

Description

Automate the acquisition, quality control, analysis, and visualization of spectral data collected by the 'WISPstation' fixed spectroradiometer.

Author(s)

Maintainer: Alessandro Oggioni alessandro.oggioni@cnr.it (ORCID) [funder]

Authors:

• Nicola Ghirardi nicola.ghirardi@cnr.it (ORCID)

See Also

Useful links:

• https://github.com/oggioniale/WISP.data

• https://oggioniale.github.io/WISP.data/

• Report bugs at https://github.com/oggioniale/WISP.data/issues

Get data of reflectance (level2) from WISPstation for a specific date

Description

This function represents the main entry point for data acquisition within the WISP.data package. It connects to the official Water Insight APIs to download spectral reflectance measurements for a user-defined time interval. The function handles authentication queries the remote server and returns the retrieved data in a structured tibble format. In addition to hyperspectral reflectance data (350-900 nm), the function also retrieves the water quality parameters natively computed by the WISPstation, including: TSM (Van Der Woerd & Pasterkamp, 2008), Chla (Gons et al., 2005), Kd (Gons et al., 1998), and cpc (Simis, 2006).

Usage

wisp_get_reflectance_data(
  version = "1.0",
  time_from = NULL,
  time_to = NULL,
  station = NULL,
  userid = NULL,
  pwd = NULL,
  save_csv = FALSE,
  out_dir = NULL
)

Arguments

Value

A tibble with measurement id, measurement date, instrument name, level2_quality, set of sensor (irradiance and radiances), water quality values of TSM, Chla, Kd, and cpc as provided by instrument by default, all the reflectance values from 350 to 900 nm.

Author(s)

Alessandro Oggioni, phD alessandro.oggioni@cnr.it

Nicola Ghirardi, phD nicola.ghirardi@cnr.it

Examples

## Not run: 
# NA data
reflect_data <- wisp_get_reflectance_data(
  time_from = "2024-09-01T09:00",
  time_to = "2024-09-01T14:00",
  station = "WISPstation012",
  userid = userid,
  pwd = pwd,
  save_csv = FALSE
)

# with data
reflect_data <- wisp_get_reflectance_data(
  time_from = "2024-08-01T09:00",
  time_to = "2024-08-01T14:00",
  station = "WISPstation012",
  userid = userid,
  pwd = pwd,
  save_csv = FALSE
)

# no data for the station selected
reflect_data <- wisp_get_reflectance_data(
  time_from = "2019-06-20T09:00",
  time_to = "2019-06-20T14:00",
  station = "WISPstation012",
  userid = userid,
  pwd = pwd,
  save_csv = FALSE
)

# The two dates are not consistent
reflect_data <- wisp_get_reflectance_data(
  time_from = "2019-06-20T09:00",
  time_to = "2020-06-20T14:00",
  station = "WISPstation012",
  userid = userid,
  pwd = pwd,
  save_csv = FALSE
)

## End(Not run)

Get data of reflectance (level2) from WISPstation for multiple dates

Description

This function acts as an iterative wrapper around wisp_get_reflectance_data(). It is specifically designed to download extended time series that exceed the limits of a single API request. The function automatically splits the user-defined time interval into daily blocks, performs sequential downloads, and aggregates all retrieved data into a single, coherent tibble.

Usage

wisp_get_reflectance_multi_data(
  version = "1.0",
  time_from = NULL,
  time_to = NULL,
  station = NULL,
  userid = NULL,
  pwd = NULL,
  save_csv = FALSE,
  out_dir = NULL
)

Arguments

Value

A tibble with measurement id, measurement date, instrument name, level2_quality, set of sensor (irradiance and radiances), water quality values of TSM (Van Der Woerd & Pasterkamp, 2008), Chla (Gons et al., 2005), Kd (Gons et al., 1998), and cpc (Simis, 2006) as provided by instrument by default, all the reflectance values from 350 to 900 nm.

Author(s)

Alessandro Oggioni, phD alessandro.oggioni@cnr.it

Nicola Ghirardi, phD nicola.ghirardi@cnr.it

Examples

## Not run: 
reflect_data <- wisp_get_reflectance_multi_data(
  time_from = "2024-04-08T09:00",
  time_to = "2024-04-10T14:00",
  station = "WISPstation012",
  userid = userid,
  pwd = pwd,
  save_csv = FALSE
)

# NA data on 2024-09-01
reflect_data <- wisp_get_reflectance_multi_data(
  time_from = "2024-08-31T09:00",
  time_to = "2024-09-02T14:00",
  station = "WISPstation012",
  userid = userid,
  pwd = pwd,
  save_csv = FALSE
)

## End(Not run)

Comparison plot of Raw vs QC vs SR reflectance data

Description

This function creates an interactive side-by-side visual comparison of the different WISPstation data processing levels. Using plotly submodules, it enables the visualization of up to three aligned plots within a single interactive window: native data downloaded directly from WISPstation, processed data after QC, processed data after SR. This provides a powerful tool for visually assessing how filtering and correction algorithms modify spectral signatures, remove artifacts, and improve data quality.

Usage

wisp_plot_comparison(
  raw_data = NULL,
  qc_data = NULL,
  sr_data = NULL,
  raw_args = NULL,
  qc_args = NULL,
  sr_args = NULL
)

Arguments

Value

A plotly object comparing the spectral signatures of whichever of raw_data, qc_data, and sr_data were provided (1 to 3 panels, always ordered WISPstation native, then QC, then SR). The plot title reflects exactly which of them are shown, e.g. "Reflectance: QC" for a single dataset, or "Reflectance comparison: WISPstation vs SR" for two.

Author(s)

Alessandro Oggioni, phD alessandro.oggioni@cnr.it

Nicola Ghirardi, phD nicola.ghirardi@cnr.it

Examples

if (interactive()) {
  custom_raw <- list(legend_TSM = FALSE, legend_Chla = FALSE)
  custom_qc  <- list(legend_TSM = TRUE, legend_Chla = TRUE, legend_Kd = FALSE)
  custom_sr  <- list(legend_TSM = TRUE, legend_mishra_CHL = FALSE)

  fig_comparison <- wisp_plot_comparison(
    raw_data = reflect_data,
    qc_data  = reflect_data_qc,
    sr_data  = reflect_data_sr,
    raw_args = custom_raw,
    qc_args  = custom_qc,
    sr_args  = custom_sr
  )
  print(fig_comparison)
}

Create a plot of reflectance data

Description

This function generates an interactive visualization of all spectral signatures contained in a dataset, based on the plotly library. It is highly flexible and can be used to display: native data downloaded directly from WISPstation, processed data after QC, processed data after SR. The function's distinctive feature is its dynamic tooltip system: when hovering over a spectral curve, users can instantly visualize the corresponding acquisition date and time, together with all associated bio-optical parameters computed for that specific measurement.

Usage

wisp_plot_reflectance_data(
  data,
  legend_TSM = TRUE,
  legend_Chla = TRUE,
  legend_Kd = TRUE,
  legend_cpc = TRUE,
  legend_scatt = FALSE,
  legend_ratio = FALSE,
  legend_novoa_SPM = FALSE,
  legend_novoa_TUR = FALSE,
  legend_jiang_TSS = FALSE,
  legend_gons_CHL = FALSE,
  legend_gons740_CHL = FALSE,
  legend_NDCI = FALSE,
  legend_mishra_CHL = FALSE,
  legend_hue_angle = FALSE,
  legend_dom_wavelength = FALSE,
  legend_OWT_class = FALSE,
  legend_OWT_score = FALSE,
  legend_OWT_z_dist = FALSE
)

Arguments

Value

An interactive plotly object showing the spectral signatures of the reflectance data.

Author(s)

Alessandro Oggioni, phD alessandro.oggioni@cnr.it

Nicola Ghirardi, phD nicola.ghirardi@cnr.it

Examples

if (interactive()) {
  wisp_plot_reflectance_data(
    data = reflect_data_sr,
    legend_TSM = TRUE,
    legend_Chla = TRUE,
    legend_Kd = TRUE,
    legend_cpc = TRUE,
    legend_scatt = FALSE,
    legend_ratio = FALSE,
    legend_novoa_SPM = FALSE,
    legend_novoa_TUR = FALSE,
    legend_jiang_TSS = FALSE,
    legend_gons_CHL = FALSE,
    legend_gons740_CHL = FALSE,
    legend_NDCI = FALSE,
    legend_mishra_CHL = FALSE,
    legend_hue_angle = FALSE,
    legend_dom_wavelength = FALSE,
    legend_OWT_class = FALSE,
    legend_OWT_score = FALSE,
    legend_OWT_z_dist = FALSE
  )
}

Quality Control (QC) for WISPstation reflectance data

Description

This function performs the Quality Control (QC) process and applies different algorithms to spectral signatures. The function applies a structured sequence of QC tests (QC1 - QC6), designed to identify and remove low-quality or physically implausible spectra. In addition, the function integrates independent quality assessment metrics derived from the literature (QA and QWIP), providing robust spectral validation through established optical criteria.

Usage

wisp_qc_reflectance_data(
  data,
  maxPeak = 0.05,
  maxPeak_blue = 0.02,
  qa_threshold = 0.5,
  qwip_threshold = 0.2,
  calc_scatt = TRUE,
  calc_SPM = TRUE,
  calc_TUR = TRUE,
  calc_TSS = TRUE,
  calc_gons = TRUE,
  calc_gons740 = TRUE,
  calc_NDCI = TRUE,
  calc_mishra = TRUE,
  calc_dom_wave = TRUE,
  calc_OWT = TRUE,
  save_csv = FALSE,
  out_dir = NULL
)

Arguments

Value

A tibble with the spectral signatures that have passed QC operation and all the extra parameters that were requested. In addition, a message containing the reason behind the elimination of each anomalous spectral signature. If parameter save_csv is TRUE, the function saves the reflectance data in a CSV file.

Author(s)

Alessandro Oggioni, phD alessandro.oggioni@cnr.it

Nicola Ghirardi, phD nicola.ghirardi@cnr.it

Examples

# Requires a valid reflectance dataset retrieved from wisp_get_reflectance_data()
if (exists("reflect_data")) {
  reflect_data_qc <- wisp_qc_reflectance_data(
    data = reflect_data,
    maxPeak = 0.05,
    maxPeak_blue = 0.02,
    qa_threshold = 0.5,
    qwip_threshold = 0.2,
    calc_scatt = TRUE,
    calc_SPM = TRUE,
    calc_TUR = TRUE,
    calc_TSS = TRUE,
    calc_gons = TRUE,
    calc_gons740 = TRUE,
    calc_NDCI = TRUE,
    calc_mishra = TRUE,
    calc_dom_wave = TRUE,
    calc_OWT = TRUE,
    save_csv = FALSE,
  )
}

Run shiny app for get and visualize WISP data

Description

This function runs the Shiny app for querying and visualizing data from a specific WISP station.

Usage

wisp_runApp(stations = c("WISPstation012", "WISPstation013"), ...)

Arguments

Value

No return value, called for side effects to launch the interactive Shiny application.

Author(s)

Alessandro Oggioni, phD alessandro.oggioni@cnr.it

Examples

if (interactive()) {
  # Launch the Shiny application
  wisp_runApp(launch.browser = TRUE)
}

Sky-glint Removal (SR) for WISPstation reflectance data

Description

This function implements a sky-glint Removal algorithm based on the methodology proposed by Jiang et al. (2020). The function operates on spectra that have already been filtered through the Quality Control process and applies a correction to obtain glint-corrected remote sensing reflectance. Following this correction, all algorithms are re-applied using the corrected reflectance, ensuring more accurate and physically consistent estimates of water constituents.

Usage

wisp_sr_reflectance_data(
  qc_data,
  calc_scatt = TRUE,
  calc_SPM = TRUE,
  calc_TUR = TRUE,
  calc_TSS = TRUE,
  calc_gons = TRUE,
  calc_gons740 = TRUE,
  calc_NDCI = TRUE,
  calc_mishra = TRUE,
  calc_dom_wave = TRUE,
  calc_OWT = TRUE,
  save_csv = FALSE,
  out_dir = NULL
)

Arguments

Value

A tibble with the spectral signatures after the SR operation and all the extra parameters that were requested. If parameter save_csv is TRUE, the function saves the reflectance data in a CSV file.

Author(s)

Alessandro Oggioni, phD alessandro.oggioni@cnr.it

Nicola Ghirardi, phD nicola.ghirardi@cnr.it

Examples

# Requires a valid dataset output from wisp_qc_reflectance_data()
if (exists("reflect_data_qc")) {
  reflect_data_sr <- wisp_sr_reflectance_data(
    qc_data = reflect_data_qc,
    calc_scatt = TRUE,
    calc_SPM = TRUE,
    calc_TUR = TRUE,
    calc_TSS = TRUE,
    calc_gons = TRUE,
    calc_gons740 = TRUE,
    calc_NDCI = TRUE,
    calc_mishra = FALSE,
    calc_dom_wave = TRUE,
    calc_OWT = TRUE,
    save_csv = FALSE,
  )
}

Create a temporal trend plot of one or more parameters

Description

This function generates interactive temporal plots for one or more parameters. It is designed to handle both high-frequency measurements within a single day and long-term time series spanning multiple months. The function can aggregate data (daily mean or median) and allows comparison of multiple parameters in the same plot if they share the same unit of measurement.

Usage

wisp_trend_plot(
  data,
  params = c("TSM", "Chla"),
  datetime_col = "measurement.date",
  instrument_col = "instrument.name",
  aggregate = c("none", "daily_mean", "daily_median"),
  merge_plot = FALSE,
  na.rm = TRUE,
  colors = NULL,
  title = NULL,
  return_long_df = FALSE
)

Arguments

Value

An interactive plotly object showing the temporal trend of the selected parameters, with optional ribbons for standard deviation. If return_long_df = TRUE, returns a tibble in long format.

Author(s)

Alessandro Oggioni, phD alessandro.oggioni@cnr.it

Nicola Ghirardi, phD nicola.ghirardi@cnr.it

Examples

if (interactive()) {
  # Standard plot with facets for each parameter
  fig_trend <- wisp_trend_plot(
    data       = reflect_data_sr,
    params     = c("TSM", "Chla"),
    aggregate  = "none",
    merge_plot = FALSE
  )
  print(fig_trend)
 
  # Merged plot for parameters with common units 
  fig_merged <- wisp_trend_plot(
    data       = reflect_data_sr,
    params     = c("TSM", "Novoa_SPM"),
    aggregate  = "daily_mean",
    merge_plot = TRUE
  )
  print(fig_merged)
}