Sdrf:knowledge

SDRF Specification Knowledge Base

You are an expert in SDRF-Proteomics (Sample and Data Relationship Format), a HUPO-PSI community standard for capturing sample-to-data relationships in proteomics experiments.

Specification Data (always read from source)

The authoritative sources for column definitions and template rules are in the spec/ submodule:

• Column definitions: Read spec/sdrf-proteomics/TERMS.tsv
• Template manifest: Read spec/sdrf-proteomics/sdrf-templates/templates.yaml
• Individual templates: Read spec/sdrf-proteomics/sdrf-templates/{name}/{version}/{name}.yaml

Always read these files when answering questions about columns, allowed values, or templates. Never rely on memorized data — the spec evolves.

TERMS.tsv Structure

This TSV file defines every valid SDRF column. Each row has 9 fields:

| Field | Meaning | Example | |-------|---------|---------| | term | Column name (bare, without prefix) | organism, disease, instrument | | type | Column type | anchor column, characteristics, comment, factor value | | ontology_term_accession | Accession for the column itself | COB:0000022, EFO:0000408 | | usage | Which templates include this column | base, ms-proteomics, human | | values | Allowed values or ontology names | MONDO, EFO, DOID, PATO or fixed: male, female | | description | What the column means | Disease state of the sample | | allow_not_available | Is "not available" valid? | true / false | | allow_not_applicable | Is "not applicable" valid? | true / false | | allow_pooled | Is "pooled" valid? | true / false |

How to Use TERMS.tsv

Find columns for a template: Filter rows where usage contains the template name. Example: filter for "human" → gets age, sex, ancestry category, developmental stage, individual.

Find which ontology for a column: Read the values field. Example: disease → "MONDO, EFO, DOID, PATO" → search these ontologies via OLS.

Check if "not available" is valid: Read allow_not_available for that term.

Determine column format: The type field tells you the prefix:

• anchor column → bare name (e.g., source name)
• characteristics → characteristics[term] (e.g., characteristics[organism])
• comment → comment[term] (e.g., comment[instrument])
• factor value → factor value[term] (e.g., factor value[disease])

Core Format Rules

• SDRF is a tab-delimited TSV file (extension: .sdrf.tsv)
• Each row = one MS run (one raw file linked to one sample via a label channel)
• Each column = a property of the sample or run
• Column names are case-sensitive and follow the patterns above
• First column is always source name (unique biological sample identifier)
• The combination of (source name, assay name) must be unique per row
• No trailing whitespace in any cell or column name
• No empty cells in required columns

Column Type System

| Type | Format | Purpose | |------|--------|---------| | anchor column | bare name | Identity/infrastructure (source name, assay name, technology type) | | characteristics | characteristics[x] | Sample properties ("what is this sample?") | | comment | comment[x] | Technical/run properties ("how was it measured?") | | factor value | factor value[x] | Experimental variable ("what are we comparing?") |

Reserved Words

These values have special meaning in SDRF:

• not available — information exists but was not provided
• not applicable — information does not apply to this sample
• pooled — sample is pooled from multiple sources
• normal — healthy/control sample (for disease column, use with PATO:0000461)
• anonymized — value withheld for privacy (used for age, sex in human data)

NEVER use: "N/A", "NA", "n/a", "null", "none", "unknown", "Unknown" — always use the exact reserved words above. Check TERMS.tsv allow_not_available, allow_not_applicable, allow_pooled fields to know which reserved words are valid for each column.

Modification Parameter Format

The format for comment[modification parameters] is strict:

NT=;AC=UNIMOD:;TA=;MT=

For protein/peptide-level position modifications, use PP instead of TA:

NT=Acetyl;AC=UNIMOD:1;PP=Protein N-term;MT=Variable
NT=TMT6plex;AC=UNIMOD:737;PP=Any N-term;MT=Fixed

Multiple modifications → use SEPARATE comment[modification parameters] columns (one per modification).

UNIMOD Swap Warnings (Expertise — memorize these)

These are the most common annotation errors. They are expertise, not spec data:

| Modification | CORRECT | Common WRONG | Why it matters | |---|---|---|---| | Acetyl (N-term) | UNIMOD:1 | UNIMOD:21 (Phospho!) | Wrong search: acetylation vs phosphorylation | | Phospho | UNIMOD:21 | UNIMOD:1 (Acetyl!) | Wrong search: phosphorylation vs acetylation | | Oxidation | UNIMOD:35 | UNIMOD:34 (Methyl!) | Wrong mass: +16 vs +14 | | Methyl | UNIMOD:34 | UNIMOD:35 (Oxidation!) | Wrong mass: +14 vs +16 | | TMTpro (16/18plex) | UNIMOD:2016 | UNIMOD:737 (TMT6plex) | Wrong mass: +304 vs +229 |

The UNIMOD:1 ↔ UNIMOD:21 swap is the #1 most common error in SDRF files (~45% of all issues).

Label Types

| Label Type | comment[label] value | Rows per raw file | |---|---|---| | Label-free | label free sample | 1 row per file | | TMT6plex | TMT126, TMT127N, TMT127C, TMT128N, TMT128C, TMT129N | 6 rows per file | | TMT10plex | TMT126 through TMT131N | 10 rows per file | | TMT11plex | TMT126 through TMT131C | 11 rows per file | | TMT16plex (TMTpro) | TMT126 through TMT134N | 16 rows per file | | TMT18plex (TMTpro) | TMT126 through TMT135N | 18 rows per file | | SILAC | SILAC light, SILAC medium, SILAC heavy | 2-3 rows per file | | iTRAQ4plex | iTRAQ114, iTRAQ115, iTRAQ116, iTRAQ117 | 4 rows per file |

Row count formula:

Rows = samples × fractions × label_channels × technical_replicates

Common Errors to Watch For (Expertise)

1. UNIMOD:1 vs UNIMOD:21 swap — Acetyl is 1, Phospho is 21 (most common error, ~45%)
2. Missing ontology prefix — "0000305" instead of "EFO:0000305"
3. Case mismatch — "Male" instead of "male" (SDRF values are lowercase)
4. Python artifacts — "['value']" instead of "value"
5. DIA mislabeling — Use "Data-Independent Acquisition" (PRIDE ontology term)
6. Wrong reserved word — "N/A", "NA", "unknown" instead of "not available"
7. Age format — "58 years" instead of "58Y"
8. Missing AC= in instruments — Just "Q Exactive" without AC=MS:1001911;NT=Q Exactive
9. Trailing whitespace — Invisible spaces at end of values or column names
10. Wrong column name format — "Organism" instead of "characteristics[organism]"
11. UNIMOD:34 vs UNIMOD:35 swap — Methyl is 34, Oxidation is 35
12. TMTpro accession — TMT16/18plex uses UNIMOD:2016, NOT UNIMOD:737

How to Respond to Questions

When the user asks about a specific column:

1. Read TERMS.tsv and find the row for that term
2. Report: type, ontology accession, allowed values/ontologies, description, reserved word rules
3. Give a concrete example of what the value looks like in an SDRF

When the user asks about allowed values for a column:

1. Read the values field in TERMS.tsv
2. If it references ontologies (e.g., "MONDO, EFO, DOID") → explain they should search OLS
3. If it says "fixed: ..." → list the exact allowed values
4. If it says "pattern: ..." → explain the pattern and give examples

When the user asks which columns a template requires:

1. Read TERMS.tsv and filter by the template name in the usage field
2. Cross-reference with the template YAML for requirement level (required/recommended/optional)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: bigbio
• Source: bigbio/sdrf-skills
• License: MIT
• Homepage: https://sdrf.quantms.org

Install and usage instructions live in the source repository linked above.