Citrus FAQ

Table of Contents Performance / Stability / Runtime Related Errors Citrus takes a long time to run Citrus crashes when running on Mac OS X Citrus fails when reading FCS files exported by FlowJo Exporting Data How do I export data from specific clusters? Data Preparation How do I tell if the same parameters are measured in all my FCS files?

Performance / Stability / Runtime Related Errors

Citrus takes a long time to run

The clustering component of Citrus is the most computationally/time-intensive component of the analysis. Efforts to decrease analysis time usually will involve speeding up the clustering process. Here are some general thoughts on decreasing runtime:

• If you are on a mac, compile the Rclusterpp clustering package using multi-threaded support. This will enable Citrus to use all available CPU cores when clustering.
• Cluster fewer cells. The citrus GUI estimates the total number of cells that will be clustered based on the number of events to be selected from each sample. See the Rclusterpp benchmark page for an estimate of clustering runtime.

Citrus crashes when running on Mac OS X

There are known problems when running Rclusterpp code compiled on Mac OS X using the default compilers supplied with XCode. This results in program crashes with the message "Abort Trap" or "Segfault". This affects the multithreaded clustering code used by the Rclusterpp package and the multithreaded nearest-neighbor mapping code in the Citrus package. A workaround for this bug is possible by re-compiling the Rclusterpp and Citrus packages using a newer version of g++ (g++ 4.8 or later) that appears to have fixed the problems compiling OpenMP code on Mac OS X. See the section on installing Citrus and Rclusterpp from source for details.

Citrus fails when reading FCS files exported by FlowJo

FCS files exported from FlowJo X are missing required keywords in them and are not readable by the flowCore library. Usually, this manifests itself with the following error:

Error in value[[3L]](cond) : 
  Unexpected Error: Error in value[[3L]](cond): Parameter(s) $BEGINDATA not contained in ‘x'

Until this error is fixed, the folks at RGLab have a patched version of flowCore that works around this issue. You can install this patched version of flowCore directly from GitHub with the following command (in R):

R> library("devtools")
R> install_github("RGLab/flowCore",dependencies=NA)

It is likely that there are other modifications to this distribution of flowCore that I am unaware of so please use at your own risk. It would be preferable to have the FlowJo FCS export function fixed.

Exporting Data

How do I export data from specific clusters?

This feature available in Citrus version 0.08 or above.

1. Start R and load the citrus package

 R> library("citrus")

2. Run the citrus.exportClusterUI() function.

 R> citrus.exportClusterUI()

3. When prompted by the file selection dialog, navigate to a citrusOutput directory and select a saved citrus clustering object file. Citrus clustering files are called "citrusClustering.rData".

4. The R dialog will prompt you to enter a list of cluster IDs. Enter one or more cluster IDs separated by commas.

 R> Enter comma-separated list of cluster ids for export: 10001, 10002

5. A directory called "clusterExportData" will be created in the same directory as the "citrusClustering.rData" file. Exported cluster data will be placed there.

Data Preparation

How do I tell if the same parameters are measured in all my FCS files?

Start R, load the citrus package, and run the following function:

 library("citrus")
 citrus.checkFileParameterConsistencyUI()

You will be prompted to select a single file. Select a single FCS file from the directory where all FCS files reside. Citrus will then check to see if all directory files have consistent parameter counts and names between FCS files.

If you need to remove parameters from an FCS file, the cytofCore package may be helpful.