mmcif_reader.hh

Go to the documentation of this file.

//------------------------------------------------------------------------------
// This file is part of the OpenStructure project <www.openstructure.org>
//
// Copyright (C) 2008-2020 by the OpenStructure authors
//
// This library is free software; you can redistribute it and/or modify it under
// the terms of the GNU Lesser General Public License as published by the Free
// Software Foundation; either version 3.0 of the License, or (at your option)
// any later version.
// This library is distributed in the hope that it will be useful, but WITHOUT
// ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
// FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more
// details.
//
// You should have received a copy of the GNU Lesser General Public License
// along with this library; if not, write to the Free Software Foundation, Inc.,
// 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
//------------------------------------------------------------------------------
#ifndef OST_MMCIF_READER_HH
#define OST_MMCIF_READER_HH

#include <map>

#include <ost/geom/geom.hh>
#include <ost/seq/sequence_list.hh>
#include <ost/mol/residue_handle.hh>
#include <ost/mol/chain_type.hh>
#include <ost/conop/compound_lib.hh>
#include <ost/io/mol/io_profile.hh>
#include <ost/io/io_exception.hh>
#include <ost/io/mol/star_parser.hh>
#include <ost/io/mol/mmcif_info.hh>

namespace ost { namespace io {

class DLLEXPORT_OST_IO MMCifReader : public StarParser  {
public:

  MMCifReader(std::istream& stream, mol::EntityHandle& ent_handle,
              const IOProfile& profile);

  MMCifReader(const String& filename, mol::EntityHandle& ent_handle,
              const IOProfile& profile);

  void Init();

  void ClearState();

  void SetRestrictChains(const String& restrict_chains);

  void SetReadCanonicalSeqRes(bool flag)
  {
    seqres_can_ = flag;
  }

  const String& GetRestrictChains() const
  {
    return restrict_chains_;
  }

  void SetAuthChainID(bool id)
  {
    auth_chain_id_ = id;
  }

  virtual bool OnBeginData(const StringRef& data_name);

  virtual bool OnBeginLoop(const StarLoopDesc& header); // tested

  virtual void OnDataRow(const StarLoopDesc& header, 
                         const std::vector<StringRef>& columns);

  virtual void OnEndData();

  seq::SequenceList GetSeqRes() const {
    return seqres_;
  }

  void SetReadSeqRes(bool flag)
  {
    read_seqres_ = flag;
  }

  bool GetReadSeqRes() const
  {
    return read_seqres_;
  }

  const MMCifInfo& GetInfo() { return info_; }

protected:
  void TryStoreIdx(const int mapping,
                   const String& item,
                   const StarLoopDesc& header)
  {
    indices_[mapping] = header.GetIndex(item);
    
    if (indices_[mapping] == -1) {
      throw IOException(this->FormatDiagnostic(STAR_DIAG_ERROR,
                                               "No item '" + item +
                                               "' found in '" +
                                               header.GetCategory()+
                                               "' header",
                                               this->GetCurrentLinenum()));
     }
  } // tested

  bool ParseAtomIdent(const std::vector<StringRef>& columns,
                      String& auth_chain_name,
                      String& cif_chain_name,
                      StringRef& res_name,
                      mol::ResNum& resnum,
                      bool& valid_res_num,
                      StringRef& atom_name,
                      char& alt_loc);

  void ParseAndAddAtom(const std::vector<StringRef>& columns);

  void ParseEntity(const std::vector<StringRef>& columns);

  void ParseEntityPoly(const std::vector<StringRef>& columns);

  void ParseCitation(const std::vector<StringRef>& columns);

  const MMCifInfoStructRefs& GetStructRefs() const { return struct_refs_; }
  String ConvertSEQRES(const String& seqres, conop::CompoundLibBasePtr compound_lib);
  void ParseCitationAuthor(const std::vector<StringRef>& columns);
  
  void ParseStructRef(const std::vector<StringRef>& columns);
  
  void ParseStructRefSeq(const std::vector<StringRef>& columns);

  void ParseStructRefSeqDif(const std::vector<StringRef>& columns);
  void ParseExptl(const std::vector<StringRef>& columns);

  void ParseRefine(const std::vector<StringRef>& columns);

  void ParsePdbxStructAssembly(const std::vector<StringRef>& columns);

  void ParsePdbxStructAssemblyGen(const std::vector<StringRef>& columns);

  std::vector<std::vector<String> > UnPackOperExperession(StringRef expression);

  void StoreExpression(const char* l, const char* s,
                       bool& is_range, int lborder,
                       std::vector<String>& single_block);

  void StoreRange(const char*& l, const char* s, bool& is_range, int& lborder,
                  std::vector<String>& single_block);

  void ParsePdbxStructOperList(const std::vector<StringRef>& columns);

  void ParseDatabasePDBRev(const std::vector<StringRef>& columns);

  void ParsePdbxAuditRevisionHistory(const std::vector<StringRef>& columns);

  void ParsePdbxAuditRevisionDetails(const std::vector<StringRef>& columns);

  void ParsePdbxDatabaseStatus(const std::vector<StringRef>& columns);

  void ParseStruct(const std::vector<StringRef>& columns);

  void ParseStructConf(const std::vector<StringRef>& columns);

  void ParseStructSheetRange(const std::vector<StringRef>& columns);

  void ParsePdbxDatabasePdbObsSpr(const std::vector<StringRef>& columns);

  void ParsePdbxEntityBranch(const std::vector<StringRef>& columns);

  void ParsePdbxEntityBranchLink(const std::vector<StringRef>& columns);

  void ParseEntityPolySeq(const std::vector<StringRef>& columns);

  void ParseEm3DReconstruction(const std::vector<StringRef>& columns);

  typedef enum {
    MMCIF_HELIX,
    MMCIF_STRAND,
    MMCIF_TURN,
    MMCIF_COIL
  } MMCifSecStructElement;

  MMCifSecStructElement DetermineSecStructType(const StringRef& type) const;

  void AssignSecStructure(mol::EntityHandle ent);

private:
  typedef enum {
    MAX_ITEMS_IN_ROW=19 
  } MMCifMagicNos;

  typedef enum {
    AUTH_ASYM_ID,      
    AS_ID,             
    LABEL_ALT_ID,      
    LABEL_ASYM_ID,     
    LABEL_ATOM_ID,
    LABEL_COMP_ID,
    LABEL_ENTITY_ID,   
    LABEL_SEQ_ID,      
    AUTH_SEQ_ID,       
    TYPE_SYMBOL,       
    CARTN_X,           
    CARTN_Y,           
    CARTN_Z,           
    OCCUPANCY,
    B_ISO_OR_EQUIV,
    PDBX_PDB_INS_CODE,
    GROUP_PDB,         
    PDBX_PDB_MODEL_NUM,
    FORMAL_CHARGE
  } AtomSiteItems;

  typedef enum {
    E_ID,              
    E_TYPE,            
    PDBX_DESCRIPTION   
  } EntityItems;

  typedef enum {
    ENTITY_ID,                    
    EP_TYPE,                      
    PDBX_SEQ_ONE_LETTER_CODE,     
    PDBX_SEQ_ONE_LETTER_CODE_CAN  
  } EntityPolyItems;

  typedef enum {
    CITATION_ID,                  
    ABSTRACT_ID_CAS,              
    BOOK_ID_ISBN,                 
    BOOK_TITLE,                   
    BOOK_PUBLISHER,               
    BOOK_PUBLISHER_CITY,          
    JOURNAL_ABBREV,               
    JOURNAL_VOLUME,               
    PAGE_FIRST,                   
    PAGE_LAST,                    
    PDBX_DATABASE_ID_DOI,         
    PDBX_DATABASE_ID_PUBMED,      
    YEAR,                         
    TITLE                         
  } CitationItems;

  typedef enum {
    AUTHOR_CITATION_ID,           
    AUTHOR_NAME,                  
    ORDINAL                       
  } CitationAuthorItems;

  typedef enum {
    EXPTL_ENTRY_ID,               
    METHOD                        
  } ExptlItems;

  typedef enum {
    REFINE_ENTRY_ID,              
    LS_D_RES_HIGH,                
    LS_D_RES_LOW,
    LS_R_FACTOR_R_WORK,           
    LS_R_FACTOR_R_FREE            
  } RefineItems;

  typedef enum {
    PSA_DETAILS,                  
    PSA_ID,                       
    METHOD_DETAILS                
  } PdbxStructAssemblyItems;

  // \enum items of the struct_ref category
  typedef enum {
    SR_ENTITY_ID,
    SR_ID,
    SR_DB_CODE,
    SR_DB_NAME,
    SR_DB_ACCESS
  } StructRefItems;
  
  typedef enum {
    SRS_ALIGN_ID,
    SRS_STRUCT_REF_ID,
    SRS_PDBX_STRAND_ID,
    SRS_DB_ALIGN_BEG,
    SRS_DB_ALIGN_END,
    SRS_ENT_ALIGN_BEG,
    SRS_ENT_ALIGN_END
  } StructRefSeqItems;
  
  typedef enum {
    SRSD_ALIGN_ID,
    SRSD_SEQ_RNUM,
    SRSD_DB_RNUM,
    SRSD_DETAILS
  } StructRefSeqDifItems;

  typedef enum {
    ASSEMBLY_ID,                  
    ASYM_ID_LIST,                 
    OPER_EXPRESSION               
  } PdbxStructAssemblyGenItems;

  typedef enum {
    PSOL_ID,    
    PSOL_TYPE,  
    VECTOR_1,   
    VECTOR_2,   
    VECTOR_3,   
    MATRIX_1_1, 
    MATRIX_1_2, 
    MATRIX_1_3, 
    MATRIX_2_1, 
    MATRIX_2_2, 
    MATRIX_2_3, 
    MATRIX_3_1, 
    MATRIX_3_2, 
    MATRIX_3_3  
  } PdbxStructOperListItems;

  typedef enum {
     STRUCT_ENTRY_ID,     
     PDBX_CASP_FLAG,      
     PDBX_DESCRIPTOR,     
     PDBX_FORMULA_WEIGHT, 
     PDBX_FORMULA_WEIGHT_METHOD, 
     PDBX_MODEL_DETAILS,  
     PDBX_MODEL_TYPE_DETAILS, 
     STRUCT_TITLE         
  } StructItems;

  typedef enum {
    SC_BEG_AUTH_ASYM_ID,  
    SC_BEG_LABEL_ASYM_ID, 
    SC_BEG_LABEL_COMP_ID, 
    SC_BEG_LABEL_SEQ_ID,  
    SC_CONF_TYPE_ID,      
    SC_END_AUTH_ASYM_ID,  
    SC_END_LABEL_ASYM_ID, 
    SC_END_LABEL_COMP_ID, 
    SC_END_LABEL_SEQ_ID,  
    SC_ID,                
  } StructConfItems;

  typedef enum {
    SSR_BEG_LABEL_ASYM_ID,     
    SSR_BEG_LABEL_COMP_ID,     
    SSR_BEG_LABEL_SEQ_ID,    
    SSR_END_LABEL_ASYM_ID,     
    SSR_END_LABEL_COMP_ID,     
    SSR_END_LABEL_SEQ_ID,      
    SSR_SHEET_ID,              
    SSR_ID,                    
    SSR_BEG_AUTH_ASYM_ID,      
    SSR_END_AUTH_ASYM_ID,      
    } StructSheetRangeItems;

  typedef enum {
    DATE,           
    PDPOS_ID,       
    PDB_ID,         
    REPLACE_PDB_ID, 
  } PdbxDatabasePDBObsSpr;

  typedef enum {
    DPI_NUM,           
    DPI_DATE,          
    DPI_DATE_ORIGINAL, 
    DPI_STATUS,        
  } DatabasePDBRevItems;

  typedef enum {
    PARH_ORDINAL,         
    PARH_REVISION_DATE,   
    PARH_MAJOR,           
    PARH_MINOR,           
  } PdbxAuditRevisionHistoryItems;

  typedef enum {
    PARD_REVISION_ORDINAL, 
    PARD_TYPE,             
  } PdbxAuditRevisionDetailsItems;

  typedef enum {
    PDS_RECVD_INITIAL_DEPOSITION_DATE, 
  } PdbxDatabaseStatusItems;

  typedef enum {
    BR_ENTITY_ID,  
    BR_ENTITY_TYPE 
  } EntityBranchItems;

  typedef enum {
    BL_ENTITY_ID,                
    BL_ATOM_ID_1,                
    BL_ATOM_ID_2,                
    BL_COMP_ID_1,                
    BL_COMP_ID_2,                
    BL_ENTITY_BRANCH_LIST_NUM_1, 
    BL_ENTITY_BRANCH_LIST_NUM_2, 
    BL_ATOM_STEREO_CONFIG_1,     
    BL_ATOM_STEREO_CONFIG_2,     
    BL_VALUE_ORDER               
  } EntityBranchLinkItems;

  typedef enum {
    EPS_ENTITY_ID,
    EPS_MON_ID,
    EPS_NUM,
    EPS_HETERO
  } EntityPolySeqItems;

  typedef enum {
    EM_RESOLUTION
  } Em3DReconstructionItems;

  typedef enum {
    ATOM_SITE,
    ENTITY,
    ENTITY_POLY,
    CITATION,
    CITATION_AUTHOR,
    EXPTL,
    REFINE,
    PDBX_STRUCT_ASSEMBLY,
    PDBX_STRUCT_ASSEMBLY_GEN,
    PDBX_STRUCT_OPER_LIST,
    STRUCT,
    STRUCT_CONF,
    STRUCT_SHEET_RANGE,
    PDBX_DATABASE_PDB_OBS_SPR,
    STRUCT_REF,
    STRUCT_REF_SEQ,
    STRUCT_REF_SEQ_DIF,
    DATABASE_PDB_REV,
    PDBX_AUDIT_REVISION_HISTORY,
    PDBX_AUDIT_REVISION_DETAILS,
    PDBX_DATABASE_STATUS,
    PDBX_ENTITY_BRANCH,
    PDBX_ENTITY_BRANCH_LINK,
    ENTITY_POLY_SEQ,
    EM_3D_RECONSTRUCTION,
    DONT_KNOW
  } MMCifCategory;

  MMCifEntityDescMap::iterator GetEntityDescMapIterator(const String& entity_id);

  typedef struct {
    String biounit_id;                              
    std::vector<String> chains;                     
    std::vector<std::vector<String> > operations;   
  } MMCifBioUAssembly;
  typedef std::vector<MMCifBioUAssembly> MMCifBioUAssemblyVector;

  typedef std::map<String, std::pair<std::vector<int>, std::vector<String> > >
    MMCifCitationAuthorMap;

  typedef struct {
    mol::ResNum start;
    mol::ResNum end;
    String chain_name;
  } MMCifHSEntry;
  typedef std::vector<MMCifHSEntry> MMCifHSVector;

  typedef struct {
    String details;
    String method_details;
  } MMCifPSAEntry;
  typedef std::map<String, MMCifPSAEntry> MMCifPSAMap;

  struct MMCifRevisionDesc {
    // silly GCC note: major() & minor() exist as macros...facepalm
    MMCifRevisionDesc(int _num, const String& _date, int _major, int _minor)
                     : date(_date) {
      num = _num;
      major = _major;
      minor = _minor;
    }
    int num;      
    String date;  
    int major;    
    int minor;    
  };

  typedef struct {
    int res_num_1;    
    String cmp_1;     
    String atm_nm_1;  
    int res_num_2;    
    String cmp_2;     
    String atm_nm_2;  
    unsigned char bond_order; 
  } MMCifPdbxEntityBranchLink;
  typedef std::map<String, std::vector<MMCifPdbxEntityBranchLink> >
    MMCifPdbxEntityBranchLinkMap;

  // members
  MMCifCategory category_;
  int category_counts_[DONT_KNOW+1]; 
  int indices_[MAX_ITEMS_IN_ROW]; 
  const IOProfile& profile_;
  mol::EntityHandle& ent_handle_;
  String restrict_chains_;
  bool auth_chain_id_;       
  bool seqres_can_;          
  mol::ChainHandle curr_chain_;
  mol::ResidueHandle curr_residue_;
  int chain_count_;
  int residue_count_;
  int atom_count_;
  bool warned_name_mismatch_;
  bool warned_rule_based_;
  String subst_res_id_; 
  bool has_model_;      
  int curr_model_;      
  std::vector<std::pair<mol::ChainHandle, String> > chain_id_pairs_;
  MMCifEntityDescMap entity_desc_map_; 
  seq::SequenceList seqres_;
  bool read_seqres_;
  MMCifInfo info_;      
  MMCifCitationAuthorMap authors_map_;
  MMCifBioUAssemblyVector bu_assemblies_;
  MMCifPSAMap bu_origin_map_; 
  MMCifHSVector helix_list_; 
  MMCifHSVector strand_list_; 
  MMCifInfoStructRefs struct_refs_;
  // for storing revisions 
  std::vector<MMCifRevisionDesc> revisions_;
  std::map<int, String> revision_types_;
  bool database_PDB_rev_added_;
  // for entity_branch connections
  MMCifPdbxEntityBranchLinkMap entity_branch_link_map_;
  // for storing entity_poly_seq
  std::map<String, std::map<int, String> > entity_poly_seq_map_;
  std::map<String, std::vector<std::pair<int, String> > > entity_poly_seq_h_map_;
};

DLLEXPORT_OST_IO unsigned char MMCifValueOrderToOSTBondOrder(
                                                    const StringRef value_order);

DLLEXPORT_OST_IO String OSTBondOrderToMMCifValueOrder(
                                                 const unsigned char bond_order);
}}

#endif

//  LocalWords:  MMCifEntityDescMap