iRfcb (version 0.5.2)

ifcb_extract_biovolumes: Extract Biovolumes from IFCB Data and Compute Carbon Content

Description

This function reads biovolume data from feature files generated by the ifcb-analysis repository (Sosik and Olson 2007) and matches them with corresponding classification results or manual annotations. It calculates biovolume in cubic micrometers and determines if each class is a diatom based on the World Register of Marine Species (WoRMS). Carbon content is computed for each region of interest (ROI) using conversion functions from Menden-Deuer and Lessard (2000), depending on whether the class is identified as a diatom.

Usage

ifcb_extract_biovolumes(
  feature_files,
  mat_folder = NULL,
  custom_images = NULL,
  custom_classes = NULL,
  class2use_file = NULL,
  micron_factor = 1/3.4,
  diatom_class = "Bacillariophyceae",
  marine_only = FALSE,
  threshold = "opt",
  multiblob = FALSE,
  feature_recursive = TRUE,
  mat_recursive = TRUE,
  drop_zero_volume = FALSE,
  use_python = FALSE,
  verbose = TRUE
)

Value

A data frame containing:

• sample: The sample name.

• classifier: The classifier used (if applicable).

• roi_number: The region of interest (ROI) number.

• class: The identified taxonomic class.

• biovolume_um3: Computed biovolume in cubic micrometers.

• carbon_pg: Estimated carbon content in picograms.

Arguments

feature_files

A path to a folder containing feature files or a character vector of file paths.

mat_folder

(Optional) Path to the folder containing class or manual annotation files.

custom_images

(Optional) A character vector of image filenames in the format DYYYYMMDDTHHMMSS_IFCBXXX_ZZZZZ.png, where "XXX" represents the IFCB number and "ZZZZZ" represents the ROI number. These filenames should match the roi_number assignment in the feature_files and can be used as a substitute for MATLAB files.

custom_classes

(Optional) A character vector of corresponding class labels for custom_images.

class2use_file

A character string specifying the path to the file containing the class2use variable (default: NULL).

micron_factor

Conversion factor for biovolume to cubic micrometers. Default is 1 / 3.4.

diatom_class

A character vector specifying diatom class names in WoRMS. Default: "Bacillariophyceae".

marine_only

Logical. If TRUE, restricts the WoRMS search to marine taxa only. Default: FALSE.

threshold

Threshold for selecting classification information ("opt" for above-threshold classification, otherwise "all"). Default: "opt".

multiblob

Logical. If TRUE, includes multiblob features. Default: FALSE.

feature_recursive

Logical. If TRUE, searches recursively for feature files when feature_files is a folder. Default: TRUE.

mat_recursive

Logical. If TRUE, searches recursively for MATLAB files in mat_folder. Default: TRUE.

drop_zero_volume

Logical. If TRUE, rows where Biovolume equals zero (e.g., artifacts such as smudges on the flow cell) are removed. Default: FALSE.

use_python

Logical. If TRUE, attempts to read .mat files using a Python-based method (SciPy). Default: FALSE.

verbose

Logical. If TRUE, prints progress messages. Default: TRUE.

Details

• Classification Data Handling:

  • If mat_folder is provided, the function reads class annotations from MATLAB .mat files.

  • If custom_images and custom_classes are supplied, they override MATLAB classification data (e.g. data from a CNN model).

  • If both mat_folder and custom_images/custom_classes are given, mat_folder takes precedence.

• MAT File Processing:

  • If use_python = TRUE, the function reads .mat files using ifcb_read_mat() (requires Python + SciPy).

  • Otherwise, it falls back to R.matlab::readMat().

References

Menden-Deuer Susanne, Lessard Evelyn J., (2000), Carbon to volume relationships for dinoflagellates, diatoms, and other protist plankton, Limnology and Oceanography, 3, doi: 10.4319/lo.2000.45.3.0569.

Sosik, H. M. and Olson, R. J. (2007), Automated taxonomic classification of phytoplankton sampled with imaging-in-flow cytometry. Limnol. Oceanogr: Methods 5, 204–216.

See Also

ifcb_read_features ifcb_is_diatom https://www.marinespecies.org/

Examples

if (FALSE) {
# Using MATLAB results:
feature_files <- "data/features"
mat_folder <- "data/classified"

biovolume_df <- ifcb_extract_biovolumes(feature_files,
                                        mat_folder)

print(biovolume_df)

# Using custom classification result:
class = c("Mesodinium_rubrum",
          "Mesodinium_rubrum")
image <- c("D20220522T003051_IFCB134_00002",
           "D20220522T003051_IFCB134_00003")

biovolume_df_custom <- ifcb_extract_biovolumes(feature_files,
                                               custom_images = image,
                                               custom_classes = class)

print(biovolume_df_custom)
}