Compiled date: 2020-10-27

Last edited: 2018-01-14

License: BSD_3_clause + file LICENSE

1 Introduction

This document offers an introduction and overview of the R/Bioconductor (R Core Team 2014, Gentleman et al. (2004)) package flowcatchR, which provides a flexible and comprehensive set of tools to detect and track flowing blood cells in time-lapse microscopy.

1.1 Why flowcatchR?

flowcatchR builds upon functionalities provided by the EBImage package (Pau et al. 2010), and extends them in order to analyze time-lapse microscopy images. Here we list some of the unique characteristics of the datasets flowcatchR is designed for:

  • The images come from intravital microscopy experiments. This means that the Signal-to-Noise Ratio (SNR) is not optimal, and, very importantly, there are potential major movements of the living specimen that can be confounded with the true movements of the particles of interest (Meijering and Smal 2008)
  • Cells are densely distributed on the images, with particles that can enter and leave the field of view
  • The acquisition frame rate is a compromise between allowing the fluorescent cells to be detected and detecting the movements properly
  • Cells can flow, temporarily adhere to the endothelial layer and/or be permanently adherent. Therefore, all movement modalities should be detected correctly throughout the entire acquisition. Cells can also cluster together and form (temporary) conglomerates

Essential features flowcatchR delivers to the user are:

  • A simple and flexible, yet complete framework to analyze flowing blood cells (and more generally time-lapse) image sets, with a system of S4 classes such as Frames, ParticleSet, and TrajectorySet constituting the backbone of the procedures
  • Techniques for aiding the detection of objects in the segmentation step
  • An algorithm for tracking the particles, adapted and improved from the proposal of Sbalzarini and Koumoutsakos (2005) (Sbalzarini and Koumoutsakos 2005), that reflects the directional aspect of the motion
  • A wide set of functions inspecting the kinematic properties of the identified trajectories (Beltman, Marée, and Boer 2009, Meijering, Dzyubachyk, and Smal (2012)), providing publication-ready summary statistics and visualization tools to help classifying identified objects

This guide includes a brief overview of the entire processing flow, from importing the raw images to the analysis of kinematic parameters derived from the identified trajectories. An example dataset will be used to illustrate the available features, in order to track blood platelets in consecutive frames derived from an intravital microscopy acquisition (also available in the package). All steps will be dissected to explore available parameters and options.

1.2 Purpose of this document

This vignette includes a brief overview of the entire processing flow, from importing the raw images to the analysis of kinematic parameters derived from the identified trajectories. An example dataset will be used to illustrate the available features, in order to track blood platelets in consecutive frames derived from an intravital microscopy acquisition (also available in the package). All steps will be dissected to explore available parameters and options.

2 Getting started

2.1 Installation

flowcatchR is an R package distributed as part of the Bioconductor project. To install flowcatchR, please start R and type:

if (!requireNamespace("BiocManager", quietly=TRUE))
    install.packages("BiocManager")
BiocManager::install("flowcatchR")

In case you might prefer to install the latest development version, this can be done with these two lines below:

install.packages("devtools") # if needed
devtools::install_github("federicomarini/flowcatchR")

Installation issues should be reported to the Bioconductor support site (http://support.bioconductor.org/).

2.2 Getting help

The flowcatchR package was tested on a variety of datasets provided from cooperation partners, yet it may require some extra tuning or bug fixes. For these issues, please contact the maintainer - if required with a copy of the error messages, the output of sessionInfo function:

maintainer("flowcatchR")
## [1] "Federico Marini <marinif@uni-mainz.de>"

Despite our best efforts to test and develop the package further, additional functions or interesting suggestions might come from the specific scenarios that the package users might be facing. Improvements of existing functions or development of new ones are always most welcome! We also encourage to fork the GitHub repository of the package (https://github.com/federicomarini/flowcatchR), develop and test the new feature(s), and finally generate a pull request to integrate it to the original repository.

2.3 Citing flowcatchR

The work underlying the development of flowcatchR has not been formally published yet. A manuscript has been submitted for peer-review. For the time being, users of flowcatchR are encouraged to cite it using the output of the citation function, as it follows:

citation("flowcatchR")
## 
## To cite the package 'flowcatchR' in publications use:
## 
##   Federico Marini, Harald Binder (2018). flowcatchR: Tools to analyze
##   in vivo microscopy imaging data focused on tracking flowing blood
##   cells. URL http://bioconductor.org/packages/flowcatchR/ doi:
##   10.18129/B9.bioc.flowcatchR
## 
## A BibTeX entry for LaTeX users is
## 
##   @Manual{,
##     title = {{flowcatchR}: Tools to analyze in vivo microscopy imaging data focused on
## tracking flowing blood cells},
##     author = {Federico Marini and Harald Binder},
##     year = {2018},
##     url = {http://bioconductor.org/packages/flowcatchR/},
##     doi = {10.18129/B9.bioc.flowcatchR},
##   }

3 Processing overview

flowcatchR works primarily with sets of fluorescent time-lapse images, where the particles of interest are marked with a fluorescent label (e.g., red for blood platelets, green for leukocytes). Although different entry spots are provided (such as the coordinates of identified points in each frame via tab delimited files), we will illustrate the characteristics of the package starting from the common protocol starting point. In this case, we have a set of 20 frames derived from an intravital microscopy acquisition, which for the sake of practicality were already registered to reduce the unwanted specimen movements (Fiji (Schindelin, Arganda-Carreras, and Frise 2012) was used for this purpose).

library("flowcatchR")
## Loading required package: EBImage
data("MesenteriumSubset")
# printing summary information for the MesenteriumSubset object
MesenteriumSubset
## Frames 
##   colorMode    : Color 
##   storage.mode : double 
##   dim          : 271 131 3 20 
##   frames.total : 60 
##   frames.render: 20 
## 
## imageData(object)[1:5,1:6,1,1]
##           [,1]      [,2]      [,3]      [,4]      [,5]      [,6]
## [1,] 0.1647059 0.2117647 0.1882353 0.1803922 0.1607843 0.1333333
## [2,] 0.2352941 0.1882353 0.1803922 0.1568627 0.1411765 0.1372549
## [3,] 0.2352941 0.2000000 0.1764706 0.1490196 0.1333333 0.1333333
## [4,] 0.2352941 0.2117647 0.1764706 0.1529412 0.1411765 0.1411765
## [5,] 0.2313725 0.2078431 0.1725490 0.1411765 0.1294118 0.1411765
## 
## Channel(s): all

To obtain the set of trajectories identified from the analysis of the loaded frames, a very compact one-line command is all that is needed:

# one command to seize them all :)
fullResults <- kinematics(trajectories(particles(channel.Frames(MesenteriumSubset,"red"))))

On a MAC OS X machine equipped with 2.8 Ghz Intel Core i7 processor and 16 GB RAM, the execution of this command takes 2.32 seconds to run (tests performed with the R package microbenchmark. On a more recent MacBook Pro (2017), the same benchmark took 1.78 seconds.

The following sections will provide additional details to the operations mentioned above, with more also on the auxiliary functions that are available in flowcatchR.

4 Image acquisition

A set of images is acquired, after a proper microscopy setup has been performed. This includes for example a careful choice of spatial and temporal resolution; often a compromise must be met to have a good frame rate and a good SNR to detect the particles in the single frames. For a good review on the steps to be taken, please refer to Meijering’s work (Meijering and Smal 2008, Meijering, Dzyubachyk, and Smal (2012)).

flowcatchR provides an S4 class that can store the information of a complete acquisition, namely Frames. The Frames class extends the Image class, defined in the EBImage package, and thus exploits the multi-dimensional array structures of the class. The locations of the images are stored as dimnames of the Frames object. To construct a Frames object from a set of images, the read.Frames function is used:

# initialization
fullData <- read.Frames(image.files="/path/to/folder/containing/images/", nframes=100) 
# printing summary information for the Frames object
fullData

nframes specifies the number of frames that will constitute the Frames object, whereas image.files is a vector of character strings with the full location of the (raw) images, or the path to the folder containing them (works automatically if images are in TIFF/JPG/PNG format). In this case we just loaded the full dataset, but for the demonstrational purpose of this vignette, we will proceed with the subset available in the MesenteriumSubset object, which we previously loaded in Section 3.

It is possible to inspect the images composing a Frames object with the function inspect.Frames (Fig. 1).

inspect.Frames(MesenteriumSubset, nframes=9, display.method="raster")