# I 'R' FlowCytobot (iRfcb): Tools for Managing Imaging FlowCytobot (IFCB) Data <a href="https://europeanifcbgroup.github.io/iRfcb/"><img src="man/figures/logo.png" align="right" height="139" alt="iRfcb website" /></a>

[![R-CMD-check](https://github.com/EuropeanIFCBGroup/iRfcb/actions/workflows/r-cmd-check.yml/badge.svg?event=push)](https://github.com/EuropeanIFCBGroup/iRfcb/actions/workflows/r-cmd-check.yml)
[![CRAN status](https://www.r-pkg.org/badges/version/iRfcb)](https://CRAN.R-project.org/package=iRfcb)
[![CRAN checks](https://badges.cranchecks.info/worst/iRfcb.svg)](https://cran.r-project.org/web/checks/check_results_iRfcb.html)
[![Codecov test coverage](https://codecov.io/gh/EuropeanIFCBGroup/iRfcb/branch/main/graph/badge.svg)](https://app.codecov.io/gh/EuropeanIFCBGroup/iRfcb?branch=main)

## 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)](https://mclanelabs.com/imaging-flowcytobot/). It streamlines the processing and analysis of IFCB data, facilitating the preparation of IFCB data and images for publication (e.g. in [GBIF](https://www.gbif.org/), [OBIS](https://obis.org/), [EMODNet](https://emodnet.ec.europa.eu/en), [SHARK](https://shark.smhi.se/en/) or [EcoTaxa](https://ecotaxa.obs-vlfr.fr)). It is especially useful for researchers using, or partly using, the MATLAB [ifcb-analysis](https://github.com/hsosik/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](https://github.com/kudelalab/PSD).
- **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](https://gradio.app/) 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:

```r
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:

```r
# 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](https://europeanifcbgroup.github.io/iRfcb/reference/index.html)

### Tutorials

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

- [iRfcb Introduction](https://europeanifcbgroup.github.io/iRfcb/articles/introduction.html)
- [Quality Control of IFCB Data](https://europeanifcbgroup.github.io/iRfcb/articles/qc-tutorial.html)
- [Handling MATLAB Results](https://europeanifcbgroup.github.io/iRfcb/articles/matlab-tutorial.html)
- [Creating a DwC-A from IFCB Data](https://europeanifcbgroup.github.io/iRfcb/articles/dwca-tutorial.html)
- [Sharing Annotated IFCB Images](https://europeanifcbgroup.github.io/iRfcb/articles/image-export-tutorial.html)
- [Prepare IFCB Images for EcoTaxa](https://europeanifcbgroup.github.io/iRfcb/articles/ecotaxa-tutorial.html)
- [WHOI-Plankton Data Integration](https://europeanifcbgroup.github.io/iRfcb/articles/whoi-plankton-data-integration.html)

### 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](https://github.com/nodc-sweden/ifcb-data-pipeline)


## 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](https://www.python.org/downloads/). For the authoritative list of functions that require Python, please visit the project's [Function Reference](https://europeanifcbgroup.github.io/iRfcb/reference/index.html#python-dependency-python-powered-python-powered-w-x-png-).

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](https://github.com/EuropeanIFCBGroup/iRfcb/issues) with a minimal reproducible example.

## Repository

For more details and the latest updates, visit the [GitHub repository](https://github.com/EuropeanIFCBGroup/iRfcb).

## License

This package is licensed under the MIT License.
