Skip to content

The spectrum collection

The spectrum collection keeps the reference spectra your controls have given, so a dye measured once can be unmixed with again on a later panel without running its control. It is filled from the Unmixing Matrix window with Add to DB, read back there with Get From DB, and looked through, corrected and regrouped in a window of its own: Spectrum Collection on the toolbar.

The collection is one file, SpectrumDB.DB, among the shared data. BFSpectra works on the same file. It is not the spectra database beside it: that is BFSpectra's catalogue of dyes and their excitation and emission spectra, the one the unmixer names its controls by.

Assays and spectra

Everything in the collection belongs to an assay: one set of controls, as one mixing matrix had them.

An assay has
A name Yours to give when it is added, and to change later
Device and S/N The cytometer's model and the instrument's serial number, as the data files give them ($CYT and $CYTSN)
Lasers The laser lines of the data
A date When the data were recorded
Parameters The detectors that were being unmixed, in the order the data has them
Spectra One for each positive control

A spectrum is one dye on its assay's detectors: the positive population's median on each of them, less the background of the negative control assigned to it. Its dye and analyte are the control's Stain and Analyte. The spread of the positive population is kept with it, and so are the background's own median and spread.

A spectrum is that instrument's view of the dye. It serves data from the same detectors of the same instrument, which is what Get From DB looks at before it offers one.

Adding an assay

Add to DB in the Unmixing Matrix window stores the matrix as it stands - one spectrum for each positive control, on the parameters being unmixed. It shows what will be stored first:

Field
Assay Name A name to find it by
Date Time When the data were recorded
Device, Serial Number From the data files. Fill them in if the files say nothing, and keep to one spelling: they decide which data the spectra are offered to later
Beads Vendor, Corpuscle Whose beads they were, and whether the controls were Beads or Cells
Lasers The laser lines
The table Each control's Analyte and Stain, which can be corrected here, and its spectrum

Save adds the assay; Cancel adds nothing.

The Spectrum Collection window

Spectrum Collection on the toolbar opens the collection to look through. The window stays open beside your work.

A chart at the top draws the spectra that are ticked. Under it, from left to right:

  • Assays - every assay in the collection.
  • Dyes - the spectra of the ticked assays, or of all of them while none is ticked.
  • Selected - spectra picked out to make a virtual assay of.

Assays

Column
Tick Tick an assay to list its spectra
Assay, Device, S/N, Lasers As given when the assay was added. Type in a cell to change it; the change is saved at once
DateTime When the data were recorded
Parents For a virtual assay, the assays whose spectra it is made of
Control
Single One assay ticked at a time: ticking one unticks the others. It is on when the window opens
Delete Deletes the ticked assays and their spectra, after asking. A virtual assay made with their spectra is deleted too, and the question names it
Select Adds the spectra of the ticked assays to Selected
Use There only when the window was opened by Get From DB

With Single off, a click ticks or unticks a row, Ctrl +click leaves that row alone ticked, and Shift +click ticks every row between it and the nearest ticked ones. Click a column header to sort by it, and again for the other way round.

Dyes

Column
Tick Tick a spectrum to draw it in the chart
Assay The assay that recorded it
Spectrum The spectrum, drawn small
Dye, Analyte Type in a cell to change either; the change is saved at once
Max Peak Its height on the detector where it is highest
SNR That height over the background's on the same detector
Mean SD The spread - robust SD - of the positive population, averaged over the detectors
Mean SD AF The same for the background
Control
Single One spectrum ticked at a time
Ribbon Draws the ticked spectra as a ribbon plot instead of lines: a distribution on every detector, from the spectrum's median and spread there, with the detectors named along the axis. Spectra recorded on other detectors than the first one ticked are left out of it
Select Adds the ticked spectra to Selected

Rows are ticked and sorted as in Assays. Sorting by Spectrum orders the dyes by where they peak. Double-click the chart to change how it is drawn.

Virtual assays

A virtual assay is an assay put together from spectra that other assays recorded: the controls you use together, each from the run that measured it best, under one name. It records nothing itself. It lists the spectra it was made of, and they stay the spectra of the assays that recorded them - its Parents.

To make one:

  1. Tick the spectra you want in Dyes and press the Select above them - or tick whole assays and press the Select above Assays. They are added to Selected. Repeat as often as needed.
  2. Press Create Virtual Assay and give the assay a name.

The new assay is listed with the others, ticked, its parents named.

What can go together

The first spectrum selected decides what the rest may be. Spectra are comparable only when they were recorded the same way, so all the spectra of a virtual assay share:

  • the device;
  • the parameters - the same detectors, in the same order;
  • the instrument, by its S/N, while Match S/N is ticked. Untick it to put together the spectra of two instruments of one model.

While anything is selected, Assays and Dyes list only what the selection could still take; what was ticked stays ticked. A Select leaves out the spectra that do not fit, and a message says how many. Ticking Match S/N again takes out of the selection what another instrument than its first spectrum's recorded.

Control
Match S/N One instrument's spectra only. Ticked when the window is first opened
Clear Empties the selection
The tick of a selected row Click it to take that spectrum out
Create Virtual Assay Adds the selection to the collection as an assay under the name you give, and empties it

A virtual assay gets the device and the parameters of its first spectrum, the S/N and the lasers of all its parents, and the date it was made.

What follows from it

  • A spectrum is listed once. With a virtual assay and one of its parents both ticked, Dyes shows the spectra they share once, each under the assay that recorded it.
  • Deleting a parent deletes the virtual assay, whole. Delete warns of it and names the virtual assay before anything is deleted. The other parents keep their spectra, and deleting a virtual assay itself deletes no spectrum.
  • A corrected dye or analyte shows in every assay that lists the spectrum.
  • Device functions, which BFSpectra trains on the collection, learn from the assays that recorded the spectra. A virtual assay adds nothing to them and counts nothing twice.

Spectra for a panel: Get From DB

Get From DB in the Unmixing Matrix window opens the collection as a dialog, to replace the mixing matrix with spectra from it. The dialog lists only the spectra your data can be unmixed with - those recorded

  • on the same device as the data, by the files' $CYT;
  • on the same instrument, by its S/N ($CYTSN), while Match S/N is ticked;
  • by an assay that measured every parameter you are unmixing. The assay may have measured more, and in another order.

The dialog's title says what is listed: spectra recorded on Aurora, S/N U1234, with the 64 parameters unmixed. Device and S/N are compared whatever the letter case. Data whose files name no device are offered only the assays that name none.

Tick an assay to see its spectra, tick the spectra to take, and press Use. They replace the mixing matrix, on the parameters being unmixed and in their order:

  • A spectrum whose analyte and dye are those of one of your controls takes that control's place and keeps its file, so mySSM still finds its events.
  • Any other comes in under the analyte and dye the collection has for it.

Closing the dialog without Use leaves the matrix as it was. An unmixing that is running has to be stopped before the matrix can be replaced. If the Spectrum Collection window was open, it becomes the dialog and closes with it. Selected works in the dialog too; the lists are then narrowed by the data and the selection both.

Another instrument's spectra

Two instruments of one model do not record a dye quite alike: lasers, filters and gains differ. That is why Match S/N starts ticked. Unticked, the dialog also lists the spectra of the model's other instruments - and since an assay may have measured more than you unmix, a three-laser instrument's data are offered the spectra of a five-laser one. Treat them as an approximation of your own instrument's.

When nothing is listed

If the collection has nothing for the data, it says so instead of opening empty:

  • The collection has no spectra recorded on Aurora, S/N U1234, with the 64 parameters unmixed. It has those of the device's other instruments: untick Match S/N to list them. The dialog opens after the message, for you to do that.
  • The collection has no spectra recorded on Aurora with the 64 parameters unmixed. No assay of that device measured all your parameters, on any instrument. No dialog opens.

If you expected spectra to be there, there are two things to check:

  • The names. Compare the device and S/N in the message with the Device and S/N columns of the Spectrum Collection window. Those hold what the files said, or what was typed, when each assay was added; correct them there by typing in the cell.
  • The parameters. A parameter left ticked that the assay did not measure - scatter, time, a detector of another configuration - is enough to rule the assay out. See Choosing the channels.