jean — Molecular Biology & Genomics

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. grid applies eight fixed thresholds: reproducible and auditable, the only one that does not move when the data does, and the only one that needs someone to have chosen the numbers. kmeans clusters both channels at once and names the clusters by where they sit, so it adapts to the well, and it CANNOT abstain because k-means partitions everything. knn classifies against a well you have already labelled and abstains into Rain when the neighbour vote is weaker than a floor you set, so it is the only one that can decline per droplet. They disagree on the droplets between the populations, and that disagreement is the honest measure of how much an answer rests on the method rather than on the data. Distinct from gate_droplets, which asks whether a droplet is EMPTY per channel and ends in a concentration; this asks which of four populations it belongs to. For ONE to FOUR targets multiplexed by amplitude, ddPCRclust names up to sixteen populations from the primary clusters and reports each target's copies per droplet, by any of three first clusterings or their consensus: density places the primaries from density gates, samspectral from spectral clustering of a faithful sample, flowpeaks from the density peaks k-means clusters climb to, and ensemble (ddPCRclust's own default) runs all three and keeps the partition that agrees most with the others, with their mean corrected Rand index as the confidence. A plate of exports with ddPCRclust's run template is classified well by well and can be normalised to a constant control.

Input Schema

TableJSON 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

TableJSON Schema

Name	Required	Description
`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

Schema Changelog

Changes observed during successful MCP inspections.

First observedOct 20, 2026

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover the safety profile (readOnlyHint, destructiveHint false), yet the description adds substantial behavioral context beyond them: `kmeans` CANNOT abstain because it partitions everything, `knn` is the only method that can decline per droplet via the `Rain` floor, `grid` is the only one whose result moves with chosen numbers, `ensemble` is the slowest, and plates are classified well by well and can be normalised to a constant control. This is well past the lower bar set by annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core purpose and organized around method families with backticked parameter names, so it is scannable despite its length. The density is justified by 7 methods and 22 parameters, though a few clauses (e.g. the 'honest measure' aside) are rhetorical rather than operational.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be explained, and the description supplies the full decision context an agent needs: which methods need `training` or thresholds, which support plates, which support one-to-four targets, and how normalisation is triggered. Nothing required to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline is 3, but the description adds meaning the schema does not: it frames `method` as a choice among methods that 'answer different questions and none of which is a fallback for another', explains that marker names vs empty slots encode target count, and clarifies plate/template interaction. It stops short of restating per-parameter syntax that the schema already carries.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('ddPCR droplet amplitudes to populations') and immediately enumerates the classification outputs (NN/NP/PN/PP) and the method families. It explicitly distinguishes itself from `gate_droplets` ('asks whether a droplet is EMPTY per channel and ends in a concentration; this asks which of four populations it belongs to'), so an agent can separate the two without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-to-use guidance per method: `grid` for reproducible/auditable fixed thresholds, `kmeans` when nothing is known and abstention is unacceptable, `knn` when a labelled well exists and per-droplet abstention is wanted, and the ddPCRclust set for one-to-four targets. It also names the alternative tool (`gate_droplets`) and the condition that selects it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All jean — Molecular Biology & Genomics tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?