Skip to contents

Extract Biovolumes from IFCB Data and Compute Carbon Content

Source: R/ifcb_extract_biovolumes.R
ifcb_extract_biovolumes.Rd

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",
  diatom_include = NULL,
  marine_only = FALSE,
  threshold = "opt",
  multiblob = FALSE,
  feature_recursive = TRUE,
  mat_recursive = TRUE,
  drop_zero_volume = FALSE,
  feature_version = NULL,
  use_python = FALSE,
  verbose = TRUE
)

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".

diatom_include

Optional character vector of class names that should always be treated as diatoms, overriding the boolean result of ifcb_is_diatom. Default: NULL.

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.

feature_version

Optional numeric or character version to filter feature files by (e.g. 2 for "_v2"). Default is NULL (no filtering).

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.

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.

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:

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) { # \dontrun{
# 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)
} # }