---
title: "iRfcb Introduction"
output:
  rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{iRfcb Introduction}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

## Introduction

The `iRfcb` package is an open-source R package designed to streamline the analysis of Imaging FlowCytobot (IFCB) data, with a focus on supporting marine ecological research and monitoring. By integrating R and Python functionalities, the package facilitates efficient handling of IFCB image data, extraction of key metadata, and preparation of outputs for further taxonomic, ecological, or spatial analyses.

This tutorial serves as an introduction to the core functionalities of `iRfcb`, providing step-by-step instructions for data preprocessing, taxonomic analysis, and SHARK-compliant data export. 

## Getting Started

### Installation

You can install the package from GitHub using the `remotes` package:
```{r, eval=FALSE}
# install.packages("remotes")
remotes::install_github("EuropeanIFCBGroup/iRfcb")
```

Load the `iRfcb` and `dplyr` libraries:
```{r, eval=FALSE}
library(iRfcb)
library(dplyr) # For data wrangling
```

```{r, include=FALSE}
library(iRfcb)
library(dplyr) # For data wrangling
```

### Download Sample Data

To get started, download sample data from the [SMHI IFCB Plankton Image Reference Library](https://doi.org/10.17044/scilifelab.25883455.v3) (Torstensson et al. 2024) with the following function:

```{r}
# Define data directory
data_dir <- "data"

# Download and extract test data in the data folder
ifcb_download_test_data(dest_dir = data_dir,
                        max_retries = 10,
                        sleep_time = 30)
```

## Extract IFCB Data

This section demonstrates a selection of general data extraction tools available in `iRfcb`.

### Extract Timestamps from IFCB sample Filenames

Extract timestamps from sample names or filenames:
```{r}
# Example sample names
filenames <- list.files("data/data/2023/D20230314", recursive = TRUE)

# Print filenames
print(filenames)

# Convert filenames to timestamps
timestamps <- ifcb_convert_filenames(filenames)

# Print result
print(timestamps)
```
If the filename includes ROI numbers (e.g., in an extracted `.png` image), a separate column, `roi`, will be added to the output.

```{r}
# Example sample names
filenames <- list.files("data/png/Alexandrium_pseudogonyaulax_050")

# Print filenames
print(filenames)

# Convert filenames to timestamps
timestamps <- ifcb_convert_filenames(filenames)

# Print result
print(timestamps)
```

### Calculate Volume Analyzed in ml

The analyzed volume of a sample can be calculated using data from `.hdr` and `.adc` files.
```{r}
# Path to HDR file
hdr_file <- "data/data/2023/D20230314/D20230314T001205_IFCB134.hdr"

# Calculate volume analyzed (in ml)
volume_analyzed <- ifcb_volume_analyzed(hdr_file)

# Print result
print(volume_analyzed)
```

### Get Sample Runtime

Get the runtime from a `.hdr` file:
```{r}
# Get runtime from HDR-file
run_time <- ifcb_get_runtime(hdr_file)

# Print result
print(run_time)
```

### Read Feature Data

Read all feature files (`.csv`) from a folder:

```{r}
# Read feature files from a folder
features <- ifcb_read_features("data/features/2023/",
                               verbose = FALSE) # Do not print progress bar

# Print output of first 10 columns from the first sample in the list
head(features[[1]])[,1:10]

# Read only multiblob feature files
multiblob_features <- ifcb_read_features("data/features/2023", 
                                         multiblob = TRUE,
                                         verbose = FALSE)

# Print output of first 10 columns from the first sample in the list
head(multiblob_features[[1]])[,1:10]
```

## Extract Images from ROI files

IFCB images stored in `.roi` files can be extracted as `.png` files using the `iRfcb` package, as demonstrated below.

Extract all images from a sample using the [`ifcb_extract_pngs`](../reference/ifcb_extract_pngs.html) function. You can specify the `out_folder`, but by default, images will be saved in a subdirectory within the same directory as the ROI file. The `gamma` can be adjusted to enhance image contrast.
```{r}
# All ROIs in sample
ifcb_extract_pngs("data/data/2023/D20230314/D20230314T001205_IFCB134.roi",
                  gamma = 1) # Default gamma value
```

Extract specific ROIs:
```{r}
# Only ROI number 2 and 5
ifcb_extract_pngs("data/data/2023/D20230314/D20230314T003836_IFCB134.roi",
                  ROInumbers = c(2, 5))
```

To extract annotated images or classified results from MATLAB files, please see the [Sharing Annotated IFCB Images](../articles/image-export-tutorial.html) and [Handling MATLAB Results](../articles/matlab-tutorial.html) tutorials.

## Taxonomical Data

Maintaining up-to-date taxonomic data is essential for ensuring accurate species names and classifications, which directly impact calculations like carbon concentrations in `iRfcb`.

Up-to-date taxonomy also ensures data harmonization by preventing issues like misspellings, outdated synonyms, or inconsistent classifications. This consistency is crucial for integrating and comparing datasets across studies, regions, and time periods, improving the reliability of scientific outcomes.

### Taxon matching with WoRMS

Taxonomic names can be matched against the [World Register of Marine Species (WoRMS)](https://www.marinespecies.org/), ensuring accuracy and consistency. The `iRfcb` package includes a built-in function for taxon matching via the WoRMS API, featuring a retry mechanism to handle server errors, making it particularly useful for automated data pipelines. For additional tools and functionality, the R package [`worrms`](https://cran.r-project.org/package=worrms) provides a comprehensive suite of options for interacting with the WoRMS database.

```{r}
# Example taxa names
taxa_names <- c("Alexandrium_pseudogonyaulax", "Guinardia_delicatula")

# Retrieve WoRMS records
worms_records <- ifcb_match_taxa_names(taxa_names, 
                                       verbose = FALSE) # Do not print progress bar

# Print result
tibble(worms_records)
```

### Check whether a class name is a diatom

This function takes a list of taxa names, cleans them, retrieves their corresponding classification records from WoRMS, and checks if they belong to the specified diatom class. The function only uses the first name (genus name) of each taxa for classification. This function can be useful for converting biovolumes to carbon according to Menden-Deuer and Lessard (2000). See [`vol2C_nondiatom`](../reference/vol2C_nondiatom.html) and [`vol2C_lgdiatom`](../reference/vol2C_lgdiatom.html) for carbon calculations (not included in NAMESPACE).

```{r}
# Read class2use file and select five taxa
class2use <- ifcb_get_mat_variable("data/config/class2use.mat")[10:15]

# Create a dataframe with class name and result from `ifcb_is_diatom`
class_list <- data.frame(class2use,
                         is_diatom = ifcb_is_diatom(class2use, verbose = FALSE))

# Print rows 10-15 of result
class_list
```
The default class for diatoms is defined as Bacillariophyceae, but may be adjusted using the `diatom_class` argument.

### Find trophic type of plankton taxa

This function takes a list of taxa names and matches them with the **SMHI Trophic Type** list used in [SHARK](https://shark.smhi.se/hamta-data/).

```{r}
# Example taxa names
taxa_list <- c("Acanthoceras zachariasii",
               "Nodularia spumigena",
               "Acanthoica quattrospina",
               "Noctiluca",
               "Gymnodiniales")

# Get trophic type for taxa
trophic_type <- ifcb_get_trophic_type(taxa_list)

# Print result
print(trophic_type)
```

## SHARK export

This function is used by SMHI to map IFCB data into the [SHARK](https://shark.smhi.se/hamta-data/) standard data delivery format. An example submission is also provided in `iRfcb`.

```{r}
# Get column names from example
shark_colnames <- ifcb_get_shark_colnames()

# Print column names
print(shark_colnames)

# Load example stored from `iRfcb`
shark_example <- ifcb_get_shark_example()

# Print first ten columns of the SHARK data submission example
head(shark_example)[1:10]
```

This concludes this tutorial for the `iRfcb` package. For more detailed information, refer to the package documentation or the other [tutorials](../articles/index.html). See how data pipelines can be constructed using `iRfcb` in the following [Example Project](https://github.com/nodc-sweden/ifcb-data-pipeline). Happy analyzing!

## Citation

```{r, echo=FALSE}
# Print citation
citation("iRfcb")
```

```{r, include=FALSE}
# Clean up
unlink(file.path(data_dir, "data/2023/D20230314/D20230314T001205_IFCB134"), recursive = TRUE)
unlink(file.path(data_dir, "data/2023/D20230314/D20230314T003836_IFCB134"), recursive = TRUE)
```

## References
- Torstensson, A., Skjevik, A-T., Mohlin, M., Karlberg, M. and Karlson, B. (2024). SMHI IFCB Plankton Image Reference Library. SciLifeLab. Dataset. https://doi.org/10.17044/scilifelab.25883455.v3