BioChain.h

Go to the documentation of this file.

/****************************************************************************
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
The BioBhasha : The Biologist's Programming Language 
Version 1.0 (19th December 2001)
Prasad, B.V.L.S.
Contact: burrashiva@yahoo.com
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
*****************************************************************************/
#ifndef BIOCHAIN_H
#define BIOCHAIN_H

#include "BioStatistics.h"
#include "BioResidue.h"

/****************************************************************************
 *
 * COMMENTARY on Each Class/Concept: Hows and Whys :
 *
 * BioChain:
 *      The explanation for BioResidue is also valid for BioChain also. A 
 *      group of Residues make up a Chain. But the number of Chains is a 
 *      variable which purely depends on the Protein/DNA. A functional
 *      protein may have 2 chains as in HIV proteinase. In PDB it is submitted
 *      as 2 Chains, A and B and I for inhibitor. Hence, a Chain described 
 *      in a PDB file could be a Functional Protein by itself or a subset of 
 *      a functional molecule. Hence BioChain can be made a seperate ADT 
 *      describing a part of the molecule. This type of Abstraction of a Protein
 *      into small Chains makes the BioObject Communication much clear, easier
 *      and efficient from the user's point of view. 
 *      As was explained the relation between BioResidue and BioAtom, here also
 *      BioChain "Has-A" BioResidues. A BioChain "AGGREGATES" BioResidues. 
 *      vector<BioResidue>residue; This takes care of the size of the Chain or 
 *      the Protein, without any programmers involvement in DMA code. This is greatest 
 *      advantage which STL's give a Programmer. 
 *      This type of Abstraction gives the user to access any Residue at any point
 *      of the Programming , at any atom. Many Software programs donot give such
 *      an option. The aim of BioBhasha has been to give tools and facilities to 
 *      the user/Programmer at Atomic Level(literally and Programming-wise). 
 *      The Mining of Data can be achieved very clearly and efficiently.
 ********************************************************************************/      
class BioChain
{

protected:

        vector<BioResidue>residue;
        char chainId_;

public:
// Default Constructor....Not recommended ...inherit the notes from BioResidue 
// Commentary also.
        BioChain();
        virtual ~BioChain();

// This Constructor expects a PDB file name. It will take only the first encountered
// Chain and terminates populating, once it sees, OXT as the AtomName. This can be used
// when the user is pretty confident that the first Chain provided in the PDB is what 
// he desires.
        BioChain(const string& );

// This Constructor is expected to be the most widely used as this gives the facility of 
// accessing a Chain by a given ChainID from the user. 
// Hence it expects not only the PDB filename as the above one, but also the ChainId which 
// the user is interested in . 
        BioChain(const string& ,char );

// This Constructor is used to instantiate a Chain while reading a PDB file. 
        BioChain(const unsigned long& atnumber,const string& atname,const string& resname,const char& ch,
                 const long& resnumber, const float& x1, const float&  y1,const float& z1,
                 const float&  oc1, const float&  bf1,const string& atrec);

// Another constructor for convinience when the an external Data is in a vectored BioResidue
// format and is desired to be made a chain to access the Chain Operationalities. 
        BioChain(const char& chid, vector<BioResidue> );

// This method is to set a NEW ChainID to the Chain. This Facility is to 
// make Chain names More Meaningful. For an Enzyme complex, 'E' is more 
// meaningful than 'A' or anyother thing. Similarly, 'I' for inhibitor is 
// more meaningful than 'U' etc....
// My Caution is : Any "set" or "push" Method should be used with restraint.
        void setChainId(const char& ch ) ;


// This gives out the ResidueNumber, Residue Name and Residue itself...
// as told in BioResidue, These methods are used for logical expression.
// For example: if ( popLastResidueNumber() == presentResidueName) ...
// populate the BioAtom vector present in that Residue.
        long getLastResidueNumber() const ;
        string getLastResidueName() const ;
        char getChainId() const ;
        bool findChainId(const char&);
        BioResidue& getLastResidue()  ;
        vector<BioResidue> getResidues();

// This gives the Number of Residues in a particular Chain.
unsigned int getNumberOfResidues() const ;
unsigned        int getNumberOfAtoms() const;
        int getResidueIndex(const long& ) const;

// This is a very important Method. This gives the facility to access any 
// residue in a chain, but ONLY BY RESIDUE INDEX....Obviously not by the 
// RESIDUE NAME and *NOT* by RESIDUE NUMBER ALSO, which ambiguates the 
// retreival of the data.
// Where ever, a part of the structure coordinates are obtained, the arguments
// refer to the RESIDUE INDEX and *NOT* to the RESIDUE NUMBER>>>>>>>>
// This is a caution to all the users.........Please Be Careful..............
// Please use getResidueIndex or getAtomIndex member functions and obtained
// the Index values of the respective residues or atoms and give those
// values AS ARGUMENTS TO THESE TYPE OF FUNCTIONS.......
// THIS IS A FACILITY TO REDUCE THE ERRORS....AS SOME PDB FILES OMIT SOME RESIDUE
// NUMBERS IF THE ELECTRON DENSITY IS NOT FOUND FOR SUCH RESIDUES OR ATOMS...
// THIS LITTLE INCONVINIENCE REDUCES THE ERROR-PRONE CHARACTER OF THE PROGRAM
// ENORMOUSLY......SO PLEASE ADOPT THE INCONVINIENCE............
        BioResidue getResidue(const int& );

// This set of methods are most important for analysing only a particular part of a 
// Structure file or a part of the protein or chain under consideration.  This is 
// also expected to be used very much. This returns the content, again as a BioChain 
// making it possible to use all the important member function for manipulation.
// Giving access every bit of information has been the main information, because 
// "The Quality of Research Differs Only in the Resolution at Which One Wants to Work."
// ARGUMENTS ARE INDECES NOT RESIDUE NUMBERS...AS PROVIDED IN THE PDB....USE
// GETRESIDUEINDEX() FUNCTION................
        BioChain getChainSegment(const long& first, const long& last);

// this method gives the ability to get the coordinates of chain segment of only a 
// particular Atom of interest...........please see explanation in showChainSegment.
// ARGUMENTS ARE INDECES NOT RESIDUE NUMBERS...AS PROVIDED IN THE PDB....USE
// GETRESIDUEINDEX() FUNCTION................
        BioChain getChainSegment(const long& first,const long& last, const string& atname);

// These Methods are primarily given to populate the BioResidue Vector Container with 
// residue information externally...
        void pushResidue(const BioResidue&);
        void pushResidue(const unsigned long& atnumber,const string& atname, const string& resname,
                    const long& resnum, const float& x1, const float& y1, const float& z1,
                      const float& oc1, const float& bf1,const string& );

// Similar to the explanation in BioResidue, this removes the Hydrogen atoms from 
// the data which is stored in a Vector<BioResidue> and returns it as a new BioChain.
        BioChain eraseHydrogen();

// This Method shows all the contents of the BioChain in a PDB format. It can be 
// written to a file, as was mentioned earlier. 
        void showChain(ostream& = cout); 
        friend ostream& operator<<(ostream& os, BioChain& ip);

// These methods also should find great utility as they give the chance of checking whether
// the proper coordinates are being taken for the analysis or not. 
// The 2nd method is grepping only the required atoms from the Chain list....
// For example: One wants to get only "CA" atoms from say 120-150 residue in a chain...then he 
// can simple write showChainSegment(120,150,"CA"); 
// ARGUMENTS ARE INDECES NOT RESIDUE NUMBERS...AS PROVIDED IN THE PDB....USE
// GETRESIDUEINDEX() FUNCTION................
        void showChainSegment(const long& ,const long&, ostream& = cout);
        void showChainSegment(const long& , const long& , const string& atname,ostream& = cout);

// This method, as the name suggests gives out the centroid of a coordinates stored in
// the chain. This returns the centroid as a BioAtom.....again...........
// This would have large application in refinement protocols, finding the least squares 
// plane, line and similar things..........
        BioPoint getCentroid();
        BioPoint getCentroid(const string& );

        vector<float> getNormalizedBfactors();
        void setNormalizedBfactors();
        float getAverageBfactor();
        

        float getDistance( const int& , const string& ,const float& ,const float& , const float&);
        float getDistance( const int& , const int& , const float& , const float& , const float& );

        float getDistance( const int& , const string& , const BioAtom&);
        float getDistance( const int& , const int& , const BioAtom& );

        void showSphereAnAtom(const unsigned int& , const string&, ostream& = cout, const float& = 2.3, const float& = 3.2);
        void showSphereAnAtom(const unsigned int& , const unsigned int& , ostream& = cout, const float& = 2.3, const float& = 3.2);

};

#endif