Scores & CV Terms¶
QPX provides two structured fields for attaching metadata to records beyond the core columns: additional_scores for numeric quality metrics and cv_params for controlled vocabulary annotations. Both are stored as arrays of structs, making them extensible without schema changes. qpxc transform relayout can store either as a struct with one field per name (Struct lists).
Additional scores¶
The additional_scores field captures search engine scores, quality metrics, and other numeric values associated with a PSM, feature, peptide, or protein group. Each entry is self-describing: it carries its name, value, and an indication of whether higher values are better.
Struct definition¶
additional_scores: array[struct{
score_name: string, -- Score identifier in snake_case (e.g. "comet_xcorr")
score_value: float, -- Numeric value
higher_better: bool, null -- true = higher is better; false = lower is better; null = unknown
}]
The higher_better field makes the data self-describing so that downstream consumers can interpret scores without looking up external ontology definitions.
A producer writes null when it does not know the direction; it never defaults to true. Most PSI-MS score terms declare no order, so QPX converters take the direction from the term when it has one, treat e-values, q-values, p-values, PEP and FDR as lower-is-better and engine match scores and probabilities as higher-is-better, and leave anything else null. A consumer ranking PSMs by a score whose higher_better is null must decide the direction itself.
snake_case naming convention
All score names in QPX use snake_case -- no colons, dots, spaces, or mixed case. This ensures score names are valid identifiers in SQL, Python, R, and any query language without quoting. The Ontology Mapping maps each snake_case name to its proper ontology term and accession. qpxc validate warns on other additional_scores names.
Example¶
[
{"score_name": "comet_xcorr", "score_value": 3.42, "higher_better": true},
{"score_name": "global_qvalue", "score_value": 0.0012, "higher_better": false},
{"score_name": "rank", "score_value": 1.0, "higher_better": false}
]
Typed q-value columns¶
Filtering on a nested score reads about 100 times the data of a flat column, and a filter on one name misses other producers. Writers therefore copy q-values from additional_scores to flat columns (specification 1.3), which is the portable way to filter: psm.confident() and feature.confident() use them. Score names are compared in snake_case, and the first match of a row wins.
| Column | Level and scope | Filled from |
|---|---|---|
psm.qvalue |
PSM, as computed by the source | qvalue, q_value, psm_qvalue, psm_level_qvalue, <engine>_qvalue, <engine>_q_value; not names of a higher level (peptide, peptidoform, protein, pg, gg, global, precursor) |
feature.peptide_qvalue |
Peptide, as computed by the source | peptide_qvalue, peptide_level_qvalue |
feature.precursor_qvalue |
Precursor, per run | precursor_qvalue, qvalue, q_value, psm_level_qvalue |
feature.global_qvalue |
Precursor, per experiment | global_qvalue |
A column stays null when the source has no such score. In specification 1.3, a score whose snake_case name equals a typed column's name and whose value exactly equals that column's filled value is written only in the flat column, not in additional_scores. Aliases such as q_value, psm_level_qvalue and percolator_q_value stay in the list because their names record the source; a same-name score with a different value also stays.
Recommended score names¶
The following score names are commonly used across QPX views. All names are snake_case. For formal ontology names and accessions, see the Ontology Mapping.
| Score name | Typical view(s) | Direction | Description |
|---|---|---|---|
posterior_error_probability |
PSM | lower is better | Posterior error probability — probability that the PSM is incorrect. Ranges 0.0–1.0. This is a top-level field in the PSM view, not stored in additional_scores |
global_qvalue |
PSM, Feature | lower is better | Global q-value at the experiment level; on a feature, read the global_qvalue column |
pg_global_qvalue |
PSM, Feature | lower is better | Protein group global q-value used to filter at the protein group level |
rank |
PSM | lower is better | Rank of the peptide in the search engine results (1 = best) |
comet_xcorr |
PSM | higher is better | Cross-correlation score from the Comet search engine |
comet_deltacn |
PSM | higher is better | Delta CN score from Comet |
comet_expect |
PSM | lower is better | Expectation value from Comet |
msgf_raw_score |
PSM | higher is better | Raw score from MS-GF+ |
msgf_spec_evalue |
PSM | lower is better | Spectral E-value from MS-GF+ |
sage_hyperscore |
PSM | higher is better | Hyperscore from Sage search engine |
parent_ion_fraction |
PSM | higher is better | Fraction of the isolation window's signal from the target precursor, 0-1 (MaxQuant PIF, FragPipe Purity, CDAP PrecursorPurity); on a feature it is the column of that name |
precursor_qvalue |
Feature | lower is better | Run-level precursor q-value (Q.Value), written to the precursor_qvalue column by the DIA-NN converter; an exact duplicate is not kept in additional_scores |
pg_qvalue |
Feature | lower is better | Run-level protein-group q-value, as emitted by the DIA-NN converter |
pg_pep |
PG | lower is better | Protein-group posterior error probability (PG.PEP), as emitted by the DIA-NN converter |
diann_lib_qvalue |
Feature | lower is better | Library q-value from DIA-NN |
diann_cscore |
Feature | higher is better | Confidence score from DIA-NN |
diann_evidence |
Feature | higher is better | Evidence score from DIA-NN |
diann_ms1_profile_corr |
Feature | higher is better | MS1 profile correlation from DIA-NN |
diann_mass_evidence |
Feature | higher is better | Mass evidence score from DIA-NN |
diann_quantity_quality |
Feature | higher is better | Quantity quality score from DIA-NN |
consensus_support |
PSM | higher is better | Number of search engines supporting the identification |
Naming convention for new scores
When adding tool-specific scores, use snake_case with the tool name as prefix: {tool}_{score}. For example, comet_xcorr, diann_cscore, sage_hyperscore. Register the mapping to the proper ontology term in ontology.parquet (see Ontology Mapping).
Names in this table are the ones producers actually write
Earlier revisions listed diann_qvalue and diann_global_qvalue, which no converter emits — the DIA-NN converter writes the precursor_qvalue and global_qvalue columns and keeps pg_qvalue in additional_scores. The table records the emitted names so a consumer can match on them.
feature.peptide_qvalue is reserved for peptide-level confidence. DIA-NN Q.Value is precursor-level, so it is written to feature.precursor_qvalue and must not be copied into feature.peptide_qvalue.
Protein-level additional scores¶
At the protein group level, additional_scores follows the same struct definition. The score_value is a float that applies to the entire protein group entry. For per-protein scores within a group, the values array index corresponds to the pg_accessions array index.
Controlled vocabulary terms¶
The cv_params field stores key-value annotations drawn from controlled vocabularies. Unlike additional_scores (which are always numeric), CV parameters can carry string values or be value-less (presence-only).
Struct definition¶
cv_params: array[struct{
cv_name: string, -- Term name from a controlled vocabulary
cv_value: string, null -- Term value; null if the term is a flag (presence-only)
}]
Example¶
[
{"cv_name": "ms level", "cv_value": "2"},
{"cv_name": "deconvoluted data", "cv_value": null},
{"cv_name": "prot:FDR threshold", "cv_value": "0.01"},
{"cv_name": "number of unmatched peaks", "cv_value": "3"}
]
Note
The cv_name is always required. The cv_value is optional -- a null value indicates a boolean/flag-style term where mere presence is meaningful (e.g., "deconvoluted data").
Where these fields are used¶
| View | additional_scores |
cv_params |
|---|---|---|
PSM (psm_file) |
Yes | Yes |
Feature (feature_file) |
Yes | Yes |
| API Views | Yes (as best_id_score) |
-- |
Protein Group (pg_file) |
Yes | -- |
MZ (mz_file) |
-- | Yes |
Warning
Do not store search engine scores in cv_params. Numeric scores belong in additional_scores, which provides the higher_better flag and enforces float typing. Reserve cv_params for non-numeric annotations and metadata.
Further reading¶
- Modifications -- localization scores use a similar score struct pattern
- Intensities -- additional processed values for features and protein groups
- QPX Format Overview -- full list of views and concepts