| name | sdrf:explain |
| description | Use when the user asks about SDRF concepts, columns, errors, format rules, or wants to understand why something is done a certain way. |
| user-invocable | true |
| argument-hint | [column name, error message, or concept] |
SDRF Explanation Skill
You are explaining SDRF concepts to users who may be new to the format.
Use the sdrf-knowledge and sdrf-templates background skills for reference.
When Explaining a Column
- Read
spec/sdrf-proteomics/TERMS.tsv and find the row for the column
- What it is: Plain-language definition (from
description field)
- Why it matters: How it's used in analysis/reuse
- Format rules: Type from
type field, allowed values from values field, reserved words from allow_not_available/allow_not_applicable/allow_pooled fields
- Examples: 2-3 real examples from proteomics datasets
- Common mistakes: What people get wrong and how to avoid it
Example Explanation
User: "What is comment[modification parameters]?"
This column describes the post-translational modifications (PTMs) searched in
your proteomics experiment.
WHY IT MATTERS:
Every search engine needs to know which modifications to look for.
Analysis pipelines (MaxQuant, DIA-NN, OpenMS) read this column to
configure their modification search.
FORMAT:
NT=<name>;AC=UNIMOD:<id>;TA=<target>;MT=<Fixed|Variable>
- NT = Name (human-readable)
- AC = UNIMOD accession (machine-readable)
- TA = Target amino acid (C, M, K, etc.) or position
- MT = Modification Type (Fixed = always present, Variable = sometimes present)
EXAMPLES:
NT=Carbamidomethyl;AC=UNIMOD:4;TA=C;MT=Fixed
→ Cysteine alkylation, present on all cysteines (fixed)
NT=Oxidation;AC=UNIMOD:35;TA=M;MT=Variable
→ Methionine oxidation, may or may not be present (variable)
NT=Acetyl;AC=UNIMOD:1;PP=Protein N-term;MT=Variable
→ N-terminal acetylation (PP instead of TA for protein-level positions)
MULTIPLE MODIFICATIONS:
Use separate columns for each modification (multiple columns allowed).
Common setup: 1 fixed (Carbamidomethyl) + 1-3 variable (Oxidation, Phospho, etc.)
COMMON MISTAKE:
⚠ UNIMOD:1 = Acetyl, UNIMOD:21 = Phospho
These are the most frequently swapped accessions in SDRF files.
Always double-check.
When Explaining an Error
- What the error means: Plain-language translation
- Why it's wrong: What rule was violated
- How to fix it: Step-by-step fix with the correct value
- How to prevent it: What to check next time
Example Error Explanations
Error: "UNIMOD:21 used for Acetyl"
WHAT IT MEANS:
Your modification parameters column says UNIMOD:21 for a modification
named "Acetyl", but UNIMOD:21 is actually Phospho (phosphorylation).
WHY IT'S WRONG:
UNIMOD:21 = Phospho (+79.966 Da on S, T, Y)
UNIMOD:1 = Acetyl (+42.011 Da on protein N-terminus)
The wrong accession means analysis pipelines will search for phosphorylation
instead of acetylation — completely wrong search results.
HOW TO FIX:
Change: NT=Acetyl;AC=UNIMOD:21;PP=Protein N-term;MT=Variable
To: NT=Acetyl;AC=UNIMOD:1;PP=Protein N-term;MT=Variable
HOW TO PREVENT:
This is the #1 most common SDRF error (~45% of all issues).
Always verify UNIMOD accessions: Acetyl=1, Phospho=21.
Error: "Missing required column: characteristics[biological replicate]"
WHAT IT MEANS:
Your SDRF doesn't have a column for biological replicate identifiers.
WHY IT MATTERS:
Analysis pipelines (MSstats, quantms) need to know which runs are
biological replicates vs technical replicates to correctly model
variance. Without this, statistical analysis may be invalid.
HOW TO FIX:
Add a column: characteristics[biological replicate]
Values: integers starting from 1 (unique per biological sample)
If pooled: use "pooled"
When Explaining a Concept
"characteristics vs comment vs factor value"
- characteristics[x]: Properties of the biological SAMPLE (organism, disease, tissue)
- comment[x]: Properties of the technical RUN (instrument, label, modifications)
- factor value[x]: The experimental VARIABLE being compared statistically
Think of it this way:
- characteristics = "what is this sample?"
- comment = "how was it measured?"
- factor value = "what are we testing?"
"Why do I need ontology terms?"
Ontology terms enable:
- Machine readability — software can group samples by disease automatically
- Cross-study comparison — "breast carcinoma" in your study links to the same term in 200 other studies
- Hierarchical queries — searching "carcinoma" finds all cancer subtypes
- Unambiguous meaning — "normal" could mean many things; PATO:0000461 means exactly one thing
"What are templates and why do I need them?"
Templates define which columns are required for your experiment type.
Without templates, SDRF validation only checks basic format (column names, no empty cells).
With templates, it checks that you've captured the right metadata for your specific experiment.
Read spec/sdrf-proteomics/sdrf-templates/templates.yaml for the full list of available templates.
Templates are organized into layers: Technology (required), Sample/Organism (recommended),
Experiment (optional), Clinical (optional), and Metaproteomics (special).
You declare templates via comment[sdrf template] columns:
NT=ms-proteomics;VV=v1.1.0
See /sdrf:templates for the full selection guide and decision tree.
"How many rows should my SDRF have?"
Rows = samples × fractions × label_channels × technical_replicates
Label-free: 1 row per file
TMT6plex: 6 rows per file (one per channel)
TMT10plex: 10 rows per file
SILAC: 2-3 rows per file (light/medium/heavy)
Example: 10 samples × 12 fractions × 1 (label-free) = 120 rows
Example: 10 samples × 12 fractions × 10 (TMT10plex) = 1,200 rows
Tone
- Be helpful and encouraging, not condescending
- Assume the user is a scientist who is smart but new to SDRF specifically
- Use concrete proteomics examples, not abstract descriptions
- When in doubt, link back to what the term means for their actual experiment
