Droplet classification

Sort droplets into their populations: two targets under three methods that disagree, or up to four targets by density, spectral clustering, flow peaks or the consensus of all three.

What it doesCopy Anchor Link

A two-target ddPCR reaction produces four kinds of droplet: those that amplified neither target, either one alone, or both. Everything downstream — copy number, linkage, fractional abundance — starts from how many droplets fall in each group. So the classification is not a step on the way to the answer; it largely is the answer, and the method that produced it belongs beside the number.

Three published methods do this, and they are offered together because they disagree, in a place that matters.

Fixed thresholds draw four boxes and put each droplet in the box it lands in. Nothing adapts, so the same numbers give the same answer on every plate forever — which is what makes it auditable, and what makes the numbers your responsibility. Droplets in none of the boxes are left uncalled.

Clusters find four groups in the data itself and name them by where they sit rather than by the order they were found. It adapts to the well, so it does not need thresholds chosen for your assay. It also cannot decline: clustering partitions everything, so a droplet sitting exactly between two populations is assigned to whichever centre is nearer, and the result looks just as confident as a droplet in the middle of a cloud.

Nearest neighbours classifies against a well you have already labelled: each droplet takes the majority label of the labelled droplets nearest it. It is the only method that can refuse one droplet at a time — set a floor on how strong that majority has to be, and anything weaker is reported as uncalled rather than assigned.

One well of 12,395 droplets against a labelled neighbour, with the vote floor at 0.9: 521 droplets did not reach it and are reported as uncalled rather than pushed into the nearest population.

Up to four targets is for multiplex reactions, where each target is told apart by its amplitude rather than by a colour of its own. A two-channel plot of a four-target well holds sixteen populations: the empty droplets, one cluster per target, and every combination of targets sharing a droplet. The method finds the empty droplets and each target's own cluster from the density of droplets along each channel, places every combination from those (a droplet carrying two targets sits roughly where the two single-target shifts add up), then refines each placement where its droplets are actually dense. Droplets between clusters (rain) are walked down the path from the lower cluster to the higher one: a share near the lower end stays with it and the rest join the higher cluster. You name the markers the well carries, as in a run template; a slot left empty is a target this well does not carry, so its populations are never searched for.

One four-target blood well, 13,387 droplets, with the share of the path given to the lower cluster raised to 0.3: copies per droplet for each of the four markers, the sixteen populations, and the one rain droplet that sat about equally near two paths.

The density gates are one of three ways to find the clusters the published method offers, and by default it runs all three and takes their consensus. Spectral clustering (SamSPECTRAL) samples representative droplets, links them by how alike their neighbourhoods are, and splits the resulting graph where it is weakest; it draws random starting points, so it takes a seed. Flow peaks (flowPeaks) fits many small Gaussian blobs and merges those whose density joins without a valley. Each partition is then named by the same marker logic as the density gates. The consensus is the member partition that agrees best with the other two, and the agreement reported beside it says how close that was: 1 means all members drew the same clusters. A member that cannot partition a well is left out of that well's consensus and named, rather than failing the run.

Give a plate (several wells, each under a # file name line) with the run template, and every well is classified with its own markers from the template. Name a constant control, a target present at the same amount in every well, and each well's copies per droplet are rescaled so that control reads the same everywhere: the plate's highest value for it, over this well's own.

Two wells, 27,445 droplets, consensus of all three approaches. Density gates answered one well and flow peaks the other, each agreeing with the other two members at 0.9997 or better; marker c is the constant control, so G07's copies per droplet were multiplied by 9.882 to bring c level with G08.

What this computesCopy Anchor Link

For every method

• a class per droplet — neither target, one, the other, both — or uncalled
• droplets per class, with each as a share of the well. This is what a copy-number or linkage read consumes next
• uncalled droplets reported separately, never folded into a population

For clusters

• the four cluster centres, each carrying the name its position earned. The names come from geometry, not from discovery order: the clusters' bounding boxes are put on a common scale and each name claims the cluster nearest its corner, greedily, so no cluster can take a name another fits better

For up to four targets

• a population per droplet, named by the markers it carries (a + c), or removed when no cluster claimed it
• droplets per population for every combination the named markers can form, and only those
• copies per droplet for each marker: its positives are every population carrying it, and copies per droplet are -ln(1 - positives / total), the Poisson correction for droplets holding more than one copy
• the primary cluster centres, one per target, from which every combination was placed
• ambiguous rain: droplets about equally near two cluster paths, counted and named (density gates only; the other approaches have no rain step)
• every member's partition when the consensus runs: its droplets per population, or the reason it could not partition the well
• which member answered and the agreement of the consensus: how close the chosen partition came to the other two, from 0 to 1
• per well on a plate: the member that answered, the agreement, droplets and removed droplets
• normalized copies per droplet: each marker in each well multiplied by the factor that brings the constant control to the plate's highest control value, with each well's factor named

Not computed, and said rather than implied

• clustering reports no uncalled droplets, ever. That is a property of the method and not a finding about your plate, and the tool says so instead of letting a zero read as a clean well

When you'd use thisCopy Anchor Link

• you want the counts, not a concentration. Copy number and linkage are ratios between populations; this produces the populations
• you distrust a call near the boundary. Run the same well twice under two methods. Where they agree, the boundary is not doing the work; where they disagree, it is, and the size of the disagreement is the size of the doubt
• you have one carefully labelled well and many like it. Label one by hand or by thresholds, then let nearest neighbours carry it across the plate, with a floor that keeps it honest about the droplets it is unsure of

Inputs and outputsCopy Anchor Link

In: one well — two amplitude columns, one row per droplet. A header line is fine. Nearest neighbours additionally needs a labelled well: the same two columns plus a class. Uncalled is a class there, not a rejection: a droplet can be assigned to it because its neighbours were uncalled, which is how an uncertain region propagates instead of quietly disappearing.

For up to four targets, a plate is several wells in one text, each under a # file name line and separated by ---, with the run template naming each well's markers. The well name is read from the file name, as the instrument writes it.

Out: the per-class counts and shares as a CSV; for a plate, one row per well and marker with positives, copies per droplet and the normalized value.

What it refuses, and says so. Overlapping threshold boxes are refused rather than resolved: with boxes that overlap, a droplet would be classified by whichever test ran first rather than by where it sits, and no answer is better than an answer that depends on evaluation order. Nearest neighbours refuses a k larger than the training set, a training row without a class, and a class name that is not one of the five.

ControlsCopy Anchor Link

• Method — two-target thresholds, clusters or nearest neighbours; or, for up to four targets, density gates, spectral clustering, flow peaks, or the consensus of all three. Changing it changes which controls exist, because they do not share knobs.
• Thresholds (fixed thresholds) — eight numbers, two per population.
• Training well (nearest neighbours) — an already-labelled well.
• Neighbours (k) — how many labelled droplets vote.
• Smallest winning share — the floor. At k = 5 a bare majority is 0.60, so any floor at or below that accepts every droplet the vote decided at all; raising it is what turns the method into one that can say "this one is between populations".
• Random seed — ties between equidistant neighbours are broken from a seeded stream. On a well-separated plate it changes nothing; where droplets sit exactly between populations it does.
• Markers (up to four targets) — four slots, as in a run template. A name is a target the well carries; an empty slot is one it does not.
• Sensitivity — how finely the first search resolves density peaks, from 0.1 to 2. Higher divides the droplets into more clusters, lower merges more; worth raising for very low or very high copy numbers.
• Share of path to lower cluster — for rain between two clusters, the share of the way from the lower cluster within which a droplet stays with it. The default gives the bottom 20% to the lower cluster.
• Random seed (spectral clustering and the consensus) — the seed of the generator that picks the spectral method's starting points. The published method never sets one, so its own answer depends on what ran before it; naming the seed makes a run repeatable.
• Run template — the instrument's run template: each well, its sample type, how many markers it carries and their names. Needed for a plate.
• Constant control — the marker to normalize every well to. Leave empty for no normalization.

The scienceCopy Anchor Link

Fixed thresholds and clustering are unsupervised: they ask only where the droplets are. Nearest neighbours is supervised: it asks where droplets like these were put before, which means it inherits whatever the training well got right and whatever it got wrong.

The naming step is the part that is easy to underestimate. Clustering returns groups numbered by the order it found them, which carries no meaning at all — a run that finds the same four clouds in a different order would label every droplet differently. So the names are assigned by position, using the worst of the two axes rather than a straight-line distance: a cluster near a corner on one channel and far on the other is scored by the channel where it is far. Then the best-fitting pairing is taken first and removed, so no group can claim a name that suits another group better.

Correctness is checked against the published open-source implementation of all three methods, over its own droplet data: twelve wells, 150,976 droplets, every droplet compared.

The up-to-four-target method is checked the same way against the published density-based multiplex method (Brink et al., Bioinformatics 2018), over the eight wells that ship with it: one, two, three and four targets, 116,717 droplets, every droplet's population, every count, every cluster centre and every copies-per-droplet value compared. The spectral and flow-peaks approaches, the consensus and the plate normalization are checked as one run of the published method over the whole eight-well plate: which approaches took part in each well, the agreement, the counts, every droplet's population and every normalized value. The spectral approach rests on an eigendecomposition reproduced to the last bit of the reference linear-algebra library (LAPACK), because its leading eigenvalues are nearly equal and the slightest difference changes which clustering it settles on.

LimitationsCopy Anchor Link

• Three or four targets need the density method. The other three divide droplets into four populations, which is all a two-target reaction has.
• No time limit per approach. The published method abandons any approach that runs past 60 seconds, so its answer can depend on the computer. Here every approach runs to the end, and a long plate runs in the background with a Stop button.
• Ambiguous rain is counted, not removed. The published method flags droplets about equally near two cluster paths for removal but never removes them, so they are counted in the nearest population. This tool does the same so its counts match, names how many there were, and does not offer the removal threshold, which changes nothing.
• Thresholds are yours. The defaults are the ones the published method ships, which came from a particular assay on a particular instrument. They are a starting point, not a calibration.
• Nearest neighbours inherits its training well. A systematically mislabelled training set produces a confidently mislabelled plate, and nothing here can detect that.
• Where the methods disagree, none of them is the referee. The disagreement is the finding.

Compared with other toolsCopy Anchor Link

Droplet gating asks a different question of the same file: whether each droplet is empty, per channel, by fitting the empty population rather than by drawing a line — and it ends in a concentration. Use it when you want copies per microlitre. Use this when you want the four populations, which is what a copy-number or linkage read needs.

Digital PCR starts from counts an instrument already produced, and is the right tool when the classification is not in question.