TASBE Tools: Characterization Workflow Documentation

Overview

This file gives a "quick start" overview of how the tools in the TASBE Characterization Workflow fit together and how to use each tool with "normal" data.  For more detailed information about how to interpret and debug the results from the tools, see the document Understanding Tool Results.

The Characterization Workflow of the TASBE tools comprises three tools:

  • FACS Machines: Specify the names of fluorescent channels that your FACS machine can acquire, and the laser/filter combination for each channel.
  • Color Models: Load and process a set of positive and negative controls for your experiment.  These both serve as controls in the usual sense and provide a model for converting from arbitrary FACS units to compensated and calibrated standard MEFL units.
  • Characterization Experiments: Load and process a set of experimental data for the behavior of a circuit with respect to varying levels of induction.

The general workflow for using these is as follows:

           
        Flow chart of characterization workflow

If you wish to follow along with the steps in this documentation, you can download the files used in this demo.

Specifying a FACS Machine

The page for creating a FACS machine looks like this:

Partially completed FACS model

The "FACS Machine Name" field is how the machine will be described in menus later, when you select it as the instrument that generated a piece of data.  The "Notes" field is whatever other information you want to include for yourself.

The most critical part of the form is the channels, which list the set of fluorescence measurements that are available from this FACS machine Make sure each "Channel Name" is exactly as it will appear in the .fcs files generated by your FACS machine.  If you get this wrong, then when you try to create color models or run experiments, you will get complaints that your channels cannot be found.  Laser and filter information is not currently used in the analysis --- it is for your benefit only.

Once you've created your FACS machines, you can review them by using the "List all my FACS machines" page and clicking on the "View Details" link by a machine.

Example list of FACS machines
Example FACS details

Making a Color Model from Controls

For a characterization experiment, the controls not only establish confirmation that the positive and negative behavior of the cells is able to be read correctly, but also provide a color models that is used for calibrating the analysis so that results can always be reported in standardized equivalent units.

To do this, you will need the following set of controls:

  • SpheroTech RCP-30-5A beads --- these are used to obtain standard MEFL units for the FITC channel
  • Blank cells (either with no plasmids or (preferably) with non-expressing plasmids) --- these are used for removing autofluorescence
  • Cells constitutively expressing each fluorescent color to be used --- these are used to compensate for spectral overlap
  • Cells simultaneously constitutively expressing sets of three fluorescent colors --- these are used to obtain standard MEFL units for all other channels

Creating a color model is done in two stages; first you use "Create a control set" to upload a collection of .fcs files for your controls. 

On this page, start by choosing a name for this data set, adding any notes you want, along with the FACS Machine and channels that you want to use.

Control set header

Below this, there are places to upload the blank and bead files, plus a file of constitutive fluorescent protein expression for each channel that you have chosen:

Entries for control .fcs files

Finally, there is a table to put in as many three-fluorescence translation models as you have in your control set:

Color translation table example

It doesn't matter which fluorescent protein goes in Channel 1 versus Channel 2: a translation model is built in both directions.  However, you must have a pair of [Channel]/FITC-A for every other channel that you are using.  If you do not, the analysis software will not be able to translate those channels into standard MEFL units.

Once you have created the control set, you will be taken to a settings page for analyzing it into a color model:

Color model settings

On this page, you just need to enter the name of the color model and how you want the channels displayed.  There are also options for changing thresholds used in constructing the color model; unless you have a reason to do so, it is best to stick with the defaults.

When you hit the "Run color model" button, the system will process for a while, then eventually display your results:

Example color model

This page includes a link for downloading a "CM.mat" file containing the Matlab/Octave data structures for the color model. When you load this .mat file, it will report many warnings, as the objects used on the server are converted into structures; you should ignore these warnings: the data inside is intact. The page also includes a collection of all of the graphs generated with the color model, which may be downloaded in either .png or PDF format:

Graphs generated for color model

Just as with FACS machines, you can return to your sets of control data using the "List all my control sets" page and return to your color models using the "List all my color models" page. You can also produce new models from the same set of controls using the "Create Color Model" link in the list of control sets.

Entering Your Experimental Data

Finally, to run analysis of a characterization experiment, you fill in three sections on the "Enter data" page.

First is the metadata for the experiment, including what construct you have used and the conditions for the experiment.  Although these are all free-text fields, they are required in order to encourage good data curation. Note that the Device name will be used as part of file names later, so you should keep it terse.

Example characterization metadata

In the next section of the form, you select which colors are being used for which parts of the characterization experiment:

  • The input is regulated by the inducer, and should correspond to the concentration of the regulatory protein being characterized
  • The output is regulated by the regulatory protein being characterized
  • The constitutive indicates the expected number of copies of the system in the cell

At present, the software assumes that you are always characterizing a one-input and one-output device that is not affected directly by your inducer.  There will eventually be options for characterization of other classes of devices.  At present, if you are characterizing just an inducer, then select an unused channel for your "output".

Example experiment channel selection

The final section of the form is where you write the name of your inducer and upload all of the .fcs files holding your experimental data:

Example experiment inductions

This table has one row for each induction level that you gathered data for, and one column for each replicate.  The example shown has 11 induction levels for which one replicate has been gathered each.  If it were in triplicate, then two presses of "Add another set of files" would add two more columns, into which more files could be added.  At present, the form requires that there be no missing replicates; this will be generalized in the future.

Analyzing Your Experimental Data

Once you have entered a data-set, you will be taken to a page where you can enter the settings for running your analysis.  The experiment name and results prefix are your choice of how you want graphs labelled and graph files named.  Another setting that you may wish to change, if you have information, is the MEFL per plasmid, which sets a linear relation between observed fluorescence and expected number of plasmids in the cell. The other settings control the "binning" that will be used for dividing cells by CFP level and thresholds for excluding data.   Unless you have reason to do otherwise, stay with the default.

Example of analysis settings

Finally, when you hit "Run experiment analysis", the system will process for several minutes, depending on how much data you have uploaded, before taking you to a results page:
Example of analysis settings
The results page shows the characterization analysis and a downloadable .mat file with the data. When you load this .mat file, it will report many warnings, as the objects used on the server are converted into structures; you should ignore these warnings: the data inside is intact. The pages also includes a collection of all of the graphs generated from the analysis of the characterization data. These graphs are mainly useful as controls, showing the calibration of each channel and the measured levels of per-cell expression noise.
Example of analysis settings
These graphs are:

  • Input/output curve for the device being characterized, with and without normalization by estimated plasmid count
  • Input/output curve for induction, with and without normalization by estimated plasmid count
  • A graph of the number of FACS events in each constitutive fluorescence level bin
  • Models of the distribution of plasmids and percentage of cells that have active expression of constitutive fluorescence