RNA-seq Experimental Design Specification
Summary
Define sample metadata, condition labels, and design formulas that specify the biological contrasts and statistical model for differential expression testing in DESeq2. This skill ensures the experiment's biological structure is formally encoded before count matrix construction.
When to use
Before constructing a DESeqDataSet from count data or tximport output, when you have raw RNA-seq samples that need to be annotated with experimental conditions, treatment groups, batch effects, or other covariates. Apply this skill when you need to specify which samples belong to which group and what statistical model will be used to test for differences between groups.
When NOT to use
- Count data has already been normalized or library-size scaled prior to model fitting; design specification is only for raw count inputs.
- Experimental samples lack defined biological conditions or contrasts (e.g., purely observational cohort without treatment groups); design formula requires at least one covariate that varies across samples.
- Sample metadata is incomplete or inconsistent with the count matrix dimensions.
Inputs
- Sample identifiers (run IDs, sample names)
- Condition labels or treatment group assignments
- Batch/blocking variables (optional but recommended)
- Count matrix or tximport list object (to validate sample count)
Outputs
- Sample metadata table (data frame with samples as rows, covariates as columns)
- Design formula object (R formula specifying statistical model)
- Factor-encoded condition variable with explicit level ordering
How to apply
Create a sample metadata table (data frame) with one row per RNA-seq sample and columns for sample identifiers, experimental condition (e.g., 'treated' vs. 'untreated'), and any batch or blocking variables. Assign condition labels to each sample as a factor with explicit level ordering to control which group serves as the reference in downstream contrasts (e.g., factor(condition, levels=c('untreated','treated'))). Construct a design formula using R formula notation (e.g., ~condition or ~batch+condition) that specifies which variables explain expression variation. The design formula is then passed to DESeqDataSetFromMatrix(), DESeqDataSetFromTximport(), or similar constructors to instantiate the statistical model. Verify the design is valid by confirming the number of rows in metadata matches the number of samples in the count matrix and that all condition levels are represented.
Related tools
- DESeq2 (Receives design formula and sample metadata to construct DESeqDataSet and fit negative binomial generalized linear model) — https://github.com/thelovelab/DESeq2
- tximport (Aggregates transcript-level abundance to gene level; output is passed to DESeqDataSetFromTximport with the design formula and metadata)
- R base (stats, formula objects) (Provides formula syntax for specifying statistical models used in design argument)
Examples
samples <- data.frame(run=c('run1','run2','run3','run4'), condition=factor(c('A','A','B','B'), levels=c('A','B')), row.names='run'); ddsTxi <- DESeqDataSetFromTximport(txi, colData=samples, design=~condition)
Evaluation signals
- Metadata table has exactly as many rows as there are samples in the count matrix (or tximport list), with matching sample identifiers as row names or a consistent ID column.
- All factor levels in the condition column are represented by at least one sample (no empty levels that would cause rank-deficient design matrix).
- Design formula is syntactically valid R formula (e.g., parseable as
formula(design_string)) and contains only variables present as columns in the metadata.
- When DESeqDataSetFromMatrix() or DESeqDataSetFromTximport() is called with the metadata and design, no error about missing variables or row count mismatch is raised.
- Reference level (first level in factor ordering) is biologically sensible for downstream contrast interpretation (e.g., 'untreated' or 'control' as baseline).
Limitations
- The design formula specifies the model structure but does not enforce sample replication; ensure each condition has multiple biological replicates to estimate dispersion accurately.
- Design matrix must be of full rank; avoid including linearly dependent variables (e.g., a batch variable that perfectly confounds with condition). DESeq2 will detect and report rank-deficiency but analysis will fail.
- Factor level ordering is critical for interpretation of log2 fold changes; changing level order changes which group is the reference but does not affect statistical significance or adjusted p-values.
Evidence
- [other] Load the tximportData package and retrieve the sample metadata table, assigning condition labels (A and B) and setting run IDs as row names.: "Load the tximportData package and retrieve the sample metadata table, assigning condition labels (A and B) and setting run IDs as row names."
- [other] Construct a DESeqDataSet from the tximport output using DESeqDataSetFromTximport(), specifying the sample metadata and design formula (
condition).: "Construct a DESeqDataSet from the tximport output using DESeqDataSetFromTximport(), specifying the sample metadata and design formula (condition)."
- [other] Set factor levels for reference comparison: 'dds$condition <- factor(dds$condition, levels = c("untreated","treated"))': "dds$condition <- factor(dds$condition, levels = c("untreated","treated"))"
- [other] Construct DESeqDataSet from count matrix: 'dds <- DESeqDataSetFromMatrix(countData = cts, colData = coldata, design= ~ batch + condition)': "dds <- DESeqDataSetFromMatrix(countData = cts, colData = coldata, design= ~ batch + condition)"
1---2name: rna-seq-experimental-design-specification3description: Use when before constructing a DESeqDataSet from count data or tximport output, when you have raw RNA-seq samples that need to be annotated with experimental conditions, treatment groups, batch effects, or other covariates.4license: CC-BY-4.05---67# RNA-seq Experimental Design Specification89## Summary1011Define sample metadata, condition labels, and design formulas that specify the biological contrasts and statistical model for differential expression testing in DESeq2. This skill ensures the experiment's biological structure is formally encoded before count matrix construction.1213## When to use1415Before constructing a DESeqDataSet from count data or tximport output, when you have raw RNA-seq samples that need to be annotated with experimental conditions, treatment groups, batch effects, or other covariates. Apply this skill when you need to specify which samples belong to which group and what statistical model will be used to test for differences between groups.1617## When NOT to use1819- Count data has already been normalized or library-size scaled prior to model fitting; design specification is only for raw count inputs.20- Experimental samples lack defined biological conditions or contrasts (e.g., purely observational cohort without treatment groups); design formula requires at least one covariate that varies across samples.21- Sample metadata is incomplete or inconsistent with the count matrix dimensions.2223## Inputs2425- Sample identifiers (run IDs, sample names)26- Condition labels or treatment group assignments27- Batch/blocking variables (optional but recommended)28- Count matrix or tximport list object (to validate sample count)2930## Outputs3132- Sample metadata table (data frame with samples as rows, covariates as columns)33- Design formula object (R formula specifying statistical model)34- Factor-encoded condition variable with explicit level ordering3536## How to apply3738Create a sample metadata table (data frame) with one row per RNA-seq sample and columns for sample identifiers, experimental condition (e.g., 'treated' vs. 'untreated'), and any batch or blocking variables. Assign condition labels to each sample as a factor with explicit level ordering to control which group serves as the reference in downstream contrasts (e.g., `factor(condition, levels=c('untreated','treated'))`). Construct a design formula using R formula notation (e.g., `~condition` or `~batch+condition`) that specifies which variables explain expression variation. The design formula is then passed to DESeqDataSetFromMatrix(), DESeqDataSetFromTximport(), or similar constructors to instantiate the statistical model. Verify the design is valid by confirming the number of rows in metadata matches the number of samples in the count matrix and that all condition levels are represented.3940## Related tools4142- **DESeq2** (Receives design formula and sample metadata to construct DESeqDataSet and fit negative binomial generalized linear model) — https://github.com/thelovelab/DESeq243- **tximport** (Aggregates transcript-level abundance to gene level; output is passed to DESeqDataSetFromTximport with the design formula and metadata)44- **R base (stats, formula objects)** (Provides formula syntax for specifying statistical models used in design argument)4546## Examples4748```49samples <- data.frame(run=c('run1','run2','run3','run4'), condition=factor(c('A','A','B','B'), levels=c('A','B')), row.names='run'); ddsTxi <- DESeqDataSetFromTximport(txi, colData=samples, design=~condition)50```5152## Evaluation signals5354- Metadata table has exactly as many rows as there are samples in the count matrix (or tximport list), with matching sample identifiers as row names or a consistent ID column.55- All factor levels in the condition column are represented by at least one sample (no empty levels that would cause rank-deficient design matrix).56- Design formula is syntactically valid R formula (e.g., parseable as `formula(design_string)`) and contains only variables present as columns in the metadata.57- When DESeqDataSetFromMatrix() or DESeqDataSetFromTximport() is called with the metadata and design, no error about missing variables or row count mismatch is raised.58- Reference level (first level in factor ordering) is biologically sensible for downstream contrast interpretation (e.g., 'untreated' or 'control' as baseline).5960## Limitations6162- The design formula specifies the model structure but does not enforce sample replication; ensure each condition has multiple biological replicates to estimate dispersion accurately.63- Design matrix must be of full rank; avoid including linearly dependent variables (e.g., a batch variable that perfectly confounds with condition). DESeq2 will detect and report rank-deficiency but analysis will fail.64- Factor level ordering is critical for interpretation of log2 fold changes; changing level order changes which group is the reference but does not affect statistical significance or adjusted p-values.6566## Evidence6768- [other] Load the tximportData package and retrieve the sample metadata table, assigning condition labels (A and B) and setting run IDs as row names.: "Load the tximportData package and retrieve the sample metadata table, assigning condition labels (A and B) and setting run IDs as row names."69- [other] Construct a DESeqDataSet from the tximport output using DESeqDataSetFromTximport(), specifying the sample metadata and design formula (~condition).: "Construct a DESeqDataSet from the tximport output using DESeqDataSetFromTximport(), specifying the sample metadata and design formula (~condition)."70- [other] Set factor levels for reference comparison: 'dds$condition <- factor(dds$condition, levels = c("untreated","treated"))': "dds$condition <- factor(dds$condition, levels = c("untreated","treated"))"71- [other] Construct DESeqDataSet from count matrix: 'dds <- DESeqDataSetFromMatrix(countData = cts, colData = coldata, design= ~ batch + condition)': "dds <- DESeqDataSetFromMatrix(countData = cts, colData = coldata, design= ~ batch + condition)"
