psm_utils

Common utilities for parsing and handling PSMs, and search engine results.

psm_utils.peptidoform

class psm_utils.peptidoform.Peptidoform(proforma_sequence: str)

Peptide sequence, modifications and charge state represented in ProForma notation.

Parameters: proforma_sequence (str) – Peptidoform sequence in ProForma v2 notation.

Examples

>>> peptidoform = Peptidoform("ACDM[Oxidation]EK")
>>> peptidoform.theoretical_mass
711.2567622919099

parsed_sequence

List of tuples with residue and modifications for each location.

Type: list

properties

Dict with sequence-wide properties.

Type: dict[str, Any]

property proforma: str

Peptidoform sequence in ProForma v2 notation.

Examples

>>> Peptidoform("AC[U:4]DEK/2").proforma
'AC[UNIMOD:4]DEK/2'

property sequence: str

Stripped peptide sequence (modifications removed).

Examples

>>> Peptidoform("AC[U:4]DEK/2").sequence
'ACDEK'

property precursor_charge: Optional[int]

Returns the charge state as integer or None if no charge assigned.

Examples

>>> Peptidoform("ACDEK/2").precursor_charge
2

>>> Peptidoform("ACDEK").precursor_charge
None

property sequential_composition: list[mass.Composition]

Atomic compositions of both termini and each residue, including modifications.

Includes N- and C-terminal, fixed, and sequential modifications. Does not include labile or unlocalized modifications.

Examples

>>> Peptidoform("ACDEK/2").sequential_composition
[Composition({'H': 1}),
Composition({'H': 5, 'C': 3, 'O': 1, 'N': 1}),
Composition({'H': 5, 'C': 3, 'S': 1, 'O': 1, 'N': 1}),
Composition({'H': 5, 'C': 4, 'O': 3, 'N': 1}),
Composition({'H': 7, 'C': 5, 'O': 3, 'N': 1}),
Composition({'H': 12, 'C': 6, 'N': 2, 'O': 1}),
Composition({'H': 1, 'O': 1})]

property composition: Composition

Atomic composition of the full peptidoform.

Includes all modifications, also labile and unlocalized.

Examples

>>> Peptidoform("ACDEK/2").composition
Composition({'H': 36, 'C': 21, 'O': 10, 'N': 6, 'S': 1})

property sequential_theoretical_mass: float

Monoisotopic mass of both termini and each (modified) residue.

Includes N- and C-terminal, fixed, and sequential modifications. Does not include labile or unlocalized modifications.

Examples

>>> Peptidoform("ACDEK/2").sequential_theoretical_mass
[1.00782503207,
03711378471,
00918478471,
02694302383001,
04259308796998,
09496301399997,
002739651629998]

property theoretical_mass: float

Monoisotopic mass of the full uncharged peptidoform.

Includes all modifications, also labile and unlocalized.

Examples

>>> Peptidoform("ACDEK/2").theoretical_mass
564.22136237892

property theoretical_mz: Optional[float]

Monoisotopic mass-to-charge ratio of the full peptidoform.

Includes all modifications, also labile and unlocalized.

Examples

>>> Peptidoform("ACDEK/2").theoretical_mz
283.11850622153

>>> Peptidoform("AC[+57.021464]DEK/2").theoretical_mz
311.62923822153

rename_modifications(mapping: dict[str, str]) → None

Apply mapping to rename modification tags.

Parameters: mapping (dict[str, str]) – Mapping of old label → new label for each modification that requires renaming. Modification labels that are not in the mapping will not be renamed.

Examples

>>> peptidoform = Peptidoform('[ac]-PEPTC[cmm]IDEK')
>>> peptidoform.rename_modifications({
...     "ac": "Acetyl",
...     "cmm": "Carbamidomethyl"
... })
>>> peptidoform.proforma
'[Acetyl]-PEPTC[Carbamidomethyl]IDEK'

add_fixed_modifications(modification_rules: list[tuple[str, list[str]]])

Add fixed modifications to peptidoform.

Add modification rules for fixed modifications to peptidoform. These will be added in the “fixed modifications” notation, at the front of the ProForma sequence.

Examples

>>> peptidoform = Peptidoform("ATPEILTCNSIGCLK")
>>> peptidoform.add_fixed_modifications([("Carbamidomethyl", ["C"])])
>>> peptidoform.proforma
'<[Carbamidomethyl]@C>ATPEILTCNSIGCLK'

apply_fixed_modifications()

Apply ProForma fixed modifications as sequential modifications.

Applies all modifications that are encoded as fixed in the ProForma notation (once at the beginning of the sequence) as modifications throughout the sequence at each affected amino acid residue.

Examples

>>> peptidoform = Peptidoform('<[Carbamidomethyl]@C>ATPEILTCNSIGCLK')
>>> peptidoform.apply_fixed_modifications()
>>> peptidoform.proforma
'ATPEILTC[Carbamidomethyl]NSIGC[Carbamidomethyl]LK'

exception psm_utils.peptidoform.PeptidoformException: Error while handling Peptidoform.

exception psm_utils.peptidoform.AmbiguousResidueException: Error while handling ambiguous residue.

exception psm_utils.peptidoform.ModificationException: Error while handling amino acid modification.

psm_utils.psm

class psm_utils.psm.PSM(*, peptidoform: Union[Peptidoform, str], spectrum_id: Union[int, str], run: Optional[str] = None, collection: Optional[str] = None, spectrum: Optional[Any] = None, is_decoy: Optional[bool] = None, score: Optional[float] = None, qvalue: Optional[float] = None, pep: Optional[float] = None, precursor_mz: Optional[float] = None, retention_time: Optional[float] = None, protein_list: Optional[List[str]] = None, rank: Optional[int] = None, source: Optional[str] = None, provenance_data: Optional[Dict[str, str]] = None, metadata: Optional[Dict[str, str]] = None, rescoring_features: Optional[Dict[str, str]] = None)

Data class representing a peptide-spectrum match (PSM).

Links a Peptidoform to an observed spectrum and holds the related information. Attribute types are coerced and enforced upon initialization.

Parameters

peptidoform (Peptidoform, str) – Peptidoform object or string in ProForma v2 notation.
spectrum_id (str, int) – Spectrum identifier as used in spectrum file (e.g., mzML or MGF), usually in HUPO-PSI nativeID format (MS:1000767), e.g., controllerType=0 controllerNumber=0 scan=423.
run (str, optional) – Name of the MS run. Usually the spectrum file filename without extension.
collection (str, optional) – Identifier of the collection of spectrum files. Usually, the ProteomeXchange identifier, e.g. PXD028735.
spectrum (any, optional) – Observed spectrum. Can be freely used, for instance as a spectrum_utils.spectrum.MsmsSpectrum object.
is_decoy (bool, optional) – Boolean specifying if the PSM is a decoy (True) or target hit (False).
score (float, optional) – Search engine score.
precursor_mz (float, optional) – Precursor m/z.
retention_time (float, optional) – Retention time.
protein_list (list[str]) – List of proteins or protein groups associated with peptide.
rank (int) – rank of a psm
source (str, optional) – PSM file type where PSM was stored. E.g., MaxQuant.
provenance_data (dict[str, str], optional) – Freeform dict to hold data describing the PSM origin, e.g. a search engine-specific identifier.
metadata (dict[str, str], optional) – More data about PSM.
rescoring_features (dict[str, str], optional) – Dict with features that can be used for PSM rescoring.

get_precursor_charge() → int: Precursor charge, as embedded in PSM.peptidoform.

get_usi(as_url=False) → str

Compile Universal Spectrum Identifier for PSM.

Parameters: as_url (bool, optional) – Return URL to proteomeXchange.org USI aggregator.

psm_utils.psm_list

class psm_utils.psm_list.PSMList(*, psm_list: List[PSM])

Data class representing a list of PSMs, with some useful functionality.

Parameters: psm_list (list[PSM]) – List of PSM instances.

Examples

Initiate a PSMList from a list of PSM objects:

>>> psm_list = PSMList(psm_list=[
...     PSM(peptidoform="ACDK", spectrum_id=1, score=140.2),
...     PSM(peptidoform="CDEFR", spectrum_id=2, score=132.9),
...     PSM(peptidoform="DEM[Oxidation]K", spectrum_id=3, score=55.7),
... ])

PSMList directly supports iteration:

>>> for psm in psm_list:
...     print(psm.peptidoform.score)
140.2
132.9
55.7

PSM properties can be accessed as a single Numpy array:

>>> psm_list["score"]
array([140.2, 132.9, 55.7], dtype=object)

PSMList supports indexing and slicing:

>>> psm_list_subset = psm_list[0:2]
>>> psm_list_subset["score"]
array([140.2, 132.9], dtype=object)

>>> psm_list_subset = psm_list[0, 2]
>>> psm_list_subset["score"]
array([140.2, 55.7], dtype=object)

property collections: list: List of collections in PSMList.

property runs: list: List of runs in PSMList.

get_psm_dict(): Get nested dictionary of PSMs by collection, run, and spectrum_id.

get_rank1_psms(lower_score_better=False) → PSMList: Return new PSMList with only first-rank PSMs

find_decoys(decoy_pattern: str) → None

Use regular expression pattern to find decoy PSMs by protein name(s).

This method allows a regular expression pattern to be applied on PSM protein_list items to set the is_decoy attribute. Decoy protein entries are commonly marked with a prefix or suffix, e.g. DECOY_, or _REVERSED. If decoy_pattern matches to a substring of all entries in protein_list, the PSM is interpreted as a decoy. Existing is_decoy entries are overwritten.

Parameters: decoy_pattern (str) – Regular expression pattern to match decoy protein entries.

Examples

>>> psm_list.find_decoys(r"^DECOY_")

calculate_qvalues(reverse: bool = True, **kwargs) → None

Calculate q-values using the target-decoy approach.

Q-values are calculated for all PSMs from the target and decoy scores. This requires that all PSMs have a score and a target/decoy state (is_decoy) assigned. Any existing q-values will be overwritten.

Parameters

reverse (boolean, optional) – If True (default), a higher score value indicates a better PSM.
**kwargs (dict, optional) – Additional arguments to be passed to pyteomics.auxiliary.target_decoy.qvalues.

rename_modifications(mapping: dict[str, str]) → None

Apply mapping to rename modification tags for all PSMs.

Applies psm_utils.peptidoform.Peptidoform.rename_modifications() on all PSM peptidoforms in the PSMList.

Parameters: mapping (dict[str, str]) – Mapping of old label → new label for each modification that requires renaming. Modification labels that are not in the mapping will not be renamed.

add_fixed_modifications(modification_rules: list[tuple[str, list[str]]])

Add fixed modifications to all PSM peptidoforms in PSMList.

Add modification rules for fixed modifications to peptidoform. These will be added in the “fixed modifications” notation, at the front of the ProForma sequence.

Examples

>>> psm_list.add_fixed_modifications([("Carbamidomethyl", ["C"])])

apply_fixed_modifications()

Apply ProForma fixed modifications as sequential modifications.

Applies psm_utils.peptidoform.Peptidoform.apply_fixed_modifications() on all PSM peptidoforms in the PSMList.

Examples

>>> psm_list.apply_fixed_modifications()

set_ranks(): Set identification ranks for all PSMs in PSMList.

to_dataframe() → DataFrame: Convert PSMList to pandas.DataFrame.