Package 'SHARK4R'

Description

This function enhances a dataset of AphiaIDs (and optionally scientific names) with their complete hierarchical taxonomy from the World Register of Marine Species (WoRMS). Missing AphiaIDs can be resolved from scientific names automatically.

Usage

add_worms_taxonomy(
  aphia_ids,
  scientific_names = NULL,
  add_rank_to_hierarchy = FALSE,
  verbose = TRUE,
  aphia_id = deprecated(),
  scientific_name = deprecated()
)

Arguments

Value

A tibble with taxonomy columns added, including:

• aphia_id, scientific_name

• worms_kingdom, worms_phylum, worms_class, worms_order, worms_family, worms_genus, worms_species

• worms_scientific_name, worms_hierarchy

Examples

# Using AphiaID only
try(add_worms_taxonomy(c(1080, 109604), verbose = FALSE))

# Using a combination of AphiaID and scientific name
try(add_worms_taxonomy(
  aphia_ids = c(NA, 109604),
  scientific_names = c("Calanus finmarchicus", "Oithona similis"),
  verbose = FALSE
))

Description

This function assigns default phytoplankton groups (Diatoms, Dinoflagellates, Cyanobacteria, or Other) to a list of scientific names or Aphia IDs by retrieving species information from the World Register of Marine Species (WoRMS). The function checks both Aphia IDs and scientific names, handles missing records, and assigns the appropriate plankton group based on taxonomic classification in WoRMS. Additionally, custom plankton groups can be specified using the custom_groups parameter, allowing users to define additional classifications based on specific taxonomic criteria.

Usage

assign_phytoplankton_group(
  scientific_names,
  aphia_ids = NULL,
  diatom_class = c("Bacillariophyceae", "Coscinodiscophyceae", "Mediophyceae",
    "Diatomophyceae"),
  dinoflagellate_class = "Dinophyceae",
  cyanobacteria_class = "Cyanophyceae",
  cyanobacteria_phylum = "Cyanobacteria",
  match_first_word = TRUE,
  marine_only = FALSE,
  return_class = FALSE,
  custom_groups = list(),
  verbose = TRUE
)

Arguments

Details

The aphia_ids parameter is not necessary but, if provided, will improve the certainty of the matching process. If aphia_ids are available, they will be used directly to retrieve more accurate WoRMS records. If missing, the function will attempt to match the scientific names to Aphia IDs by querying WoRMS using the scientific name(s), with an additional fallback mechanism to match based on the first word of the scientific name.

To skip one of the default plankton groups, you can set the class or phylum of the respective group to an empty string (""). For example, to skip the "Cyanobacteria" group, you can set cyanobacteria_class = "" or cyanobacteria_phylum = "". These taxa will then be placed in Others.

Custom groups are processed in the order they appear in the custom_groups list. If a taxon matches multiple custom groups, it will be assigned to the group that appears last in the list, as later matches overwrite earlier ones. For example, if ⁠Teleaulax amphioxeia⁠ matches both Cryptophytes (class-based) and a specific group Teleaulax (name-based), it will be assigned to Teleaulax if Teleaulax is listed after Cryptophytes in the custom_groups list.

Value

A tibble with two columns: scientific_name and plankton_group, where the plankton group is assigned based on taxonomic classification.

See Also

https://marinespecies.org/ for WoRMS website.

https://CRAN.R-project.org/package=worrms

Examples

# Assign plankton groups to a list of species names
try(result <- assign_phytoplankton_group(
  scientific_names = c("Tripos fusus", "Diatoma", "Nodularia spumigena", "Octactis speculum"),
  verbose = FALSE))

if (exists("result")) print(result)

# Improve classification by explicitly providing Aphia IDs for ambiguous taxa
# Actinocyclus and Navicula are names shared by both diatoms and animals,
# which can lead to incorrect group assignment without an Aphia ID
try(result <- assign_phytoplankton_group(
  scientific_names = c("Actinocyclus", "Navicula", "Nodularia spumigena", "Tripos fusus"),
  aphia_ids = c(148944, 149142, NA, NA),
  verbose = FALSE))

if (exists("result")) print(result)

# Assign plankton groups using additional custom grouping
custom_groups <- list(
    Cryptophytes = list(class = "Cryptophyceae"),
    Ciliates = list(phylum = "Ciliophora")
)

# Assign with custom groups
try(result_custom <- assign_phytoplankton_group(
  scientific_names = c("Teleaulax amphioxeia", "Mesodinium rubrum", "Dinophysis acuta"),
  aphia_ids = c(106306, 232069, 109604),
  custom_groups = custom_groups,         # Adding custom groups
  verbose = FALSE
))

if (exists("result_custom")) print(result_custom)

Description

Calculates zooplankton biomass by combining per-individual dry weight ("Dry weight (mean)", in ug) with abundance measurements in the same observation. Two biomass parameters are produced:

• Biomass concentration (mg/m3) from "Abundance" rows (ind/m3).

• Integrated biomass (mg/m2) from "Integrated abundance" rows (ind/m2).

Usage

calc_zooplankton_biomass(
  data,
  abundance_parameter = "Abundance",
  integrated_abundance_parameter = "Integrated abundance",
  dry_weight_parameter = "Dry weight (mean)",
  biomass_concentration_parameter = "Biomass concentration",
  integrated_biomass_parameter = "Integrated biomass",
  append = TRUE,
  drop_na_values = TRUE,
  keep_reference = FALSE
)

Arguments

Details

The conversion is biomass = dry_weight_ug * abundance / 1000 so that the result is expressed in mg/m3 or mg/m2.

Value

A tibble. By default, the original data are returned with calculated biomass rows appended. If append = FALSE, only the calculated rows are returned.

Observation key

Dry-weight and abundance rows are matched one-to-one using the following columns, which together identify a single zooplankton observation in SHARK:

• platform_code

• station_name

• sample_date

• sample_time

• sample_min_depth_m

• sample_max_depth_m

• aphia_id

• sex_code

• dev_stage_code

• size_class

One biomass row is produced per matching abundance row (no aggregation across size classes or development stages). Abundance rows without a matching dry-weight value yield NA biomass and are dropped by default.

If no "Dry weight (mean)" rows are present in data, the function calls calc_zooplankton_dry_weight() internally to compute them from "Length (mean)" before calculating biomass.

See Also

calc_zooplankton_dry_weight()

Examples

zoo <- dplyr::tibble(
  platform_code = "77SE",
  station_name = "ANHOLT E",
  sample_date = as.Date("2023-06-01"),
  sample_time = "10:00",
  sample_min_depth_m = 0,
  sample_max_depth_m = 30,
  aphia_id = 104251,
  sex_code = NA_character_,
  dev_stage_code = "AD",
  size_class = NA_character_,
  parameter = c("Length (mean)", "Abundance", "Integrated abundance"),
  value = c(800, 120, 3600),
  unit = c("um", "ind/m3", "ind/m2")
)

calc_zooplankton_biomass(zoo, append = FALSE)

Description

Calculates zooplankton dry weight from rows where parameter equals "Length (mean)" using bundled taxa-specific coefficients for mesozooplankton from Kattegat and Skagerrak.

Usage

calc_zooplankton_dry_weight(
  data,
  length_parameter = "Length (mean)",
  dry_weight_parameter = "Dry weight (mean)",
  append = TRUE,
  drop_na_values = TRUE,
  keep_reference = FALSE
)

Arguments

Details

The dry weight calculation follows:

DW = 10^((B * log10(length)) - A)

For nauplii (dev_stage_code == "NP"), taxon-specific nauplii coefficients are used when available. Otherwise, the general coefficients for "copepod nauplii *all copepod species" are used. All other development stages use the non-nauplii coefficients. In practice, these coefficients are used for adults as well as copepodite stages and other non-NP stages.

The calculation assumes that SHARK "Length (mean)" values are reported in um. Calculated dry-weight rows are assigned the unit ug.

The bundled coefficient workbook used by this function can be accessed with: system.file("extdata", "Mesozooplankton_Kattegat_Skagerrak_taxa_and_biomass_calculations.xlsx", package = "SHARK4R").

Matching is performed using aphia_id, as preferred for SHARK data. Taxa with no matching coefficient keep NA dry-weight values.

Value

A tibble. By default, the original data are returned with calculated "Dry weight (mean)" rows appended. If append = FALSE, only the calculated rows are returned.

Reference coefficient table

The bundled workbook used for these coefficients can be downloaded directly: Download coefficient workbook (.xlsx)

For a local copy within an installed package, use: system.file("extdata", "Mesozooplankton_Kattegat_Skagerrak_taxa_and_biomass_calculations.xlsx", package = "SHARK4R")

To download the latest version directly: Download from GitHub

References

1. Hay SJ, Kiørboe T, Matthews A (1991) Zooplankton biomass and production in the North Sea during the Autumn Circulation experiment, October 1987-March 1988. Continental Shelf Research 11(12):1453-1476. doi:10.1016/0278-4343(91)90021-W

2. Hygum BH, Rey C, Hansen BW (2000) Growth and development rates of Calanus finmarchicus nauplii during a diatom spring bloom. Marine Biology 136:1075-1085. doi:10.1007/s002270000313

3. Hay SJ, Evans GT, Gamble JC (1988) Birth, growth and death rates for enclosed populations of calanoid copepods. Journal of Plankton Research 10(3):431-454. doi:10.1093/plankt/10.3.431

4. Satapoomin S (1999) Carbon content of some common tropical Andaman Sea copepods. Journal of Plankton Research 21(11):2117-2123. doi:10.1093/plankt/21.11.2117

5. Uye SI (1982) Length-weight relationships of important zooplankton from the Inland Sea of Japan. Journal of the Oceanographical Society of Japan 38:149-158. doi:10.1007/BF02110286

6. Hernroth L, ed. (1985) Recommendations on methods for marine biological studies in the Baltic Sea: mesozooplankton biomass assessment / individual volume technique. Publication / The Baltic Marine Biologists - BMB, 10. Lysekil: Institute of Marine Research.

7. Atienza D, Saiz E, Calbet A (2006) Feeding ecology of the marine cladoceran Penilia avirostris: natural diet, prey selectivity and daily ration. Marine Ecology Progress Series 315:211-220. doi:10.3354/meps315211

8. Almeda R, Calbet A, Alcaraz M, Yebra L, Saiz E (2010) Effects of temperature and food concentration on the survival, development and growth rates of naupliar stages of Oithona davisae (Copepoda, Cyclopoida). Marine Ecology Progress Series 410:97-109. doi:10.3354/meps08625

9. Hirche HJ, Mumm N (1992) Distribution of dominant copepods in the Nansen Basin, Arctic Ocean, in summer. Deep-Sea Research Part A. Oceanographic Research Papers 39(Suppl. 2):S485-S505. doi:10.1016/S0198-0149(06)80017-8

10. Paffenhöfer GA (1976) On the biology of appendicularia of the southeastern North Sea. In: 10th European Symposium on Marine Biology, Ostend, Belgium, 17-23 September 1975, Vol. 2, pp. 437-455.

See Also

calc_zooplankton_biomass()

Examples

# Minimal example with a few rows
zoo <- dplyr::tibble(
  scientific_name = c("Acartia clausi", "Calanus finmarchicus", "Unknown taxon"),
  parameter = c("Length (mean)", "Length (mean)", "Length (mean)"),
  value = c(200, 250, 160),
  aphia_id = c(104251, 104464, 999999),
  dev_stage_code = c("AD", "NP", "NP")
)

# Calculate dry weight rows only
calc_zooplankton_dry_weight(zoo, append = FALSE)


# Download zooplankton data from SHARK
zoo_shark <- get_shark_data(
  "sharkdata_zooplankton",
  dataTypes = "Zooplankton",
  fromYear = 2023,
  toYear = 2023,
  stationName = "ANHOLT E",
  verbose = FALSE,
)

# Calculate dry weight from "Length (mean)" and return only the new rows
calc_zooplankton_dry_weight(
  zoo_shark,
  append = FALSE
)

Description

This function checks whether the codes reported in a specified column of a dataset (e.g., project codes, ship codes, etc.) are present in the official SHARK codelist provided by SMHI. If a cell contains multiple codes separated by commas, each code is checked individually. The function downloads and caches the codelist if necessary, compares the reported values against the valid codes, and returns a tibble showing which codes matched. Informative messages are printed if unmatched codes are found.

Usage

check_codes(
  data,
  field = "sample_project_name_en",
  code_type = "PROJ",
  match_column = "Description/English translate",
  clean_cache_days = 30,
  verbose = TRUE
)

Arguments

Value

A tibble with unique reported codes (after splitting comma-separated entries) and a logical column match_type indicating if they exist in the SHARK codelist.

See Also

get_shark_codes() to get the current code list.

clean_shark4r_cache() to manually clear cached files.

Description

This function checks whether the required and recommended global and datatype-specific SHARK system fields are present in a data frame.

• Required fields: Missing or empty required fields are reported as errors.

• Recommended fields: Missing or empty recommended fields are reported as warnings, but only if level = "warning" is specified.

Usage

check_datatype(data, level = "error")

Arguments

Value

A tibble summarizing missing or empty fields, with columns:

• level: "error" or "warning".

• field: Name of the missing or empty field.

• row: Row number where the value is missing (NA) or NA if the whole column is missing.

• message: Description of the issue.

Examples

# Example with required fields missing
df <- data.frame(
  visit_year = 2024,
  station_name = NA
)
check_datatype(df, level = "error")

# Example checking recommended fields as warnings
check_datatype(df, level = "warning")

Description

check_depth() inspects one or two depth columns in a dataset and reports potential problems such as missing values, non-numeric entries, or values that conflict with bathymetry and shoreline information. It can also validate depths against bathymetry data retrieved from a terra::SpatRaster object or, if bathymetry = NULL, via the lookup_xy() function, which calls the OBIS XY lookup API to obtain bathymetry (using EMODnet Bathymetry) and shore distance.

Usage

check_depth(
  data,
  depth_cols = c("sample_min_depth_m", "sample_max_depth_m"),
  lat_col = "sample_latitude_dd",
  lon_col = "sample_longitude_dd",
  report = TRUE,
  depthmargin = 0,
  shoremargin = NA,
  bathymetry = NULL
)

Arguments

Details

The following checks are performed:

1. Missing depth column → warning

2. Empty depth column (all values missing) → warning

3. Non-numeric depth values → warning

4. Depth exceeds bathymetry + margin (depthmargin) → warning

5. Negative depth at offshore locations (beyond shoremargin) → warning

6. Minimum depth greater than maximum depth (if two columns supplied) → error

7. Longitude/latitude outside raster bounds → warning

8. Missing bathymetry value at coordinate → warning

The function has been modified from the obistools package (Provoost and Bosch, 2024).

Value

A tibble with one row per detected problem, containing:

level

Severity of the issue ("warning" or "error").

row

Row index in the input data where the issue occurred.

field

Name of the column(s) involved.

message

Human-readable description of the problem.

If report = FALSE, returns the subset of input rows that failed any check.

References

Provoost P, Bosch S (2024). “obistools: Tools for data enhancement and quality control” Ocean Biodiversity Information System. Intergovernmental Oceanographic Commission of UNESCO. R package version 0.1.0, https://iobis.github.io/obistools/.

See Also

lookup_xy, check_onland

Examples

# Example dataset with one depth column
example_data <- data.frame(
  sample_latitude_dd = c(59.3, 58.1, 57.5),
  sample_longitude_dd = c(18.0, 17.5, 16.2),
  sample_depth_m = c(10, -5, NA)
)

# Validate depths using OBIS XY lookup (bathymetry = NULL)
try(check_depth(example_data, depth_cols = "sample_depth_m"))

# Example dataset with min/max depth columns
example_data2 <- data.frame(
  sample_latitude_dd = c(59.0, 58.5),
  sample_longitude_dd = c(18.0, 17.5),
  sample_min_depth_m = c(5, 15),
  sample_max_depth_m = c(3, 20)
)

try(check_depth(example_data2, depth_cols = c("sample_min_depth_m", "sample_max_depth_m")))

# Return only failing rows
try(check_depth(example_data, depth_cols = "sample_depth_m", report = FALSE))

Description

This function checks a SHARK data frame against the required and recommended fields defined for a specific datatype. It verifies that all required fields are present and contain non-empty values. If level = "warning", it also checks for recommended fields and empty values within them.

Note: A single "*" marks required fields in the standard SHARK template. A double "**" is often used to specify columns required for national monitoring only. For more information, see: https://www.smhi.se/data/hav-och-havsmiljo/datavardskap-oceanografi-och-marinbiologi/leverera-data

Usage

check_fields(
  data,
  datatype,
  level = "error",
  stars = 1,
  bacterioplankton_subtype = "abundance",
  field_definitions = .field_definitions
)

Arguments

Details

Field definitions for SHARK data can be loaded in two ways:

1. From the SHARK4R package bundle (default): The package contains a built-in object, .field_definitions, which stores required and recommended fields for each datatype.

2. From GitHub (latest official version): To use the most up-to-date field definitions, you can load them directly from the SHARK4R-statistics repository:

       defs <- load_shark4r_fields()
       check_fields(my_data, "Phytoplankton", field_definitions = defs)
       

Delivery-format (all-caps) data: If the column names in data are all uppercase (e.g. SDATE), check_fields() assumes the dataset follows the official SHARK delivery template. In this case:

• Required fields are determined from the delivery template using get_delivery_template() and find_required_fields().

• Recommended fields are ignored because the delivery templates do not define them.

• The function validates that all required columns exist and contain non-empty values.

This ensures that both internal SHARK4R datasets (with camelCase or snake_case columns) and official delivery files (ALL_CAPS columns) are validated correctly using the appropriate rules.

Stars in the template

Leading asterisks in the delivery template indicate required levels:

• * = standard required column

• * = required for national monitoring

• Other symbols = additional requirement level

The stars parameter in check_fields() controls how many levels of required columns to include.

Value

A tibble with the following columns:

level

Either "error" or "warning".

field

The name of the field that triggered the check.

row

Row number(s) in data where the issue occurred, or NA if the whole field is missing.

message

A descriptive message explaining the problem.

The tibble will be empty if no problems are found.

See Also

load_shark4r_fields for fetching the latest field definitions from GitHub, get_delivery_template for downloading delivery templates from SMHI's website.

Examples

# Example 1: Using built-in field definitions for "Phytoplankton"
df_phyto <- data.frame(
  visit_date = "2023-06-01",
  sample_id = "S1",
  scientific_name = "Skeletonema marinoi",
  value = 123
)

# Check fields
check_fields(df_phyto, "Phytoplankton", level = "warning")


# Example 2: Load latest definitions from GitHub and use them
try(defs <- load_shark4r_fields(verbose = FALSE))

# Check fields using loaded field definitions
if (exists("defs")) try(check_fields(df_phyto, "Phytoplankton", field_definitions = defs))


# Example 3: Custom datatype with required + recommended fields
defs <- list(
  ExampleType = list(
    required = c("id", "value"),
    recommended = "comment"
  )
)

# Example data
df_ok <- data.frame(id = 1, value = "x", comment = "ok")

# Check fields using custom field definitions
check_fields(df_ok, "ExampleType", level = "warning", field_definitions = defs)

Description

This function checks for logical rule violations in benthos/epibenthos data by applying a user-defined condition to values for a given parameter. It is intended to replace the old family of ⁠check_*_*_logical()⁠ functions.

Usage

check_logical_parameter(
  data,
  param_name,
  condition,
  return_df = FALSE,
  return_logical = FALSE
)

Arguments

Value

A DT datatable, a data.frame, a logical vector, or NULL if no problems found.

Examples

# Example dataset
df <- dplyr::tibble(
  station_name = c("A1", "A2", "A3", "A4"),
  sample_date = as.Date("2023-05-01") + 0:3,
  sample_id = 101:104,
  parameter = c("Biomass", "Biomass", "Abundance", "Biomass"),
  value = c(5, -2, 10, 0)
)

# 1. Check that Biomass is never negative
check_logical_parameter(df, "Biomass", function(x) x < 0,  return_df = TRUE)

# 2. Same check, but return problematic rows as a data frame
check_logical_parameter(df, "Biomass", function(x) x < 0, return_df = TRUE)

# 3. Return logical vector marking problematic rows
check_logical_parameter(df, "Biomass", function(x) x < 0, return_logical = TRUE)

# 4. Check that Abundance is not zero (no problems found -> returns NULL)
abundance_check <- check_logical_parameter(df, "Abundance", function(x) x == 0)
print(abundance_check)

Description

This function attempts to determine whether stations in a dataset are reported using nominal positions (i.e., generic or repeated coordinates across events), rather than actual measured coordinates.

Usage

check_nominal_station(data, verbose = TRUE)

Arguments

Details

The function compares the number of unique sampling dates with the number of unique station coordinates.

If the number of unique sampling dates is larger than the number of unique station coordinates, the function suspects nominal station positions and issues a warning.

Value

A data frame with distinct station names and their corresponding latitude/longitude positions, if nominal positions are suspected. Otherwise, returns NULL.

Examples

df <- data.frame(
  sample_date = rep(seq.Date(Sys.Date(), by = "day", length.out = 3), each = 2),
  station_name = rep(c("ST1", "ST2"), 3),
  sample_longitude_dd = rep(c(15.0, 16.0), 3),
  sample_latitude_dd = rep(c(58.5, 58.6), 3)
)
check_nominal_station(df)

Description

Identifies records whose coordinates fall on land, optionally applying a buffer to allow points near the coast.

Usage

check_onland(
  data,
  land = NULL,
  report = FALSE,
  buffer = 0,
  offline = FALSE,
  plot_leaflet = FALSE,
  only_bad = FALSE
)

Arguments

Details

The function supports both offline and online modes:

• Offline mode (offline = TRUE): uses a local simplified shoreline from a cached geopackage (land.gpkg). If the file does not exist, it is downloaded automatically and cached across R sessions.

• Online mode (offline = FALSE): uses the OBIS web service to determine distance to the shore.

The function assumes all coordinates are in WGS84 (EPSG:4326). Supplying coordinates in a different CRS will result in incorrect intersection tests.

Optionally, a leaflet map can be plotted. Points on land are displayed as red markers, while points in water are green. If only_bad = TRUE, only the red points (on land) are plotted.

Value

If report = TRUE, a tibble with columns:

• field: always NA (placeholder for future extension)

• level: "warning" for all flagged rows

• row: row numbers in data flagged as located on land

• message: description of the issue

If report = FALSE and plot_leaflet = FALSE, returns a subset of data with only the flagged rows. If plot_leaflet = TRUE, returns a leaflet map showing points on land (red) and in water (green), unless only_bad = TRUE, in which case only red points are plotted.

Examples

# Example data frame with coordinates
example_data <- data.frame(
  sample_latitude_dd = c(59.3, 58.1, 57.5),
  sample_longitude_dd = c(18.6, 17.5, 16.7)
)

# Report points on land with a 100 m buffer
try(report <- check_onland(example_data, report = TRUE, buffer = 100))
if (exists("report")) print(report)

# Plot all points colored by land/water
try(map <- check_onland(example_data, plot_leaflet = TRUE))

# Plot only bad points on land
try(map_bad <- check_onland(example_data, plot_leaflet = TRUE, only_bad = TRUE))

# Remove points on land by adding a buffer of 2000 m
try(ok <- check_onland(example_data, report = FALSE, buffer = 2000))
if (exists("ok")) print(nrow(ok))

Description

This function checks whether values for a specified parameter exceed a predefined threshold. Thresholds are provided in a dataframe (default .threshold_values), which should contain columns for parameter, datatype, and at least one numeric threshold column (e.g., extreme_upper). Only rows in data matching both the parameter and delivery_datatype (datatype) are considered. Optionally, data can be grouped by a custom column (e.g., location_sea_basin) when thresholds vary by group.

Usage

check_outliers(
  data,
  parameter,
  datatype,
  threshold_col = "extreme_upper",
  thresholds = .threshold_values,
  custom_group = NULL,
  direction = c("above", "below"),
  return_df = FALSE,
  verbose = TRUE
)

Arguments

Details

• Only rows in data matching both parameter and delivery_datatype are checked.

• If custom_group is specified, thresholds are applied per group.

• If threshold_col does not exist in thresholds, the function stops with a warning.

• Values exceeding (or below) the threshold are flagged as outliers.

• Intended for interactive use in Shiny apps where threshold_col can be selected dynamically.

Value

If outliers are found, returns a DT::datatable or a data.frame (if return_df = TRUE) containing: datatype, station_name, sample_date, sample_id, parameter, value, threshold, and custom_group if specified. Otherwise, prints a message indicating that values are within the threshold range (if verbose = TRUE) and returns invisible(NULL).

See Also

get_shark_statistics() for preparing updated threshold data.

Examples

# Minimal example dataset
example_data <- dplyr::tibble(
  station_name = c("S1", "S2"),
  sample_date = as.Date(c("2025-01-01", "2025-01-02")),
  sample_id = 1:2,
  shark_sample_id_md5 = letters[1:2],
  sample_min_depth_m = c(0, 5),
  sample_max_depth_m = c(1, 6),
  parameter = c("Param1", "Param1"),
  value = c(5, 12),
  delivery_datatype = c("TypeA", "TypeA")
)

example_thresholds <- dplyr::tibble(
  parameter = "Param1",
  datatype = "TypeA",
  extreme_upper = 10,
  mild_upper = 8
)

# Check for values above "extreme_upper"
check_outliers(
  data = example_data,
  parameter = "Param1",
  datatype = "TypeA",
  threshold_col = "extreme_upper",
  thresholds = example_thresholds,
  return_df = TRUE
)

# Check for values above "mild_upper"
check_outliers(
  data = example_data,
  parameter = "Param1",
  datatype = "TypeA",
  threshold_col = "mild_upper",
  thresholds = example_thresholds,
  return_df = TRUE
)

Description

Applies parameter-specific and row-wise logical rules to benthos/epibenthos data, flagging measurements that violate defined conditions. This function replaces multiple deprecated ⁠check_*_logical()⁠ functions with a general, flexible implementation.

Usage

check_parameter_rules(
  data,
  param_conditions = get(".param_conditions", envir = asNamespace("SHARK4R")),
  rowwise_conditions = get(".rowwise_conditions", envir = asNamespace("SHARK4R")),
  return_df = FALSE,
  return_logical = FALSE,
  verbose = TRUE
)

Arguments

Details

This function evaluates each parameter in param_conditions and rowwise_conditions. Only parameters present in the dataset are checked. Messages are printed indicating whether values are within expected ranges or which rows violate rules.

Value

A named list of results for each parameter:

Logical vector

If return_logical = TRUE.

Data frame

If return_df = TRUE and violations exist.

DT datatable

If violations exist and return_df = FALSE.

NULL

If no violations exist for the parameter.

Invisible return.

Examples

df <- data.frame(
  station_name = c("A1", "A2", "A3", "A4"),
  sample_date = as.Date("2023-05-01") + 0:3,
  sample_id = 101:104,
  parameter = c("Wet weight", "Wet weight", "Abundance", "BQIm"),
  value = c(0, 5, 0, 3)
)

# Check against default package rules
check_parameter_rules(df)

# Return problematic rows as data.frame
check_parameter_rules(df, return_df = TRUE)

# Return logical vectors for each parameter
rule_check <- check_parameter_rules(df, return_logical = TRUE)
print(rule_check)

Description

This function downloads the products folder from the SHARK4R GitHub repository and places them in a user-specified directory. These folders contain Shiny applications and R Markdown documents used for quality control (QC) of SHARK data.

Usage

check_setup(path, run_app = FALSE, force = FALSE, verbose = TRUE)

Arguments

Details

If the path folders already exist, the download will be skipped unless force = TRUE is specified. Optionally, the function can launch the QC Shiny app directly after setup.

Value

An (invisible) list with the path to the local products folder:

Examples

# Download support files into a temporary directory
try(check_setup(path = tempdir()))

# Force re-download if already present
try(check_setup(path = tempdir(), force = TRUE))

# Download and run the QC Shiny app
if(interactive()){
 try(check_setup(path = tempdir(), run_app = TRUE))
}

Description

Matches reported station names against the SMHI curated station list ("station.txt") and checks whether matched stations fall within pre-defined distance limits. This helps ensure that station assignments are spatially consistent.

Usage

check_station_distance(
  data,
  station_file = NULL,
  plot_leaflet = FALSE,
  try_synonyms = TRUE,
  fallback_crs = 4326,
  only_bad = FALSE,
  verbose = TRUE
)

Arguments

Details

Optionally, a leaflet map of stations can be plotted. SMHI stations that match the reported data are shown as blue circles, with their allowed radius visualized and displayed in the popup (e.g., "ST1 (Radius: 1000 m)"). Reported stations are shown as markers colored by whether they fall within the radius (green), outside the radius (red), or unmatched (gray).

If try_synonyms = TRUE, the function will attempt a second match using the SYNONYM_NAMES column in the station database, splitting multiple synonyms separated by <or>.

The function first checks if a station file path is provided via the station_file argument. If not, it looks for the NODC_CONFIG environment variable. This variable can point to a folder where the NODC (Swedish National Oceanographic Data Center) configuration and station file are stored, typically including:

• <NODC_CONFIG>/config/station.txt

If NODC_CONFIG is set and the folder exists, the function will use station.txt from that location. Otherwise, it falls back to the bundled station.zip included in the SHARK4R package.

Value

If plot_leaflet = FALSE, returns a data frame with columns:

station_name

Reported station name.

match_type

TRUE if station matched in SMHI list, FALSE otherwise.

distance_m

Distance in meters from reported station to matched SMHI station.

within_limit

TRUE if distance <= allowed radius, FALSE if outside, NA if unmatched.

If plot_leaflet = TRUE, the function produces a leaflet map showing:

• Blue circles for SMHI stations with radius in the popup.

• Reported stations colored by status: green (within radius), red (outside radius), gray (unmatched).

• If only_bad = TRUE, only the red stations (outside radius) are displayed.

Examples

# Example data
df <- data.frame(
  station_name = c("ANHOLT E", "BY5 BORNHOLMSDJ", "NEW STATION"),
  sample_longitude_dd = c(12.1, 15.97, 17.5),
  sample_latitude_dd  = c(56.7, 55.25, 58.7)
)

# Check station distance
try(check_station_distance(df, try_synonyms = TRUE, verbose = FALSE))

# Plot bad points in leaflet map
try(map <- check_station_distance(df,
                              plot_leaflet = TRUE,
                              only_bad = TRUE,
                              verbose = FALSE))

Description

This function checks whether entries in the value column of a dataset are valid numeric or logical values. It is particularly useful for identifying common data entry errors such as inequality symbols (<, >) or unintended text strings (e.g., "NA", "below detection"). The function reports any invalid entries in an interactive DT::datatable for easy inspection.

Usage

check_value_logical(data, return_df = FALSE)

Arguments

Value

A DT::datatable or data frame listing unique invalid entries, or NULL (invisibly) if all values are correctly formatted as numeric or logical.

Examples

# Example dataset with mixed valid and invalid values
df <- data.frame(
  station_name = c("A", "B", "C", "D", "E"),
  value = c("3.4", "<0.2", "TRUE", "NA", "5e-3")
)

# Check for invalid (non-numeric / non-logical) entries
check_value_logical(df, return_df = TRUE)

# Example with all valid numeric and logical values
df_valid <- data.frame(value = c(1.2, 0, TRUE, FALSE, 3.5))
check_value_logical(df_valid)

Description

This function inspects a dataset containing sample coordinates to identify potential issues where longitude or latitude values are zero (0), which typically indicate missing or erroneous station positions. The function can return a summary table, a filtered data frame, or a logical vector highlighting problematic rows. It is useful as a data quality control step before spatial analyses or database imports.

Usage

check_zero_positions(
  data,
  coord = "longitude",
  return_df = FALSE,
  return_logical = FALSE,
  verbose = TRUE
)

Arguments

Value

A DT datatable, a data.frame, a logical vector, or NULL (if no problems found and return_logical = FALSE).

Examples

# Example data
df <- data.frame(
  station_name = c("A", "B", "C"),
  sample_longitude_dd = c(15.2, 0, 18.7),
  sample_latitude_dd = c(56.3, 58.1, 0)
)

# Check for zeroes in both coordinates and return as data.frame
check_zero_positions(df, coord = "both", return_df = TRUE)

# Return a logical vector instead of a table
check_zero_positions(df, coord = "both", return_logical = TRUE)

Description

This function scans a dataset for cases where the measurement column (value) contains zero (0) values, which may indicate missing, censored, or erroneous data. It returns either a DT::datatable for easy inspection or a plain data.frame of the affected rows. This function is useful for quality control and validation prior to data aggregation, reporting, or database submission.

Usage

check_zero_value(data, return_df = FALSE)

Arguments

Value

A DT datatable or a data.frame of zero-value records, or NULL (invisibly) if no zero values are found.

Examples

# Example dataset
df <- data.frame(
  station_name = c("A", "B", "C", "D"),
  sample_date = as.Date(c("2023-06-01", "2023-06-02", "2023-06-03", "2023-06-04")),
  value = c(3.2, 0, 1.5, 0)
)

# Return a plain data.frame of zero-value records
check_zero_value(df, return_df = TRUE)

Description

Deletes cached files in the SHARK4R cache directory that are older than a specified number of days.

Usage

clean_shark4r_cache(
  days = 1,
  cache_dir = NULL,
  clear_perm_cache = FALSE,
  search_pattern = NULL,
  verbose = TRUE
)

Arguments

Details

The cache is automatically cleared for files older than 24 hours. Files in the perm subdirectory are not removed automatically and must be cleared explicitly using clear_perm_cache = TRUE.

Value

Invisible NULL. Messages are printed about what was deleted and whether the in-memory session cache was cleared.

See Also

get_peg_list(), get_nomp_list(), get_shark_codes(), get_dyntaxa_dwca(), get_shark_statistics() for functions that populate the cache.

Examples

# Remove files older than 60 days and clear session cache
  try(clean_shark4r_cache(days = 60))

Description

This function constructs a taxonomy table based on Dyntaxa taxon IDs. It queries the SLU Artdatabanken API (Dyntaxa) to fetch taxonomy information and organizes the data into a hierarchical table.

Usage

construct_dyntaxa_table(
  taxon_ids,
  subscription_key = Sys.getenv("DYNTAXA_KEY"),
  shark_output = TRUE,
  add_parents = TRUE,
  add_descendants = FALSE,
  add_descendants_rank = "genus",
  add_synonyms = TRUE,
  add_missing_taxa = FALSE,
  add_hierarchy = FALSE,
  verbose = TRUE,
  add_genus_children = deprecated(),
  recommended_only = deprecated(),
  parent_ids = deprecated()
)

Arguments

Details

A valid Dyntaxa API subscription key is required. You can request a free key for the "Taxonomy" service from the ArtDatabanken API portal: https://api-portal.artdatabanken.se/

Note: Please review the API conditions and register for access before using the API. Data collected through the API is stored at SLU Artdatabanken. Please also note that the authors of SHARK4R are not affiliated with SLU Artdatabanken.

Value

A tibble representing the constructed taxonomy table.

See Also

get_worms_taxonomy_tree for an equivalent WoRMS function

SLU Artdatabanken API Documentation

Examples

## Not run: 
# Construct Dyntaxa taxonomy table for taxon IDs 238366 and 1010380
taxon_ids <- c(238366, 1010380)
taxonomy_table <- construct_dyntaxa_table(taxon_ids, "your_subscription_key")
print(taxonomy_table)

## End(Not run)

Description

This function converts geographic coordinates provided in the DDMM format (degrees and minutes) to decimal degrees. It can handle:

• DDMM (e.g., 5733 to 57°33' to 57.55°)

• DDMMss or DDMMss… (extra digits after minutes are interpreted as fractional minutes, e.g., 573345 to 57°33.45' to 57.5575°)

Usage

convert_ddmm_to_dd(coord)

Arguments

Details

Non-numeric characters are removed before conversion. Coordinates shorter than 4 digits are returned as NA.

Value

A numeric vector of decimal degrees corresponding to the input coordinates. Names from the input vector are removed.

Examples

# Basic DDMM input
convert_ddmm_to_dd(c(5733, 6045))
# Input with fractional minutes
convert_ddmm_to_dd(c("573345", "604523"))
# Input with non-numeric characters
convert_ddmm_to_dd(c("57°33'", "60°45'23\""))

Description

Draws a pie chart at each station on a map. When pies would overlap in crowded regions, the pies are displaced asymmetrically away from their true station coordinates and a leader line + anchor dot is drawn so the viewer can still tell which pie belongs to which station. Works with any grouping (phytoplankton groups, zooplankton orders, microbial phyla, ...) and any numeric value (biomass, biovolume, abundance, ...).

Usage

create_pie_map(
  data,
  station_col = "station_name",
  lon_col = "sample_longitude_dd",
  lat_col = "sample_latitude_dd",
  group_col = "group",
  value_col = "value",
  label_col = station_col,
  group_levels = NULL,
  group_colors = NULL,
  group_labels = NULL,
  radius = 0.28,
  size_by = NULL,
  size_range = c(0.15, 0.4),
  repel = TRUE,
  min_sep = 2.4,
  min_disp = 1.6,
  show_labels = TRUE,
  label_size = 3,
  pie_border_color = "white",
  pie_border_width = 0.3,
  leader_color = "gray20",
  leader_width = 0.5,
  anchor_color = "gray10",
  anchor_fill = "white",
  anchor_size = 1.8,
  basemap = NULL,
  basemap_source = c("ne", "eea", "obis"),
  basemap_scale = "medium",
  basemap_fill = "gray95",
  basemap_border = "gray70",
  sea_color = "aliceblue",
  xlim = NULL,
  ylim = NULL,
  pad = 1,
  title = NULL,
  legend_title = "Group",
  verbose = TRUE
)

Arguments

Details

Coastline sources available via basemap_source when basemap = NULL:

• "ne" - Natural Earth 1:10m / 1:50m / 1:110m land vectors, fetched on the fly through rnaturalearth::ne_countries(). Resolution is controlled by basemap_scale. See https://www.naturalearthdata.com. Requires the rnaturalearth and rnaturalearthdata packages (both Suggests).

• "eea" - high-resolution European coastline from the European Environment Agency (EEA Coastline 2017). Best choice for detailed regional maps of European waters. Downloaded chunked from the EEA arcgis service the first time and cached locally. Dataset metadata: https://sdi.eea.europa.eu/catalogue/datahub/api/records/9faa6ea1-372a-4826-a3c7-fb5b05e31c52/formatters/xsl-view?output=pdf&language=eng&approved=true.

• "obis" - global land polygon distributed by the Ocean Biodiversity Information System, downloaded from https://obis-resources.s3.amazonaws.com/land.gpkg.

The "eea" and "obis" datasets are cached across sessions and can be cleared with clean_shark4r_cache().

Value

A ggplot object.

Examples

# Six SHARK monitoring stations spanning the Swedish west coast,
# Kattegat, and Baltic Proper. Note that SLÄGGÖ and Å17 sit close
# enough on the Skagerrak shelf that their pies will be repelled and
# drawn with leader lines.
stations <- dplyr::tibble(
  station_name = rep(c("SLÄGGÖ", "Å17", "ANHOLT E", "BY2 ARKONA",
                       "BY31 LANDSORTSDJ", "BY38 KARLSÖDJ"), each = 4),
  sample_latitude_dd  = rep(c(58.25984, 58.28434, 56.66866, 54.97116,
                              58.59366, 57.11717), each = 4),
  sample_longitude_dd = rep(c(11.43567, 10.50432, 12.11117, 14.09883,
                              18.23633, 17.66867), each = 4),
  group = rep(c("Diatoms", "Dinoflagellates",
                "Cyanobacteria", "Other"), 6),
  value = c( 60, 25, 10,  5,   # SLÄGGÖ
             55, 30,  5, 10,   # Å17
             40, 45,  5, 10,   # ANHOLT E
             15, 20, 55, 10,   # BY2 ARKONA
             20, 25, 45, 10,   # BY31 LANDSORTSDJ
             25, 20, 45, 10)   # BY38 KARLSÖDJ
)

# The default basemap uses `rnaturalearth` + `rnaturalearthdata` (both
# Suggests); each example below is guarded by a single-line check so the
# plots render inline rather than all at once after a large `if` block.
has_basemap <- requireNamespace("rnaturalearth",     quietly = TRUE) &&
               requireNamespace("rnaturalearthdata", quietly = TRUE)


# 1. Uniform pie size, default palette, automatic map extent.
if (has_basemap) create_pie_map(stations)

# 2. Scale pie radius by the station's total value (`size_by = "total"`):
#    stations with larger summed biomass get bigger pies. `size_range`
#    controls the smallest/largest radius (in latitude degrees). Pie
#    sizes are relative within the plot only; no size legend is drawn.
if (has_basemap) create_pie_map(
  stations,
  size_by      = "total",
  size_range   = c(0.20, 0.55),
  group_colors = c(Diatoms         = "#4A90D9",
                   Dinoflagellates = "#E74C3C",
                   Cyanobacteria   = "#14B8A6",
                   Other           = "#95A5A6"),
  legend_title = "Taxon group",
  title        = "Phytoplankton composition (pie size = total biomass)"
)

# 3. Scale pie radius by an external per-station metric. Here we add a
#    fake chlorophyll-a column and pass its name to `size_by` - any
#    numeric per-station column in `data` works (e.g. secchi depth,
#    cell counts, nutrient concentrations).
stations$chla <- rep(c(3.1, 2.8, 4.2, 1.1, 1.5, 1.3), each = 4)
if (has_basemap) create_pie_map(
  stations,
  size_by      = "chla",
  size_range   = c(0.18, 0.50),
  legend_title = "Taxon group",
  title        = "Pie size scaled by chlorophyll-a"
)

# 4. Use the high-resolution EEA coastline instead of the Natural Earth
#    default. The first call downloads the EEA polygon and caches it
#    for re-use; subsequent calls are fast. `basemap_scale` is ignored
#    for EEA. Suitable for regional European maps where Natural Earth's
#    coastline is too coarse.
try(create_pie_map(
  stations,
  basemap_source = "eea",
  legend_title   = "Taxon group",
  title          = "High-resolution EEA coastline",
  verbose        = FALSE
))

Description

Identifies which columns are mandatory in the SHARK delivery template based on rows starting with "*" (one or more). You can specify how many levels of asterisks to include.

Usage

find_required_fields(
  datatype,
  stars = 1,
  bacterioplankton_subtype = "abundance"
)

Arguments

Details

Note: A single "*" marks required fields in the standard SHARK template. A double "**" is often used to specify columns required for national monitoring only. For more information, see: https://www.smhi.se/data/hav-och-havsmiljo/datavardskap-oceanografi-och-marinbiologi/leverera-data

Value

A character vector of column names that are required in the template.

Examples

# Only single "*" required columns
try(find_required_fields("Bacterioplankton"))

# Include both "*" and "**" required columns (national monitoring too)
try(find_required_fields("Bacterioplankton", stars = 2))

# Include up to three levels of "*"
try(find_required_fields("Phytoplankton", stars = 3))

Description

Downloads and reads the SHARK Excel delivery template for a given datatype. The template contains the column definitions and headers used for submission.

Usage

get_delivery_template(
  datatype,
  sheet = "Kolumner",
  header_row = 4,
  skip = 1,
  bacterioplankton_subtype = "abundance",
  force = FALSE,
  clean_cache_days = 1
)

Arguments

Value

A tibble containing the delivery template. Column names are set from the header row.

Examples

# Bacterioplankton abundance
try(abun <- get_delivery_template("Bacterioplankton",
                              bacterioplankton_subtype = "abundance"))

if (exists("abun")) print(abun)

# Bacterioplankton production
try(prod <- get_delivery_template("Bacterioplankton",
                              bacterioplankton_subtype = "production"))

# Phytoplankton template
try(phyto <- get_delivery_template("Phytoplankton"))

# Phytoplankton column explanation (sheet number 3)
try(phyto_column_explanation <- get_delivery_template("Phytoplankton",
                                                  sheet = 3,
                                                  header_row = 4,
                                                  skip = 3))

if (exists("phyto_column_explanation")) print(phyto_column_explanation)

Description

This function downloads a complete Darwin Core Archive (DwCA) of Dyntaxa from the SLU Artdatabanken API, extracts the archive, and reads the specified CSV file into R.

Usage

get_dyntaxa_dwca(
  subscription_key = Sys.getenv("DYNTAXA_KEY"),
  file_to_read = "Taxon.csv",
  force = FALSE,
  verbose = TRUE
)

Arguments

Details

By default, the archive is downloaded and cached across R sessions. On subsequent calls, the function reuses the cached copy of the extracted files to avoid repeated downloads. Use the force parameter to re-download the archive if needed. The cache is cleared automatically after 24 hours, but you can also manually clear it using clean_shark4r_cache.

A valid Dyntaxa API subscription key is required. You can request a free key for the "Taxonomy" service from the ArtDatabanken API portal: https://api-portal.artdatabanken.se/

Note: Please review the API conditions and register for access before using the API. Data collected through the API is stored at SLU Artdatabanken. Please also note that the authors of SHARK4R are not affiliated with SLU Artdatabanken.

Value

A tibble containing the data from the specified CSV file.

See Also

clean_shark4r_cache() to manually clear cached files.

Examples

## Not run: 
# Provide your Dyntaxa API subscription key
subscription_key <- "your_subscription_key"

# Download and read the Taxon.csv file
taxon_data <- get_dyntaxa_dwca(subscription_key, file_to_read = "Taxon.csv")

## End(Not run)

Description

This function queries the SLU Artdatabanken API (Dyntaxa) to retrieve parent taxon IDs for the specified taxon IDs. It constructs a request with the provided taxon IDs, sends the request to the SLU Artdatabanken API, and processes the response to return a list of parent taxon IDs.

Usage

get_dyntaxa_parent_ids(
  taxon_ids,
  subscription_key = Sys.getenv("DYNTAXA_KEY"),
  verbose = TRUE
)

Arguments

Details

A valid Dyntaxa API subscription key is required. You can request a free key for the "Taxonomy" service from the ArtDatabanken API portal: https://api-portal.artdatabanken.se/

Note: Please review the API conditions and register for access before using the API. Data collected through the API is stored at SLU Artdatabanken. Please also note that the authors of SHARK4R are not affiliated with SLU Artdatabanken.

Value

A list containing parent taxon IDs corresponding to the specified taxon IDs.

See Also

SLU Artdatabanken API Documentation

Examples

## Not run: 
# Get parent taxon IDs for taxon IDs 238366 and 1010380
parent_ids <- get_dyntaxa_parent_ids(c(238366, 1010380), "your_subscription_key")
print(parent_ids)

## End(Not run)

Description

This function queries the SLU Artdatabanken API (Dyntaxa) to retrieve taxonomic information for the specified taxon IDs. It constructs a request with the provided taxon IDs, sends the request to the SLU Artdatabanken API, and processes the response to return taxonomic information in a data frame.

Usage

get_dyntaxa_records(taxon_ids, subscription_key = Sys.getenv("DYNTAXA_KEY"))

Arguments

Details

A valid Dyntaxa API subscription key is required. You can request a free key for the "Taxonomy" service from the ArtDatabanken API portal: https://api-portal.artdatabanken.se/

Note: Please review the API conditions and register for access before using the API. Data collected through the API is stored at SLU Artdatabanken. Please also note that the authors of SHARK4R are not affiliated with SLU Artdatabanken.

Value

A tibble containing taxonomic information for the specified taxon IDs. Columns include taxonId, names, category, rank, isRecommended, and parentTaxonId.

See Also

SLU Artdatabanken API Documentation

Examples

## Not run: 
# Get taxonomic information for taxon IDs 238366 and 1010380
taxon_info <- get_dyntaxa_records(c(238366, 1010380), "your_subscription_key")
print(taxon_info)

## End(Not run)

Description

This function retrieves the IOC-UNESCO Taxonomic Reference List of Harmful Microalgae (Lundholm et al. 2009) from the World Register of Marine Species (WoRMS). The data is returned as a dataframe, with options to customize the fields included in the download.

Usage

get_hab_list(
  species_only = TRUE,
  harmful_non_toxic_only = FALSE,
  aphia_id = TRUE,
  scientific_name = TRUE,
  authority = TRUE,
  fossil = TRUE,
  rank_name = TRUE,
  status_name = TRUE,
  qualitystatus_name = TRUE,
  modified = TRUE,
  lsid = TRUE,
  parent_id = TRUE,
  stored_path = TRUE,
  citation = TRUE,
  classification = TRUE,
  environment = TRUE,
  accepted_taxon = TRUE,
  verbose = TRUE
)

Arguments

Details

This function submits a POST request to the WoRMS database to retrieve the IOC-UNESCO Taxonomic Reference List of Harmful Microalgae. The downloaded data can include various fields, which are controlled by the input parameters. If a field is not required, set the corresponding parameter to FALSE to exclude it from the output.

Value

A tibble containing the HABs taxonomic list, with columns based on the selected parameters.

References

Lundholm, N.; Bernard, C.; Churro, C.; Escalera, L.; Hoppenrath, M.; Iwataki, M.; Larsen, J.; Mertens, K.; Murray, S.; Probert, I.; Salas, R.; Tillmann, U.; Zingone, A. (Eds) (2009 onwards). IOC-UNESCO Taxonomic Reference List of Harmful Microalgae. https://www.marinespecies.org/hab/. doi:10.14284/362

See Also

https://www.marinespecies.org/hab/ for IOC-UNESCO Taxonomic Reference List of Harmful Microalgae

Examples

# Download the default HABs taxonomic list
try(habs_taxlist_df <- get_hab_list())
if (exists("habs_taxlist_df")) head(habs_taxlist_df)

# Include higher taxa records
try(habs_taxlist_df <- get_hab_list(species_only = FALSE))
if (exists("habs_taxlist_df")) head(habs_taxlist_df)

# Retrieve only non-toxigenic harmful species (experimental stage)
try(habs_taxlist_df <- get_hab_list(harmful_non_toxic_only = TRUE, verbose = FALSE))
if (exists("habs_taxlist_df")) head(habs_taxlist_df)

# Include only specific fields in the output
try(habs_taxlist_df <- get_hab_list(aphia_id = TRUE, scientific_name = TRUE, authority = FALSE))
if (exists("habs_taxlist_df")) head(habs_taxlist_df)

Description

This function downloads the latest available Nordic Marine Phytoplankton Group (NOMP) biovolume zip archive from SMHI, unzips it, and reads the first Excel file by default. You can also specify which file in the archive to read.

Usage

get_nomp_list(
  year = as.numeric(format(Sys.Date(), "%Y")),
  file = NULL,
  sheet = NULL,
  force = FALSE,
  base_url = NULL,
  clean_cache_days = 30,
  verbose = TRUE
)

Arguments

Value

A tibble with the contents of the requested Excel file.

See Also

clean_shark4r_cache() to manually clear cached files.

Examples

# Get the latest available list
  try(nomp_list <- get_nomp_list())
  if (exists("nomp_list")) head(nomp_list)

  # Get the 2023 list and clean old cache files older than 60 days
  try(nomp_list_2023 <- get_nomp_list(2023, clean_cache_days = 60))
  if (exists("nomp_list_2023")) head(nomp_list_2023)

Description

This function retrieves external links related to algae taxa from the Nordic Microalgae API. It takes a vector of slugs (taxon identifiers) and returns a data frame containing the external links associated with each taxon. The data includes the provider, label, external ID, and the URL of the external link.

Usage

get_nua_external_links(slug, verbose = TRUE, unparsed = FALSE)

Arguments

Details

The slugs (taxon identifiers) used in this function can be retrieved using the get_nua_taxa() function, which returns a data frame with a column for taxon slugs, along with other relevant metadata for each taxon.

Value

When unparsed = FALSE: a tibble containing the following columns:

See Also

https://nordicmicroalgae.org/ for Nordic Microalgae website.

https://nordicmicroalgae.org/api/ for Nordic Microalgae API documentation.

Examples

# Retrieve external links for a vector of slugs
  slugs <- c("chaetoceros-debilis", "alexandrium-tamarense")
  try(external_links <- get_nua_external_links(
    slug = slugs, verbose = FALSE
  ))
  if (exists("external_links")) head(external_links)

Description

This function retrieves harmfulness information related to algae taxa from the Nordic Microalgae API. It takes a vector of slugs (taxon identifiers) and returns a data frame containing the harmfulness information associated with each taxon. The data includes the provider, label, external ID, and the URL of the external link.

Usage

get_nua_harmfulness(slug, verbose = TRUE)

Arguments

Details

The slugs (taxon identifiers) used in this function can be retrieved using the get_nua_taxa() function, which returns a data frame with a column for taxon slugs, along with other relevant metadata for each taxon.

Value

A tibble containing the following columns:

See Also

https://nordicmicroalgae.org/ for Nordic Microalgae website.

https://nordicmicroalgae.org/api/ for Nordic Microalgae API documentation.

Examples

# Retrieve external links for a vector of slugs
  try(harmfulness <- get_nua_harmfulness(slug = c("dinophysis-acuta",
                                              "alexandrium-ostenfeldii"),
                                     verbose = FALSE))
  if (exists("harmfulness")) print(harmfulness)

Description

This function retrieves media URLs for automated imaging images from the Nordic Microalgae API. These are images from automated imaging instruments (e.g., IFCB) used for image labeling purposes. It returns URLs for different renditions (large, medium, original, small) along with basic attribution.

Usage

get_nua_image_labeling_links(unparsed = FALSE)

Arguments

Value

When unparsed = FALSE: a tibble with the following columns:

• slug: The slug of the related taxon.

• image_l_url: The URL for the "large" rendition.

• image_o_url: The URL for the "original" rendition.

• image_s_url: The URL for the "small" rendition.

• image_m_url: The URL for the "medium" rendition.

• contributor: The contributor of the media item.

• copyright_holder: The copyright holder.

• license: The license of the media item.

• imaging_instrument: Comma-separated list of imaging instruments.

• priority: The priority of the image.

See Also

https://nordicmicroalgae.org/ for Nordic Microalgae website.

https://nordicmicroalgae.org/api/ for Nordic Microalgae API documentation.

get_nua_image_labeling_metadata for retrieving full metadata for image labeling images.

get_nua_media_links for retrieving regular media image URLs.

Examples

# Retrieve image labeling media links
try(il_links <- get_nua_image_labeling_links(unparsed = FALSE))

# Preview the extracted data
if (exists("il_links")) head(il_links)

Description

This function retrieves detailed metadata for automated imaging images from the Nordic Microalgae API. These are images from automated imaging instruments (e.g., IFCB) used for image labeling purposes. It returns comprehensive metadata including location, instrument, dataset, and taxonomic information.

Usage

get_nua_image_labeling_metadata(unparsed = FALSE)

Arguments

Value

When unparsed = FALSE: a tibble with the following columns:

• slug: The slug of the media item.

• taxon_slug: The slug of the related taxon.

• scientific_name: The scientific name of the related taxon.

• file: The filename of the media item.

• type: The MIME type of the media item.

• title: The title of the media item.

• caption: The caption of the media item.

• license: The license of the media item.

• location: The location where the media was collected.

• contributor: The contributor of the media item.

• copyright_holder: The copyright holder.

• imaging_instrument: Comma-separated list of imaging instruments.

• training_dataset: DOI or URL of the training dataset.

• sampling_date: The date the sample was collected.

• geographic_area: The geographic area of collection.

• latitude_degree: The latitude in degrees.

• longitude_degree: The longitude in degrees.

• institute: Comma-separated list of institutes.

• contributing_organisation: The contributing organisation.

• priority: The priority of the image.

• created_at: The creation timestamp.

• updated_at: The last update timestamp.

See Also

https://nordicmicroalgae.org/ for Nordic Microalgae website.

https://nordicmicroalgae.org/api/ for Nordic Microalgae API documentation.

get_nua_image_labeling_links for retrieving image labeling media URLs.

get_nua_media_metadata for retrieving regular media metadata.

Examples

# Retrieve image labeling metadata
try(il_metadata <- get_nua_image_labeling_metadata(unparsed = FALSE))

# Preview the extracted data
if (exists("il_metadata")) head(il_metadata)

Description

This function retrieves media information from the Nordic Microalgae API and extracts slugs and URLs for different renditions (large, original, small, medium) for each media item.

Usage

get_nua_media_links(unparsed = FALSE)

Arguments

Value

When unparsed = FALSE: a tibble with the following columns:

• slug: The slug of the related taxon.

• l_url: The URL for the "large" rendition.

• o_url: The URL for the "original" rendition.

• s_url: The URL for the "small" rendition.

• m_url: The URL for the "medium" rendition.

See Also

https://nordicmicroalgae.org/ for Nordic Microalgae website.

https://nordicmicroalgae.org/api/ for Nordic Microalgae API documentation.

Examples

# Retrieve media information
try(media_info <- get_nua_media_links(unparsed = FALSE))

# Preview the extracted data
if (exists("media_info")) head(media_info)

Description

This function retrieves metadata for media items from the Nordic Microalgae API. It returns detailed attributes such as title, caption, location, sampling date, geographic coordinates, and contributor information.

Usage

get_nua_media_metadata(unparsed = FALSE)

Arguments

Value

When unparsed = FALSE: a tibble with the following columns:

• slug: The slug of the media item.

• taxon_slug: The slug of the related taxon.

• scientific_name: The scientific name of the related taxon.

• file: The filename of the media item.

• type: The MIME type of the media item.

• title: The title of the media item.

• caption: The caption of the media item.

• license: The license of the media item.

• location: The location where the media was collected.

• contributor: The contributor of the media item.

• photographer_artist: The photographer or artist.

• copyright_holder: The copyright holder.

• copyright_stamp: The copyright stamp.

• galleries: Comma-separated list of galleries.

• technique: The imaging technique used.

• contrast_enhancement: The contrast enhancement method used.

• preservation: The preservation method used.

• stain: The stain used.

• sampling_date: The date the sample was collected.

• geographic_area: The geographic area of collection.

• latitude_degree: The latitude in degrees.

• longitude_degree: The longitude in degrees.

• institute: Comma-separated list of institutes.

• contributing_organisation: The contributing organisation.

• created_at: The creation timestamp.

• updated_at: The last update timestamp.

See Also

https://nordicmicroalgae.org/ for Nordic Microalgae website.

https://nordicmicroalgae.org/api/ for Nordic Microalgae API documentation.

get_nua_media_links for retrieving media image URLs.

Examples

# Retrieve media metadata
try(media_metadata <- get_nua_media_metadata(unparsed = FALSE))

# Preview the extracted data
if (exists("media_metadata")) head(media_metadata)

Description

This function retrieves all taxonomic information for algae taxa from the Nordic Microalgae API. It fetches details including scientific names, authorities, ranks, and image URLs (in different sizes: large, medium, original, and small).

Usage

get_nua_taxa(unparsed = FALSE)

Arguments

Value

When unparsed = FALSE: a tibble containing the following columns:

See Also

https://nordicmicroalgae.org/ for Nordic Microalgae website.

https://nordicmicroalgae.org/api/ for Nordic Microalgae API documentation.

Examples

# Retrieve and display taxa data
  try(taxa_data <- get_nua_taxa(unparsed = FALSE))
  if (exists("taxa_data")) head(taxa_data)

Description

This function downloads the EG-Phyto (previously PEG) biovolume zip archive from ICES (using cache_peg_zip()), unzips it, and reads the first Excel file by default. You can also specify which file in the archive to read.

Usage

get_peg_list(
  file = NULL,
  sheet = NULL,
  force = FALSE,
  url = "https://www.ices.dk/data/Documents/ENV/PEG_BVOL.zip",
  clean_cache_days = 30,
  verbose = TRUE
)

Arguments

Value

A tibble with the contents of the requested Excel file.

See Also

clean_shark4r_cache() to manually clear cached files.

Examples

# Read the first Excel file from the PEG zip
  try(peg_list <- get_peg_list())
  if (exists("peg_list")) head(peg_list)

Description

This function downloads the SHARK codes Excel file from SMHI (if not already cached) and reads it into R. The file is stored in a persistent cache directory so it does not need to be downloaded again in subsequent sessions.

Usage

get_shark_codes(
  url =
    "https://smhi.se/oceanografi/oce_info_data/shark_web/downloads/codelist_SMHI.xlsx",
  sheet = 1,
  skip = 1,
  force = FALSE,
  clean_cache_days = 30
)

Arguments

Value

A tibble containing the contents of the requested sheet.

See Also

clean_shark4r_cache() to manually clear cached files.

Examples

# Read the first sheet, skipping the first row
  try(codes <- get_shark_codes())
  if (exists("codes")) head(codes)

  # Force re-download of the Excel file
  try(codes <- get_shark_codes(force = TRUE))

Description

The get_shark_data() function retrieves tabular data from the SHARK database hosted by SMHI. The function sends a POST request to the SHARK API with customizable filters, including year, month, taxon name, water category, and more, and returns the retrieved data as a structured tibble. To view available filter options, see get_shark_options.

Usage

get_shark_data(
  tableView = "sharkweb_overview",
  headerLang = "internal_key",
  save_data = FALSE,
  file_path = NULL,
  delimiters = "point-tab",
  lineEnd = "win",
  encoding = "utf_8",
  dataTypes = c(),
  bounds = c(),
  fromYear = NULL,
  toYear = NULL,
  months = c(),
  parameters = c(),
  checkStatus = "",
  qualityFlags = c(),
  deliverers = c(),
  orderers = c(),
  projects = c(),
  datasets = c(),
  minSamplingDepth = "",
  maxSamplingDepth = "",
  redListedCategory = c(),
  taxonName = c(),
  stationName = c(),
  vattenDistrikt = c(),
  seaBasins = c(),
  counties = c(),
  municipalities = c(),
  waterCategories = c(),
  typOmraden = c(),
  helcomOspar = c(),
  seaAreas = c(),
  hideEmptyColumns = FALSE,
  row_limit = 10^7,
  prod = TRUE,
  utv = FALSE,
  verbose = TRUE
)

Arguments

Details

This function sends a POST request to the SHARK API with the specified filters. The API returns a delimited text file (e.g., tab- or semicolon-separated), which is downloaded and read into R as a tibble. If the row_limit parameter is exceeded, the data is retrieved in yearly chunks and combined into a single table. Adjusting the row_limit parameter may be necessary when retrieving large datasets or detailed reports. Note that making very large requests (e.g., retrieving the entire SHARK database) can be extremely time- and memory-intensive.

Value

A tibble containing the retrieved SHARK data, parsed from the API's delimited text response. Column types are inferred automatically.

Note

For large queries spanning multiple years or including several data types, retrieval can be time-consuming and memory-intensive. Consider filtering by year, data type, or region for improved performance.

See Also

• https://shark.smhi.se/en – SHARK database portal

• get_shark_options() – Retrieve available filters

• get_shark_table_counts() – Check table row counts before download

• get_shark_datasets() – To download datasets as zip-archives

Examples

# Retrieve chlorophyll data from 2019 to 2020 for April to June
  try(shark_data <- get_shark_data(fromYear = 2019, toYear = 2020,
                               months = c(4, 5, 6), dataTypes = "Chlorophyll",
                               verbose = FALSE))
  if (exists("shark_data")) print(shark_data)

Description

Downloads one or more datasets (zip-archives) from the SHARK database (Swedish national marine environmental data archive) and optionally unzips them. The function matches provided dataset names against all available SHARK datasets.

Usage

get_shark_datasets(
  dataset_name,
  save_dir = NULL,
  prod = TRUE,
  utv = FALSE,
  unzip_file = FALSE,
  return_df = FALSE,
  encoding = "latin_1",
  guess_encoding = TRUE,
  verbose = TRUE
)

Arguments

Value

If return_df = FALSE, a named list of character vectors. Each element corresponds to one matched dataset and contains either the path to the downloaded zip file (if unzip_file = FALSE) or the path to the extraction directory (if unzip_file = TRUE). If return_df = TRUE, a single combined data frame with all dataset contents, including a source column indicating the dataset.

See Also

https://shark.smhi.se/en for SHARK database.

get_shark_options() for listing available datasets.

get_shark_data() for downloading tabular data.

Examples

# Get a specific dataset
try(get_shark_datasets("SHARK_Phytoplankton_2023_SMHI_BVVF", verbose = FALSE))

# Get all Zooplankton datasets from 2022 and unzip them
try(get_shark_datasets(
  dataset_name = "Zooplankton_2022",
  unzip_file = TRUE,
  verbose = FALSE
))

# Get all Chlorophyll datasets and return as a combined data frame
try(combined_df <- get_shark_datasets(
  dataset_name = "Chlorophyll",
  return_df = TRUE,
  verbose = FALSE
))
if (exists("combined_df")) head(combined_df)

Description

The get_shark_options() function retrieves available search options from the SHARK database. It sends a GET request to the SHARK API and returns the results as a structured named list.

Usage

get_shark_options(prod = TRUE, utv = FALSE, unparsed = FALSE)

Arguments

Details

This function sends a GET request to the ⁠/api/options⁠ endpoint of the SHARK API to retrieve available search filters and options that can be used in SHARK data queries.

Value

A named list of available search options from the SHARK API. If unparsed = TRUE, returns the raw JSON structure as a list.

See Also

get_shark_data() for retrieving actual data from the SHARK API.

https://shark.smhi.se/en for the SHARK database portal.

Examples

# Retrieve available search options (simplified)
  try(shark_options <- get_shark_options())
  if (exists("shark_options")) names(shark_options)

  # Retrieve full unparsed JSON response
  try(raw_options <- get_shark_options(unparsed = TRUE))

  # View available datatypes
  if (exists("shark_options")) print(shark_options$dataTypes)

Description

Downloads SHARK data for a given time period, filters to numeric parameters, and calculates descriptive statistics and Tukey outlier thresholds.

Usage

get_shark_statistics(
  fromYear = NULL,
  toYear = NULL,
  datatype = NULL,
  group_col = NULL,
  min_obs = 3,
  max_non_numeric_frac = 0.05,
  cache_result = FALSE,
  prod = TRUE,
  utv = FALSE,
  verbose = TRUE
)

Arguments

Details

By default, the function uses the previous five complete years. For example, if called in 2025 it will use data from 2020–2024.

Value

A tibble with one row per parameter (and optionally per group) and the following columns:

parameter

Parameter name (character).

datatype

SHARK datatype (character).

min, Q1, median, Q3, max

Observed quantiles.

P01, P05, P95, P99

1st, 5th, 95th and 99th percentiles.

IQR

Interquartile range.

mean

Arithmetic mean of numeric values.

sd

Standard deviation of numeric values.

var

Variance of numeric values.

cv

Coefficient of variation (sd / mean).

mad

Median absolute deviation.

mild_lower, mild_upper

Lower/upper bounds for mild outliers (1.5 × IQR).

extreme_lower, extreme_upper

Lower/upper bounds for extreme outliers (3 × IQR).

n

Number of numeric observations used.

fromYear

First year included in the SHARK data download (numeric).

toYear

Last year included in the SHARK data download (numeric).

<group_col>

Optional grouping column if provided.

Examples

# Uses previous 5 years automatically, Chlorophyll data only
try(res <- get_shark_statistics(datatype = "Chlorophyll", verbose = FALSE))
if (exists("res")) print(res)

# Group by station name and save result in persistent cache
try(res_station <- get_shark_statistics(datatype = "Chlorophyll",
                                    group_col = "station_name",
                                    cache_result = TRUE,
                                    verbose = FALSE))
if (exists("res_station")) print(res_station)

Description

The get_shark_table_counts() function retrieves the number of records (row counts) from various SHARK data tables based on specified filters such as year, months, data type, stations, and taxa. To view available filter options, see get_shark_options.

Usage

get_shark_table_counts(
  tableView = "sharkweb_overview",
  fromYear = 2019,
  toYear = 2020,
  months = c(),
  dataTypes = c(),
  parameters = c(),
  orderers = c(),
  qualityFlags = c(),
  deliverers = c(),
  projects = c(),
  datasets = c(),
  minSamplingDepth = "",
  maxSamplingDepth = "",
  checkStatus = "",
  redListedCategory = c(),
  taxonName = c(),
  stationName = c(),
  vattenDistrikt = c(),
  seaBasins = c(),
  counties = c(),
  municipalities = c(),
  waterCategories = c(),
  typOmraden = c(),
  helcomOspar = c(),
  seaAreas = c(),
  prod = TRUE,
  utv = FALSE
)

Arguments

Value

An integer representing the total number of rows in the requested SHARK table after applying the specified filters.

See Also

https://shark.smhi.se/en for SHARK database.

get_shark_options to see filter options

get_shark_data to download SHARK data

Examples

# Retrieve chlorophyll data for April to June from 2019 to 2020
  try(shark_data_counts <- get_shark_table_counts(fromYear = 2019, toYear = 2020,
                                              months = c(4, 5, 6), dataTypes = c("Chlorophyll")))
  if (exists("shark_data_counts")) print(shark_data_counts)

Description

This function collects data from the IOC-UNESCO Toxins Database and returns information about toxins.

Usage

get_toxin_list(return_count = FALSE, insecure = FALSE)

Arguments

Details

The TLS certificate for toxins.hais.ioc-unesco.org may occasionally lapse. When this happens the default (secure) request fails with a certificate error. The insecure argument provides a deliberate, opt-in escape hatch: in an interactive session the function prompts before retrying without verification, while a non-interactive session aborts and instructs the caller to set insecure = TRUE. Only disable verification when you have confirmed that the failure is caused by the known certificate issue, as it removes protection against a tampered or spoofed response.

Value

If return_count = TRUE, the function returns a numeric value representing the number of toxins in the database. Otherwise, it returns a tibble of toxins with detailed information.

See Also

https://toxins.hais.ioc-unesco.org/ for IOC-UNESCO Toxins Database.

Examples

# Retrieve the full list of toxins
try(toxin_list <- get_toxin_list())
if (exists("toxin_list")) head(toxin_list)

# Retrieve only the count of toxins
try(toxin_count <- get_toxin_list(return_count = TRUE))
if (exists("toxin_count")) print(toxin_count)

# If the server's TLS certificate has expired, the verification step can be
# bypassed explicitly. Only do this when the certificate issue is known and
# trusted, as it disables protection against tampering.
try(toxin_list <- get_toxin_list(insecure = TRUE))
if (exists("toxin_list")) head(toxin_list)

Description

Retrieves the hierarchical taxonomy for one or more AphiaIDs from the World Register of Marine Species (WoRMS) and returns it in a wide format. Optionally, a hierarchy string column can be added that concatenates ranks.

Usage

get_worms_classification(
  aphia_ids,
  add_rank_to_hierarchy = FALSE,
  verbose = TRUE
)

Arguments

Details

The function performs the following steps:

1. Validates input AphiaIDs and removes NA values.

2. Retrieves the hierarchical classification for each AphiaID using worrms::wm_classification().

3. Converts the hierarchy to a wide format with one column per rank.

4. Adds a worms_hierarchy string concatenating all ranks.

5. Preserves input order and duplicates.

Value

A tibble where each row corresponds to an input AphiaID. Typical columns include:

aphia_id

The AphiaID of the taxon (matches input).

scientific_name

The last scientific name in the hierarchy for this AphiaID.

taxonomic ranks

Columns for each rank present in the WoRMS hierarchy (e.g., Kingdom, Phylum, Class, Order, Family, Genus, Species). Missing ranks are NA.

worms_hierarchy

A concatenated string of all ranks for this AphiaID. Added for every row if wm_classification() returned hierarchy data. Format depends on add_rank_to_hierarchy.

See Also

wm_classification, https://marinespecies.org/

Examples

# Single AphiaID
try(single_taxa <- get_worms_classification(109604, verbose = FALSE))
if (exists("single_taxa")) print(single_taxa)

# Multiple AphiaIDs
try(multiple_taxa <- get_worms_classification(c(109604, 376667), verbose = FALSE))
if (exists("multiple_taxa")) print(multiple_taxa)

# Hierarchy with ranks in the string
try(with_rank <- get_worms_classification(c(109604, 376667),
                                      add_rank_to_hierarchy = TRUE,
                                      verbose = FALSE))

# Print hierarchy columns with ranks
if (exists("with_rank")) print(with_rank$worms_hierarchy[1])

# Compare with result when add_rank_to_hierarchy = FALSE
if (exists("multiple_taxa")) print(multiple_taxa$worms_hierarchy[1])