PEFFFile.h

Go to the documentation of this file.

// Copyright (c) 2002-present, OpenMS Inc. -- EKU Tuebingen, ETH Zurich, and FU Berlin
// SPDX-License-Identifier: BSD-3-Clause
//
// --------------------------------------------------------------------------
// $Maintainer: OpenMS Team $
// $Authors: OpenMS Team $
// --------------------------------------------------------------------------
 
#pragma once
 
#include <OpenMS/CONCEPT/Exception.h>
#include <OpenMS/CONCEPT/ProgressLogger.h>
#include <OpenMS/DATASTRUCTURES/StringUtils.h>
#include <OpenMS/FORMAT/FASTAFile.h>
#include <OpenMS/CHEMISTRY/AASequence.h>
#include <OpenMS/CHEMISTRY/ProteaseDigestion.h>
 
#include <fstream>
#include <limits>
#include <map>
#include <vector>
 
namespace OpenMS
{
  struct OPENMS_DLLAPI PEFFModification
  {
    Size position{0};         
    std::string accession;         
    std::string name;              
    std::string optional_tag;      
    UInt annotation_id{std::numeric_limits<UInt>::max()};  
 
    enum class Type { PSI_MOD, UNIMOD, GENERIC };
    Type type{Type::GENERIC};
 
    PEFFModification() = default;
    PEFFModification(Size pos, const std::string& acc, const std::string& n, const std::string& tag = "", UInt aid = std::numeric_limits<UInt>::max())
      : position(pos), accession(acc), name(n), optional_tag(tag), annotation_id(aid)
    {
      if (StringUtils::hasPrefix(accession, "MOD:"))
      {
        type = Type::PSI_MOD;
      }
      else if (StringUtils::hasPrefix(accession, "UNIMOD:"))
      {
        type = Type::UNIMOD;
      }
    }
 
    bool operator==(const PEFFModification& rhs) const
    {
      return position == rhs.position && accession == rhs.accession &&
             name == rhs.name && type == rhs.type &&
             optional_tag == rhs.optional_tag && annotation_id == rhs.annotation_id;
    }
  };
 
  struct OPENMS_DLLAPI PEFFVariantSimple
  {
    Size position{0};         
    char variant_aa{'\0'};    
    std::string optional_tag;      
    UInt annotation_id{std::numeric_limits<UInt>::max()};  
 
    PEFFVariantSimple() = default;
    PEFFVariantSimple(Size pos, char aa, const std::string& tag = "", UInt aid = std::numeric_limits<UInt>::max())
      : position(pos), variant_aa(aa), optional_tag(tag), annotation_id(aid) {}
 
    bool operator==(const PEFFVariantSimple& rhs) const
    {
      return position == rhs.position && variant_aa == rhs.variant_aa &&
             optional_tag == rhs.optional_tag && annotation_id == rhs.annotation_id;
    }
  };
 
  struct OPENMS_DLLAPI PEFFVariantComplex
  {
    Size start_position{0};   
    Size end_position{0};     
    std::string replacement;       
    std::string optional_tag;      
    UInt annotation_id{std::numeric_limits<UInt>::max()};  
 
    PEFFVariantComplex() = default;
    PEFFVariantComplex(Size start, Size end, const std::string& repl, const std::string& tag = "", UInt aid = std::numeric_limits<UInt>::max())
      : start_position(start), end_position(end), replacement(repl), optional_tag(tag), annotation_id(aid) {}
 
    bool operator==(const PEFFVariantComplex& rhs) const
    {
      return start_position == rhs.start_position && end_position == rhs.end_position &&
             replacement == rhs.replacement && optional_tag == rhs.optional_tag &&
             annotation_id == rhs.annotation_id;
    }
  };
 
  struct OPENMS_DLLAPI PEFFProcessedRegion
  {
    Size start_position{0};   
    Size end_position{0};     
    std::string accession;         
    std::string name;              
    std::string optional_tag;      
    UInt annotation_id{std::numeric_limits<UInt>::max()};  
 
    PEFFProcessedRegion() = default;
    PEFFProcessedRegion(Size start, Size end, const std::string& acc, const std::string& n = "", const std::string& tag = "", UInt aid = std::numeric_limits<UInt>::max())
      : start_position(start), end_position(end), accession(acc), name(n), optional_tag(tag), annotation_id(aid) {}
 
    bool operator==(const PEFFProcessedRegion& rhs) const
    {
      return start_position == rhs.start_position && end_position == rhs.end_position &&
             accession == rhs.accession && name == rhs.name && optional_tag == rhs.optional_tag &&
             annotation_id == rhs.annotation_id;
    }
  };
 
  struct OPENMS_DLLAPI PEFFDisulfideBond
  {
    std::string id1;                  
    std::string id2;                  
    std::string optional_tag;         
    UInt annotation_id{std::numeric_limits<UInt>::max()};  
 
    PEFFDisulfideBond() = default;
    PEFFDisulfideBond(const std::string& i1, const std::string& i2, const std::string& tag = "", UInt aid = std::numeric_limits<UInt>::max())
      : id1(i1), id2(i2), optional_tag(tag), annotation_id(aid) {}
 
    bool operator==(const PEFFDisulfideBond& rhs) const
    {
      return id1 == rhs.id1 && id2 == rhs.id2 && optional_tag == rhs.optional_tag &&
             annotation_id == rhs.annotation_id;
    }
  };
 
  struct OPENMS_DLLAPI PEFFEntry
  {
    // Basic fields
    std::string prefix;             
    std::string identifier;
    std::string sequence;
 
    // Metadata
    std::vector<std::string> protein_names;   
    std::string gene_name;                     
    Int ncbi_tax_id{0};                  
    std::string taxonomy_name;                 
    Size sequence_length{0};             
    std::string sequence_version;              
    std::string entry_version;                 
    Int protein_existence{0};            
    std::string db_unique_id;                  
    std::string entry_id;                      
    std::vector<std::string> alt_accessions;   
 
    // Annotations
    std::vector<PEFFModification> modifications;
    std::vector<PEFFVariantSimple> simple_variants;
    std::vector<PEFFVariantComplex> complex_variants;
    std::vector<PEFFProcessedRegion> processed_regions;
    std::vector<PEFFDisulfideBond> disulfide_bonds;  
    std::vector<std::string> proteoforms;     
 
    // Custom annotations
    std::map<std::string, std::string> custom_annotations;
 
    PEFFEntry() = default;
 
    PEFFEntry(const PEFFEntry& rhs) = default;
    PEFFEntry(PEFFEntry&& rhs) noexcept = default;
    PEFFEntry& operator=(const PEFFEntry& rhs) = default;
    PEFFEntry& operator=(PEFFEntry&& rhs) noexcept = default;
 
    bool operator==(const PEFFEntry& rhs) const
    {
      return prefix == rhs.prefix &&
             identifier == rhs.identifier &&
             sequence == rhs.sequence &&
             protein_names == rhs.protein_names &&
             gene_name == rhs.gene_name &&
             ncbi_tax_id == rhs.ncbi_tax_id &&
             taxonomy_name == rhs.taxonomy_name &&
             sequence_length == rhs.sequence_length &&
             sequence_version == rhs.sequence_version &&
             entry_version == rhs.entry_version &&
             protein_existence == rhs.protein_existence &&
             db_unique_id == rhs.db_unique_id &&
             entry_id == rhs.entry_id &&
             alt_accessions == rhs.alt_accessions &&
             modifications == rhs.modifications &&
             simple_variants == rhs.simple_variants &&
             complex_variants == rhs.complex_variants &&
             processed_regions == rhs.processed_regions &&
             disulfide_bonds == rhs.disulfide_bonds &&
             proteoforms == rhs.proteoforms &&
             custom_annotations == rhs.custom_annotations;
    }
 
    FASTAFile::FASTAEntry toFASTAEntry() const;
 
    static PEFFEntry fromFASTAEntry(const FASTAFile::FASTAEntry& fasta);
 
    AASequence getSequence() const;
 
    AASequence getModifiedSequence() const;
 
    void getVariantSequences(
      std::vector<std::string>& descriptions,
      std::vector<AASequence>& sequences,
      bool include_complex = false) const;
 
    AASequence getProcessedSequence(const std::string& region_accession = "PEFF:0001021") const;
 
    void digestWithVariants(
      const ProteaseDigestion& digestor,
      std::vector<std::string>& descriptions,
      std::vector<AASequence>& sequences,
      Size min_length = 6,
      Size max_length = 40,
      bool include_reference = true,
      bool include_variants = true,
      bool include_modifications = false) const;
 
    void generatePeptides(
      const ProteaseDigestion& digestor,
      std::vector<std::string>& descriptions,
      std::vector<AASequence>& sequences,
      const std::vector<std::string>& fixed_mods = {},
      const std::vector<std::string>& variable_mods = {},
      Size max_variable_mods_per_peptide = 2,
      Size min_length = 6,
      Size max_length = 40,
      bool include_reference = true,
      bool include_peff_variants = true,
      bool include_peff_modifications = true,
      Size max_peff_mods_per_proteoform = 0) const;
 
  private:
    static std::vector<std::pair<std::string, AASequence>> enumeratePEFFModifications_(
      const AASequence& peptide,
      const std::vector<std::pair<Size, const PEFFModification*>>& peff_mods,
      const std::string& base_description,
      Size max_selected = 0);
  };
 
  struct OPENMS_DLLAPI PEFFCustomKeyDef
  {
    std::string key_name;
    std::string description;
    std::string concept_curie;
    std::string regexp;
    std::vector<std::string> field_names;
    std::vector<std::string> field_types;
 
    bool operator==(const PEFFCustomKeyDef& rhs) const
    {
      return key_name == rhs.key_name && description == rhs.description &&
             concept_curie == rhs.concept_curie && regexp == rhs.regexp &&
             field_names == rhs.field_names && field_types == rhs.field_types;
    }
  };
 
  struct OPENMS_DLLAPI PEFFDatabaseMetadata
  {
    std::string version{"1.0"};
    std::string db_name;
    std::string prefix;
    std::string db_description;
    bool is_decoy{false};
    std::vector<std::string> db_sources;
    std::string db_version;
    Size number_of_entries{0};
 
    enum class SequenceType { AA, NA };
    SequenceType sequence_type{SequenceType::AA};
 
    std::vector<std::string> general_comments;     
    std::string conversion;                         
    std::map<std::string, std::string> specific_keys;    
    std::map<std::string, std::string> specific_values;  
    std::vector<std::string> optional_tag_defs;
    std::vector<PEFFCustomKeyDef> custom_key_defs;  
    bool has_annotation_identifiers{false};    
    bool is_proteoform_db{false};              
 
    std::map<std::string, std::string> unrecognized_keys;  
 
    PEFFDatabaseMetadata() = default;
 
    bool operator==(const PEFFDatabaseMetadata& rhs) const
    {
      return version == rhs.version &&
             db_name == rhs.db_name &&
             prefix == rhs.prefix &&
             db_description == rhs.db_description &&
             is_decoy == rhs.is_decoy &&
             db_sources == rhs.db_sources &&
             db_version == rhs.db_version &&
             number_of_entries == rhs.number_of_entries &&
             sequence_type == rhs.sequence_type &&
             general_comments == rhs.general_comments &&
             conversion == rhs.conversion &&
             specific_keys == rhs.specific_keys &&
             specific_values == rhs.specific_values &&
             optional_tag_defs == rhs.optional_tag_defs &&
             custom_key_defs == rhs.custom_key_defs &&
             has_annotation_identifiers == rhs.has_annotation_identifiers &&
             is_proteoform_db == rhs.is_proteoform_db &&
             unrecognized_keys == rhs.unrecognized_keys;
    }
  };
 
  class OPENMS_DLLAPI PEFFFile : public ProgressLogger
  {
  public:
    PEFFFile() = default;
 
    ~PEFFFile() override = default;
 
    void load(const std::string& filename,
              std::vector<PEFFEntry>& entries,
              std::vector<PEFFDatabaseMetadata>& headers) const;
 
    void store(const std::string& filename,
               const std::vector<PEFFEntry>& entries,
               const PEFFDatabaseMetadata& header) const;
 
    void store(const std::string& filename,
               const std::vector<PEFFEntry>& entries,
               const std::vector<PEFFDatabaseMetadata>& headers) const;
 
    void readStart(const std::string& filename);
 
    bool readNext(PEFFEntry& entry);
 
    const std::vector<PEFFDatabaseMetadata>& getHeaders() const;
 
    bool atEnd() const;
 
    void writeStart(const std::string& filename, const PEFFDatabaseMetadata& header);
 
    void writeStart(const std::string& filename, const std::vector<PEFFDatabaseMetadata>& headers);
 
    void writeNext(const PEFFEntry& entry);
 
    void writeEnd();
 
    static bool isPEFFFile(const std::string& filename);
 
    static std::string toProForma(const PEFFEntry& entry);
 
  protected:
    void parseHeaderLine_(const std::string& line, PEFFDatabaseMetadata& header, bool& new_db);
 
    void parseAnnotations_(const std::string& description, PEFFEntry& entry);
 
    PEFFModification parseModification_(const std::string& tuple);
 
    PEFFVariantSimple parseVariantSimple_(const std::string& tuple);
 
    PEFFVariantComplex parseVariantComplex_(const std::string& tuple);
 
    PEFFProcessedRegion parseProcessedRegion_(const std::string& tuple);
 
    PEFFDisulfideBond parseDisulfideBond_(const std::string& tuple);
 
    std::vector<std::string> parseParenList_(const std::string& value);
 
    std::string formatHeader_(const PEFFDatabaseMetadata& header) const;
 
    std::string formatHeader_(const std::vector<PEFFDatabaseMetadata>& headers) const;
 
    std::string formatEntry_(const PEFFEntry& entry) const;
 
 
    bool readEntry_(std::string& id, std::string& description, std::string& seq);
 
    std::fstream infile_;                           
    std::ofstream outfile_;                         
    std::vector<PEFFDatabaseMetadata> headers_;     
    Size entries_read_{0};                          
    std::streampos fileSize_{0};                    
    std::string seq_;                               
    std::string id_;                                
    std::string description_;                       
  };
 
} // namespace OpenMS