src/mmdb_utils.h

Go to the documentation of this file.

//  $Id: mmdb_utils.h $
//  =================================================================
//
//   CCP4 Coordinate Library: support of coordinate-related
//   functionality in protein crystallography applications.
//
//   Copyright (C) Eugene Krissinel 2000-2008.
//
//    This library is free software: you can redistribute it and/or
//    modify it under the terms of the GNU Lesser General Public
//    License version 3, modified in accordance with the provisions
//    of the license to address the requirements of UK law.
//
//    You should have received a copy of the modified GNU Lesser
//    General Public License along with this library. If not, copies
//    may be downloaded from http://www.ccp4.ac.uk/ccp4license.php
//
//    This program 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.
//
//  =================================================================
//
//    12.09.13   <--  Date of Last Modification.
//                   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
//  -----------------------------------------------------------------
//
//  **** Module  :   MMDBF_Utils <interface>
//       ~~~~~~~~~
//  **** Project :   MacroMolecular Data Base (MMDB)
//       ~~~~~~~~~
//
//  **** Classes :   mmdb::ContainerClass ( containered class template )
//       ~~~~~~~~~   mmdb::ContString     ( containered string         )
//                   mmdb::ClassContainer ( container of classes       )
//                   mmdb::AtomPath       ( atom path ID               )
//                   mmdb::QuickSort      ( quick sort of integers     )
//
//  **** Functions : Date9to11  ( DD-MMM-YY   -> DD-MMM-YYYY          )
//       ~~~~~~~~~~~ Date11to9  ( DD-MMM-YYYY -> DD-MMM-YY            )
//                   Date9toCIF ( DD-MMM-YY   -> YYYY-MM-DD           )
//                   Date11toCIF( DD-MMM-YYYY -> YYYY-MM-DD           )
//                   DateCIFto9 ( YYYY-MM-DD  -> DD-MMM-YY            )
//                   DateCIFto11( YYYY-MM-DD  -> DD-MMM-YYYY          )
//                   GetInteger ( reads integer from a string         )
//                   GetReal    ( reads real from a string            )
//                   GetIntIns  ( reads integer and insert code       )
//                   PutInteger ( writes integer into a string        )
//                   PutRealF   ( writes real in F-form into a string )
//                   PutIntIns  ( writes integer and insert code      )
//                   CIFGetInteger ( reads and deletes int from CIF   )
//                   CIFGetReal    ( reads and deletes real from CIF  )
//                   CIFGetString  ( reads and deletes string from CIF)
//                   CIFGetInteger1 (reads and del-s int from CIF loop)
//                   CIFGetReal1    (reads and del-s int from CIF loop)
//                   Mat4Inverse    ( inversion of 4x4 matrices       )
//                   GetErrorDescription (ascii line to an Error_XXXXX)
//                   ParseAtomID    ( parses atom ID line             )
//                   ParseResID     ( parses residue ID line          )
//                   ParseAtomPath  ( parses full atom path           )
//
//   (C) E. Krissinel  2000-2013
//
//  =================================================================
//

#ifndef __MMDB_Utils__
#define __MMDB_Utils__

#include "mmdb_io_stream.h"
#include "mmdb_mmcif_.h"
#include "mmdb_defs.h"

namespace mmdb  {

  // ==================  Date functions  ===================

  // converts  DD-MMM-YY  to DD-MMM-YYYY; appends terminating zero
  extern void  Date9to11   ( cpstr Date9, pstr Date11 );

  // converts DD-MMM-YYYY to DD-MMM-YY;  does not append terminating zero
  extern void  Date11to9   ( cpstr Date11, pstr Date9 );

  // converts DD-MMM-YY   to YYYY-MM-DD;  appends terminating zero
  extern void  Date9toCIF  ( cpstr Date9, pstr DateCIF );

  // converts DD-MMM-YYYY to YYYY-MM-DD;  appends terminating zero
  extern void  Date11toCIF ( cpstr Date11, pstr DateCIF );

  // converts YYYY-MM-DD  to DD-MMM-YY;   appends terminating zero
  extern void  DateCIFto9  ( cpstr DateCIF, pstr Date9 );

  // converts YYYY-MM-DD  to DD-MMM-YYYY; appends terminating zero
  extern void  DateCIFto11 ( cpstr DateCIF, pstr Date11 );


  // =================  Format functions  ==================

  //   Returns true if S contains an integer number in its
  // first M characters. This number is returned in N.
  //   The return is false if no integer number may be
  // recognized. In this case, N is assigned MinInt4 value.
  extern bool GetInteger ( int & N, cpstr S, int M );

  //   Returns true if S contains a real number in its
  // first M characters. This number is returned in R.
  //   The return is false if no real number may be
  // recognized. In this case, R is assigned -MaxReal value.
  extern bool GetReal ( realtype & R, cpstr S, int M );

  //   Returns true if S contains an integer number in its
  // first M characters. This number is returned in N. In addition
  // to that, GetIntIns() retrieves the insertion code which may
  // follow the integer and returns it in "ins" (1 character +
  // terminating 0).
  //   The return is false if no integer number may be
  // recognized. In this case, N is assigned MinInt4 value,
  // "ins" just returns (M+1)th symbol of S (+terminating 0).
  extern bool  GetIntIns ( int & N, pstr ins, cpstr S, int M );

  //  Integer N is converted into ASCII string of length M
  // and pasted onto first M characters of string S. No
  // terminating zero is added.
  //  If N is set to MinInt4, then first M characters of
  // string S are set to space.
  extern void  PutInteger ( pstr S, int N, int M );

  //  Real R is converted into ASCII string of length M
  // and pasted onto first M characters of string S. No
  // terminating zero is added. The conversion is done
  // according to fixed format FM.L
  //  If R is set to -MaxReal, then first M characters of
  // string S are set to the space character.
  extern void  PutRealF ( pstr S, realtype R, int M, int L );

  //  Integer N is converted into ASCII string of length M
  // and pasted onto first M characters of string S. No
  // terminating zero is added. The insert code ins is put
  // immediately after the integer.
  //  If N is set to MinInt4, then first M+1 characters of
  // string S are set to space, and no insert code are
  // appended.
  extern void  PutIntIns ( pstr S, int N, int M, cpstr ins );


  //   CIFInteger(..), CIFReal(..) and CIFGetString(..) automate
  // extraction and analysis of data from CIF file. If the data
  // is erroneous or absent, they store an error message in
  // CIFErrorLocation string (below) and return non-zero.
  extern ERROR_CODE CIFGetInteger  ( int & I, mmcif::PStruct Struct,
                                     cpstr Tag,
                                     bool Remove=true );
  extern ERROR_CODE CIFGetReal     ( realtype & R, mmcif::PStruct Struct,
                                     cpstr Tag,
                                     bool Remove=true );
  extern ERROR_CODE CIFGetString   ( pstr S, mmcif::PStruct Struct,
                                      cpstr Tag, int SLen,
                                      cpstr DefS,
                                      bool Remove=true );

  extern ERROR_CODE CIFGetInteger  ( int & I, mmcif::PLoop Loop, cpstr Tag,
                                     int & Signal );
  extern ERROR_CODE CIFGetIntegerD ( int & I, mmcif::PLoop Loop, cpstr Tag,
                                     int defValue=MinInt4 );
  extern ERROR_CODE CIFGetInteger1 ( int & I, mmcif::PLoop Loop, cpstr Tag,
                                     int nrow );

  extern ERROR_CODE CIFGetReal     ( realtype & R, mmcif::PLoop Loop,
                                     cpstr Tag, int & Signal );
  extern ERROR_CODE CIFGetReal1    ( realtype & R, mmcif::PLoop Loop,
                                     cpstr Tag, int nrow );

  extern ERROR_CODE CIFGetString   ( pstr S, mmcif::PLoop Loop, cpstr Tag,
                                     int row, int SLen, cpstr DefS );

  //  Calculates AI=A^{-1}
  extern void  Mat4Inverse ( mat44 & A, mat44 & AI );
  //  Calculates A=B*C
  extern void  Mat4Mult    ( mat44 & A, mat44 & B, mat44 & C );
  //  Calculates A=B^{-1}*C
  extern void  Mat4Div1    ( mat44 & A, mat44 & B, mat44 & C );
  //  Calculates A=B*C^{-1}
  extern void  Mat4Div2    ( mat44 & A, mat44 & B, mat44 & C );
  //  Calculates determinant of the rotation part
  extern realtype Mat4RotDet ( mat44 & T );

  //  Sets up a unit matrix
  extern void  Mat4Init  ( mat44 & A );
  extern void  Mat3Init  ( mat33 & A );

  //  Calculates AI=A^{-1}, returns determinant
  extern realtype Mat3Inverse ( mat33 & A, mat33 & AI );

  extern bool isMat4Unit ( mat44 & A, realtype eps, bool rotOnly );

  //  Copies A into AC
  extern void  Mat4Copy  ( mat44 & A, mat44 & ACopy );
  extern void  Mat3Copy  ( mat33 & A, mat33 & ACopy );
  extern bool  isMat4Eq  ( mat44 & A, mat44 & B, realtype eps,
                             bool rotOnly );

  extern void TransformXYZ   ( mat44 & T,
                              realtype & X, realtype & Y, realtype & Z );
  extern realtype TransformX ( mat44 & T,
                               realtype X, realtype Y, realtype Z );
  extern realtype TransformY ( mat44 & T,
                               realtype X, realtype Y, realtype Z );
  extern realtype TransformZ ( mat44 & T,
                               realtype X, realtype Y, realtype Z );


  extern char CIFErrorLocation[200];

  //  Returns ASCII string explaining the nature of
  // Error_xxxx error code.
  extern cpstr  GetErrorDescription ( ERROR_CODE ErrorCode );



  //  ================  ContainerClass  ====================

  DefineClass(ContainerClass);
  DefineStreamFunctions(ContainerClass);

  class ContainerClass : public io::Stream  {

    friend class ClassContainer;

    public :

      ContainerClass ();
      ContainerClass ( io::RPStream Object );
      ~ContainerClass() {}

      //    ConvertPDBASCII(..) will return one of the Error_XXXXX
      // constants, see <mmdb_defs.h>
      virtual ERROR_CODE ConvertPDBASCII ( cpstr )
                                         { return Error_NoError; }
      virtual void PDBASCIIDump    ( pstr, int ) {}
      virtual bool PDBASCIIDump1   ( io::RFile ) { return false; }
      virtual void MakeCIF         ( mmcif::PData, int ) {}

      //   Append(..) should return true if CC is appended to this class.
      // If this is not the case, CC is merely put on the top of
      // container.
      //   Note: Append(..) detects the necessity to append CC and
      // performs all the necessary actions for that. The rest of CC
      // will be disposed by Class Container.
      //   Note: Class Container checks every new class, which is
      // being added to it (see CClassContainer::AddData(..)), only
      // against the top of container.
      virtual bool Append ( PContainerClass CC );

      //  GetCIF(..) extracts any necessary information from CIF and
      //  returns in Signal:
      //    Error_noError : the information was successfully extracted,
      //                  this instance of container class should be
      //                  stored, and unchanged value of Signal should
      //                  be passed to the next (newly created) instance
      //                  of this container class.
      //    Error_EmptyCIF : there is no information for this type of
      //                  containers to extract. This instance of
      //                  container class should be deleted and input
      //                  for this type of container class terminated.
      //    Other          : the corresponding error. This instance of
      //                  container class should be deleted and the
      //                  whole input stopped.
      virtual ERROR_CODE GetCIF ( mmcif::PData, int & n )
                                     { n = -1; return Error_EmptyCIF; }
      virtual CLASS_ID GetClassID () { return ClassID_Template; }

      virtual void Copy ( PContainerClass ) {}

      void write ( io::RFile ) {}
      void read  ( io::RFile ) {}

    protected :
      int  ContinuationNo;

  };


  //  ========================  ContString  =========================

  DefineClass(ContString);
  DefineStreamFunctions(ContString);

  class ContString : public ContainerClass  {

    public :

      pstr Line;  // a string

      ContString ();
      ContString ( cpstr S );
      ContString ( io::RPStream Object );
      ~ContString();

      ERROR_CODE ConvertPDBASCII ( cpstr S );
      void       PDBASCIIDump    ( pstr S, int N );
      bool       PDBASCIIDump1   ( io::RFile f );
      void       MakeCIF         ( mmcif::PData CIF, int N );
//      void       GetCIF1         ( mmcif::PData CIF, ERROR_CODE & Signal,
//                                   int & pos );
      bool       Append          ( PContainerClass ContString   );
      CLASS_ID   GetClassID      () { return ClassID_String; }

      void  Copy  ( PContainerClass CString );

      void  write ( io::RFile f );
      void  read  ( io::RFile f );

    protected :
      pstr CIFCategory,CIFTag;

      void InitString();

  };


  //  ==============  ClassContainer  ====================

  DefineClass(ClassContainer);
  DefineStreamFunctions(ClassContainer);

  class ClassContainer : public io::Stream  {

    public :

      ClassContainer  ();
      ClassContainer  ( io::RPStream Object );
      ~ClassContainer ();

      void    FreeContainer      ();
      void    AddData            ( PContainerClass Data );
      virtual void PDBASCIIDump  ( io::RFile f );
      virtual void MakeCIF       ( mmcif::PData CIF );
      //  GetCIF(..) will return one of the Error_XXXXX constants,
      //  see <mmdb_defs.h>
      virtual ERROR_CODE  GetCIF ( mmcif::PData CIF, int ClassID );
      virtual PContainerClass MakeContainerClass ( int ClassID );

      // Copy will empty the class if parameter is set to NULL
      virtual void Copy          ( PClassContainer CContainer );

      inline int Length()  { return length; }
      PContainerClass  GetContainerClass ( int ContClassNo );

      void  write ( io::RFile f );
      void  read  ( io::RFile f );

    protected :
      int              length;
      PPContainerClass Container;

      void Init();

  };


  //  ======================  ID parsers  ==========================

  DefineClass(AtomPath);
  DefineStreamFunctions(AtomPath);

  enum APATH_FLAG  {
    APATH_ModelNo     = 0x00000001,
    APATH_ChainID     = 0x00000002,
    APATH_SeqNum      = 0x00000004,
    APATH_InsCode     = 0x00000008,
    APATH_ResName     = 0x00000010,
    APATH_AtomName    = 0x00000020,
    APATH_Element     = 0x00000040,
    APATH_AltLoc      = 0x00000080,
    APATH_Incomplete  = 0x00000100,
    APATH_WC_ModelNo  = 0x00001000,
    APATH_WC_ChainID  = 0x00002000,
    APATH_WC_SeqNum   = 0x00004000,
    APATH_WC_InsCode  = 0x00008000,
    APATH_WC_ResName  = 0x00010000,
    APATH_WC_AtomName = 0x00020000,
    APATH_WC_Element  = 0x00040000,
    APATH_WC_AltLoc   = 0x00080000
  };

  class AtomPath : public io::Stream  {

    public :

      int      modelNo;
      ChainID  chainID;
      int      seqNum;
      InsCode  insCode;
      ResName  resName;
      AtomName atomName;
      Element  element;
      AltLoc   altLoc;
      int      isSet;

      AtomPath  ();
      AtomPath  ( cpstr ID );
      AtomPath  ( io::RPStream Object );
      ~AtomPath ();

      //  SetPath(..) parses the Atom Path ID string, which
      //  may be incomplete. Below {..} means blocks that
      //  may be omitted; any elements within such blocks
      //  may be omitted as well.
      //
      //  1. If ID starts with '/' then the ID must be of
      //     the following form:
      //   /mdl{/chn{/seq(res).i{/atm[elm]:a}}}
      //
      //  2. If ID starts with a letter:
      //        chn{/seq(res).i{/atm[elm]:a}}
      //
      //  3. If ID starts with a number or '(':
      //            seq(res).i{/atm[elm]:a}
      //
      //  4. If ID contains colon ':' or '[' then
      //     it may be just
      //                       atm[elm]:a
      //
      //  The following are valid samples of IDs:
      //
      //     /1      model number 1
      //     /1/A/23(GLU).A/CA[C]:A  model number 1, chain A,
      //             residue 23 GLU insertion code A, C-alpha
      //             atom in alternative location A
      //     A/23    residue 23 of chain A
      //     CA[C]:  atom C-alpha
      //     [C]     a carbon
      //     *[C]:*  same as above
      //     :A      an atom with insertion code A
      //     5       residue number 5
      //     (GLU)   residue GLU
      //
      //   All spaces are ignored. SetPath(..) sets bit of isSet
      // for each element present. Any element may be a wildcard
      // '*'. Wildcard for model will set modelNo=0, for sequence
      // number will set seqNum=MinInt4.
      //
      // Returns:
      //   0   <-> Ok
      //   -1  <-> wrong numerical format for model
      //   -2  <-> wrong numerical format for sequence number
      int SetPath ( cpstr ID );

      void write ( io::RFile f );
      void read  ( io::RFile f );

    protected :
      void InitAtomPath();

  };


  //  --------------------------------------------------------------

  DefineClass(QuickSort);

  class QuickSort : public io::Stream  {

    public :
      QuickSort ();
      QuickSort ( io::RPStream Object );
      ~QuickSort() {}
      virtual int  Compare ( int i, int j );
      virtual void Swap    ( int i, int j );
      void Sort ( void * sortdata, int data_len );

    protected :
      int    selSortLimit,dlen;
      void * data;

      void SelectionSort ( int left, int right );
      int  Partition     ( int left, int right );
      void Quicksort     ( int left, int right );

  };


  //  --------------------------------------------------------------

  extern void  takeWord ( pstr & p, pstr wrd, cpstr ter, int l );

  //   ParseAtomID(..) reads the atom ID of the following form:
  //    {name} {[element]} {:altcode}
  // (here {} means that the item may be omitted; any field may have
  // value of wildcard '*'), and returns the atom name in aname,
  // element name - in elname, and alternate location code - in aloc.
  // Except for the alternate location code, missing items are
  // replaced by wildcards. Missing alternate location code is
  // returned as empty string "".
  //   Leading spaces are allowed; any other space will terminate
  // the parsing.
  //   The followings are perfectly valid atom IDs:
  //        CA[C]:A     (carbon C_alpha in location A)
  //        CA[*]:A     (either C_alpha or Ca in location A)
  //        CA:A        (same as above)
  //        CA          (either C_alpha or Ca with no location indicator)
  //        CA[]        (same as above)
  //        CA[C]:      (C_alpha with no location indicator)
  //        [C]         (any carbon with no location indicator)
  //        [C]:*       (any carbon with any location indicator)
  //        *[C]:*      (same as above)
  //        :A          (any atom in location A)
  //        *[*]:A      (same as above)
  //        *[*]:*      (any atom)
  //        *           (any atom with no alternate location indicator)
  extern void ParseAtomID ( cpstr ID, AtomName aname,
                            Element elname, AltLoc   aloc );

  //   ParseResID(..) reads the residue ID of the following form:
  //    {seqnum} {(name)} {.inscode}
  // (here {} means that the item may be omitted; any field may have
  // value of wildcard '*'), and returns the sequence number in sn,
  // insertion code - in inscode, and residue name - in resname.
  // If a wildcard was specified for the sequence number, then
  // ParseResID(..) returns 1. Missing residue name is replaced by
  // the wildcard '*', and misisng insertion code is returned as empty
  // string "".
  //   Leading spaces are allowed; any other space will terminate
  // the parsing.
  //   Return 0 means Ok, 1 - wildcard for the sequence number,
  // 2 - an error in numerical format of the sequence number
  // (other items are parsed).
  //   The followings are perfectly valid residue IDs:
  //        27(ALA).A   (residue 27A ALA)
  //        27().A      (residue 27A)
  //        27(*).A     (same as above)
  //        27.A        (same as above)
  //        27          (residue 27)
  //        27().       (same as above)
  //        (ALA)       (any ALA without insertion code)
  //        (ALA).      (same as above)
  //        (ALA).*     (any ALA)
  //        *(ALA).*    (any ALA)
  //        .A          (any residue with insertion code A)
  //        *(*).A      (same as above)
  //        *(*).*      (any residue)
  //        *           (any residue with no insertion code)
  extern int ParseResID ( cpstr ID, int & sn,
                          InsCode inscode, ResName resname );


  //   ParseAtomPath(..) parses an atom path string of the following
  // structure:
  //   /mdl/chn/seq(res).i/atm[elm]:a
  // where all items may be represented by a wildcard '*' and
  //   mdl   - model number (mandatory); at least model #1 is always
  //           present; returned in mdl; on a wildcard mdl is set to 0
  //   chn   - chain identifier ( mandatory); returned in chn; on a
  //           wildcard chn is set to '*'
  //   seq   - residue sequence number (mandatory); returned in sn;
  //           on a wild card ParseAtomPath(..) returns 1
  //   (res) - residue name in round brackets (may be omitted);
  //           returnded in res; on a wildcard res is set to '*'
  //   .i    - insert code after a dot; if '.i' or 'i' is missing
  //           then a residue without an insertion code is looked for;
  //           returned in ic; on a wildcard (any insertion code would
  //           do) ic is set to '*'
  //   atm   - atom name (mandatory); returned in atm; on a wildcard
  //           atm is set to '*'
  //   [elm] - chemical element code in square brackets; it may
  //           be omitted but could be helpful for e.g.
  //           distinguishing C_alpha and CA; returned in elm;
  //           in a wildcard elm is set to '*'
  //   :a    - alternate location indicator after colon; if
  //           ':a' or 'a' is missing then an atom without
  //           alternate location indicator is looked for; returned
  //           in aloc; on a wildcard (any alternate code would do)
  //           aloc is set to '*'.
  // All spaces are ignored, all identifiers should be in capital
  // letters (comparisons are case-sensitive).
  //   The atom path string may be incomplete. If DefPath is supplied,
  // the function will try to get missing elements from there. If
  // missing items may not be found in DefPath, they are replaced by
  // wildcards.
  //   ParseAtomPath(..) returns the following bits:
  //      0                 - Ok
  //      APATH_Incomplete  - if path contains wildcards. Wildcards for
  //                          residue name and chemical element will be
  //                          ignored here if sequence number and
  //                          atom name, correspondingly, are provided.
  //      APATH_WC_XXXXX    - wildcard for different elements
  //      -1                - wrong numerical format for model (fatal)
  //      -2                - wrong numerical format for seqNum (fatal)

  extern int ParseAtomPath ( cpstr     ID,
                             int &     mdl,
                             ChainID   chn,
                             int &     sn,
                             InsCode   ic,
                             ResName   res,
                             AtomName  atm,
                             Element   elm,
                             AltLoc    aloc,
                             PAtomPath DefPath=NULL );



  extern int ParseSelectionPath ( cpstr   CID,
                                  int &   iModel,
                                  pstr    Chains,
                                  int &   sNum1,
                                  InsCode ic1,
                                  int &   sNum2,
                                  InsCode ic2,
                                  pstr    RNames,
                                  pstr    ANames,
                                  pstr    Elements,
                                  pstr    altLocs );



  extern void MakeSelectionPath ( pstr       CID,
                                  int        iModel,
                                  cpstr      Chains,
                                  int        sNum1,
                                  const InsCode ic1,
                                  int        sNum2,
                                  const InsCode ic2,
                                  cpstr      RNames,
                                  cpstr      ANames,
                                  cpstr      Elements,
                                  cpstr      altLocs );

}  // namespace mmdb

#endif