Package csb |
[frames] | no frames]

# Source Code for Package csb

      1  """
      2  CSB is a high-level, object-oriented library used to solve problems in the
      3  field of Computational Structural Biology.
      4
      5
      6  Introduction
      7  ============
      8
      9  The library is composed of a set of highly branched python packages
     10  (namespaces). Some of the packages are meant to be directly used by
     11  the clients (core library), while others are utility modules and take
     12  part in the development of the library:
     13
     14      1. Core class library -- object-oriented, granular, with an emphasis
     15         on design and clean interfaces. A Sequence is not a string, and a
     16         Structure is not a dict or list. Naming conventions matter.
     17
     18      2. Application framework -- executable console applications
     19         ("protocols"), which consume objects from the core library.
     20         The framework ensures that each CSB application is also reusable
     21         and can be instantiated as a regular python object without any
     22         ugly side effects (sys.exit() and friends). See L{csb.apps} for more
     23         details.
     24
     25      3. Test framework -- built on top of the standard unittest as a thin
     26         wrapping layer. Provides some sugar like transparent management of
     27         test data files, and modular test execution. L{csb.test} will give
     28         you all the details.
     29
     30  The core library is roughly composed of:
     31
     32      - bioinformatics API: L{csb.bio}, which includes stuff like
     33        L{csb.bio.io}, L{csb.bio.structure}, L{csb.bio.sequence},
     34        L{csb.bio.hmm}
     35
     36      - statistics API: L{csb.statistics}, L{csb.numeric}
     37
     38      - utilities - L{csb.io}, L{csb.core}
     39
     40
     41  Getting started
     42  ===============
     43
     44  Perhaps one of the most frequently used parts of the library is the
     45  L{csb.bio.structure} module, which provides the L{Structure}, L{Chain},
     46  L{Residue} and L{Atom} objects. You could easily build a L{Structure}
     47  from scratch, but a far more common scenario is parsing a structure from
     48  a PDB file using one of the L{AbstractStructureParser}s. All bio IO
     49  objects, including the StructureParser factory, are defined in
     50  L{csb.bio.io} and sub-packages:
     51
     52      >>> from csb.bio.io.wwpdb import StructureParser
     53      >>> p = StructureParser("/some/file/pdb1x80.ent")
     54      >>> s = p.parse_structure()
     55      >>> print(s)
     56      <Structure: 1x80, 2 chains>
     57
     58  The last statement will return a L{csb.bio.structure.Structure} instance,
     59  which is a composite hierarchical object:
     60
     61      >>> for chain_id in s.chains:
     62              chain = s.chains[chain_id]
     63              for residue in chain.residues:
     64                  for atom_id in residue.atoms:
     65                      atom = residue.atoms[atom_id]
     66                      print(atom.vector)
     67
     68  Some of the inner objects in this hierarchy behave just like dictionaries
     69  (but are not):
     70
     71      >>> s.chains['A']        # access chain A by ID
     72      <Chain A: Protein>
     73      >>> s['A']               # the same
     74      <Chain A: Protein>
     75
     76  Others behave like collections:
     77
     78      >>> chain.residues[10]               # 1-based access to the residues in the chain
     79      <ProteinResidue [10]: PRO 10>
     80      >>> chain[10]                        # 0-based, list-like access
     81      <ProteinResidue [11]: GLY 11>
     82
     83  But all entities are iterable because they inherit the C{items} iterator
     84  from L{AbstractEntity}. The above loop can be shortened:
     85
     86      >>> for chain in s.items:
     87              for residue in chain.items:
     88                  for atom in residue.items:
     89                      print(atom.vector)
     90
     91  or even more:
     92
     93      >>> from csb.bio.structure import Atom
     94      >>> for atom in s.components(klass=Atom):
     95              print(atom.vector)
     96
     97  You may also be interested in extracting a sub-chain from this structure:
     98
     99      >>> s.chains['B'].subregion(3, 20)    # from positions 3 to 20, inclusive
    100      <Chain B: Protein>
    101
    102  or modifying it in some way, for example, in order to append a new residue,
    103  try:
    104
    105      >>> from csb.bio.structure import ProteinResidue
    106      >>> from csb.bio.sequence import ProteinAlphabet
    107      >>> residue = ProteinResidue(401, ProteinAlphabet.ALA)
    108      >>> s.chains['A'].residues.append(residue)
    109
    110  Finally, you would probably want to save your structure back to a PDB file:
    111
    112      >>> s.to_pdb('/some/file/name.pdb')
    113
    114
    115  Where to go from here
    116  =====================
    117
    118  If you want to dive into statistics, you could peek inside L{csb.statistics}
    119  and its sub-packages. For example, L{csb.statistics.pdf} contains a collection
    120  of L{probability density objects<csb.statistics.pdf.AbstractDensity>},
    121  like L{Gaussian<csb.statistics.pdf.Normal>} or L{Gamma<csb.statistics.pdf.Gamma>}.
    122
    123  But chances are you would first like to try reading some files, so you could
    124  start exploring L{csb.bio.io} right now. As we have already seen,
    125  L{csb.bio.io.wwpdb} provides PDB L{Structure<csb.bio.structure.Structure>}
    126  parsers, for example L{csb.bio.io.wwpdb.RegularStructureParser} and
    127  L{csb.bio.io.wwpdb.LegacyStructureParser}.
    128
    129  L{csb.bio.io.fasta} is all about reading FASTA
    130  L{Sequence<csb.bio.sequence.AbstractSequence>}s and
    131  L{SequenceAlignment<csb.bio.sequence.AbstractAlignment>}s. Be sure to check out
    132  L{csb.bio.io.fasta.SequenceParser}, L{csb.bio.io.fasta.SequenceAlignmentReader}
    133  and L{csb.bio.io.fasta.StructureAlignmentFactory}.
    134
    135  If you are working with HHpred (L{ProfileHMM<csb.bio.hmm.ProfileHMM>}s,
    136  L{HHpredHit<csb.bio.hmm.HHpredHit>}s), then L{csb.bio.io.hhpred} is for you.
    137  This package provides L{csb.bio.io.hhpred.HHProfileParser} and
    138  L{csb.bio.io.hhpred.HHOutputParser}, which are used to read *.hhm and *.hhr
    139  files.
    140
    141  Finally, if you want to make some nice plots with matplotlib, you may like the
    142  clean object-oriented interface of our L{Chart<csb.io.plots.Chart>}. See
    143  L{csb.io.plots} and maybe also L{csb.io.tsv} to get started.
    144
    145
    146  Development
    147  ===========
    148
    149  When contributing code to CSB, please take into account the following:
    150
    151      1. New features or bug fixes should always be accompanied by test cases.
    152         Also, always run the complete test suite before committing. For more
    153         details on this topic, see L{csb.test}.
    154
    155      2. The source code of CSB must be cross-platform and cross-interpreter
    156         compatible. L{csb.core} and L{csb.io} will give you all necessary
    157         details on how to use the CSB compatibility layer.
    158
    159
    160  License
    161  =======
    162
    163  CSB is open source and distributed under OSI-approved MIT license::
    164
    165      Copyright (c) 2012 Michael Habeck
    166
    167      Permission is hereby granted, free of charge, to any person obtaining
    168      a copy of this software and associated documentation files (the
    169      "Software"), to deal in the Software without restriction, including
    170      without limitation the rights to use, copy, modify, merge, publish,
    171      distribute, sublicense, and/or sell copies of the Software, and to
    172      permit persons to whom the Software is furnished to do so, subject to
    173      the following conditions:
    174
    175      The above copyright notice and this permission notice shall be
    176      included in all copies or substantial portions of the Software.
    177
    178      THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
    179      EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
    180      MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
    181      IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
    182      CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
    183      TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
    184      SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
    185
    186  """
    187
    188  __version__ = '1.2.3.{revision}'
    189
    190
    191 -class Version(object):
    192      """
    193      CSB version number.
    194      """
    195
    196 -    def __init__(self):
    197
    198          version = __version__.split('.')
    199
    200          if not len(version) in (3, 4):
    201              raise ValueError(version)
    202
    203          self._package = __name__
    204
    205          self._major = version[0]
    206          self._minor = version[1]
    207          self._micro = version[2]
    208          self._revision = None
    209
    210          if len(version) == 4:
    211              self._revision = version[3]
    212
    213 -    def __str__(self):
    214          return self.short
    215
    216 -    def __repr__(self):
    217          return '{0.package} {0.full}'.format(self)
    218
    219      @property
    220 -    def major(self):
    221          """
    222          Major version (huge, incompatible changes)
    223          @rtype: int
    224          """
    225          return int(self._major)
    226
    227      @property
    228 -    def minor(self):
    229          """
    230          Minor version (significant, but compatible changes)
    231          @rtype: int
    232          """
    233          return int(self._minor)
    234
    235      @property
    236 -    def micro(self):
    237          """
    238          Micro version (bug fixes and small enhancements)
    239          @rtype: int
    240          """
    241          return int(self._micro)
    242
    243      @property
    244 -    def revision(self):
    245          """
    246          Build number (exact repository revision number)
    247          @rtype: int
    248          """
    249          try:
    250              return int(self._revision)
    251          except:
    252              return self._revision
    253
    254      @property
    255 -    def short(self):
    256          """
    257          Canonical three-part version number.
    258          """
    259          return '{0.major}.{0.minor}.{0.micro}'.format(self)
    260
    261      @property
    262 -    def full(self):
    263          """
    264          Full version, including the repository revision number.
    265          """
    266          return '{0.major}.{0.minor}.{0.micro}.{0.revision}'.format(self)
    267
    268      @property
    269 -    def package(self):
    270          return self._package
    271