Data transfer: Export from FlowCam and import to EcoTaxa for comprehensive annotation and library development.

Jaclyn Smith; Jennifer Wolny; Alex Barth; Savannah Stresser; Robert Hill; Yakov Pachepsky

Jan 29, 2026

Version 3

Data transfer: Export from FlowCam and import to EcoTaxa for comprehensive annotation and library development. V.3

DOI

https://dx.doi.org/10.17504/protocols.io.5jyl88d4dl2w/v3

Jaclyn Smith^1,2,3,4,
Jennifer Wolny⁴,
Alex Barth⁵,
Savannah Stresser⁶,
Robert Hill²,
Yakov Pachepsky¹

¹USDA-ARS Environmental Microbial Food Safety Laboratory;
²University of Maryland Department of Environmental Science and Technology;
³Oak Ridge Institute for Science and Education;
⁴US Food and Drug Administration Human Foods Program;
⁵University of Texas at Austin;
⁶Yokogawa Fluid Imaging Technologies, Inc.

Jaclyn Smith: Presently at the Food and Drug Administration Human Foods Program. Please use [email protected] for questions or inquiries regarding this protocol.;

Flowcam to Ecotaxa protocol

Jaclyn Smith

DOI: https://dx.doi.org/10.17504/protocols.io.5jyl88d4dl2w/v3

Protocol Citation: Jaclyn Smith, Jennifer Wolny, Alex Barth, Savannah Stresser, Robert Hill, Yakov Pachepsky 2026. Data transfer: Export from FlowCam and import to EcoTaxa for comprehensive annotation and library development.. protocols.io https://dx.doi.org/10.17504/protocols.io.5jyl88d4dl2w/v3Version created by Jaclyn Smith

License: This is an open access protocol distributed under the terms of the Creative Commons Attribution License, which permits unrestricted use, distribution, and reproduction in any medium, provided the original author and source are credited

Protocol status: Working

We use this protocol and it's working

Created: January 29, 2026

Last Modified: January 29, 2026

Protocol Integer ID: 241740

Keywords: FlowCam, Ecotaxa, flowcam data within ecotaxa, export from flowcam, flowcam data, flowcam, multiple flowcam, import to ecotaxa, other flowcam user, other flowcam users with this type, ecotaxa language, ecotaxa, called flowprocess, data transfer, export, visualspreadsheet, associated metadata, improved annotation, comprehensive annotation, import

Funders Acknowledgements:

United States Department of Agriculture

Abstract

This procedure outlines the steps needed to export imagery and associated metadata of individual or multiple FlowCam runs into EcoTaxa. Working with FlowCam data within EcoTaxa allows for improved annotation and predictability capacity across large datasets. This step-by-step procedure is based off of the initial R code called FlowProcess written by Alex Barth and has been updated with VisualSpreadsheet 6.0 and EcoTaxa language and page design to assist other FlowCam users with this type of data transfer.

Scope and Applicability

This procedure outlines the steps needed to export imagery and associated metadata of individual or multiple FlowCam runs into EcoTaxa. Working with FlowCam data within EcoTaxa allows for improved annotation and predictability capacity across large datasets. This step-by-step procedure is based off of the initial R code called FlowProcess written by Alex Barth and has been updated with VisualSpreadsheet 6.0 and EcoTaxa language and page design to assist other FlowCam users with this type of data transfer.

Summary of Method

Export of images and metadata from FlowCam's software VisualSpreadsheets 6.0.6 (or earlier) into EcoTaxa 2.8 using RStudio version 2025.09.1+401 and the FlowProcess code written by Alex Barth (https://github.com/TheAlexBarth/FlowProcess/tree/main).

This protocol is not compatible with VisualSpreadsheets 4.0 and earlier. 

Sample Processing

Samples are run using the FlowCam instrument according to user needs at desired flow rate, magnification, and volume. 

Due to the length of time it takes to export digital files generated in FlowCam, it is recommended to export data from VisualSpreadsheet to EcoTaxa as samples are processed rather than in bulk.

Additionally, EcoTaxa uploads are limited to 500mb zip file size. 

Sample Post-processing - Removal of Duplicates

Occasionally, and depending on species present in sample, a FlowCam run can produce duplicate images of the same cell or colony which might get stuck or sluggishly pass through the flow cell. For this protocol it is advised that duplicates be removed prior to export from the FlowCam software. This can be performed by sorting images by capture ID and manually scrolling through and selecting duplicate images. Alex Barth, the creator of the FlowProcess code, also has available a 'duplicate_deleter.R' code which may be utilized, but will not be discussed in this protocol. Please refer to his website for use of this code. https://github.com/TheAlexBarth/FlowProcess/blob/main/R/duplicate_deleter.R 

Export from VisualSpreadsheet

Prior to exporting from VisualSpreadsheet, you will need to make sure that the correct particle properties are selected for export. The FlowProcess code requires at minimum the following particle properties to be selected in order to run properly: 
- Diameter (ESD)
- Diameter (ABD)
- Diameter (FD)
- Average Blue
- Average Green
- Average Red
- Capture X
- Capture Y
- Circle Fit
- Circularity
- Circularity (Hu)
- Compactness
- Convex Perimeter
- Convexity
- Edge Gradient
- Elongation 
- Feret Angle Max
- Feret Angle Min
- Fiber Curl
- Fiber Straightness
- Geodesic Thickness
- Geodesic Length
- Perimeter
- Length
- Roughness
- Symmetry
- Width 
- Intensity
- Date
- Calibration Image
- Source Image 
- Calibration Factor
- UUID

To select particle properties go to Preferences>Particle Properties...

 

This will prompt the particle properties window to open. Then check the boxes for the properties mentioned in Step 5.0 under the export column. Once all properties are selected click the "Okay" button to save selected particle properties.

In the FlowCam's software, VisualSpreadsheet, open the run that is to be exported:

File>Open Data...

In the "Select Data" window, select the "Open Data" button.

Select the run which is to be exported in the "Select Data" window. Then select the "Open" button. We are selecting TestRun_1 as a sample dataset for this protocol.

The run will now appear as open in the "Select Data" window. Select "OK" button.

With the sample run open in the VisualSpreadsheet software, the particle images for this run will then be exported. Note: Particle images are also referred to as vignettes in EcoTaxa terminology.

To export particle images: FIle>Export>Images...

The "Particle Image Exporter" window will then open. Select the run which is to exported for this example that is TestRun_1, then select the "Export" button.

Selecting the "Export" button will generate a "Choose An Output Directory" window. This is where you will select to save the exported images. This process will create its own folder with the same name as the run. Select a destination that works best. Then select the "Select Folder" button to begin particle image export to desired folder.

Allow Particle Image Export to run to completion. 

Export Metadata for sample run. For each run that is exported, two metadata files will need to be exported and named appropriately in order for the FlowProcess code to work properly. These two metadata files are the Particle Data and Summary Data. The order in which these two metadata files are exported is not important. The summary data can be exported prior to the particle data and vice versa.

First the particle data will be exported. File>Export>Particle Data...

This will generate the "Choose Data To Export" window. TestRun_1 will automatically show up since that is the run that is currently open. Check the box next to the run and select the "OK" button. 

This will generate the "Choose a filename and location." window. It is imperative that this file is named the same as the run name with "_data" at the end in order for the FlowProcess code to recognize this as a metadata file. Make sure to save as a Comma-Separated Values or .csv file. This should be saved in the folder created in the particle image export previously.  Select the "Save" button.

After the Particle Data has been saved, the Summary Data then needs to be saved. File>Export>Summary Data...

This will generate the "Choose a filename and location." window. It is imperative that this file is named the same as the run name with "_summary" at the end in order for the FlowProcess code to recognize this as the summary metadata file. Make sure to save as a Comma-Separated Values or .csv file. This should be saved in the folder created in the particle image export previously. Select the "Save" button.

At the end of this process each exported run folder will contain a "RUNNAME_data.csv" and "RUNNAME_summary.csv" files along with all the individual particle images for each run. The run folder is now ready to be entered. The FlowProcess code will combine the Data and Summary .csv files into a single .tsv file, which is the format required by EcoTaxa for the upload process. 

Conversion Using FlowProcess R code

The following steps are completed using the FlowProcess code. https://github.com/TheAlexBarth/FlowProcess

While this protocol focuses on using RStudio, it is worth noting that the FlowProcess code can be ran in base R as well. 

The Rstudio window is comprised of three main panes. In this protocol, Rstudio panes will be indicated using red numerals in the figures. 
Those three panes are: 
I. The console where you can enter code manually.
II. The environment which shows all commands and objects once run.
III. The files pane which shows the files of your working project.

Create a new empty R Script file to store the FlowProcess code. The use of an Rscript file will allow for quick reproducibility and a way to store the FlowProcess code for future conversions. Alternatively, you could use an R Markdown file, R Notebook file, or enter and run the FlowProcess code directly in the console. 

Click the new file button

Select R Script file or file of choice.

Click the save icon and save the R Script file in the location of your choice.

After opening a new R Script file, the Rstudio window is now comprised of 4 main panes: 
I. The console where you can enter code manually.
II. The environment which shows all commands and objects once run.
III. The files pane which shows the files of your working project.
IV. The new R Script file.

In the new R Script file install the following package in order to load the FlowProcess code directly from GitHub. To do this type "install.packages("remotes")" into the R Script and click the run button while the cursor is on line 1. This only needs to be performed once as that package will remain installed in RStudio.

Once run, there will be a confirmation that the package was downloaded.

Next the FlowProcess package will need to be installed. Again, this only needs to be done once as it will remain installed in RStudio. To install FlowProcess enter the following code into the R Script file: "remotes::install_github("thealexbarth/flowprocess")"
 to install FlowProcess as an R package. 
When installing from GitHub flowprocess will be all lowercase. 

Once successfully installed there will be a confirmation in the console.

Load the FlowProcess code. After installation you can now load the FlowProcess package by entering the following into the R Script window:
"library(FlowProcess)"

When loading the package in R Studio make sure the F and the P are capitalized in FlowProcess.

With the cursor on the same line as the code hit the Run button to load the FlowProcess package.

You are now ready to run the FlowProcess code. This can be done one of two ways either for a single sample run using the establish_flowprocess() command or with multiple sample runs using the batch_flowprocess() command.  

Step 20 will show how to perform a single sample run conversion. 
Step 21 will show how to perform multiple sample run conversions. 

For single sample run conversion: Set your root_dir to the location of the exported FlowCam run dataset with the run images, SAMPLE_data.csv, and SAMPLE_summary.csv files 

For Mac users type into the R Script where your run is located:
root_dir<-"~/Desktop/protocol/testdata/TestRun_1"
Then with the cursor on the line of code hit the Run button.


There is no need for a "/" at the end of TestRun_1.

For PC users enter into the console where your run is located:
root_dir<-"C/:Desktop/protocol/testdata/TestRun_1"

Once the root_dir is set it will be displayed in the environment.

To execute the FlowProcess code on a single run you will type into the R SCript:
establish_flowprocess(root_dir)
Then with the cursor on the line of code hit the Run button.

Once the run is complete the console will show a "[1] TRUE" which indicates the run was successful.

Prior to running the FlowProcess code your run folder will look like this:

In your run folder there will be a data file, summary file, and all the images from the run.

After running the FlowProcess code your run folder will look like this:

 In your run folder there will be a .tsv file and all the images from the run.

The run folder is now ready to be zipped for upload into EcoTaxa.
For Mac users, right click the folder and select "Compress TestRun_1"

This will create the zip file which will be used for importing to Ecotaxa.

For PC users, right click run folder then select "Compress to...>ZIP file" and follow the prompts to save the zip file.

For multiple or batch sample run conversion: Follow all the steps above until Step 20. 

Set the root_dir to the parent location with the multiple folders of exported FlowCam Data. In this example, the code line would read "~/Desktop/protocol/testdata"

For Mac users, enter into the console: 
root_dir<-"~/Desktop/protocol/testdata"
Then with the cursor on the line of code hit the Run button.




For PC users, enter into the console:
root_dir<-"C:/Desktop/protocol/testdata"
Followed by the return key or enter key.

To execute the FlowProcess code on a batch of runs you will type into the console:
batch_flowprocess(root_dir)

Then with the cursor on the line of code hit the Run button.

For multiple runs there will be a progress bar present to show the progress of the data conversion.

Prior to running batch_flowprocess, in each run folder there will be the run images, a data file, and summary file for each run. Similar to what is displayed in Step 20.5 in this protocol. 

After running batch_flowprocess, in each run folder there will be the run images and a .tsv file for each run. Similar to what is displayed in Step 20.6 in this protocol. 

Repeat Step 20.7 to zip the batch of files or individual files. One requirement of Ecotaxa is that the zip files must be smaller than 500mb in order to upload. Depending on the size of your runs you may need to make multiple zip files. 

To run additional single sample runs or multiple sample runs, all you will need to do is change the root_dir locations and re-execute either establish_flowprocess(root_dir) or batch_flowprocess(root_dir) with the updated root_dir.

Import into EcoTaxa

Once the FlowCam run has been exported, processed through the FlowProcess code, and zipped, it is now ready to be imported into EcoTaxa. To do this you must have an active account with EcoTaxa. 

Once your account is created and you are logged in, you can either create a new project or add to an existing project. 

First select the "Contribute to a project" link. 

For this protocol we will be creating a new project by clicking the "Create a project" link.

In the create project link, the following fields are required:
- Title
- Instrument
- Status
- Access
- Privileges

The instruments must be selected as "FlowCam". If you plan on identifying your images you must select either "Annotate" or "Annotate no prediction" under the status section. You can select your images to be either private, public, or open for the access. Under privileges, you can add additional personnel who may need to have access in the project. Once you have finished entering information press the save button.

Once the project is created it will show up on the Home>Projects page.

To add a FlowCam run to a project, select the settings button on the project of choice.

Once in the project settings page, hover over the "Import" button from the top menu, and select "General Import". 

Once on the Import screen, select the "Upload or select from my files" button.

You can either select the "BROWSE LOCAL FILES" button, or drag and drop your zipped file into the gray bar where the "BROWSE LOCAL FILES" button is located.

Once the file is selected or dragged and dropped into the web page, the Import screen will look as follows. For the purpose of this protocol we will only be uploading TestRun_1.zip. Depending on file size it may take several minutes to upload. 

 Once uploaded our file can be seen in the "My Files" section of the Import page.

To import, select TestRun_1.zip and it will highlight that run and populate a "SELECT TO IMPORT" button to the right. Hit the "SELECT TO IMPORT" button to begin upload to EcoTaxa.

Once the "SELECT TO IMPORT" button is selected the "Start Task" button at the bottom of the import page will now selectable. Hit the "Start Task" button to begin the import.

After the "Start Task" button is selected, a new screen will be generated which will show the progress of the upload. 

Once the import is complete you can then select the "Go to Manual Classification Screen" or "Go to Automatic Classification Screen" to start classifying your FlowCam run images. 

You have successfully uploaded a FlowCam run (particle images and metadata) into EcoTaxa for classification.