ifcb_extract_biovolumes: Extract Biovolumes from IFCB Data and Compute Carbon Content
In iRfcb: Tools for Managing Imaging FlowCytobot (IFCB) Data

View source: R/ifcb_extract_biovolumes.R

ifcb_extract_biovolumes

R Documentation

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

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.

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.

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

## Not run: 
# 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)

## End(Not run)

iRfcb documentation built on Aug. 20, 2026, 1:06 a.m.