User's Guide

Introduction

FacsKin is a computer program that enables the mathematical description and statistical comparison of Flow Cytometry acquired kinetic measurements (such as calcium flux measurements). The output of a Flow Cytometry measurement is an FCS file containing FSC, SSC, fluorescent and time parameter values for each cell in the specimen. Kinetic measurements are special because the distribution of at least one parameter (the kinetic parameter) changes as time passes. FacsKin is able to describe the kinetic change that occurs during the measurement by fitting different functions to the kinetic parameter values. By selecting a common function that describes every measurement well, FacsKin is able to compare different groups of measurements based on parameters of the selected function. The available functions and thus the kinetic changes that FacsKin is able to describe are the following (Figure 1):

  • constant: the value of the kinetic parameter is constant during the measurement timeframe
  • logist+: the kinetic parameter starts at a given value, increases during the measurement timeframe and reaches a given value
  • logist-: same as logist+, but the kinetic parameter value is decreasing during the measurement timeframe
  • dlogist+: the kinetic parameter starts at a given value, increases, reaches a maximum value and then decreases and reaches a given value during the measurement timeframe
  • dlogist-: same as dlogist+, but the kinetic parameter value first decreases, reaches a minimum and then increases

The analysis with FacsKin requires the following steps (Figure 2):

  1. Acquiring measurement data
  2. Starting FacsKin
  3. Opening and gating FCS files
  4. Generating a .kinetics file from the gated data in R.
  5. Opening different .kinetics files and selecting a common function (a .kinetics file contains the results of fitting all 5 previously described functions to the gated data)
  6. Creating groups and comparing parameters of the selected function in different groups

The detailed description of the these steps follows.

1. Acquiring measurement data

FacsKin is only able to analyse those measurements that were acquired by a Flow Cytometer in compliance with these criteria:

  • All requirements specified for the particular dyes (such as staining time, protecting samples from light, vortexing the sample before measurement etc.) should be carefully followed.
  • Before starting recording data check the stream and flow rate so that the event count per second be stable and the control dot-plots look as expected. The minimum flow rate that could be analysed with FacsKin is 200 events/s but optimally the flow rate should be around 1000 events/s.
  • IMPORTANT: before stimulating the specimen (eg. PHA activation of lymphocytes) record a baseline of at least 30 seconds length. Optimally the length of the baseline is 10% of the length of the whole measurement. Also make sure that the kinetic parameter of interest reaches a constant value before the end of the recording (for calcium flux measurements in activated lymphocytes this usually takes at least 15 minutes). This second constant time range should be optimally 10% of the whole measurement as well.
  • In case you need to pause sample acquisition and data recording for the stimulation of your sample after recording a baseline (eg. because you are using a Flow Cytometer in which the sample is not accessible during the measurement) the time taken for the stimulation of the specimen should be recorded either by the Flow Cytometer (creating an FCS with a gap between the baseline and the stimulated measurement) or the researcher (by measuring the time with a clock and recording the baseline and the stimulated measurements into separate FCS files - you will be asked for the length of this time when opening the two FCS files with FacsKin). This time should be as short as possible.
  • The sample should contain enough cells so that the desired timeframe could be recorded.
  • During the measurement the flow rate should be constant (size of the flow rate as described earlier) and the control dot-plots should be monitored at all time.
  • If possible use FCS 3.0 format when exporting data.

2. Starting FacsKin

FacsKin runs on any computer with at least 1 GB of RAM and on a recent Linux, Mac OS X or Windows operating system.

2.1. Starting FacsKin on Windows

  1. Download and install Java.
  2. Download FacsKin from https://facskin.bitbucket.io/FacsKin.zip and open the downloaded ZIP file.

  3. Copy the FacsKin folder from the ZIP file to your Desktop (or to any folder you wish).
  4. Start the program by clicking FacsKin (MS-DOS Batch File) in the FacsKin folder.

2.2. Starting FacsKin on Mac OS X

  1. Download and install Java.

  2. Download FacsKin from https://facskin.bitbucket.io/FacsKin.zip and open it.
  3. Control-right click on Facskin.Command and select Open.

  4. Answer Open to the question "Are you sure you want to open it?"

Upgrading and Uninstalling

FacsKin does not detect new versions automatically. To check whether a new version is available, look at the top-left corner of the website https://facskin.bitbucket.io and compare the version given there with the one mentioned in the About Box (Help / About). The newest version of FacsKin is always available as a ZIP bundle on the following URL: https://facskin.bitbucket.io/FacsKin.zip. To uninstall FacsKin installed by this method simply delete the containing folder.

The user data of FacsKin on Linux is stored in ~/.FacsKin, on Windows it is stored in a subfolder of the Application Data folder in the user's home directory. The size and position of the FacsKin window is stored here. When uninstalling FacsKin, this data will remain on the computer, but you can safely delete it any time.

3. Opening and gating FCS files

When starting FacsKin, the Open file panel appears automatically but you can reach this panel from the File/Open menu item later. From the Open panel, select the FCS file you want to load and click Open (you can select multiple files at once, they will be opened in separate tabs).

Concatenating FCS files: If you have a separate FCS file for the baseline measurement and another one for the measurement after stimulation you should open the first measurement and then append the second one by the File/Append FCS menu item. A pop-up window will ask you about the size of gap (in seconds) that should be inserted between the two measurements. This value should be as close to the real value as possible because it can influence the analysis. The default value is 30 seconds. (You can check whether the measurement was appended correctly by selecting the Time parameter on the horizontal axis. You should notice a gap of the same size you selected.)

After opening an FCS file a tab will appear labeled with the name of the FCS file. In the middle you will see the scatter plot of the selected channels (by default FSC (forward scatter) on the horizontal and SSC (side scatter) on the vertical axis). You can select the channel on the corresponding axis by clicking on the drop down menu near the corresponding axis. You can display the selected channel on a logarithmic scale by clicking the Log checkbox. To view the histogram of the channel selected on the horizontal axis, select Histogram from the drop down menu for the vertical axis. On the right side you can see some information about the measurement (filename, FCS version, date of measurement and count of events).

Gating:

  • Scatter plot gate: to pick out events based on two parameters, select the desired parameters on the horizontal and vertical axes, and select the vertices of the polygon by clicking on the scatter plot with the left mouse button. The semi-finished polygon is drawn with red color and if you finished the selection it is drawn with green color. To restart the selection of the polygon click on the scatter plot with the right mouse button. You can select a rectangle instead of a polygon by selecting Rectangular gate on the left. (It is especially helpful when gating based on the time parameter. This is sometimes important when there was some disturbance during a time point of the measurement. In this case the time range where the disturbance occurred should be gated out with inverse gate, see below.)

  • Histogram gate: to pick out events based on one parameter, select Histogram on the vertical axis and select the area on the histogram plot by clicking the left mouse button and dragging until selection end. The red rectangle shows the currently selected range.

By clicking the Add Gate button you can apply the selected gate. If you want to pick out the events outside the selected area, select the Inverse gate checkbox before clicking Add Gate. You can follow the change in the number of events on the right side of the window.

Currently you cannot cancel gates individually but you can restart gating by clicking the Clear all gates button.

To view the change in the value of the measured kinetic parameter over time, select the time channel on the horizontal axis, select the channel for the kinetic parameter on the vertical axis and click the Show medians checkbox. The green curve shows how the median values change over time. From this plot you can get an impression about the type of kinetic response the measurement shows. If the kinetic response shown by this plot can't be described by the available functions (eg. the value of the measured kinetic parameter first increases, then decreases, then increases again - out of the 5 functions available none can describe the last increasing part) you should consider creating a gate based on the time parameter selecting only a region were the change of the measured kinetic value could be described by one of the functions.

When you gated the desired cell population finish gating by clicking the Done gating button.

After gating, you have to save the gated data to the analysis folder.
  1. Select the measured kinetic parameter. If you have a channel for that parameter you should choose the appropriate channel in the left drop down menu under the Choose parameter ratio to be analyzed against time label and leave the value 1.0 in the right drop down menu. If you want to analyze the ratio of two parameters (eg. Fluo-3/Fura Red corresponding to FITC/PerCP), choose the appropriate parameters in the nominator (left) and denominator (right) checkbox.
  2. You can optionally give the length of the baseline part of the measurement (seconds). If given, the starting value parameter of the fitted function will be the median value of the baseline part.
  3. You need to select the number of quantiles to be fitted. If selecting 1, only one function will be fitted to the measurement which will describe how the middle cells behave in terms of the kinetic process (Use only median functions cannot be disabled, see below). If selecting 201, the whole range of cells will be described, however, the fitting process will take much longer.
  4. Choose a name for the analysis.
  5. Save gated data into a .gated file in the analysis folder. This folder is inside the FacsKin folder (where you extracted the FacsKin zip bundle). The .gated file is a gzip-compressed file containing the gated data in text format.

4. Generating a .kinetics file from the gated data in R

  1. If you don't have R installed on your computer, download and install it.
  2. Start the R environment (RGui) -- there should be an icon on your desktop.
  3. Select File/Change dir...

  4. Select the folder facskin (where you extracted the FacsKin zip bundle) and click OK.

  5. Type source("run.R") in the R Console window and press Enter.

  6. If you get a result similar to the following, it means that you haven't specified the correct folder. 
    > source("run.R")
Error in file(filename, "r", encoding = encoding) : 
  cannot open the connection
In addition: Warning message:
In file(filename, "r", encoding = encoding) :
  cannot open file 'run.R': No such file or directory
    In this case please go back to step 3. again.
  7. Otherwise, wait until you see a result similar to the following:
    > source("run.R")
fct: 1 -> 1
fct: 4 -> 1
fct: 4 -> 1
fct: 8 -> 1
fct: 8 -> 1
>
    If there are several .gated files in the analysis folder, a .kinetics file will be generated for all of them. This can take several minutes. If R finished computation, you can find the .kinetics files in the analysis folder.

  8. Move away all the .gated and .kinetics files from the analysis folder, so that next time you run the R program, it doesn't compute the .kinetics files again.

5. Opening different .kinetics files and selecting a common function

You can open .kinetics files in FacsKin just as you did it with FCS files. A tab named Kinetics will be opened where you see the following (Figure 12):

  • (green) on top there is a plot showing the median points of the measurement and the currently selected function fitted to these median points. The median points are the medians of the kinetic fluorescent parameter values selected before saving the gated cell population (the same points as the green lines shown in Figure 6).
  • on the bottom you see a table where each row corresponds to an opened .kinetics file.
  • (red) to choose between functions, click on the column header of the gray-background columns. To select the constant function, click constant etc. Note how the plot changes while selecting different functions. The function selected in Figure 12. is logist+.
  • (blue) the last columns of the table change when selecting different functions: each function has a different set of parameters. Clicking the column of a parameter results in visualizing the distribution of that parameter ((orange)).
  • while moving the mouse over the plot you can track the coordinates with the cursor. When selecting Use Only Median Functions only the parameters of the function fitted to the median points appear in the table. Try to match the parameters in the table with the corresponding coordinates seen on the plot (eg. maximum value parameter in the table should have the same value as the second coordinate of the highest value of the function as seen on the plot).
  • (purple) by default the kinetic parameter is standardized so at time point 0 the value of the median point is 1 (the vertical axis shows relative parameter values). If you deselect Preferences/Standardization, the function will start at the real measured value (note how the values on the vertical axis change in the plot - now the vertical axis shows absolute parameter values). Standardization can help when you would like to compare measurements that were measured under different conditions. The standardization works as follows: the median is calculated from the first 10 seconds of the measurement (you can set this in Preferences/Set Baseline Length) and all the parameter values are divided by this median.
  • to open more .kinetics files click File/Open. You can select more .kinetics files at once in the Open panel.
  • to save the currently opened .kinetics files in one zip file so as to easily open them next time at once, click File/Save as. Next time just open the zip file with FacsKin and each .kinetics file contained in that zip file will be loaded.
  • (light blue) right clicking a .kinetics file name in the first column brings up a pop-up menu where you can remove, rename or get information of a .kinetics file.

Detailed description of the functions: each function has an own set of parameters. These parameters describe the function entirely: eg. if you know all the 8 individual parameters of a dlogist+ function you will be able draw the function. The available functions and the parameters describing them are the following:

  • each function has an AUC parameter:
    • AUC: the area under curve from time point 0 to by default 600 s (this can be changed in Preferences/Set Maximum Time for AUC menu item - set it to length of the measurement). Eg. if the vertical axis is calibrated for intracellular Calcium concentration (mmol/l), the AUC shows the amount of time all the Calcium atoms spend in one liter of cell volume during the measurement timeframe.
  • constant: the function is a horizontal line having the same value all the time.
    Parameter:
    • constant value
  • logist+: an S-shape function that starts at a given value (starting value) increases and reaches a higher given value (ending value).
    Parameters:
    • starting value: the limit of the function at -∞ (minus infinity). It is not necessarily the value at time point 0. If the function begins with a steep, the starting value is lower than the value at time point 0. This is one reason why it is necessary to record a baseline at the beginning of the measurement
    • ending value: the limit of the function at +∞ (positive infinity). Not necessarily the value of the function at the end of the measurement
    • time to reach 50% value: the time point when the function reaches the 50% value. The 50% value is the average of the starting value and the ending value (unit: s)
    • slope at 50% value: the slope of the function at the 50% value. This is always positive (unit: int/s where int is the unit of the vertical axis. Meaning: how much does the intensity change during 1 second)

  • logist-: an S-shape function that starts at a given value (starting value) decreases and reaches a lower given value (ending value).
    Parameters:
    • starting value: the limit of the function at -∞ (minus infinity). It is not necessarily the value at time point 0. If the function begins with a steep, the starting value is higher than the value at time point 0. This is one reason why it is necessary to record a baseline at the beginning of the measurement
    • ending value: the limit of the function at +∞ (positive infinity). Not necessarily the value of the function at the end of the measurement
    • time to reach 50% value: the time point when the function reaches the 50% value. The 50% value is the average of the starting value and the ending value (unit: s)
    • slope at 50% value: the slope of the function at the 50% value. This is always negative (unit: int/s where int is the unit of the vertical axis. Meaning: how much does the intensity change during 1 second)

  • dlogist+: a function that starts at a given value, has an increasing phase, reaches a maximum, has a decreasing phase and reaches a given ending value.
    Parameters:
    • starting value: the limit of the function at -∞ (minus infinity). It is not necessarily the value at time point 0. If the function begins with a steep, the starting value is lower than the value at time point 0. This is one reason why it is necessary to record a baseline at the beginning of the measurement
    • maximum value: the maximum of the function. It is possible that the maximum point is not in the measurement timeframe (usually meaning that the selected function doesn't fit the measurement well)
    • ending value: the limit of the function at +∞ (positive infinity). Not necessarily the value of the function at the end of the measurement
    • time to reach maximum value: the time point when the function reaches the maximum value (uint: s)
    • time from the first 50% value to maximum: the distance between the time point where the function reaches the first 50% value and where the function reaches the maximum. The first 50% value is the average of the starting value and the maximum (unit: s)
    • slope at first 50% value: the slope of the function at the first 50% value. It is always positive (unit: int/s where int is the unit of the vertical axis. Meaning: how much does the intensity change during 1 second)
    • time from maximum to the second 50% value: the distance between the time point where the function reaches the maximum and where the function reaches the second 50% value. The second 50% value is the average of the maximum and the ending value (unit: s)
    • slope at second 50% value: the slope of the function at the second 50% value. It is always negative (unit: int/s where int is the unit of the vertical axis. Meaning: how much does the intensity change during 1 second)

  • dlogist-: a function that starts at a given value, has a decreasing phase, reaches a minimum, has an increasing phase and reaches a given ending value.
    Parameters:
    • starting value: the limit of the function at -∞ (minus infinity). It is not necessarily the value at time point 0. If the function begins with a steep, the starting value is higher than the value at time point 0. This is one reason why it is necessary to record a baseline at the beginning of the measurement
    • minimum value: the minimum of the function. It is possible that the minimum point is not in the measurement timeframe (usually meaning that the selected function doesn't fit the measurement well)
    • ending value: the limit of the function at +∞ (positive infinity). Not necessarily the value of the function at the end of the measurement
    • time to reach minimum value: the time point when the function reaches the minimum value (uint: s)
    • time from the first 50% value to minimum: the distance between the time point where the function reaches the first 50% value and where the function reaches the minimum. The first 50% value is the average of the starting value and the minimum (unit: s)
    • slope at first 50% value: the slope of the function at the first 50% value. It is always negative (unit: int/s where int is the unit of the vertical axis. Meaning: how much does the intensity change during 1 second)
    • time from maximum to the second 50% value: the distance between the time point where the function reaches the minimum and where the function reaches the second 50% value. The second 50% value is the average of the minimum and the ending value (unit: s)
    • slope at second 50% value: the slope of the function at the second 50% value. It is always positive (unit: int/s where int is the unit of the vertical axis. Meaning: how much does the intensity change during 1 second)

How to choose the best function: to compare measurements you have to select a common function that describes every .kinetics file that you opened. The following criteria should be met when selecting a function:

  • select the function that describes the kinetic response of the measurement best: the plot shows you how well the fitted function follows the median values. Eg. if the median values are increasing with time during the measurement you should consider selecting the logist+ function.
  • select the function with the lowest CV value. CV means cross validation values. The lower the CV value the closer the function to the median values. The CV values are shown for each function in the column corresponding to the function. The lowest CV-value for each .kinetics file is written with red color. A small difference (5% difference should be considered small) in CV values of two functions means that the two functions are almost equally good in this aspect and you should make a choice between them based on the other criteria.
  • if there are still more functions to consider you should select the simpler function: the function that is more to the left in the table and with fewer parameters. If you select a too complex function for a simple measurement kinetic some of your parameters will be without meaning. Eg. if you select the dlogist+ function for a measurement with logist+ kinetic the parameters that describe the decreasing phase of the dlogist+ function (time from maximum to second 50% value, slope at second 50% value, ending value) will have no biological meaning and will have random values with big error. The parameters outside the measurement timeframe are printed with bright color and suggest that the selected function is too complex for the measurement. Another reason for having bright colored parameters can be that you haven't recorded a baseline before starting the stimulation and thus the starting value and related parameters will have a value outside the range of the median values. This is why you should always record a baseline.
  • if you opened multiple .kinetics files you should select the best common function that describes all measurements. If there are some measurements that don't follow the selected function (eg. don't have a decreasing phase while most of the measurements have an increasing and a decreasing phase) be prepared that some of the parameters (in the case of our example the parameters describing the decreasing phase) won't have a biological meaning. Another solution to this problem would be to gate every FCS and analyse them again so that the each gated dataset only contains only the events from the same phase (only from the increasing phase in our example)

If it is selected before fitting, each function is fitted 201 times to different quantiles of the kinetic values so as to enable the description of the whole data range of the measurement (Figure 18). In this case every parameter in the table is given as a parameter distribution (median [quartiles] values). You can think of these parameter distributions in a similar way as of the distributions of directly measured parameters like FSC, SSC and fluorescent parameters: each event in the measurement has an FSC parameter and you are allowed to view the FSC-distribution of a gated set of events. For kinetic parameters like starting value, maximum etc. we don't know the individual values for each event but we are able to view the distributions. We can even compare these distributions, see below.

If you only fitted to 1 quantile or you select Use Only Median Functions only the parameters of the median function are shown in table and only these are used for further comparison (ie. from one measurement you will only get one maximum parameter value instead of a whole distribution of the maximum parameter).

6. Creating groups and comparing parameters

To compare eg. the Slope at 50% value parameter of different measurements, a metric has to be derived from the distribution of Slope at 50% value for each kinetics file. Afterwards, one can compare these metrics among different groups.

FacsKin is able to derive two different metrics:

  1. the median of the distribution. To select this metric, select the Use Only Median Functions checkbox.
  2. the T score of the distribution calculated by Probabiliy Binning method. The T score is a metric that shows how much the distribution differs from a control distribution (0.0 means no difference, the higher the value, the greater the difference). In our case, the control distribution is the Slope at 50% value distributions of all the different kinetics files combined into one distribution. To calculate T scores, click the Calculate T scores button (Figure 20).

The first method does not take into account the whole range of the measured values, only the middle (median) of the measurement. For more information on how the second method works, see http://www.ncbi.nlm.nih.gov/pubmed/11598945.

Creating groups: in the table, by clicking on the drop down menu in a row of a .kinetics file you can assign a group to that .kinetics file. To create a new group select (new) from the drop down menu and give a name to the new group. Each newly opened .kinetics file will be given the group of the .kinetics file in the last row. To view the parameter values aggregated by groups click the Group Data button (Figure 21). The resulting table shows one row per group and the values in each group are the values of the individual .kinetics files combined. A color is assigned to each group and all the functions and median points in the plot that correspond to a group are drawn with the same color.

Comparison: after grouping measurements, the comparison results are shown in the last two rows of the table. A Kruskall-Wallis rank-sum test is performed for each parameter. In the case of two groups this test is equivalent to the Wilcoxon rank-sum test (Mann-Whitney U-test). The chi sqaure values are shown in the last but one row and the p values are shown in the last row. If the p value is smaller than 0.05 it is printed in red.

Exporting comparison data:

  • by right clicking the plots in the Kinetics tab you are able to export the image as a PNG file.
  • by right clicking the table in the Kinetics panel you can copy the contents of the table to the clipboard (Copy table contents). You can paste the table directly into a spreadsheet program such as Excel.
  • by right clicking the column of a parameter in the Kinetics tab you can copy the distributions of the selected parameter in each group/.kinetics file to the clipboard (Copy parameter data). You can paste these values directly into a spreadsheet program such as Excel.
  • by right clicking the name of a group/.kinetics file (first column in the table) in the Kinetics tab you can copy the distributions for every parameter to the clipboard (Copy parameter data). You can paste these values directly into a spreadsheet program such as Excel.
  • by right clicking the table in the Kinetics tab you can export all data contained in the .kinetics files opened to the clipboard and you can paste it as R code into the R statistical programming environment (http://www.r-project.org) for further statistical analysis.

Pairing measurements: if you have logically paired measurements, such as a control and a test measurement for each sample and you would like to test whether the difference between the control and the test measurement differs among different groups of measurements you can use the Pair Data feature:

  • For each test measurement select the corresponding control measurement from the drop-down menu in column Pair

  • Select the appropriate groups in the Group column.
  • Click the Pair Data button. Depending on whether you selected Use Only Median Functions, the result is the following:
    • If Use Only Median Functions was not selected, a probability binning comparison is performed between each test measurement and it's corresponding control and the T scores are given in the table.
    • If Use Only Median Functions was selected, the parameter of the median function of the control measurement is subtracted from that of the test measurement for each corresponding parameter and for each measurement.

  • Click the Group Data button. This groups the values calculated in the previous step as specified in the Group column.