PDBFile.h

Go to the documentation of this file.

// -*- Mode: C++; tab-width: 2; -*-
// vi: set ts=2:
//

#ifndef BALL_FORMAT_PDBFILE_H
#define BALL_FORMAT_PDBFILE_H

#ifndef BALL_CONCEPT_PROPERTY_H
# include <BALL/CONCEPT/property.h>
#endif

#ifndef BALL_FORMAT_GENERICMOLFILE_H
# include <BALL/FORMAT/genericMolFile.h>
#endif

#ifndef BALL_DATATYPE_OPTIONS_H
# include <BALL/DATATYPE/options.h>
#endif

#ifndef BALL_DATATYPE_QUADRUPLE_H
# include <BALL/DATATYPE/quadruple.h>
#endif

#ifndef BALL_FORMAT_PDBDEFS_H
# include <BALL/FORMAT/PDBdefs.h>
#endif

#ifndef BALL_FORMAT_PDBINFO_H
# include <BALL/FORMAT/PDBInfo.h>
#endif

#ifndef BALL_KERNEL_PDBAtom_H
# include <BALL/KERNEL/PDBAtom.h>
#endif

#ifndef BALL_KERNEL_SYSTEM_H
# include <BALL/KERNEL/system.h>
#endif

#ifndef BALL_KERNEL_RESIDUE_H
# include <BALL/KERNEL/residue.h>
#endif

#ifndef BALL_KERNEL_SECONDARYSTRUCTURE_H
# include <BALL/KERNEL/secondaryStructure.h>
#endif

namespace BALL
{

  class BALL_EXPORT PDBFile
    : public GenericMolFile,
      public PropertyManager
  {
    public:

    struct BALL_EXPORT Option 
    {
      static const char* VERBOSITY;

      static const char* STRICT_LINE_CHECKING;
      
      static const char* CHOOSE_MODEL;

      static const char* STORE_SKIPPED_RECORDS;

      static const char* IGNORE_XPLOR_PSEUDO_ATOMS;

      static const char* PARSE_PARTIAL_CHARGES;

      static const char* WRITE_PDBFORMAT_1996;
    };

    struct BALL_EXPORT Default 
    {
      static const Index VERBOSITY;

      static const bool STRICT_LINE_CHECKING;

      static const Index CHOOSE_MODEL;

      static const bool STORE_SKIPPED_RECORDS;

      static const bool IGNORE_XPLOR_PSEUDO_ATOMS;

      static const bool PARSE_PARTIAL_CHARGES;

      static const bool WRITE_PDBFORMAT_1996;

    };

    Options options;
    PDBInfo info;


    PDBFile();
      
    PDBFile(const String& filename, File::OpenMode open_mode = std::ios::in);

    PDBFile(const Options& new_options);

    virtual ~PDBFile();


    virtual void clear(int state);

    virtual void clear();



    virtual float getVersion() const;

    void open(const String& name, File::OpenMode open_mode=std::ios::in);

    void selectModel(Index index);

    void selectAltLocationIndicator(char c);

    Index getSelectedModel() const;

    void selectAllModels();

    Index getCurrentModel() const;

    char* getRecordString();

    const char* getRecordString() const;

    Index getRecordNumber() const;

    PDB::RecordType getRecordType() const;

    virtual const char* getAtomElementSymbol
      (const PDB::Atom atom_name,
       PDB::Atom element_symbol);

    virtual const char* getAtomName
      (const PDB::Atom atom_name);

    virtual char getAtomRemotenessIndicator
      (const PDB::Atom atom_name);

    virtual short getAtomBranchDesignator
      (const PDB::Atom atom_name);

    Size countRecordFields() const;

    Size countRecord
      (PDB::RecordType record_type,
       bool from_begin_of_file = true);

    Size countRecords
      (bool from_begin_of_file = true);

    bool parseLine(const char* line, Size size, const char* format_string, ...);

    bool readLine(char* line, Size size, bool extract_values);

    bool readFirstRecord(bool read_values = true);

    bool readNextRecord(bool read_values = true);

    bool readRecords();

    virtual bool readUnknownRecord(const char* line);

    virtual bool readInvalidRecord(const char* line);

    bool skipCurrentRecord();

    virtual bool interpretRecord(const PDB::RecordANISOU& record);
    virtual bool fillRecord(const char* line, Size size, PDB::RecordANISOU& record);
    virtual bool parseRecordANISOU(const char* line, Size size);

    virtual bool interpretRecord(const PDB::RecordATOM& record);
    virtual bool fillRecord(const char* line, Size size, PDB::RecordATOM& record);
    virtual bool parseRecordATOM(const char* line, Size size);

    virtual bool interpretRecord(const PDB::RecordAUTHOR& record);
    virtual bool fillRecord(const char* line, Size size, PDB::RecordAUTHOR& record);
    virtual bool parseRecordAUTHOR(const char* line, Size size);

    virtual bool interpretRecord(const PDB::RecordCAVEAT& record);
    virtual bool fillRecord(const char* line, Size size, PDB::RecordCAVEAT& record);
    virtual bool parseRecordCAVEAT(const char* line, Size size);

    virtual bool interpretRecord(const PDB::RecordCISPEP& record);
    virtual bool fillRecord(const char* line, Size size, PDB::RecordCISPEP& record);
    virtual bool parseRecordCISPEP(const char* line, Size size);

    virtual bool interpretRecord(const PDB::RecordCOMPND& record);
    virtual bool fillRecord(const char* line, Size size, PDB::RecordCOMPND& record);
    virtual bool parseRecordCOMPND(const char* line, Size size);

    virtual bool interpretRecord(const PDB::RecordCONECT& record);
    virtual bool fillRecord(const char* line, Size size, PDB::RecordCONECT& record);
    virtual bool parseRecordCONECT(const char* line, Size size);

    virtual bool interpretRecord(const PDB::RecordCRYST1& record);
    virtual bool fillRecord(const char* line, Size size, PDB::RecordCRYST1& record);
    virtual bool parseRecordCRYST1(const char* line, Size size);

    virtual bool interpretRecord(const PDB::RecordDBREF& record);
    virtual bool fillRecord(const char* line, Size size, PDB::RecordDBREF& record);
    virtual bool parseRecordDBREF(const char* line, Size size);

    virtual bool interpretRecord(const PDB::RecordEND& record);
    virtual bool fillRecord(const char* line, Size size, PDB::RecordEND& record);
    virtual bool parseRecordEND(const char* line, Size size);

    virtual bool interpretRecord(const PDB::RecordENDMDL& record);
    virtual bool fillRecord(const char* line, Size size, PDB::RecordENDMDL& record);
    virtual bool parseRecordENDMDL(const char* line, Size size);

    virtual bool interpretRecord(const PDB::RecordEXPDTA& record);
    virtual bool fillRecord(const char* line, Size size, PDB::RecordEXPDTA& record);
    virtual bool parseRecordEXPDTA(const char* line, Size size);

    virtual bool interpretRecord(const PDB::RecordFORMUL& record);
    virtual bool fillRecord(const char* line, Size size, PDB::RecordFORMUL& record);
    virtual bool parseRecordFORMUL(const char* line, Size size);

    virtual bool interpretRecord(const PDB::RecordFTNOTE& record);
    virtual bool fillRecord(const char* line, Size size, PDB::RecordFTNOTE& record);
    virtual bool parseRecordFTNOTE(const char* line, Size size);

    virtual bool interpretRecord(const PDB::RecordHEADER& record);
    virtual bool fillRecord(const char* line, Size size, PDB::RecordHEADER& record);
    virtual bool parseRecordHEADER(const char* line, Size size);

    virtual bool interpretRecord(const PDB::RecordHELIX& record);
    virtual bool fillRecord(const char* line, Size size, PDB::RecordHELIX& record);
    virtual bool parseRecordHELIX(const char* line, Size size);

    virtual bool interpretRecord(const PDB::RecordHET& record);
    virtual bool fillRecord(const char* line, Size size, PDB::RecordHET& record);
    virtual bool parseRecordHET(const char* line, Size size);

    virtual bool interpretRecord(const PDB::RecordHETATM& record);
    virtual bool fillRecord(const char* line, Size size, PDB::RecordHETATM& record);
    virtual bool parseRecordHETATM(const char* line, Size size);

    virtual bool interpretRecord(const PDB::RecordHETNAM& record);
    virtual bool fillRecord(const char* line, Size size, PDB::RecordHETNAM& record);
    virtual bool parseRecordHETNAM(const char* line, Size size);

    virtual bool interpretRecord(const PDB::RecordHETSYN& record);
    virtual bool fillRecord(const char* line, Size size, PDB::RecordHETSYN& record);
    virtual bool parseRecordHETSYN(const char* line, Size size);

    virtual bool interpretRecord(const PDB::RecordHYDBND& record);
    virtual bool fillRecord(const char* line, Size size, PDB::RecordHYDBND& record);
    virtual bool parseRecordHYDBND(const char* line, Size size);

    virtual bool interpretRecord(const PDB::RecordJRNL& record);
    virtual bool fillRecord(const char* line, Size size, PDB::RecordJRNL& record);
    virtual bool parseRecordJRNL(const char* line, Size size);

    virtual bool interpretRecord(const PDB::RecordKEYWDS& record);
    virtual bool fillRecord(const char* line, Size size, PDB::RecordKEYWDS& record);
    virtual bool parseRecordKEYWDS(const char* line, Size size);

    virtual bool interpretRecord(const PDB::RecordLINK& record);
    virtual bool fillRecord(const char* line, Size size, PDB::RecordLINK& record);
    virtual bool parseRecordLINK(const char* line, Size size);

    virtual bool interpretRecord(const PDB::RecordMASTER& record);
    virtual bool fillRecord(const char* line, Size size, PDB::RecordMASTER& record);
    virtual bool parseRecordMASTER(const char* line, Size size);

    virtual bool interpretRecord(const PDB::RecordMODEL& record);
    virtual bool fillRecord(const char* line, Size size, PDB::RecordMODEL& record);
    virtual bool parseRecordMODEL(const char* line, Size size);

    virtual bool interpretRecord(const PDB::RecordMODRES& record);
    virtual bool fillRecord(const char* line, Size size, PDB::RecordMODRES& record);
    virtual bool parseRecordMODRES(const char* line, Size size);

    virtual bool interpretRecord(const PDB::RecordMTRIX1& record);
    virtual bool fillRecord(const char* line, Size size, PDB::RecordMTRIX1& record);
    virtual bool parseRecordMTRIX1(const char* line, Size size);

    virtual bool interpretRecord(const PDB::RecordMTRIX2& record);
    virtual bool fillRecord(const char* line, Size size, PDB::RecordMTRIX2& record);
    virtual bool parseRecordMTRIX2(const char* line, Size size);

    virtual bool interpretRecord(const PDB::RecordMTRIX3& record);
    virtual bool fillRecord(const char* line, Size size, PDB::RecordMTRIX3& record);
    virtual bool parseRecordMTRIX3(const char* line, Size size);

    virtual bool interpretRecord(const PDB::RecordOBSLTE& record);
    virtual bool fillRecord(const char* line, Size size, PDB::RecordOBSLTE& record);
    virtual bool parseRecordOBSLTE(const char* line, Size size);

    virtual bool interpretRecord(const PDB::RecordORIGX1& record);
    virtual bool fillRecord(const char* line, Size size, PDB::RecordORIGX1& record);
    virtual bool parseRecordORIGX1(const char* line, Size size);

    virtual bool interpretRecord(const PDB::RecordORIGX2& record);
    virtual bool fillRecord(const char* line, Size size, PDB::RecordORIGX2& record);
    virtual bool parseRecordORIGX2(const char* line, Size size);

    virtual bool interpretRecord(const PDB::RecordORIGX3& record);
    virtual bool fillRecord(const char* line, Size size, PDB::RecordORIGX3& record);
    virtual bool parseRecordORIGX3(const char* line, Size size);

    virtual bool interpretRecord(const PDB::RecordREMARK& record);
    virtual bool fillRecord(const char* line, Size size, PDB::RecordREMARK& record);
    virtual bool parseRecordREMARK(const char* line, Size size);

    virtual bool interpretRecord(const PDB::RecordREVDAT& record);
    virtual bool fillRecord(const char* line, Size size, PDB::RecordREVDAT& record);
    virtual bool parseRecordREVDAT(const char* line, Size size);

    virtual bool interpretRecord(const PDB::RecordSCALE1& record);
    virtual bool fillRecord(const char* line, Size size, PDB::RecordSCALE1& record);
    virtual bool parseRecordSCALE1(const char* line, Size size);

    virtual bool interpretRecord(const PDB::RecordSCALE2& record);
    virtual bool fillRecord(const char* line, Size size, PDB::RecordSCALE2& record);
    virtual bool parseRecordSCALE2(const char* line, Size size);

    virtual bool interpretRecord(const PDB::RecordSCALE3& record);
    virtual bool fillRecord(const char* line, Size size, PDB::RecordSCALE3& record);
    virtual bool parseRecordSCALE3(const char* line, Size size);

    virtual bool interpretRecord(const PDB::RecordSEQADV& record);
    virtual bool fillRecord(const char* line, Size size, PDB::RecordSEQADV& record);
    virtual bool parseRecordSEQADV(const char* line, Size size);

    virtual bool interpretRecord(const PDB::RecordSEQRES& record);
    virtual bool fillRecord(const char* line, Size size, PDB::RecordSEQRES& record);
    virtual bool parseRecordSEQRES(const char* line, Size size);

    virtual bool interpretRecord(const PDB::RecordSHEET& record);
    virtual bool fillRecord(const char* line, Size size, PDB::RecordSHEET& record);
    virtual bool parseRecordSHEET(const char* line, Size size);

    virtual bool interpretRecord(const PDB::RecordSIGATM& record);
    virtual bool fillRecord(const char* line, Size size, PDB::RecordSIGATM& record);
    virtual bool parseRecordSIGATM(const char* line, Size size);

    virtual bool interpretRecord(const PDB::RecordSIGUIJ& record);
    virtual bool fillRecord(const char* line, Size size, PDB::RecordSIGUIJ& record);
    virtual bool parseRecordSIGUIJ(const char* line, Size size);

    virtual bool interpretRecord(const PDB::RecordSITE& record);
    virtual bool fillRecord(const char* line, Size size, PDB::RecordSITE& record);
    virtual bool parseRecordSITE(const char* line, Size size);

    virtual bool interpretRecord(const PDB::RecordSLTBRG& record);
    virtual bool fillRecord(const char* line, Size size, PDB::RecordSLTBRG& record);
    virtual bool parseRecordSLTBRG(const char* line, Size size);

    virtual bool interpretRecord(const PDB::RecordSOURCE& record);
    virtual bool fillRecord(const char* line, Size size, PDB::RecordSOURCE& record);
    virtual bool parseRecordSOURCE(const char* line, Size size);

    virtual bool interpretRecord(const PDB::RecordSPRSDE& record);
    virtual bool fillRecord(const char* line, Size size, PDB::RecordSPRSDE& record);
    virtual bool parseRecordSPRSDE(const char* line, Size size);

    virtual bool interpretRecord(const PDB::RecordSSBOND& record);
    virtual bool fillRecord(const char* line, Size size, PDB::RecordSSBOND& record);
    virtual bool parseRecordSSBOND(const char* line, Size size);

    virtual bool interpretRecord(const PDB::RecordTER& record);
    virtual bool fillRecord(const char* line, Size size, PDB::RecordTER& record);
    virtual bool parseRecordTER(const char* line, Size size);

    virtual bool interpretRecord(const PDB::RecordTITLE& record);
    virtual bool fillRecord(const char* line, Size size, PDB::RecordTITLE& record);
    virtual bool parseRecordTITLE(const char* line, Size size);

    virtual bool interpretRecord(const PDB::RecordTURN& record);
    virtual bool fillRecord(const char* line, Size size, PDB::RecordTURN& record);
    virtual bool parseRecordTURN(const char* line, Size size);

    virtual bool interpretRecord(const PDB::RecordTVECT& record);
    virtual bool fillRecord(const char* line, Size size, PDB::RecordTVECT& record);
    virtual bool parseRecordTVECT(const char* line, Size size);

    virtual bool hasFormat();

    typedef HashMap<PDB::Integer, PDBAtom*> PDBAtomMap;
    typedef Quadruple<String, PDB::Character, PDB::Integer, PDB::AChar> ResidueQuadruple;
    typedef HashMap<ResidueQuadruple, Residue*> ResidueMap;
    typedef std::list<ResidueQuadruple> QuadrupleList;
    typedef std::list<SecondaryStructure*> SecStructList;
    


    PDBFile& operator >> (Protein& protein);

    PDBFile& operator >> (Molecule& molecule);

    PDBFile& operator >> (System& system);

    PDBFile& operator << (const Protein& protein);

    PDBFile& operator << (const System& system);

    PDBFile& operator << (const Molecule& molecule);

    bool read(Protein& protein);

    bool read(Molecule& protein);

    bool read(System& system);

    Molecule* read();

    bool write(const Protein& protein);

    bool write(const Molecule& molecule);

    bool write(const System& system);

    bool write(const System& system, const PDBInfo& info);

    protected:

    //_
    PDBFile(const File& pdbf);

    //_
    PDBFile& operator = (const PDBFile& pdbf);

    /*_ A helper function for initializing certain data structures. Used by
        constructors.
    */
    void init_() ;

    void postprocessSSBonds_();
    void postprocessHelices_();
    void postprocessSheetsTurns_(QuadrupleList& sectruct_list, SecStructList& new_secstruct_list);
    void postprocessRandomCoils_();

    

    // Method related to the writing of PDB files

    // 
    void write_(const AtomContainer& ac, const PDBInfo& info = PDBInfo());

    void writeRecord_(PDB::RecordType record, ...);
    void writeCONECTRecords_(PDB::Structure::ConectAtomList& cl);

    void writeRawRecord_(const char* format, const char* tag, ...);
    
    void addAllRecords_(const PDBInfo& info, PDB::RecordType type);
    
    void writeRecord_(const PDB::RecordSEQRES& seqres);
    void writeRecord_(const PDB::RecordHELIX& helix);
    void writeRecord_(const PDB::RecordSHEET& helix);
    void writeRecord_(const PDB::RecordTURN& helix);
    void writeRecord_(const PDB::RecordSSBOND& helix);
    void writeRecord_(const PDB::RecordCONECT& helix);
    void writeRecord_(const PDB::RecordCRYST1& cryst1);
    void writeRecord_(const PDB::RecordMTRIX1& mtrix1);
    void writeRecord_(const PDB::RecordMTRIX2& mtrix2);
    void writeRecord_(const PDB::RecordMTRIX3& mtrix3);
    
    void writeAtom_(const PDB::Structure::AtomEntry& atom, PDB::AdditionalAtomInfo& cr, bool hetatm = false);
    
    void writeTitleSection_(const PDB::Structure& structure, const PDBInfo& info);
    void writePrimaryStructureSection_(const PDB::Structure& structure, const PDBInfo& info);
    void writeHeterogenSection_(const PDB::Structure& structure, const PDBInfo& info);
    void writeSecondaryStructureSection_(const PDB::Structure& structure, const PDBInfo& info);
    void writeConnectivityAnnotationSection_(const PDB::Structure& structure, const PDBInfo& info);
    void writeMiscellaneousFeaturesSection_(const PDB::Structure& structure, const PDBInfo& info);
    void writeCrystallographicSection_(const PDB::Structure& structure, const PDBInfo& info);
    void writeCoordinateSection_(const PDB::Structure& structure, const PDBInfo& info);
    void writeConnectivitySection_(const PDB::Structure& structure, const PDBInfo& info);
    void writeBookKeepingSection_(const PDB::Structure& structure, const PDBInfo& info);

    void writeSEQRESSection_(const std::vector<std::pair<char, String> >& chain_residues);
    void writeHELIXSection_(const PDB::Structure& structure);
    void writeSHEETSection_(const PDB::Structure& structure);
    void writeTURNSection_(const PDB::Structure& structure);
    void writeSSBONDSection_(const PDB::Structure& structure);
    void writeHYDBNDSection_(const PDB::Structure& structure);
    void writeSLTBRGSection_(const PDB::Structure& structure);
    void writeCRYST1Section_(const PDB::Structure& structure);
    void writeMTRIXnSection_(const PDB::Structure& structure);

    static void extractStructure_(const AtomContainer& ac, PDB::Structure& structure);
    
    static bool isHeteroAtom_(const Atom& atom);
    
    static void updateAdditionalAtomInfo_(const PDB::Structure::AtomEntry& atom, PDB::AdditionalAtomInfo& cr);
      

    char line_buffer_[PDB::SIZE_OF_PDB_LINE_BUFFER];

    String residue_name_;
    Index residue_sequence_number_;
    Index current_model_;
    Index current_record_;
    Size record_fields_;
    PDB::RecordType current_record_type_;
    PDB::RecordTypeFormat compare_record_type_format_; 

    PDBAtomMap PDB_atom_map_;
    ResidueMap residue_map_;
    QuadrupleList ssbond_list_;
    QuadrupleList helix_list_;
    QuadrupleList sheet_list_;
    QuadrupleList turn_list_;

    SecStructList new_helix_secstruc_list_;
    SecStructList new_sheet_secstruc_list_;
    SecStructList new_turn_secstruc_list_;

    char alternate_location_indicator_;
    PDB::AChar insertion_code_;
    PDB::Character chain_ID_;
    PDB::Integer sequence_number_;
    PDB::AChar code_;
    Protein* current_protein_;
    const Protein* current_const_protein_;
    Chain* current_chain_;
    const Chain* current_const_chain_;
    Residue*  current_residue_;
    const Residue* current_const_residue_;
    PDBAtom* current_PDB_atom_;
    const Atom* current_const_atom_;
    String name_;
    HashMap<const Atom*, Position> atom_map_;
    
    PDB::BookKeeping book_keeping_;

    int verbosity_;

    bool strict_line_checking_;

    Index selected_model_;

    bool store_skipped_records_;

    bool ignore_xplor_pseudo_atoms_;
    
    bool parse_partial_charges_;

    bool write_pdbformat_1996_;

    bool read_done_;
  };





  inline
  BALL_EXPORT HashIndex Hash(const PDBFile::ResidueQuadruple& quadruple)
    
  {
    return (Index)quadruple.third;
  }

  inline
  BALL_EXPORT std::ostream& operator << (std::ostream& s, const Quadruple<String,PDB::Character,PDB::Integer,PDB::AChar>& /* q */)
  {
    return s;
  }



# ifndef BALL_NO_INLINE_FUNCTIONS
#   include <BALL/FORMAT/PDBFile.iC>
# endif

} // namespace BALL

#endif // BALL_FORMAT_PDBFILE_H