Skip to main content
Glama

differential_abundance_flow_cytometry

Read-only

diffcyt differential abundance over project FCS files and a sample sheet: every sample's events (optionally one gated population) clustered together by FlowSOM on asinh-transformed channels, counted per sample, and each cluster's abundance compared between two levels of a sample-sheet column by edgeR (negative binomial GLM, Cox-Reid common and shrunk tagwise dispersions, likelihood-ratio test, Benjamini-Hochberg), optionally adjusting for a second column; with state channels, also each cluster's median of each state channel compared between the levels by limma (diffcyt testDS_limma: medians weighted by event count, empirical Bayes, moderated t, Benjamini-Hochberg).

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "sample_sheet": "<sample_sheet>",
      "condition": "<condition>"
    },
    "name": "differential_abundance_flow_cytometry"
  }
}

Input Schema

NameRequiredDescriptionDefault
xdimNoFlowSOM map width.
ydimNoFlowSOM map height.
_filesNoThe 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.
gatingNoa Gating-ML or FlowJo .wsp in the project; empty for none.
meta_kNothe number of metaclusters. Only applies when meta_clustering is true.
derivedNoas analyze_flow_cytometry.
samplesNothe FCS files to compare, by name or id, comma-separated; empty for every FCS file in the project.
_subjectNoThe 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.
channelsNothe channels to cluster on (diffcyt's type markers), comma-separated PnN or PnS; empty for every fluorescence channel.
comparedNothe level compared with the baseline; empty for the first other one.
documentNothe FCS file in the project, by name or id.
conditionYesthe sample sheet's column whose two levels are compared.
covariateNoa second sample-sheet column the model adjusts for (donor, batch, time); empty for none.
min_cellsNoa cluster is tested when at least min_samples samples hold this many of its events.
normalizeNoTMM normalisation factors on the cluster counts.
referenceNothe condition's baseline level; empty for the first in the sheet.
populationNoa population of the strategy, gated in every file before clustering; empty for every event.
min_samplesNosee min_cells; empty for half the samples.
state_trendNotestDS_limma's trend: the prior variance follows each row's average median (limma eBayes trend = TRUE).
cluster_seedNoR's set.seed before the map is trained (diffcyt seed_clustering).
compensationNoas analyze_flow_cytometry.auto
covariate_asNothe adjusting column as groups (a factor) or as a number. Values: factor (groups), number (a number).factor
sample_sheetYesa CSV in the project whose first column, headed sample, names each FCS file.
state_channelsNochannels whose per-cluster medians are compared too (diffcyt's state markers, testDS_limma), comma-separated PnN or PnS, none of them clustered on; empty for none.
meta_clusteringNogroup the map nodes into metaclusters by ConsensusClusterPlus (otherwise every node is a cluster).
cluster_cofactorNoasinh(x / cofactor) before clustering: diffcyt's default 5 is the CyTOF one, 150 common for fluorescence.
compensation_methodNoas analyze_flow_cytometry.flowkit

Output Schema

NameRequiredDescriptionDefault
countsYesthe cluster × sample event counts, the samples and the clustered channels
clustersYesper cluster: logFC, logCPM, LR, p and adjusted p (NaN, with the reason, where the filter left it out)
dispersionYesedgeR's common dispersion, the tested clusters' tagwise dispersions and the prior degrees of freedom
differential_stateYeswhen state channels were given: per cluster and state marker, the median difference (asinh scale), average median, moderated t, p and adjusted p, and the prior df

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changed
    • addedInput schema / properties / state_channels
      Added value: +{
      +  "default": "",
      +  "description": "channels whose per-cluster medians are compared too (diffcyt's state markers, testDS_limma), comma-separated PnN or PnS, none of them clustered on; empty for none.",
      +  "type": "string"
      +}
    • addedInput schema / properties / state_trend
      Added value: +{
      +  "default": true,
      +  "description": "testDS_limma's trend: the prior variance follows each row's average median (limma eBayes trend = TRUE).",
      +  "type": "boolean"
      +}
    • addedOutput schema / properties / differential_state
      Added value: +{
      +  "description": "when state channels were given: per cluster and state marker, the median difference (asinh scale), average median, moderated t, p and adjusted p, and the prior df"
      +}
    • changedOutput schema / required
      Previous value: -[
      -  "clusters",
      -  "counts",
      -  "dispersion"
      -]New value: +[
      +  "clusters",
      +  "counts",
      +  "differential_state",
      +  "dispersion"
      +]
  2. Added

TDQS

A3.6/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. Beyond that, the description adds substantial behavioral detail: clustering is performed jointly across all samples, counts are per-sample, testing uses negative binomial GLM with Cox-Reid and shrunk tagwise dispersions, LRT plus Benjamini-Hochberg, and a separate limma testDS_limma branch when state channels are supplied. It omits runtime cost and how failures in individual files are handled, so not a 5.

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

Conciseness3/5

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

The core purpose is front-loaded in the first clause, which is good. However, the remainder is a single run-on sentence loaded with stacked parentheticals ('negative binomial GLM, Cox-Reid common and shrunk tagwise dispersions, likelihood-ratio test, Benjamini-Hochberg'), which makes it dense to scan. The statistical detail earns some of its space but could be restructured into shorter sentences or a compact list.

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

Completeness4/5

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

For a 27-parameter, two-branch tool with an output schema, the description covers the full analysis path: clustering, counting, differential abundance testing, and the optional state-marker branch. It also flags practical knobs like the CyTOF-5 versus fluorescence-150 cofactor convention. It leaves out prerequisites for the sample sheet beyond the schema text and does not describe what happens when populations are absent from some files, keeping it just shy of complete.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema already defines every one of the 27 parameters, and the baseline is 3. The description does add some connective meaning — that clustering spans all samples together, that one gated population may be selected, that a second column may be adjusted for, and that state channels are tested via medians rather than clustered on — but it does not explain parameter values, defaults, or the min_cells/min_samples testing rule beyond what the schema states.

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

Purpose4/5

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

The opening clause names a specific method and resource: 'diffcyt differential abundance over project FCS files and a sample sheet,' and the rest of the sentence enumerates the exact pipeline (FlowSOM clustering, per-sample counts, edgeR GLM/LRT/BH, optional limma DS test). An agent can tell this is a cluster-abundance comparison between two condition levels. It never names a sibling tool (e.g. compare_flow_cytometry_populations or differential_expression) to distinguish itself, so it falls short of a 5.

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

Usage Guidelines3/5

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

Usage is only implied through the described statistics: two levels of a sample-sheet column, optional covariate adjustment, optional state-channel medians. There is no explicit 'use this when...' statement, no when-not guidance, and no routing to the closely related differential_expression or compare_flow_cytometry_populations tools. The agent must infer the decision boundary from the method names alone.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources