differential_expression
Differential expression from raw RNA-seq read counts, by one of the three standard count models.
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": {
"counts": "<counts>",
"samples": "<samples>"
},
"name": "differential_expression"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | one fitted coefficient to report, by its DESeq2 name (e.g. 'condition_treated_vs_untreated') or its model-matrix column ('conditiontreated'); empty is the last. | |
| test | No | Wald: one coefficient or contrast. LRT: the full design against `reduced`, testing every removed term at once. Only applies when method is DESeq2. | Wald |
| useT | No | Wald p-values from a Student t on each gene's summed weights (or the sample count) minus the coefficients, instead of the normal: zinbwave's recommendation for weighted single-cell data. Wald test only. Only applies when method is DESeq2. | |
| alpha | No | the target FDR: the summary counts genes below this adjusted p, and DESeq2's independent filtering maximizes rejections at it. | |
| blind | No | fit the transformation's dispersion trend under ~ 1, blind to the design (DESeq2's default, for quality assessment); off reuses the fitted design and trend, for downstream use when large differences between groups are expected. Only applies when method is DESeq2. | |
| minmu | No | the floor on fitted means in the GLM and the dispersion fit; empty is DESeq2's default, 0.5, or 1e-6 with fitType glmGamPoi. Single-cell counts, often below 1, want a small value such as 1e-6 (zinbwave's vignette). Only applies when method is DESeq2. | |
| _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. | |
| counts | Yes | raw read counts (never normalized values or TPM): genes in rows with the gene ID first, samples in columns, tab- or comma-separated, a header row naming the samples. | |
| design | No | the design formula over the sample table's columns, the variable of interest last (e.g. '~ batch + condition'). | ~ condition |
| method | No | the count model: DESeq2 (negative binomial, Wald or LRT), edgeR-QL (negative binomial with quasi-likelihood F-test) or limma-voom (precision-weighted linear model on log-CPM, moderated t). | DESeq2 |
| pcaTop | No | plotPCA's ntop: the PCA uses this many genes with the largest variance of the transformed values. Only applies when method is DESeq2. | |
| sfType | No | size factors: median of ratios over genes with no zero (ratio), with zeros allowed (poscounts, for sparse data), or iterated to maximise the NB likelihood of all but the worst-fitting 5% of genes (iterate, when every gene has a zero). Only applies when method is DESeq2. | ratio |
| shrink | No | shrink the reported coefficient's or contrast's log2 fold changes toward zero where the counts cannot support them (DESeq2 lfcShrink), for ranking and plotting by effect size; p-values stay the unshrunken test's. apeglm: adaptive Cauchy prior, posterior mode (a coefficient only). ashr: mixture-of-normals prior, posterior mean. normal: DESeq2's original zero-centred Normal prior (Wald only), a contrast on the expanded model matrix. With lfcThreshold, apeglm and ashr give s-values of a false sign or a fold change inside the threshold, and normal re-tests the shrunken fit. Only applies when method is DESeq2. | none |
| fitType | No | the dispersion trend: parametric (asymptDisp + extraPois / mean, DESeq2's default, which falls back to local when it does not fit), local (locfit regression of log dispersion on log mean), the mean of gene-wise estimates, or glmGamPoi (gene-wise maximum likelihood by glmGamPoi, a local-median trend and quasi-likelihood shrinkage; with test LRT the p-values are glmGamPoi's quasi-likelihood F test; no outlier replacement, minmu 1e-6, no observation weights). Only applies when method is DESeq2. | parametric |
| reduced | No | the reduced design for the likelihood-ratio test. Only applies when method is DESeq2. | |
| samples | Yes | the sample table: a header row, then one row per sample with its name (as in the count table's header) first and the design's variables after; the run uses this table's sample order. | |
| weights | No | optional: observation weights (assays(dds)[["weights"]]), the same genes and samples as `counts`, e.g. zinbwave's posterior probability that a single-cell count is not a dropout. DESeq2 divides each gene's weights by their largest and uses them in the base means, the dispersion likelihoods (samples at or below 0.01 leave the Cox-Reid term), the GLM and its tests. Only applies when method is DESeq2. | |
| _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. | |
| contrast | No | 'factor, numerator, denominator': the log2 fold change of numerator over denominator. Empty is the design's last coefficient. Under edgeR and voom the denominator must be the factor's reference level. | |
| minCount | No | filterByExpr: the count, at the median library size, a gene needs in the smallest group's worth of samples (taken as CPM). Only applies when method is edgeR-QL or limma-voom. | |
| pcaGroup | No | plotPCA's intgroup: the sample-table variables, separated by commas, that colour the samples (joined with ':' when more than one); empty is the factor of the reported comparison. Only applies when method is DESeq2. | |
| betaPrior | No | DESeq2's pre-1.16 default: a zero-mean Normal prior on every level's log2 fold change, so the reported fold changes, SEs and Wald test are the shrunken (MAP) ones. Wald only, no interactions; use instead of `shrink`. Only applies when method is DESeq2. | |
| reference | No | reference level per factor, 'variable=level' separated by commas; a factor not named takes its alphabetically first level, as R does. | |
| transform | No | the count transformation the sample-level checks (PCA, sample distances) run on: vst (DESeq2's variance stabilizing transformation, the trend fitted on 1,000 genes; with fewer than 1,000 genes above a mean of 5 use VST), VST (varianceStabilizingTransformation, every gene), rlog (regularized log, a per-gene ridge fit, slow above ~30 samples) or normTransform (log2 of normalized count + 1, no stabilization). none skips the checks. Only applies when method is DESeq2. | vst |
| avgTxLength | No | optional: tximport's average transcript lengths (txi$length), the same genes and samples as `counts`. DESeq2 then normalizes by gene-by-sample factors (each gene's lengths over their geometric mean, times median-of-ratios size factors), correcting for changes in transcript usage between samples. Only applies when method is DESeq2. | |
| cooksCutoff | No | the Cook's distance cutoff; empty is DESeq2's F(0.99; p, m - p). Only applies when method is DESeq2. | |
| cooksFilter | No | set the p-value of genes with a Cook's-distance outlier to NA. Only applies when method is DESeq2. | |
| filterByExpr | No | keep only genes edgeR's filterByExpr finds expressed (the edgeR and limma workflows' first step); off fits every gene. Only applies when method is edgeR-QL or limma-voom. | |
| lfcThreshold | No | test |log2 fold change| against this threshold instead of 0. Only applies when method is DESeq2. | |
| altHypothesis | No | which side of the threshold is the alternative. Only applies when method is DESeq2. | greaterAbs |
| minTotalCount | No | filterByExpr: the total count a gene needs across all samples. Only applies when method is edgeR-QL or limma-voom. | |
| pAdjustMethod | No | multiple-testing adjustment across genes (R `p.adjust`). | BH |
| independentFiltering | No | drop low-mean genes from the adjustment when that gains rejections at `alpha`. Only applies when method is DESeq2. | |
| minReplicatesForReplace | No | samples per group from which outlier counts are replaced and the gene refitted, instead of flagged. Only applies when method is DESeq2. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| genes | Yes | one row per gene: log2FoldChange, stat (DESeq2 Wald or LRT, edgeR F, voom moderated t), pvalue, padj, why padj is NA, the normalized counts per sample; DESeq2 adds baseMean, lfcSE, the gene-wise, fitted and final dispersions, whether it was refitted and with `shrink` the shrunken fold change, its SE and s-value (normal with lfcThreshold: the shrunken fit's p-value and padj); edgeR and voom add logCPM, the raw, prior and posterior variance (edgeR's QL dispersion) and the total df, and voom the B-statistic | |
| maPlot | Yes | log2 fold change (shrunken, with `shrink`) against mean normalized count (DESeq2) or average log2 CPM (edgeR, voom), significant genes apart | |
| summary | Yes | genes up and down at alpha and tested, with the method's own fit: DESeq2's outliers, low counts, filter threshold, size factors, dispersion trend and shrinkage prior; edgeR's common and average QL dispersion and prior df; voom's span and prior variance; the filterByExpr cutoffs and library sizes | |
| upGenes | Yes | significant genes with positive log2 fold change, one per line | |
| volcano | Yes | -log10 p against log2 fold change, significant genes apart | |
| downGenes | Yes | significant genes with negative log2 fold change, one per line | |
| samplePca | Yes | DESeq2 runs only (null under edgeR and voom): plotPCA on the transformed counts (`transform`, `blind`): PC2 against PC1 per sample, one series per `pcaGroup` level, each axis labelled with its share of the variance | |
| meanCounts | Yes | DESeq2 runs only (empty under edgeR and voom): every tested gene with its mean normalized count (baseMean), 'gene value' per line: the gene weights for a Wallenius-weighted over-representation test, which corrects for the extra power to call well-counted genes | |
| rankedList | Yes | tested genes by their test statistic, decreasing: DESeq2's Wald statistic, voom's moderated t, or edgeR's signed square root of F (a t with the same df): the ranked list for GSEA | |
| testedGenes | Yes | every gene with an adjusted p-value, one per line: the background (universe) for over-representation analysis | |
| dispersionPlot | Yes | DESeq2: gene-wise, fitted and final dispersions against mean count. edgeR: quarter-root raw, squeezed and trend QL dispersions against average log2 CPM (plotQLDisp). voom: sqrt standard deviation against log2 count size, with the lowess trend that sets the weights | |
| sampleDistances | Yes | DESeq2 runs only (null under edgeR and voom): the sample checks as data: the transformation and its trend, the PCA genes, percentVar, PC1 and PC2 per sample, the sample-to-sample Euclidean distance matrix over every gene and its complete-linkage clustering (leaf order, merges, heights), as the vignette's heatmap draws it; or why the checks could not run | |
| significantGenes | Yes | genes with padj below alpha, one per line: the gene list for over-representation analysis |