TASBE tools: Understanding Tool Results

About this Document

For an introduction and over of the tools in the TASBE Characterization Workflow, see the Characterization Workflow Documentation. This document provides a more in depth discussion of how to interpret and debug the results generated by particular tools.

This is a living document, which we are continuing to update. If you run into problems which this file is not able to help you resolve, please send email to biotools@bbn.com.

Table of Contents

  1. Uploading Data
    1. I was uploading data and then it stalled or crashed!  What happened?
  2. Color Models
    1. How do I fix an "Unable to find channel" or "Missing channel" error?
    2. What does the warning: "Only one bead peak found, assuming brightest" or "Only two bead peaks found, assuming brightest two" mean?
    3. How do I fix the error: "Bead calibration failed: found no bead peaks"?
    4. How do I fix the error: "Bead calibration failed: found unexpectedly many bead peaks"?
    5. What does the warning: "Bead calibration probably incorrect: fit more than 5 percent off" mean?
    6. What are the Color Mapping Controls for?
    7. How should I set up colors for my Color Mapping Controls?
    8. What does the error "Not all channels can be translated to standard MEFL units" mean?
    9. What does the warning "Translation from [Channel] to [Channel] not invertible" mean?
  3. Experiment Analysis
    1. What does the warning "Assuming only a single inducer exists" mean?
  4. Other Errors and Warnings
    1. Warnings about Displays and Printing
    2. Result thumbnails are broken links in the Chrome browser
    3. Missing files and "GPL Ghostscript 8.70: Unrecoverable error, exit code 1"

Uploading Data

I was uploading data and then it stalled or crashed! What happened?

This bug has been reported several times for large data sets (around 1,000 MB) or large .fcs files (around 15 MB each). If it happens to you, please send email to biotools@bbn.com and get help from us in sorting the problem out.

Color Models

How do I fix an "Unable to find channel" or "Missing channel" error?

This error is typically caused by a mismatch between the specification of flow cytometry channels that you have provided and the header information in your .fcs files. Check and be sure that each channel name is precisely identical, including capitalization and whitespace.

What does the warning: "Only one bead peak found, assuming brightest" or "Only two bead peaks found, assuming brightest two" mean?

Fluorescent beads are designed with different size gaps between the different fluorescence peaks, so that as long as you can see at least three peaks in your flow cytometry data's FITC data, then you can correctly convert from arbitrary FITC units into standard MEFL units. Typically, the only reason that you will see less peaks is if you have a very strong fluorescent protein in your FITC channel, and have adjusted the channel sensitivity to be quite low to avoid saturation. This would mean that only the one or two brightest peaks from the beads will be above the threshold level where the software starts looking for peaks.

Here is an example of what a correct single-peak "bead-calibration" graph looks like (the red line shows where the software has found a peak):

Bead calibration with single peak

If you have not adjusted your FITC channel sensitivity to be very low, then there is likely a problem of some sort. The "bead-calibration" graph can help you identify what the problem is.

How do I fix the error: "Bead calibration failed: found no bead peaks"?

If you have adjusted your FITC channel to be extremely low sensitivity, then the brightest peak produced by SpheroTech RCP-30-5A beads may still be to the left of the default cutoff of 102. If this happens, then you will need to adjust the "bead min" setting down from its default of 2, to the exponent where you want the cutoff to be (e.g., 1.5 cuts off the search for peaks at 101.5). The lower the threshold, however, the more that quantization noise that can interfere with computing the peak, so if the peak is too low, you may want to consider adjusting your channel to be more sensitive.

If you have not adjusted your FITC channel sensitivity to be very low, then there is likely a problem with your equipment or your
protocols. The "bead-calibration" graph can help you identify what the problem is.

How do I fix the error: "Bead calibration failed: found unexpectedly many bead peaks"?

This error means that the software has found more peaks than should be produced by SpheroTech RCP-30-5A beads, and so therefore knows that something is wrong. The most likely causes are:

  • Bead data is noisy because not enough was taken: the graphed data should highest peaks on the graph should should be at least 500 or so on the graph
  • Problems with your equipment or protocol, such as contamination or calibration problems.

If you have noisy bead data, then the software's ability to guess what thresholds it should set for finding peaks is likely to fail, producing a "bead-calibration" graph like the one below (the red lines show where the software has found peaks).

Noisy bead data with too many peaks

You can adjust this by setting the "bead peak threshold" parameter by hand, rather than allowing it to be automatically computed. The graph below shows correctly identified peaks produced by manually setting the threshold to 30.

Hand-tuned bead calibration

What does the warning: "Bead calibration probably incorrect: fit more than 5 percent off" mean?

Fluorescent beads are designed with different size gaps between the different fluorescence peaks, so that as long as you can see at least three peaks in your flow cytometry data's FITC data, then you can correctly convert from arbitrary FITC units into standard MEFL units. If the peaks found by the software have different gaps than the peaks that should be produced by SpheroTech RCP-30-5A beads, then it indicates that the calibration process has gone wrong somehow.

This warning is generally caused by the same sort of issues as the "Bead calibration failed: found unexpectedly many bead peaks" error above, and usually indicates a problem that must be corrected in the same way. If the difference is very slight, however, then it may indicate that your data noisier than expected but still usable: you should inspect the "bead-calibration" graph and see whether the peaks found by the software (red lines) align well with the distribution curve (blue line).

What are the Color Mapping Controls for?

The Color Mapping Controls are used by the tools for two purposes:

  1. mapping measured fluorescence to standard units of MEFL (Molecules of Equivalent Fluorescein)
  2. computing expected levels of expression variability.

With regards to the first purpose: MEFL is only defined for the FITC channel of a flow cytometer, so only one fluorescent marker (whichever is measured with FITC), can have its expression converted directly to MEFL. The Color Mapping controls are used to answer the question: "What would I have measured here, if I were using the FITC-channel marker instead?" Co-expression of three identically regulated fluorescent markers allows one marker to be used as a control for studying the relative expression levels of the other two markers.

With regards to the second: variation in the expression of a sequence comes both from variability of the context (e.g., cell size, state and health, number of circuit copies) and also from sequence-specific variability (e.g., input variation, stochastic expression processes). Co-expression of two identically regulated fluorescent markers allows the tools to separate these two classes of variability from one another by considering how much each marker varies with respect to the other in individual cells.

How should I set up colors for my Color Mapping Controls?

If you have only one fluorescent marker, choose something that you can measure effectively in your flow cytometer's FITC channel. Then you will not need and Color Mapping Controls.

If you have three fluorescent markers, create a system that constitutively co-expresses all three markers. For those organisms where it is possible, our recommended best-practice is lipofection with an equal dosage of three plasmids (one per marker): this both avoids construction of a special-purpose multi-marker plasmid and also avoids possible effects from sequence ordering. When creating your Control Set in the online tools, you need to add two rows, where each row uses a different non-FITC marker as the Constitutive Channel.

If you have more than three markers, break them into groups of two plus the FITC marker, choosing the groups to minimize spectral overlap. For example, if your markers are Blue, Cyan, FITC, Red, and IR, you could group them into Cyan, Red, FITC and into Blue, IR, FITC. Then treat each group as described for three markers.

The tools do not currently support a system with precisely two fluorescent markers. If you need this, contact us at biotools@bbn.com.

What does the error "Not all channels can be translated to standard MEFL units" mean?

When you see this error, it should follow immediately after one or more warnings saying "No pairwise translation for [Channel X] to [your FITC channel]". This error means that something has gone wrong with your control data. Usually, this is either because you have not added a Color Mapping Control with Channel X and your FITC channel, or else because one or more of your controls is failing to express properly. This could be either the Color Mapping Control itself or one of the others, whose failed expression causes the translation to be working with invalid numbers.

This error can also be caused by misconfiguring your flow cytometer: if you gave more than one channel the same laser/filter combination, the code will think they are the same channel and get very confused. This is not a bug in the code, but a feature intended to allow data to be compared even if channels are relabeled in a flow cytometer.

What does the warning "Translation from [Channel] to [Channel] not invertible" mean?

One of the tools' internal validity checks on a color model is to test that the function for translating from color A to color B is precisely the inverse of the function for translating from color B to color A. If a round-trip of translating a test value results in a value more than 5% different than the initial value, then you will see this warning. This typically indicates that something has gone wrong with your controls. If the value reported is very close to 1, however, your data may still be usable: you should inspect the associated "color-translation" plots and see whether there is a mostly linear region of high expression and that this region is well aligned with the black sequence of extracted data points and the red line of the extracted translation model, as in the example below:

Good color translation sample

Experiment Analysis

What does the warning "Assuming only a single inducer exists" mean?

You can ignore this warning. It means that someday we want to support analysis of experiments where you change more than one parameter.

Other Errors and Warnings

Warnings about Displays and Printing

When you run either the Color Model tool or Experiment Analysis tool, the "Errors and Warnings" section in your output will generally start with something like the following:

warning: X11 DISPLAY environment variable not set
warning: print.m: epstool binary is not available.
Some output formats are not available.
warning: print.m: fig2dev binary is not available.
Some output formats are not available.
warning: print.m: pstoedit binary is not available.
Some output formats are not available.

These warnings about displays and printing should be ignored. They come from the software that we are using the create the graphs, which complains that it would like more toys to play with. They don't affect its output, but we haven't figured out how to keep it from generating them yet.

Result thumbnails are broken links in the Chrome browser

We do not know why, but currently the Google Chrome browser shows broken links rather than thumbnail images in all results pages. The images are still there: you can retrieve them through the links below the thumbnails as usual. For the present, we recommend using a different browser, such as Firefox or Safari.

Missing files and "GPL Ghostscript 8.70: Unrecoverable error, exit code 1"

The current version of the online tools is not quite smart enough about handling names with anything other than alphanumeric characters. When one gets through, the code makes a hash of the output filenames, and are likely to see this error and have files go missing.

This most frequently happens when you have a space in the name of a flow cytometer channel, or an experiment device or inducer. Change the name to remove unusual characters and try again.