Extract Biovolumes from IFCB Data and Compute Carbon Content

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,
  class_files = NULL,
  custom_images = NULL,
  custom_classes = NULL,
  class2use_file = NULL,
  micron_factor = 1/3.4,
  diatom_class = "Bacillariophyceae",
  diatom_include = NULL,
  marine_only = FALSE,
  diatom_equation = c("large", "all", "auto"),
  threshold = "opt",
  multiblob = FALSE,
  feature_recursive = TRUE,
  class_recursive = TRUE,
  drop_zero_volume = FALSE,
  feature_version = NULL,
  use_cell_counts = FALSE,
  single_cell_values = c(-1, 0),
  carbon_conversion = c("roi", "cell"),
  use_python = FALSE,
  verbose = TRUE,
  mat_folder = deprecated(),
  mat_files = deprecated(),
  mat_recursive = deprecated()
)

Arguments

feature_files: A path to a folder containing feature files or a character vector of file paths.
class_files: (Optional) A character vector of full paths to classification or manual annotation files (.mat, .h5, or .csv), or a single path to a folder containing such files. Supply a single file format per sample: a sample represented twice (e.g. by both a .mat and a .h5) would have its ROIs counted once per file, so this is rejected with an error naming the affected samples.
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 classification files.
custom_classes: (Optional) A character vector of corresponding class labels for custom_images.
class2use_file: (Optional) A character string specifying the path to the file containing the class2use variable. Only required for manual results (default: NULL).
micron_factor: Conversion factor from microns per pixel (default: 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.
diatom_equation: A character string selecting which Menden-Deuer and Lessard (2000) carbon-to-volume relationship to apply to diatoms. "large" (default) uses the large-diatom (> 3000 micron^3) equation (vol2C_lgdiatom), matching the ifcb-analysis convention. "all" uses the all-sizes diatom equation (vol2C_diatom), which assigns more carbon to small cells. "auto" (vol2C_diatom_auto) selects between them per volume, using the large-diatom equation above 3000 micron^3 and the all-sizes equation at or below it, so each stays inside its calibrated size range. "auto" needs no cell_count data and is independent of carbon_conversion. Be aware that the two are discontinuous at that boundary (about 190 pgC against 135 pgC), so "auto" makes predicted carbon fall as a cell grows across it; that is why it is not the default. "auto" selects on whatever volume the conversion receives, which is the per-cell volume when carbon_conversion = "cell". Note that biovolume is measured per region of interest (ROI/image), so it is not a per-cell volume unless carbon_conversion = "cell" is used: chains of small cells register a large ROI biovolume. Non-diatom protists always use vol2C_nondiatom regardless of this setting.
threshold: A character string controlling which classification to use. "opt" (default) uses the threshold-applied classification, where predictions below the per-class optimal threshold are labeled "unclassified". Any other value (e.g. "all") uses the raw winning class without any threshold applied.
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.
class_recursive: Logical. If TRUE and class_files is a folder, searches recursively for classification files. 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_cell_counts: Logical. If TRUE, reads the optional per-ROI cell_count data stored by the diatom chain counter in .mat/.h5/.csv classification files and adds cell_count (raw) and cell_count_resolved (resolved abundance) columns to the output. Only supported with automated class_files; not with manual files or custom_images. Default: FALSE.
single_cell_values: Integer vector of cell_count values that should be treated as a single cell when resolving cell_count_resolved. Default is c(-1, 0), i.e. ROIs that were not counted (-1) and ROIs where no cells were detected (0) each count as one cell. Values not listed are used verbatim. Only used when use_cell_counts = TRUE.
carbon_conversion: A character string controlling how the Menden-Deuer and Lessard (2000) relationships are applied. "roi" (default) applies the selected equation once to the whole ROI biovolume, matching the ifcb-analysis convention and reproducing previous results exactly. "cell" divides the ROI biovolume by the resolved cell count, applies the equation to that per-cell volume, and multiplies back by the count, which is how the relationships are defined (log pgC cell^-1). Requires use_cell_counts = TRUE. carbon_pg remains a per-ROI total in both cases, not carbon per cell. ROIs holding a single cell, ROIs that were never chain-counted, and ROIs from files carrying no cell_count data are all converted as one cell, so only ROIs with cell_count >= 2 change.
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.
mat_folder: Use class_files instead.
mat_files: Use class_files instead.
mat_recursive: Use class_recursive instead.

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.
cell_count, cell_count_resolved (only when use_cell_counts = TRUE): the raw per-ROI cell count and the resolved number of cells used for abundance.

Details

Classification Data Handling:
- If class_files is provided, the function reads class annotations from .mat, .h5, or .csv files.
- If custom_images and custom_classes are supplied, they override classification file data (e.g. data from a CNN model).
- If both class_files and custom_images/custom_classes are given, class_files takes precedence.
MAT File Processing:
- If use_python = TRUE, the function reads .mat files using ifcb_read_mat() (requires Python + SciPy).
- Otherwise, it reads .mat files with the default R reader.
Per-cell carbon conversion:
- The Menden-Deuer and Lessard (2000) relationships are fitted per cell (log pgC cell^-1 = log a + b * log V), but an IFCB biovolume describes a whole region of interest, which for a chain-forming diatom is the whole chain. Every one of these relationships has b < 1, so applying one to an aggregated chain volume returns less carbon than applying it per cell and summing. The two differ by a factor of n^(1-b): about 1.28 for an 8-cell chain and 1.43 for 20 cells under the large-diatom equation.
- carbon_conversion = "cell" divides the ROI biovolume evenly among the counted cells, which assumes the cells in a chain are of similar size.
- It further assumes the ROI biovolume is cell volume. This is weakest for Chaetoceros, whose setae add to the measured ROI biovolume without being cell material, so the per-cell volume is overestimated and per-cell carbon is biased high; whole-ROI conversion biases it low instead. Neither is corrected here.

References

Menden-Deuer Susanne, Lessard Evelyn J., (2000), Carbon to volume relationships for dinoflagellates, diatoms, and other protist plankton, Limnology and Oceanography, 45(3), 569-579, 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.

Groves, G. J. J., Arthur, G., Bresnan, E., Whyte, C., Arce, P. and Davidson, K. (2026), Automatic enumeration of chains of marine diatoms using "You Only Look Once" - a machine learning approach. Journal of Plankton Research, 48(2), fbaf064, doi: 10.1093/plankt/fbaf064.

Examples

if (FALSE) { # \dontrun{
# Using classification results:
feature_files <- "data/features"
class_files <- "data/classified"

biovolume_df <- ifcb_extract_biovolumes(feature_files,
                                        class_files)

print(biovolume_df)

# Using custom classification result:
classes <- c("Mesodinium_rubrum",
             "Mesodinium_rubrum")
images <- c("D20220522T003051_IFCB134_00002",
           "D20220522T003051_IFCB134_00003")

biovolume_df_custom <- ifcb_extract_biovolumes(feature_files,
                                               custom_images = images,
                                               custom_classes = classes)

print(biovolume_df_custom)
} # }