README.md

In iRfcb: Tools for Managing Imaging FlowCytobot (IFCB) Data

I 'R' FlowCytobot (iRfcb): Tools for Managing Imaging FlowCytobot (IFCB) Data

Overview

The iRfcb R package offers a suite of tools for managing and performing quality control on plankton data generated by the Imaging FlowCytobot (IFCB). It streamlines the processing and analysis of IFCB data, facilitating the preparation of IFCB data and images for publication (e.g. in GBIF, OBIS, EMODNet, SHARK or EcoTaxa). It is especially useful for researchers using, or partly using, the MATLAB ifcb-analysis package.

Functional Highlights

• Data Management: Functions for reading raw and processed IFCB files, counting and summarizing annotated or classified image data, and accessing, correcting, and merging manually annotated datasets.
• Quality Control: Tools for geospatial quality control of IFCB data and analysis of Particle Size Distribution.
• Image Extraction: Tools to extract and prepare images for publication.
• Image Classification: Functions to classify IFCB images through a CNN model served by a Gradio application.
• Taxonomical Data: Tools for handling and analyzing taxonomic data and calculating biomass concentration from image data.

Installation

You can install iRfcb from CRAN using:

install.packages("iRfcb")

Development version

To access a feature from the development version of iRfcb, install the latest development version from GitHub using the remotes package:

# install.packages("remotes")
remotes::install_github("EuropeanIFCBGroup/iRfcb")

Documentation and Tutorials

Reference

For a detailed overview of all available iRfcb functions, please visit the reference section:

• Function Reference

Tutorials

Explore the key features and capabilities of iRfcb through the tutorials:

• iRfcb Introduction
• Quality Control of IFCB Data
• Handling MATLAB Results
• Creating a DwC-A from IFCB Data
• Sharing Annotated IFCB Images
• Prepare IFCB Images for EcoTaxa
• WHOI-Plankton Data Integration

Example Usage

iRfcb is designed for integration into IFCB data processing pipelines. For an example, see its implementation in the following project:

• Example Data Pipelines

Python Dependency

A few functions in iRfcb require Python, and you will be notified when you call one of these functions. Python is needed for morphological feature extraction (ifcb_extract_features()), particle size distribution analysis (ifcb_psd()), and the optional Python-based .mat reader (ifcb_read_mat()). You can download Python from the official website: python.org/downloads. For the authoritative list of functions that require Python, please visit the project's Function Reference.

A Python virtual environment (venv) can be created using the ifcb_py_install() function before calling functions that require Python.

The iRfcb package can also be configured to automatically activate an installed Python venv upon loading by setting an environment variable. This feature is especially useful for users who regularly interact with Python dependencies within the iRfcb package.

USE_IRFCB_PYTHON

• Description: The USE_IRFCB_PYTHON environment variable controls whether the package automatically activates a pre-installed Python venv (e.g. using ifcb_py_install()) when the package is loaded. The optional IRFCB_PYTHON_VENV variable controls which venv is activated.
• Default: By default, neither variable is set. This means that the Python environment will not be loaded automatically, and the user must call the ifcb_py_install() function manually before using a Python feature.
• Usage: To enable automatic setup of the Python environment when iRfcb is loaded, set USE_IRFCB_PYTHON to "TRUE". By default the package activates the first available venv named iRfcb found in reticulate::virtualenv_root() (as listed by reticulate::virtualenv_list()). To load a specific environment instead, also set IRFCB_PYTHON_VENV to either the name of a venv under reticulate::virtualenv_root() or a full path to a venv directory. If IRFCB_PYTHON_VENV is set but cannot be resolved, no environment is activated (auto-discovery is not attempted). Both variables must be set before iRfcb is loaded.

How to Set These Variables

You can set the variables in your R session or make them persistent across sessions:

1. Temporary for the session: Set the variables before loading iRfcb: r Sys.setenv(USE_IRFCB_PYTHON = "TRUE") Sys.setenv(IRFCB_PYTHON_VENV = "/path/to/my/venv") # optional; or a named venv, e.g. "iRfcb-3.11"

2. Permanent across sessions: To ensure these settings persist across R sessions, add them to your .Renviron file in your R home directory. You can easily edit the file using: r usethis::edit_r_environ("user")

Then add the following lines (the second is optional): text USE_IRFCB_PYTHON=TRUE IRFCB_PYTHON_VENV=/path/to/my/venv This will automatically set the environment variables each time you start an R session.

Getting help

If you encounter a bug or need an IFCB feature that’s missing, please report it on GitHub with a minimal reproducible example.

Repository

For more details and the latest updates, visit the GitHub repository.

License

This package is licensed under the MIT License.

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