cytoflow.operations.bead_calibration

class cytoflow.operations.bead_calibration.BeadCalibrationOp[source]

Bases: traits.has_traits.HasStrictTraits

Calibrate arbitrary channels to molecules-of-fluorophore using fluorescent beads (eg, the Spherotech RCP-30-5A rainbow beads.)

Computes a log-linear calibration function that maps arbitrary fluorescence units to physical units (ie molecules equivalent fluorophore, or MEF).

To use, set beads_file to an FCS file containing events collected using the same cytometer settings as the data you’re calibrating. Specify which beads you ran by setting beads to match one of the values of BeadCalibrationOp.BEADS; and set units to which channels you want calibrated and in which units. Then, call estimate() and check the peak-finding with default_view().plot(). If the peak-finding is wacky, try adjusting bead_peak_quantile and bead_brightness_threshold. When the peaks are successfully identified, call apply() to scale your experimental data set.

If you can’t make the peak finding work, please submit a bug report!

This procedure works best when the beads file is very clean data. It does not do its own gating (maybe a future addition?) In the meantime, I recommend gating the acquisition on the FSC/SSC channels in order to get rid of debris, cells, and other noise.

Finally, because you can’t have a negative number of fluorescent molecules (MEFLs, etc) (as well as for math reasons), this module filters out negative values.

units

A dictionary specifying the channels you want calibrated (keys) and the units you want them calibrated in (values). The units must be keys of the beads attribute.

Type:Dict(Str, Str)
beads_file

A file containing the FCS events from the beads.

Type:File
beads

The beads’ characteristics. Keys are calibrated units (ie, MEFL or MEAP) and values are ordered lists of known fluorophore levels. Common values for this dict are included in BeadCalibrationOp.BEADS.

Type:Dict(Str, List(Float))
bead_peak_quantile

The quantile threshold used to choose bead peaks.

Type:Int (default = 80)
bead_brightness_threshold

How bright must a bead peak be to be considered?

Type:Float (default = 100)
bead_brightness_cutoff

If a bead peak is above this, then don’t consider it. Takes care of clipping saturated detection. Defaults to 70% of the detector range.

Type:Float
bead_histogram_bins

The number of bins to use in computing the bead histogram. Tweak this if the peak find is having difficulty, or if you have a small number of events

Type:Int (default = 512)
force_linear

A linear fit in log space doesn’t always go through the origin, which means that the calibration function isn’t strictly a multiplicative scaling operation. Set force_linear to force the such behavior. Keep an eye on the diagnostic plot, though, to see how much error you’re introducing!

Type:Bool (default = False)

Notes

The peak finding is rather sophisticated.

For each channel, a 256-bin histogram is computed on the log-transformed bead data, and then the histogram is smoothed with a Savitzky-Golay filter (with a window length of 5 and a polynomial order of 1).

Next, a wavelet-based peak-finding algorithm is used: it convolves the smoothed histogram with a series of wavelets and looks for relative maxima at various length-scales. The parameters of the smoothing algorithm were arrived at empircally, using beads collected at a wide range of PMT voltages.

Finally, the peaks are filtered by height (the histogram bin has a quantile greater than bead_peak_quantile) and intensity (brighter than bead_brightness_threshold).

How to convert from a series of peaks to mean equivalent fluorochrome? If there’s one peak, we assume that it’s the brightest peak. If there are two peaks, we assume they’re the brightest two. If there are n >=3 peaks, we check all the contiguous n-subsets of the bead intensities and find the one whose linear regression (in log space!) has the smallest norm (square-root sum-of-squared-residuals.)

There’s a slight subtlety in the fact that we’re performing the linear regression in log-space: if the relationship in log10-space is Y=aX + b, then the same relationship in linear space is x = 10**X, y = 10**y, and y = (10**b) * (x ** a).

Examples

Create a small experiment:

>>> import cytoflow as flow
>>> import_op = flow.ImportOp()
>>> import_op.tubes = [flow.Tube(file = "tasbe/rby.fcs")]
>>> ex = import_op.apply()

Create and parameterize the operation

>>> bead_op = flow.BeadCalibrationOp()
>>> beads = "Spherotech RCP-30-5A Lot AA01-AA04, AB01, AB02, AC01, GAA01-R"
>>> bead_op.beads = flow.BeadCalibrationOp.BEADS[beads]
>>> bead_op.units = {"Pacific Blue-A" : "MEBFP",
...                  "FITC-A" : "MEFL",
...                  "PE-Tx-Red-YG-A" : "MEPTR"}
>>>
>>> bead_op.beads_file = "tasbe/beads.fcs"

Estimate the model parameters

>>> bead_op.estimate(ex)

Plot the diagnostic plot

>>> bead_op.default_view().plot(ex)
_images/cytoflow-operations-bead_calibration-4.png

Apply the operation to the experiment

>>> ex = bead_op.apply(ex)
estimate(experiment)[source]

Estimate the calibration coefficients from the beads file.

Parameters:experiment (Experiment) – The experiment used to compute the calibration.
apply(experiment)[source]

Applies the bleedthrough correction to an experiment.

Parameters:experiment (Experiment) – the experiment to which this operation is applied
Returns:A new experiment with the specified channels calibrated in physical units. The calibrated channels also have new metadata:
  • bead_calibration_fn : Callable (pandas.Series –> pandas.Series)
    The function to calibrate raw data to bead units
  • bead_units : String
    The units this channel was calibrated to
Return type:Experiment
default_view(**kwargs)[source]

Returns a diagnostic plot to see if the peak finding is working.

Returns:An diagnostic view, call plot() to see the diagnostic plots
Return type:IView
BEADS = {'Spherotech RCP-30-5A Lot AA01-AA04, AB01, AB02, AC01, GAA01-R': {'MEAP': [587, 2433, 6720, 17962, 30866, 51704, 146080], 'MEAPCY7': [718, 1920, 5133, 9324, 14210, 26735], 'MEBFP': [700, 1705, 4262, 17546, 35669, 133387, 412089], 'MECSB': [179, 400, 993, 3203, 6083, 17777, 36331], 'MECY': [1437, 4693, 12901, 36837, 76621, 261671, 1069858], 'MEFL': [692, 2192, 6028, 17493, 35674, 126907, 290983], 'MEPCY7': [32907, 107787, 503797], 'MEPE': [505, 1777, 4974, 13118, 26757, 94930, 250470], 'MEPTR': [207, 750, 2198, 6063, 12887, 51686, 170219]}, 'Spherotech RCP-30-5A Lot AG01, AF02, AD04 and AAE01': {'MEAP': [373, 1079, 3633, 9896, 28189, 79831, 151008], 'MEAPCY7': [2864, 7644, 19081, 37258], 'MEBFP': [861, 1997, 5776, 15233, 45389, 152562, 396759], 'MECSB': [216, 464, 1232, 2940, 7669, 19812, 35474], 'MECY': [1614, 4035, 12025, 31896, 95682, 353225, 1077421], 'MEFL': [792, 2079, 6588, 16471, 47497, 137049, 271647], 'MEPCY7': [14916, 42336, 153840, 494263], 'MEPE': [531, 1504, 4819, 12506, 36159, 109588, 250892], 'MEPTR': [233, 669, 2179, 5929, 18219, 63944, 188785]}, 'Spherotech RCP-30-5A Lot AK02, AK03, AK04': {'MEAP': [341, 1027, 3156, 7750, 23446, 68702, 116813], 'MEAPCY7': [173, 427, 1097, 2399, 6359, 17475, 30725], 'MEBFP': [844, 1958, 5422, 13522, 42717, 153501, 420359], 'MECSB': [205, 470, 1211, 2740, 7516, 20122, 35573], 'MECY': [1414, 3809, 10852, 27904, 85866, 324106, 1040895], 'MECY7': [12752, 39057, 142958, 448890], 'MEFL': [771, 2106, 6262, 15183, 45292, 136258, 291042], 'MEPE': [487, 1474, 4516, 11260, 34341, 107608, 260461], 'MEPTR': [205, 643, 2021, 5278, 17018, 62451, 198933]}, 'Spherotech URCP-100-2H (9 peaks)': {'MEAP': [369, 749, 3426, 10413, 50013, 177490, 500257, 1252120], 'MEAPCY7': [1363, 2656, 9791, 25120, 96513, 328967, 864905, 2268931], 'MEBFP': [1957, 5579, 16005, 53621, 168302, 459809, 1581762, 4999251], 'MECSB': [989, 2959, 8277, 25524, 71603, 173069, 491388, 1171641], 'MEFL': [3531, 11373, 34643, 107265, 324936, 835306, 2517654, 6069240], 'MEPCY': [6501, 20302, 59517, 183870, 550645, 1569470, 5109318, 17854584], 'MEPCY7': [4490, 10967, 30210, 87027, 283621, 975312, 4409101, 24259524], 'MEPE': [2785, 9525, 28421, 90313, 275589, 713181, 2209251, 5738784], 'MEPTR': [1158, 4161, 12528, 41140, 130347, 344149, 1091393, 2938710]}}

A dictionary containing the calibrated beads that Cytoflow currently knows about. The available bead sets, the fluorophores and the laser / filter sets with which they were characterized are below:

  • Spherotech RCP-30-5A Lot AK02, AK03, AK04
    • MECSB (Cascade Blue, 405 –> 450/50)
    • MEBFP (BFP, 405 –> 530/40)
    • MEFL (Fluroscein, 488 –> 530/40)
    • MEPE (Phycoerythrin, 488 –> 575/25)
    • MEPTR (PE-Texas Red, 488 –> 613/20)
    • MECY (Cy5, 488 –> 680/30)
    • MEPCY7 (PE-Cy7, 488 –> 750 LP)
    • MEAP (APC, 633 –> 665/20)
    • MEAPCY7 (APC-Cy7, 635 –> 750 LP)
  • Spherotech RCP-30-5A Lot AG01, AF02, AD04 and AAE01
    • MECSB (Cascade Blue, 405 –> 450/50)
    • MEBFP (BFP, 405 –> 530/40)
    • MEFL (Fluroscein, 488 –> 530/40)
    • MEPE (Phycoerythrin, 488 –> 575/25)
    • MEPTR (PE-Texas Red, 488 –> 613/20)
    • MECY (Cy5, 488 –> 680/30)
    • MEPCY7 (PE-Cy7, 488 –> 750 LP)
    • MEAP (APC, 633 –> 665/20)
    • MEAPCY7 (APC-Cy7, 635 –> 750 LP)
  • Spherotech RCP-30-5A Lot AA01-AA04, AB01, AB02, AC01, GAA01-R
    • MECSB (Cascade Blue, 405 –> 450/50)
    • MEBFP (BFP, 405 –> 530/40)
    • MEFL (Flurosceine, 488 –> 530/40)
    • MEPE (Phycoerythrin, 488 –> 575/25)
    • MEPTR (PE-Texas Red, 488 –> 613/20)
    • MECY (Cy5, 488 –> 680/30)
    • MEPCY7 (PE-Cy7, 488 –> 750 LP)
    • MEAP (APC, 633 –> 665/20)
    • MEAPCY7 (APC-Cy7, 635 –> 750 LP)
  • Spherotech URCP-100-2H (9 peaks)
    • MECSB (Cascade Blue, 405 –> 450/50)
    • MEBFP (BFP, 405 –> 530/40)
    • MEFL (Flurosceine, 488 –> 530/40)
    • MEPE (Phycoerythrin, 488 –> 575/25)
    • MEPTR (PE-Texas Red, 488 –> 613/20)
    • MECY (Cy5, 488 –> 680/30)
    • MEPCY7 (PE-Cy7, 488 –> 750 LP)
    • MEAP (APC, 633 –> 665/20)
    • MEAPCY7 (APC-Cy7, 635 –> 750 LP)
class cytoflow.operations.bead_calibration.BeadCalibrationDiagnostic[source]

Bases: traits.has_traits.HasStrictTraits

A diagnostic view for BeadCalibrationOp.

Plots the smoothed histogram of the bead data; the peak locations; a scatter plot of the raw bead fluorescence values vs the calibrated unit values; and a line plot of the model that was computed. Make sure that the relationship is linear; if it’s not, it likely isn’t a good calibration!

op

The operation instance whose parameters we’re plotting. Set automatically if you created the instance using BeadCalibrationOp.default_view().

Type:Instance(BeadCalibrationOp)
plot(experiment)[source]

Plots the diagnostic view.

Parameters:experiment (Experiment) – The experiment used to create the diagnostic plot.