quality-control-sample-selection-and-marking
Summary
Identify and designate quality-control (QC) samples within a metabolomics dataset by leveraging sample metadata annotations, enabling downstream normalization and batch-effect correction. This skill is essential for preparing data for RLSC and other QC-sample-dependent normalization methods.
When to use
Your metabolomics dataset contains samples analyzed across multiple batches or runs, and you have sample-level metadata (sampledata) with a 'type' or classification field. You intend to apply QC-aware normalization methods (e.g., RLSC via NormQcsamples, or internal-standard or QC-metabolite methods via NormQcmets) that require explicit identification of QC samples to model and correct batch variation.
When NOT to use
- Your dataset contains no technical replicates or QC samples; QC-sample-based normalization requires explicit QC replicates to estimate batch structure.
- QC samples are already fully integrated into the feature matrix without metadata linking; you cannot retrospectively recover QC status from intensity patterns alone.
- You plan to use only univariate scaling methods (e.g., median, mean, sum normalization) that do not leverage QC sample behavior; selection and marking would be wasted effort.
Inputs
- sampledata: dataframe with unique sample names as row names; must include 'type' or 'class' column identifying sample category (e.g., 'QC', 'sample') and 'order' column with run sequence
- featuredata: metabolomics intensity matrix (rows=samples, columns=metabolites) in same row order as sampledata
Outputs
- annotated sampledata: sampledata dataframe with QC samples flagged and sorted by run order
- QC sample index: vector or logical flag identifying which rows in featuredata and sampledata correspond to QC samples
How to apply
Inspect the sampledata dataframe to identify a column (commonly 'type' or 'class') that distinguishes QC samples from biological samples. QC samples are typically technical replicates or pooled reference materials analyzed at regular intervals throughout the run. Subset or flag rows in sampledata where this column equals 'QC' or a similar designation. Ensure sampledata is sorted by the 'order' column (run sequence) before passing to normalization functions; this ordering is critical for RLSC to correctly model drift. Document which rows are QC samples in the metadata so downstream normalization functions can access and use them to estimate and remove systematic variation. Verify that QC samples are distributed throughout the run (not clustered at the beginning or end) to capture temporal batch effects.
Related tools
- NormalizeMets (R package containing NormQcsamples and NormQcmets functions that accept marked QC samples as input for RLSC and other QC-aware normalization methods) — https://github.com/metabolomicstats/NormalizeMets
- RStudio (integrated development environment for R; recommended for inspecting and manipulating sampledata metadata)
- R (statistical computing environment; used to subset, flag, and sort sampledata and featuredata)
Examples
# Load sampledata; inspect and flag QC samples
library(NormalizeMets)
data(Didata)
sampledata_sorted <- sampledata[order(sampledata$order), ]
qc_idx <- which(sampledata_sorted$type == "QC")
# Pass to NormQcsamples for RLSC normalization
featuredata_norm <- NormQcsamples(featuredata, sampledata_sorted, method='rlsc', span=0, deg=2, lg=TRUE)
Evaluation signals
- sampledata contains a populated 'type' or 'class' column with at least one 'QC' entry and at least one non-QC entry (e.g., 'sample'); no missing values in this column for rows to be used.
- sampledata is sorted by the 'order' column in ascending sequence with no gaps; verify using all(diff(sampledata$order) > 0) or equivalent.
- QC samples are distributed across the run (not all at start/end); verify by inspecting the 'order' values of QC-flagged rows and checking for temporal coverage (e.g., QC samples appear in first quartile, middle, and last quartile of the run).
- Dimension consistency: nrow(sampledata) == nrow(featuredata) and row names match exactly; no samples lost or reordered during QC flagging.
- Passing marked QC samples to NormQcsamples produces a normalized featuredata matrix with no errors or warnings related to missing QC sample indices; output dimensions match input.
Limitations
- QC sample designation requires pre-existing metadata; if sampledata lacks a 'type' field or QC samples are not recorded, this skill cannot proceed.
- Sparse or unevenly distributed QC samples (e.g., only at run start or end) limit the ability of downstream RLSC to model and correct drift; RLSC assumes QC samples span the temporal range.
- This skill marks and selects QC samples but does not validate their analytical quality (e.g., whether QC intensities are reproducible or outlying); quality assessment is a separate step (e.g., via RlaPlots or PcaPlots on QC subsets).
- The R package requires R ≥ 3.4.3; older versions may not support NormQcsamples or may have incompatible dependencies.
Evidence
- [other] Sort featuredata and sampledata by run order (sampledata$order column). Call NormQcsamples with the sorted featuredata and sampledata, specifying method='rlsc': "Sort featuredata and sampledata by run order (sampledata$order column). Call NormQcsamples with the sorted featuredata and sampledata, specifying method='rlsc'"
- [readme] sampledata is a dataframe that contains sample-specific information. These information can include sample type, order of analysis, factors of interest and other sample-specific data relevant to the analysis. Unique sample names need to be provided as row names.: "sampledata is a dataframe that contains sample-specific information. These information can include sample type, order of analysis, factors of interest and other sample-specific data relevant to the"
- [other] NormQcsamples<- function(featuredata, sampledata, method = c('rlsc'), span = 0, deg = 2, lg = TRUE...: "NormQcsamples<- function(featuredata, sampledata, method = c("rlsc"), span = 0, deg = 2, lg = TRUE..."
- [readme] Metabolomics data are inevitably subject to a component of unwanted variation, due to factors such as batch effects, matrix effects, and confounding biological variation.: "Metabolomics data are inevitably subject to a component of unwanted variation, due to factors such as batch effects, matrix effects, and confounding biological variation."
1---2name: quality-control-sample-selection-and-marking3description: Use when your metabolomics dataset contains samples analyzed across multiple batches or runs, and you have sample-level metadata (sampledata) with a 'type' or classification field. You intend to apply QC-aware normalization methods (e.4license: CC-BY-4.05---67# quality-control-sample-selection-and-marking89## Summary1011Identify and designate quality-control (QC) samples within a metabolomics dataset by leveraging sample metadata annotations, enabling downstream normalization and batch-effect correction. This skill is essential for preparing data for RLSC and other QC-sample-dependent normalization methods.1213## When to use1415Your metabolomics dataset contains samples analyzed across multiple batches or runs, and you have sample-level metadata (sampledata) with a 'type' or classification field. You intend to apply QC-aware normalization methods (e.g., RLSC via NormQcsamples, or internal-standard or QC-metabolite methods via NormQcmets) that require explicit identification of QC samples to model and correct batch variation.1617## When NOT to use1819- Your dataset contains no technical replicates or QC samples; QC-sample-based normalization requires explicit QC replicates to estimate batch structure.20- QC samples are already fully integrated into the feature matrix without metadata linking; you cannot retrospectively recover QC status from intensity patterns alone.21- You plan to use only univariate scaling methods (e.g., median, mean, sum normalization) that do not leverage QC sample behavior; selection and marking would be wasted effort.2223## Inputs2425- sampledata: dataframe with unique sample names as row names; must include 'type' or 'class' column identifying sample category (e.g., 'QC', 'sample') and 'order' column with run sequence26- featuredata: metabolomics intensity matrix (rows=samples, columns=metabolites) in same row order as sampledata2728## Outputs2930- annotated sampledata: sampledata dataframe with QC samples flagged and sorted by run order31- QC sample index: vector or logical flag identifying which rows in featuredata and sampledata correspond to QC samples3233## How to apply3435Inspect the sampledata dataframe to identify a column (commonly 'type' or 'class') that distinguishes QC samples from biological samples. QC samples are typically technical replicates or pooled reference materials analyzed at regular intervals throughout the run. Subset or flag rows in sampledata where this column equals 'QC' or a similar designation. Ensure sampledata is sorted by the 'order' column (run sequence) before passing to normalization functions; this ordering is critical for RLSC to correctly model drift. Document which rows are QC samples in the metadata so downstream normalization functions can access and use them to estimate and remove systematic variation. Verify that QC samples are distributed throughout the run (not clustered at the beginning or end) to capture temporal batch effects.3637## Related tools3839- **NormalizeMets** (R package containing NormQcsamples and NormQcmets functions that accept marked QC samples as input for RLSC and other QC-aware normalization methods) — https://github.com/metabolomicstats/NormalizeMets40- **RStudio** (integrated development environment for R; recommended for inspecting and manipulating sampledata metadata)41- **R** (statistical computing environment; used to subset, flag, and sort sampledata and featuredata)4243## Examples4445```46# Load sampledata; inspect and flag QC samples47library(NormalizeMets)48data(Didata)49sampledata_sorted <- sampledata[order(sampledata$order), ]50qc_idx <- which(sampledata_sorted$type == "QC")51# Pass to NormQcsamples for RLSC normalization52featuredata_norm <- NormQcsamples(featuredata, sampledata_sorted, method='rlsc', span=0, deg=2, lg=TRUE)53```5455## Evaluation signals5657- sampledata contains a populated 'type' or 'class' column with at least one 'QC' entry and at least one non-QC entry (e.g., 'sample'); no missing values in this column for rows to be used.58- sampledata is sorted by the 'order' column in ascending sequence with no gaps; verify using all(diff(sampledata$order) > 0) or equivalent.59- QC samples are distributed across the run (not all at start/end); verify by inspecting the 'order' values of QC-flagged rows and checking for temporal coverage (e.g., QC samples appear in first quartile, middle, and last quartile of the run).60- Dimension consistency: nrow(sampledata) == nrow(featuredata) and row names match exactly; no samples lost or reordered during QC flagging.61- Passing marked QC samples to NormQcsamples produces a normalized featuredata matrix with no errors or warnings related to missing QC sample indices; output dimensions match input.6263## Limitations6465- QC sample designation requires pre-existing metadata; if sampledata lacks a 'type' field or QC samples are not recorded, this skill cannot proceed.66- Sparse or unevenly distributed QC samples (e.g., only at run start or end) limit the ability of downstream RLSC to model and correct drift; RLSC assumes QC samples span the temporal range.67- This skill marks and selects QC samples but does not validate their analytical quality (e.g., whether QC intensities are reproducible or outlying); quality assessment is a separate step (e.g., via RlaPlots or PcaPlots on QC subsets).68- The R package requires R ≥ 3.4.3; older versions may not support NormQcsamples or may have incompatible dependencies.6970## Evidence7172- [other] Sort featuredata and sampledata by run order (sampledata$order column). Call NormQcsamples with the sorted featuredata and sampledata, specifying method='rlsc': "Sort featuredata and sampledata by run order (sampledata$order column). Call NormQcsamples with the sorted featuredata and sampledata, specifying method='rlsc'"73- [readme] sampledata is a dataframe that contains sample-specific information. These information can include sample type, order of analysis, factors of interest and other sample-specific data relevant to the analysis. Unique sample names need to be provided as row names.: "sampledata is a dataframe that contains sample-specific information. These information can include sample type, order of analysis, factors of interest and other sample-specific data relevant to the"74- [other] NormQcsamples<- function(featuredata, sampledata, method = c('rlsc'), span = 0, deg = 2, lg = TRUE...: "NormQcsamples<- function(featuredata, sampledata, method = c("rlsc"), span = 0, deg = 2, lg = TRUE..."75- [readme] Metabolomics data are inevitably subject to a component of unwanted variation, due to factors such as batch effects, matrix effects, and confounding biological variation.: "Metabolomics data are inevitably subject to a component of unwanted variation, due to factors such as batch effects, matrix effects, and confounding biological variation."
