Sample Metadata Preparation and Assignment
Summary
Construct a sample metadata table (colData) that maps sample identifiers to experimental conditions and covariates, then assign it as the column-level annotation for a DESeqDataSet. This is a prerequisite for differential expression testing, as DESeq2 uses metadata to define the design formula and contrast groups.
When to use
Before constructing a DESeqDataSet from any count matrix (whether from tximport, HTSeq, featureCounts, or raw counts). You have sample identifiers (run IDs, file names, or row names) and must link them to condition labels (e.g., 'treated' vs 'untreated') and any batch or covariate information needed for the design formula.
When NOT to use
- colData already exists and is correctly formatted — proceed directly to DESeqDataSet construction.
- Performing unsupervised analysis (e.g., clustering, PCA) on raw counts where condition is not yet known — metadata is not strictly required for exploratory analysis.
- Using an already-constructed DESeqDataSet from tximeta, which automatically includes full sample metadata — metadata assignment is already handled.
Inputs
- Sample run/file identifiers (character vector or table)
- Condition labels per sample (character or factor)
- Optional batch/covariate annotations per sample (numeric or factor)
Outputs
- colData object (DataFrame with sample row names and condition columns)
- DESeqDataSet with assigned column metadata
How to apply
Create a data frame with sample identifiers as row names and experimental condition(s) as columns. Assign condition labels (e.g., 'A' and 'B', or 'treated' and 'untreated') explicitly to each sample; if performing differential expression, specify which level should be the reference by converting the condition column to a factor and setting factor levels with factor(condition, levels=c('untreated','treated')). Include additional columns for batch, replicate ID, or other covariates that will appear in the design formula. Pass this metadata table to DESeqDataSetFromMatrix(), DESeqDataSetFromTximport(), or DESeqDataSet() via the colData parameter. Verify that row names in colData match column names in the count matrix and that all samples are represented.
Related tools
- DESeq2 (Accepts colData as input to DESeqDataSetFromMatrix(), DESeqDataSetFromTximport(), and DESeqDataSet() constructors; uses metadata to define design formula and specify contrasts) — https://github.com/thelovelab/DESeq2
- tximport (Produces a list that is paired with colData in DESeqDataSetFromTximport() to construct a DESeqDataSet)
- tximeta (Automatically generates a SummarizedExperiment with metadata; can be converted to DESeqDataSet using colData from the SE)
Examples
samples <- data.frame(condition=c('A','B','A','B'), row.names=c('run1','run2','run3','run4')); samples$condition <- factor(samples$condition, levels=c('A','B')); dds <- DESeqDataSetFromTximport(txi, colData=samples, design=~condition)
Evaluation signals
- colData row names match count matrix column names exactly (no reordering or misalignment).
- All rows in colData are represented (no missing samples); all columns in count matrix are represented in colData.
- Condition column is a factor with explicitly specified levels; reference level is listed first in
levels() output.
- DESeqDataSet construction completes without error;
colData(dds) returns the assigned metadata.
- Design formula (e.g.,
~condition or ~batch+condition) uses column names that exist in colData; model.matrix(design, colData) produces a valid design matrix.
Limitations
- Factor level ordering must be manually specified; the default alphabetical ordering may not reflect your intended reference level for contrast computation.
- Missing or mismatched sample identifiers between metadata and count matrix will cause silent column reordering or loss of data — always verify row/column alignment before DESeqDataSet construction.
- Complex experimental designs with many confounders or interactions require careful design formula specification; tximeta or external metadata curation tools may be preferable for large cohort studies.
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.: "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).: "DESeqDataSetFromTximport(txi, colData = samples, design = ~ condition)"
- [other] Set factor levels for reference comparison before DESeq analysis.: "dds$condition <- factor(dds$condition, levels = c("untreated","treated"))"
- [other] colData is passed to DESeqDataSet constructors; the design formula uses columns from colData.: "dds <- DESeqDataSetFromMatrix(countData = cts, colData = coldata, design= ~ batch + condition)"
1---2name: sample-metadata-preparation-and-assignment3description: Use when before constructing a DESeqDataSet from any count matrix (whether from tximport, HTSeq, featureCounts, or raw counts). You have sample identifiers (run IDs, file names, or row names) and must link them to condition labels (e.4license: CC-BY-4.05---67# Sample Metadata Preparation and Assignment89## Summary1011Construct a sample metadata table (colData) that maps sample identifiers to experimental conditions and covariates, then assign it as the column-level annotation for a DESeqDataSet. This is a prerequisite for differential expression testing, as DESeq2 uses metadata to define the design formula and contrast groups.1213## When to use1415Before constructing a DESeqDataSet from any count matrix (whether from tximport, HTSeq, featureCounts, or raw counts). You have sample identifiers (run IDs, file names, or row names) and must link them to condition labels (e.g., 'treated' vs 'untreated') and any batch or covariate information needed for the design formula.1617## When NOT to use1819- colData already exists and is correctly formatted — proceed directly to DESeqDataSet construction.20- Performing unsupervised analysis (e.g., clustering, PCA) on raw counts where condition is not yet known — metadata is not strictly required for exploratory analysis.21- Using an already-constructed DESeqDataSet from tximeta, which automatically includes full sample metadata — metadata assignment is already handled.2223## Inputs2425- Sample run/file identifiers (character vector or table)26- Condition labels per sample (character or factor)27- Optional batch/covariate annotations per sample (numeric or factor)2829## Outputs3031- colData object (DataFrame with sample row names and condition columns)32- DESeqDataSet with assigned column metadata3334## How to apply3536Create a data frame with sample identifiers as row names and experimental condition(s) as columns. Assign condition labels (e.g., 'A' and 'B', or 'treated' and 'untreated') explicitly to each sample; if performing differential expression, specify which level should be the reference by converting the condition column to a factor and setting factor levels with `factor(condition, levels=c('untreated','treated'))`. Include additional columns for batch, replicate ID, or other covariates that will appear in the design formula. Pass this metadata table to `DESeqDataSetFromMatrix()`, `DESeqDataSetFromTximport()`, or `DESeqDataSet()` via the `colData` parameter. Verify that row names in colData match column names in the count matrix and that all samples are represented.3738## Related tools3940- **DESeq2** (Accepts colData as input to DESeqDataSetFromMatrix(), DESeqDataSetFromTximport(), and DESeqDataSet() constructors; uses metadata to define design formula and specify contrasts) — https://github.com/thelovelab/DESeq241- **tximport** (Produces a list that is paired with colData in DESeqDataSetFromTximport() to construct a DESeqDataSet)42- **tximeta** (Automatically generates a SummarizedExperiment with metadata; can be converted to DESeqDataSet using colData from the SE)4344## Examples4546```47samples <- data.frame(condition=c('A','B','A','B'), row.names=c('run1','run2','run3','run4')); samples$condition <- factor(samples$condition, levels=c('A','B')); dds <- DESeqDataSetFromTximport(txi, colData=samples, design=~condition)48```4950## Evaluation signals5152- colData row names match count matrix column names exactly (no reordering or misalignment).53- All rows in colData are represented (no missing samples); all columns in count matrix are represented in colData.54- Condition column is a factor with explicitly specified levels; reference level is listed first in `levels()` output.55- DESeqDataSet construction completes without error; `colData(dds)` returns the assigned metadata.56- Design formula (e.g., `~condition` or `~batch+condition`) uses column names that exist in colData; `model.matrix(design, colData)` produces a valid design matrix.5758## Limitations5960- Factor level ordering must be manually specified; the default alphabetical ordering may not reflect your intended reference level for contrast computation.61- Missing or mismatched sample identifiers between metadata and count matrix will cause silent column reordering or loss of data — always verify row/column alignment before DESeqDataSet construction.62- Complex experimental designs with many confounders or interactions require careful design formula specification; tximeta or external metadata curation tools may be preferable for large cohort studies.6364## Evidence6566- [other] Load the tximportData package and retrieve the sample metadata table, assigning condition labels (A and B) and setting run IDs as row names.: "retrieve the sample metadata table, assigning condition labels (A and B) and setting run IDs as row names"67- [other] Construct a DESeqDataSet from the tximport output using DESeqDataSetFromTximport(), specifying the sample metadata and design formula (~condition).: "DESeqDataSetFromTximport(txi, colData = samples, design = ~ condition)"68- [other] Set factor levels for reference comparison before DESeq analysis.: "dds$condition <- factor(dds$condition, levels = c("untreated","treated"))"69- [other] colData is passed to DESeqDataSet constructors; the design formula uses columns from colData.: "dds <- DESeqDataSetFromMatrix(countData = cts, colData = coldata, design= ~ batch + condition)"
HolobiomicsLab