AutoSpectral in Honeychrome

olivertburton
May 26
11 min read

I'm happy to announce that the AutoSpectral workflow for unmixing is being incorporated into the Honeychrome application. Honeychrome is an open-source, Python-based software that you can download and run, interacting with it like commercial software such as FlowJo or FCS Express. Unlike those, it's free to use.

Most of the development of Honeychrome has been done by Samson Rogers, but I've chipped in for the integration of AutoSpectral. The software is in beta testing, and there are still some bugs with my implementation of AutoSpectral, but we feel it performs well enough to release for testing. This should enable anyone to use the unmixing tools, without having to interact with a black box or enter code. I'll cover more about Honeychrome itself, and how you can contribute it you're a developer, in a separate article. We'll probably also need an article about the cool and very cheap open-source spectral cytometer that accompanies Honeychrome as part of the Cytkit project. Today, let's launch into how to use Honeychrome for unmixing of spectral flow cytometry data.

Note: Honeychrome does not currently support unmixing of FCS files from the BD FACSDiscover S8 and A8. Most of the testing so far has been on files from the Cytek Aurora. We've also had some intermittent issues with large files from the Sony ID7000. The issue with the FACSDiscover, at least, should be rectified fairly soon.

Installation

First, download and install Honeychrome. Head over to Cytkit and download the installer for your operating system. This should be as simple as downloading and double-clicking to run the installer. If you're more computationally inclined, you can also clone the GitHub repository and run it directly from Python.

We're going to need some data. If you want to do unmixing, you need to start with files containing the raw data. On the ID7000 and the Aurora, you get separate raw files; on BD's machines, you get the raw and unmixed data all in the same file. I'm going to be using the data from the AutoSpectral workflow example, which you can download here, if you need something to work with.

Getting Started

Now, let's open Honeychrome and start working.

You should see this after clicking on Honeychrome's bee "sidekick" icon:

We're going to create a New Experiment.

Type in the name of your experiment. I'm going to call mine AutoSpectral Demo.

To start, you'll get a blank experiment, looking like this.

Head to the View menu up top and untick Acquisition Panel and Gains Panel to hide those and give yourself more space. Those panels are useful when you're using Honeychrome to acquire samples on a cytometer, but we don't need them right now.

Loading Data

Now, first thing is to add our data. Honeychrome organizes your data into folder in the Experiments folder, which will be created on the root of your user directory tree. The simplest way (for most users) to do this is to use the "Import FCS Files" option in the File menu:

Clicking that brings up this window:

If you use Option A, you bring up the folder for the Honeychrome experiment you're working on, and you can drag in FCS files or folders into the Raw folder.

Since you probably already have your FCS files organized nicely in a folder from the cytometer, you can use option B. For this, we're just going to tell Honeychrome where the data already are, no need to move or copy them.

The fields on the righthand side are selectable, so you can click on these to chang the location, telling Honeychrome where each item is. Let's change the location of the "Single Stain Controls Folder" to the copy of the data I've already got. Click on the "Raw/Single stain controls" field to change it.

Finding the existing single-stained controls folder

After linking:

And we can do the same for the "Raw Samples Folder":

Hit "Okay" once you've linked everything. Hit "Update Experiment Configuration".

Honeychrome has found the files and updated the experiment configuration on the basis that these files are from the 5-laser Cytek Aurora.

Et voila! Samples appear:

Notice that any subfolder organization of the "Raw Samples Folder" is maintained.

Interacting With Data

Let's take a moment to look at the data before we jump into the unmixing workflow. Click on any of the samples to load the data on the screen, which by default will be showing the Raw Data tab.

Here's my CD4 BV421 single-stained cell control:

We've got a default FSC/SSC gate and a singlet gate. Then we've got a spectral ribbon plot showing us the data in all the detectors. There's also a 1D histogram for each detector if you scroll down. Gates can be moved, or they can be adjusted by dragging on any of the corners with a small box icon. To change which gate is used to select the data displayed on a plot, click on the title. For example, we could change the spectral ribbon plot to display all events (root), if we wanted to:

The transformations on the axes are adjustable with the mouse, in a way that will likely be familiar to users of the ID7000. Let's create a new plot to play with. Either click the big + sign to create a new plot:

Or, right-click on an existing gate to create a new plot from that set of gated events:

By default, these new plots will appear at the bottom, after all the other plots, which maybe should be changed for the Raw Data tab. Anyway. Click on the axis label markers to change which parameters are displayed:

Drag on the numbers to change the transformation (scaling):

If you drag near zero, you adjust the compression (width basis) of the biexponential transform.

If you drag on the upper portion, you can change the range, increasing or decreasing it. Note: these are not intended to be examples of what the transformation parameters should be, merely examples of how to set them.

Click on another sample to load that data, and so on.

Unmixing using the Spectral Process

The Spectral Process tab is where you isolate your spectral signatures for your fluorophores. Today we're doing unmixing, but you would also use this tab for performing compensation if you were doing conventional flow. There are two workflows for the isolation of the spectral profiles. The basic one uses a standard positive/negative approach, analogous to what you'd get on any cytometer, but largely automated, so it should be pretty quick. I'm not going to touch on that too much today, focusing instead on the AutoSpectral control cleaning workflow that has been integrated here.

When you first open the Spectral Process tab, it will be empty, like so:

There is a Show Help button at the top that you can click for general guidance on how to use it:

This may be hidden again when you're done with it.

To use the AutoSpectral control cleaning workflow, tick the box for "Show AutoSpectral Cleaning". This should bring up the help section for the AutoSpectral control cleaning workflow, which you can again hide when you're done with it.

Let's follow the instructions, shall we?

First, let's change the gates in the Raw Data tab to include most everything.

We just want to be sure that we're capturing the brightest events somewhere in those gates. Beyond that it doesn't matter much, and it will matter even less in the next version.

For the next couple of steps, the order isn't so important. Let's mark our unstained samples before proceeding. Marking your unstained samples tells Honeychrome the sample doesn't have fluorophore signals in it. This means the control can be used for determination of the background for single-stained controls and/or autofluorescence extraction. Honeychrome automatically detects anything with the label "Unstained" and marks it as unstained. That's why we've got blue droplets next to the "Unstained (Cells)" sample and the entire folder that I created called "Unstained samples".

That BioLegend Positive Beads control is my unstained beads. Let's mark that accordingly. Right-click and select "Mark as unstained".

In the Spectral Process tab, click "Auto generate spectral controls". If you have a lot of controls, this might take a minute or two.

We get a filled in table and a filled in plot (Profiles Viewer) showing the fluorophores in our controls. Honeychrome has automatically detected the dyes (Label column), provided those are in the FCS file names. If you have put your markers in the file names and Honeychrome recognizes them, those will be automatically added to Antigen. You may change both the Label and Antigen to suit your preferences. Fill in stuff that's missing, since those labels get written to any FCS files you create and they get put on the plots in the Unmixed Data tab.

Check the details in the table. Are the Particle Type assignments correct? Is the Major Channel (Peak Channel) correct? Change these if not.

At the moment, we are looking at the spectral signatures from the standard postive-negative workflow, using internal negatives to calculate the profiles. Let's start the AutoSpectral workflow. First, if you have separate unstained controls (these work better), switch "Using internal negatives" to "Using unstained negatives". An "Unstained Negative" column appears in the table.

If you've marked your unstained samples and set your Particle Type correctly, you'll automatically get pairing in the "Unstained Negative" column. The negative can be configured individually for each control using the drop-down. You should see all suitable negatives (matching Particle Type, marked as unstained), including the option to use an internal negative.

If you want to see the impact of using separate unstained samples on the spectral profiles, just hit the "Recalculate" button.

For the control cleaning, there are currently two levels: a basic cleaning using scatter-matched negative events to find a suitable background, and a more robust, but slower, cleaning using noise exclusion and robust linear modelling. The latter is useful when you have few positive events or lots of noise. This will be simplified in the next version.

Let's use the noise exclusion for our Siglec F PE control, since that has the fewest positive events. To do that, tick the "Exclude noise" box for the control(s). Do this prior to running the control cleaning. If you forget, just tick the box and run the cleaning again.

Now, scroll down to the AutoSpectral Control Cleaning box below the Profiles Viewer.

Spectral Profiles here are without cleaning, with separate unstained negatives

Hit "Clean Controls". This may take a minute or two. Should be faster in the next version.

The fluorophore spectra shown in the Profiles Viewer are now the "cleaned" versions.

These are pretty easy controls, but we've still managed to remove some of the spurious low-level signals off the violet and blue lasers. For more on how this works, check out the article on Colibri Cytometry.

If you want, you can view the impact of the control cleaning on any control. In the Control Cleaning box, tick the options to show the various plots.

Purple events are the brightest 250 positive events, which are the ones being used for the calculation. This is CD45 BUV395 on murine splenocytes, so we didn't really have an internal negative to speak of. The blue events are the scatter-matched selected events from the separate unstained sample. You can adjust the position of the gates here for the standard positive/negative approach, but this really isn't important for the AutoSpectral workflow.

Scatter-matching allows us to find the most similar cells in the separate unstained sample, on the basis that those will be best matched for background, giving us the most accurate spectral determination. See Mario Roederer's article. This will be improved in the next version.

Scatter-matching for dead cells for the viability dye

Finally, we have the noise exclusion, which identifies potentially problematic events in the unstained sample (the events that stick up the middle), excludes them and performs robust linear modelling to downweight anything far from the trendline.

In this case, it isn't doing much because there isn't a ton of noise in the PE region.

There's a bunch of other info in the Spectral Process tab. You get a cosine similarity matrix, a Hotspot Matrix and your unmixing matrix, all plotted as heatmaps for visualization. Below that, you have NxN plots and Spillover Fine Tuning sections that you can use to adjust compensation on top of the unmixing (I don't recommend this, but this sort of freehand fiddling is widely done).

Once you have extracted spectral profiles, the data can be viewed in the Unmixed Data tab. There is no separate unmixing step--they're already unmixed.

Unmixed Data for CD3 APC single-stained bead control

AutoSpectral Autofluorescence Extraction

The second part of the AutoSpectral workflow that has been incorporated into Honeychrome is the per-cell autofluorescence extraction. To use this, head over to the AutoSpectral AF tab.

Tick the "Show AutoSpectral AF process" to use it.

Before we start using it, I'm going to make a point that you should not use the per-cell AF extraction in combination with manual extraction of single or multiple AF signatures. So, by default, unstained samples are not included in Honeychrome's spectral model, and you shouldn't see any in the Spectral Process table or the Profiles Viewer. If you do, remove those and recalculate the profiles before using AutoSpectral AF.

Now, select the unstained sample you want to use as a source of autofluorescence from the drop-down (all cell-based samples marked as unstained should appear here).

Click "Extract AF Profile".

Here's what the liver looks like:

If you have multiple sources of AF, like I have multiple unstained tissue samples in this experiment, extract the AF from each one. You can, if you want, save the profiles for later use as a CSV file. Click on each set of profiles below the "Stored AF Profiles" plot to view them.

Now, let's move to the unmixing process. We first want to assign our AF profiles to the samples. There's a tool here to let you play around with this, testing the impact on the unmixing. Let's assign the profiles from the unstained liver to the fully stained liver, then see how it looks.

Click on the sample on the lefthand panel to load it. The unmixing will proceed automatically, but might take some seconds for large samples.

Mouse liver, without or with per-cell AF extraction

This is a panel deliberately designed to minimize the impact of autofluorescence on the fluorophore channels. That is, this is more or less a best-case scenario for this tissue.

As with the other plots, change the transformations, parameters or gates applied by clicking on the relevant portions of the plot. Try other samples, etc.

Mouse lung, without or with per-cell AF extraction

Once you have assigned AF profiles to a sample, per-cell AF extraction will be applied to the unmixing throughout, including in the Unmixed Data tab. Deselect the AF profiles to remove this and revert to standard unmixing without AF extraction.

At the moment, the per-cell fluorophore optimization part of the AutoSpectral unmixing has not been integrated into Honeychrome. You should see most of the benefits, however, just with the control cleaning and per-cell autofluorescence extraction.

Exporting the Data

Honeychrome offers basic analysis functionalities, including basic gating hierarchies and sample comparison graphing functions. We are also busy expanding Honeychrome with new data analysis pipelines and a plugin system in Python to allow you to develop and import custom workflows. In the meantime, you'll probably be looking to export your unmixed data as FCS files for use elsewhere. Here's how you do that.

In the File menu, select "Batch Export FCS Files".

A pop-up will appear. Select the samples you want to export as unmixed FCS files. They will be exported with the labels you have added to the table in the Spectral Process tab, using any assigned AF profiles, and including any spillover fine tuning (compensation adjustment) you have applied.

Hit "Proceed" and the export will start.

All done! There is no "Save" button because the experiment is always saved. If you close it at any point, it will reopen to the point you left off at.