Merge pull request #96 from compomics/feature/flashlfq-output

Add reader and writer for FlashLFQ

CHANGELOG.md

@@ -5,11 +5,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## Unreleased
+## [1.1.0] - 2024-09-05
 
 ### Added
 
 - `Peptidoform`: Add `modified_sequence` property to return the modified sequence in ProForma format, but without charge state.
+- `io`: Add support for reading and writing FlashLFQ generic TSV files.
 
 
 ## [1.0.1] - 2024-08-28

README.rst

@@ -89,6 +89,7 @@ Supported file formats
 ===================================================================================================================== ======================== =============== ===============
  File format psm_utils tag Read support Write support
 ===================================================================================================================== ======================== =============== ===============
+ `FlashLFQ generic TSV <https://github.com/smith-chem-wisc/FlashLFQ/wiki/Identification-Input-Formats>`_ ``flashlfq`` ✅ ✅
  `ionbot CSV <https://ionbot.cloud/>`_ ``ionbot`` ✅ ❌
  `OpenMS idXML <https://www.openms.de/>`_ ``idxml`` ✅ ✅
  `MaxQuant msms.txt <https://www.maxquant.org/>`_ ``msms`` ✅ ❌

docs/source/api/psm_utils.io.rst

@@ -7,6 +7,14 @@ psm_utils.io
 
 
 
+psm_utils.io.flashlfq
+##################
+
+.. automodule:: psm_utils.io.flashlfq
+ :members:
+ :inherited-members:
+
+
 psm_utils.io.idxml
 ##################
 

example_files/example.flashlfq.tsv

@@ -0,0 +1,18 @@
+File Name Scan Retention Time Precursor Charge Base Sequence Full Sequence Peptide Monoisotopic Mass Protein Accession
+SmallCalibratible_Yeast 24.80555 2 KAPAGGAADAAAK KAPAGGAADAAAK 
+SmallCalibratible_Yeast 24.95372 2 KAPAAAPAASK KAPAAAPAASK 
+SmallCalibratible_Yeast 24.77032 2 KQAIETANK KQAIETANK 
+SmallCalibratible_Yeast 24.17319 2 RVDEGGAQDK RVDEGGAQDK 
+SmallCalibratible_Yeast 24.26695 2 KDAEPQSDSTTSK KDAEPQSDSTTSK 
+SmallCalibratible_Yeast 24.10798 2 EKAEAEAEK EKAEAEAEK 
+SmallCalibratible_Yeast 24.06874 2 EKAEAEAEK EKAEAEAEK 
+SmallCalibratible_Yeast 24.77398 2 FKEEDEKESQR FKEEDEKESQR 
+SmallCalibratible_Yeast 24.90638 2 YDHEASSSYK YDHEASSSYK 
+SmallCalibratible_Yeast 24.40345 3 SKDVTDSATTKK SKDVTDSATTKK 
+SmallCalibratible_Yeast 24.71679 2 FKEEDEKESQR FKEEDEKESQR 
+SmallCalibratible_Yeast 24.39968 2 ALKQEGAANK ALKQEGAANK 
+SmallCalibratible_Yeast 24.67303 2 SKDVTDSATTK SKDVTDSATTK 
+SmallCalibratible_Yeast 24.45053 2 KLEDHPK KLEDHPK 
+SmallCalibratible_Yeast 24.77398 1 HIDAGAK HIDAGAK 
+SmallCalibratible_Yeast 24.9022 2 YLAKEEEKK YLAKEEEKK 
+SmallCalibratible_Yeast 24.76278 2 YAGEVSHDDK YAGEVSHDDK 

psm_utils/__init__.py

@@ -1,6 +1,6 @@
 """Common utilities for parsing and handling PSMs, and search engine results."""
 
-__version__ = "1.0.1"
+__version__ = "1.1.0"
 __all__ = ["Peptidoform", "PSM", "PSMList"]
 
 from warnings import filterwarnings

psm_utils/io/__init__.py

@@ -8,6 +8,7 @@
 
 from rich.progress import track
 
+import psm_utils.io.flashlfq as flashlfq
 import psm_utils.io.idxml as idxml
 import psm_utils.io.ionbot as ionbot
 import psm_utils.io.maxquant as maxquant
@@ -28,6 +29,12 @@
 from psm_utils.psm_list import PSMList
 
 FILETYPES = {
+ "flashlfq": {
+ "reader": flashlfq.FlashLFQReader,
+ "writer": flashlfq.FlashLFQWriter,
+ "extension": ".tsv",
+ "filename_pattern": r"^.*\.flashlfq\.tsv$",
+ },
  "ionbot": {
  "reader": ionbot.IonbotReader,
  "writer": None,

psm_utils/io/flashlfq.py

@@ -0,0 +1,228 @@
+"""
+Reader and writer for the FlashLFQ generic TSV format.
+
+See the `FlashLFQ documentation <https://github.com/smith-chem-wisc/FlashLFQ/wiki/Identification-Input-Formats>`_
+for more information on the format.
+
+Notes
+-----
+- The FlashLFQ format does not contain the actual spectrum identifier. When reading a FlashLFQ
+ file, the spectrum identifier is set to the row number in the file.
+- The FlashLFQ format does not contain the precursor m/z, but the theoretical monoisotopic mass.
+ This value is not read into the PSM object, but can be calculated from the peptidoform.
+- To read from a FlashLFQ file, the ``Full Sequence`` column is expected to contain a ProForma v2
+ compatible peptidoform notation.
+
+"""
+
+from __future__ import annotations
+
+import csv
+import logging
+from pathlib import Path
+from typing import Optional, Union
+
+import numpy as np
+
+from psm_utils.io._base_classes import ReaderBase, WriterBase
+from psm_utils.io._utils import set_csv_field_size_limit
+from psm_utils.io.exceptions import PSMUtilsIOException
+from psm_utils.psm import PSM
+from psm_utils.psm_list import PSMList
+
+set_csv_field_size_limit()
+
+LOGGER = logging.getLogger(__name__)
+
+
+class FlashLFQReader(ReaderBase):
+ """Reader for FlashLFQ TSV format."""
+
+ required_columns = ["Full Sequence", "Precursor Charge"]
+
+ def __iter__(self):
+ """Iterate over file and return PSMs one-by-one."""
+ with open(self.filename, "rt") as open_file:
+ reader = csv.DictReader(open_file, delimiter="\t")
+ if not all(col in reader.fieldnames for col in self.required_columns):
+ raise PSMUtilsIOException(
+ f"FlashLFQ TSV file must contain the following columns: {self.required_columns}"
+ )
+ for i, row in enumerate(reader):
+ yield self._parse_entry(row, spectrum_id=str(i))
+
+ def _parse_entry(self, entry: dict, spectrum_id) -> PSM:
+ """Parse single FlashLFQ TSV entry to :py:class:`~psm_utils.psm.PSM`."""
+ # Replace empty strings with None
+ entry = {k: v if v else None for k, v in entry.items()}
+
+ # Parse entry
+ return PSM(
+ peptidoform=f"{entry['Full Sequence']}/{entry['Precursor Charge']}",
+ spectrum_id=spectrum_id,
+ run=entry.get("File Name"),
+ retention_time=entry.get("Scan Retention Time"),
+ protein_list=self._parse_protein_list(entry.get("Protein Accessions")),
+ )
+
+ @staticmethod
+ def _parse_protein_list(protein_accessions: Optional[str]) -> list[str]:
+ """Parse protein list string to list of protein accessions."""
+ if not protein_accessions:
+ return []
+ elif ";" in protein_accessions: # Docs define separator as semicolon
+ return protein_accessions.split(";")
+ elif "|" in protein_accessions: # Example file uses pipe
+ return protein_accessions.split("|")
+ else:
+ return [protein_accessions] # Single protein
+
+
+class FlashLFQWriter(WriterBase):
+ """Reader for FlashLFQ TSV format."""
+
+ def __init__(
+ self,
+ filename: Union[str, Path],
+ *args,
+ fdr_threshold: float = 0.01,
+ only_targets: bool = True,
+ **kwargs,
+ ):
+ """
+ Reader for psm_utils TSV format.
+
+ Parameters
+ ----------
+ filename
+ Path to PSM file.
+ fdr_threshold
+ FDR threshold for filtering PSMs.
+ only_targets
+ If True, only target PSMs are written to file. If False, both target and decoy PSMs
+ are written.
+
+ """
+ super().__init__(filename, *args, **kwargs)
+
+ self.fdr_threshold = fdr_threshold
+ self.only_targets = only_targets
+
+ self._open_file = None
+ self._writer = None
+ self.fieldnames = None
+
+ def __enter__(self) -> FlashLFQWriter:
+ if Path(self.filename).is_file():
+ # Get fieldnames from existing file
+ with open(self.filename, "rt") as open_file:
+ # Get fieldnames
+ self.fieldnames = open_file.readline().strip().split("\t")
+ mode = "at"
+ else:
+ # Set default fieldnames
+ self.fieldnames = [
+ "File Name",
+ "Base Sequence",
+ "Full Sequence",
+ "Peptide Monoisotope Mass",
+ "Scan Retention Time",
+ "Precursor Charge",
+ "Protein Accessions",
+ ]
+ mode = "wt"
+
+ # Open file and writer
+ self._open_file = open(self.filename, mode, newline="")
+ self._writer = csv.DictWriter(
+ self._open_file,
+ fieldnames=self.fieldnames,
+ extrasaction="ignore",
+ delimiter="\t",
+ )
+
+ if mode == "wt":
+ self._writer.writeheader()
+
+ return self
+
+ def __exit__(self, *args, **kwargs) -> None:
+ self._open_file.close()
+ self._open_file = None
+ self._writer = None
+
+ def write_psm(self, psm: PSM):
+ """
+ Write a single PSM to new or existing PSM file.
+
+ Parameters
+ ----------
+ psm
+ PSM object to write.
+
+ """
+ if psm.qvalue and psm.qvalue > self.fdr_threshold:
+ return
+ if self.only_targets and psm.is_decoy:
+ return
+
+ entry = self._psm_to_entry(psm)
+ try:
+ self._writer.writerow(entry)
+ except AttributeError as e:
+ raise PSMUtilsIOException(
+ f"`write_psm` method can only be called if `{self.__class__.__qualname__}`"
+ "is opened in context (i.e., using the `with` statement)."
+ ) from e
+
+ def write_file(self, psm_list: PSMList):
+ """
+ Write an entire PSMList to a new PSM file.
+
+ Parameters
+ ----------
+ psm_list
+ PSMList object to write to file.
+
+ """
+ # Filter out decoys
+ if self.only_targets:
+ # Accept both None and False
+ target_mask = np.array([not psm.is_decoy for psm in psm_list])
+ LOGGER.debug(f"Skipping {~target_mask.sum()} decoy PSMs for FlashLFQ file.")
+ else:
+ target_mask = np.ones(len(psm_list), dtype=bool)
+
+ # Filter out PSMs above FDR threshold
+ if any(psm.qvalue is None for psm in psm_list):
+ LOGGER.warning(
+ "Not all PSMs have a q-value. Skipping FDR filtering for FlashLFQ file."
+ )
+ fdr_mask = np.ones(len(psm_list), dtype=bool)
+ else:
+ fdr_mask = psm_list["qvalue"] <= self.fdr_threshold
+ filtered_by_fdr = (~fdr_mask & target_mask).sum()
+ LOGGER.debug(f"Skipping {filtered_by_fdr} PSMs above FDR threshold for FlashLFQ file.")
+
+ filtered_psm_list = psm_list[target_mask & fdr_mask]
+
+ with open(self.filename, "wt", newline="") as f:
+ writer = csv.DictWriter(
+ f, fieldnames=self.fieldnames, delimiter="\t", extrasaction="ignore"
+ )
+ writer.writeheader()
+ for psm in filtered_psm_list:
+ writer.writerow(self._psm_to_entry(psm))
+
+ @staticmethod
+ def _psm_to_entry(psm: PSM) -> dict:
+ """Convert :py:class:`~psm_utils.psm.PSM` to FlashLFQ TSV entry."""
+ return {
+ "File Name": psm.run,
+ "Base Sequence": psm.peptidoform.sequence,
+ "Full Sequence": psm.peptidoform.modified_sequence,
+ "Peptide Monoisotope Mass": psm.peptidoform.theoretical_mass,
+ "Scan Retention Time": psm.retention_time,
+ "Precursor Charge": psm.peptidoform.precursor_charge,
+ "Protein Accessions": ";".join(psm.protein_list),
+ }