classify_droplets
Read-only
ddPCR droplet amplitudes to populations. For TWO targets, a four-way classification — NN, NP, PN, PP — under any of THREE published methods that answer different questions and none of which is a fallback for another.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| k | No | for `knn`: how many nearest labelled neighbours vote. Only applies when method is knn. | |
| prob | No | for `knn`: the smallest winning share of the vote that counts as a call. Below it the droplet is `Rain`. 0 disables the floor. At k = 5 a bare 3-2 majority is 0.6, so any floor at or below 0.5 accepts every droplet the vote decided at all. Only applies when method is knn. | |
| _files | No | The project: record references shaped like _subject. Their records become library documents a tool names in sequences/parts/document; a trace or alignment is found by file name. | |
| ch1_nn | No | grid: Ch1 below this and Ch2 below `ch2_nn` is NN. Only applies when method is grid. | |
| ch1_np | No | grid: Ch1 below this and Ch2 above `ch2_np` is NP. Only applies when method is grid. | |
| ch1_pn | No | grid: Ch1 above this and Ch2 below `ch2_pn` is PN. Only applies when method is grid. | |
| ch1_pp | No | grid: Ch1 above this and Ch2 above `ch2_pp` is PP. Only applies when method is grid. | |
| ch2_nn | No | grid: the Ch2 half of the NN box. Only applies when method is grid. | |
| ch2_np | No | grid: the Ch2 half of the NP box. Only applies when method is grid. | |
| ch2_pn | No | grid: the Ch2 half of the PN box. Only applies when method is grid. | |
| ch2_pp | No | grid: the Ch2 half of the PP box. Only applies when method is grid. | |
| method | No | which classifier. `grid` needs its eight thresholds to suit your assay; `kmeans` needs nothing and cannot abstain; `knn` needs `training` and is the only one that can leave a droplet unassigned; `density`, `samspectral`, `flowpeaks` and `ensemble` (ddPCRclust) are for one to four targets and name populations by marker number (`1`, `1+2`, ...); `ensemble` runs the other three and is the slowest. | kmeans |
| markers | No | for `density`: the well's four marker slots, comma-separated, as in ddPCRclust's run template. A name is a target the reaction carries; an EMPTY slot is one it does not, so `a,,c,d` is a three-target well whose cluster 2 is missing. The number of names is the number of targets. Only applies when method is density or samspectral or flowpeaks or ensemble. | M1,M2,M3,M4 |
| _subject | No | The record to act on: exactly one of sequence, accession (+source), sample (an id from list_samples) or file ({name, text} or {name, base64}); record_index picks one record of several. | |
| droplets | Yes | the well to classify: two amplitude columns, `Ch1` then `Ch2`, one row per droplet. A header line is optional. This is the whole well, not a summary. For the ddPCRclust methods it may instead be a PLATE: each export as `# <file name>` then its CSV, separated by a line of `---`, the well id read from the file name (`..._B01_Amplitude.csv`). | |
| sam_seed | No | for `samspectral` and `ensemble`: R's `set.seed` before the run. SamSPECTRAL keeps the best of 1000 k-means starts drawn from it, and on a plate one stream runs through the wells in order, as `ddPCRclust()` does. Only applies when method is samspectral or ensemble. | |
| template | No | for a PLATE under the ddPCRclust methods: ddPCRclust's run template (a `>name, channel1=..., channel2=..., description` line, then `Well,Sample type,# of markers,Marker 1..Marker 4`). Each well then takes its own row's markers instead of `markers`. Only applies when method is density or samspectral or flowpeaks or ensemble. | |
| training | No | for `knn` only: an already-labelled well, as `Ch1,Ch2,class` with class one of NN, NP, PN, PP or Rain. Rain IS a class here and not a rejection — a droplet can be assigned to it on the strength of its neighbours, separately from the probability floor below. Only applies when method is knn. | |
| random_seed | No | for `knn`: ties among equidistant neighbours, and among tied winning classes, are broken from this stream. On a well-separated plate it changes nothing; where droplets sit exactly between populations it does, and a deterministic tie-break would be stable and wrong. Only applies when method is knn. | |
| sensitivity | No | for `density`: how finely the initial cluster search resolves density peaks (its step is 0.02 / sensitivity³). Higher divides the data into more clusters, lower merges more. Only applies when method is density or samspectral or flowpeaks or ensemble. | |
| distance_param | No | for `density`: the share of the path between two clusters within which rain goes to the LOWER one; the rest goes to the higher one. Only applies when method is density or samspectral or flowpeaks or ensemble. | |
| constant_control | No | for a PLATE under the ddPCRclust methods: the marker that should read the same in every well. Every well's copies per droplet are multiplied by the control's highest value on the plate over its own, as `calculateCPDs(constantControl =)` does. Empty: no normalisation. Only applies when method is density or samspectral or flowpeaks or ensemble. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| total | Yes | droplets classified — the denominator the counts sum to | |
| wells | Yes | for a PLATE: every well's counts, copies per droplet, confidence and members, or the reason no member could partition it. `classes`, `counts` and `total` are empty for a plate | |
| counts | Yes | droplets per class, which is what a copy-number read consumes next. Rain is reported separately and is never folded into a population | |
| method | Yes | which classifier produced this. A classification without its method is not comparable with another, because the three disagree on the droplets between populations | |
| params | Yes | every parameter the run used, defaults included: the thresholds, k and the floor each move the answer | |
| centres | Yes | for `kmeans`: the final cluster centres with the name geometry gave each one; for `density`: the primary cluster centres, named by marker. Empty for the other methods, which have no centres | |
| classes | Yes | one label per droplet, in the order given: NN, NP, PN, PP, or Rain where the method abstained | |
| members | Yes | for the ddPCRclust methods: each first clustering that ran, with its population counts or the error that left it out of the consensus. `ensemble` is only as good as the members that agreed | |
| confidence | Yes | for the ddPCRclust methods: the mean corrected Rand index between the member partitions (1 when one member answered). Low means the three first clusterings disagree about this well | |
| normalised | Yes | for a PLATE with `constant_control`: every well's copies per droplet after scaling to the control's highest value on the plate, with each well's factor. Null without a control | |
| copies_per_droplet | Yes | for the ddPCRclust methods on one well: each named marker's positive droplets (every population carrying it) and its copies per droplet, -ln(1 - positives / total). Empty for the two-target methods |