[lucas-diedrich]

Related to MannLabs/alphapepttools#99 (comment)

Currently, the columns do not always mean the same thing across readers. We define what each constant key actually means in the docstring of the Metaclass to have a common definition

This PR only adds definitions for each Key in the PsmDfCols Metaclass. In a next step, column mappings can be updated based on these standardized defintions.

[lucas-diedrich]

Currently updated definitions

Missing definitions

• MOD_SITES
• TO_REMOVE
• AA_MASS_DIFFS
• DIANN_SPEC_INDEX
• QUERY_ID
• FDR1_SEARCH1, FDR2_SEARCH1, FDR1_SEARCH2, FDR2_SEARCH2

Constant Name	Standardized Column Name	Definition
MOD_SITES	mod_sites		❌
MODIFIED_SEQUENCE	modified_sequence	Peptide sequence annotated with modification locations and standardized modification labels.
SEQUENCE	sequence	Peptide amino-acid sequence without modification annotations (plain sequence of residues). Primary key: Feature-Peptide
DECOY	decoy	Label indicating whether the matched sequence is a decoy (reverse/shuffled) entry used for FDR estimation.
MODS	mods	List of modifications on the peptide in Unimod standardization.
SCORE	score	Primary identification score for the PSM produced by the search engine quantifying quality of the PSM in arbitrary units.
TO_REMOVE	to_remove		❌
AA_MASS_DIFFS	aa_mass_diffs		❌
AA_MASS_DIFF_SITES	aa_mass_diff_sites
RT	rt	Retention time of the precursor (time when the precursor eluted during chromatography) in [UNIT].
RT_START	rt_start	Start of search window in retention time of the precursor (time when the precursor eluted during chromatography) in [UNIT].
RT_STOP	rt_stop	End of search window in retention time of the precursor (time when the precursor eluted during chromatography) in [UNIT].
RT_NORM	rt_norm	Normalized retention time of the precursor (time when the precursor eluted during chromatography) in [UNIT].
SPEC_IDX	spec_idx	Spectrum index or internal spectrum identifier used by some file formats/engines to reference a spectrum; may be distinct from scan number.
SCANNR	scannr	MS/MS scan number (integer) indexing the spectrum within the raw file; use to locate the spectrum in vendor files or mzML.
FDR	fdr	False discovery rate (FDR) or q-value associated with the PSM.
NAA	nAA	Number of amino acids in the sequence.
CCS	ccs	Collision Cross Section (CCS) value for the ion in [UNIT].
MOBILITY	mobility	Ion mobility value associated with the precursor when available in [UNIT].
PEPTIDE_FDR	peptide_fdr	FDR or q-value estimated at the peptide-sequence level.
PROTEIN_FDR	protein_fdr	FDR or q-value estimated at the protein or protein-group level.
RAW_NAME	raw_name	Original filename or run identifier as reported by the acquisition system or search engine. Represents the raw data source that produced the spectrum. Primary key: Observation
CHARGE	charge	Charge state of the precursor.
PROTEINS	proteins	Protein names (human readable format) of the matching protein group.
INTENSITY	intensity	Intensity of the corresponding protein group.
SCAN_NUM	scan_num	MS/MS scan number (integer) indexing the scan within the raw file.
PRECURSOR_MZ	precursor_mz	Measured precursor mass-to-charge ratio (m/z) for the MS/MS spectrum.
DIANN_SPEC_INDEX	diann_spec_idx		❌
UNIPROT_IDS	uniprot_ids	Uniprot identifiers of the corresponding protein group. Primary key: Feature-Protein
GENES	genes	Gene names (typically in HGNC nomenclature) of the corresponding protein group. Primary key: Value: Protein Intensity
QUERY_ID	query_id		❌
FDR1_SEARCH1	fdr1_search1		❌
FDR2_SEARCH1	fdr2_search1		❌
FDR1_SEARCH2	fdr1_search2		❌
FDR2_SEARCH2	fdr2_search2		❌

[vbrennsteiner]

LGTM save for missing documentations, but in general I would not spend too much time digging them up, but instead wait until use-cases appear for the more obscure columns like "TO_REMOVE", "AA_MASS_DIFFS" and "A_MASS_DIFF_SITES".