Molecule.py 78 KB
Newer Older
pjropp's avatar
pjropp committed
1 2 3
"""
Copyright (c) 2017 Jacob Durrant. MIT license. Please see LICENSE.txt for full details.
"""
pjropp's avatar
pjropp committed
4
from __future__ import absolute_import
pjropp's avatar
pjropp committed
5
from scoria import dumbpy as numpy
pjropp's avatar
pjropp committed
6 7 8 9 10 11 12
from .FileIO import FileIO
from .AtomsAndBonds import AtomsAndBonds
from .Selections import Selections
from .Manipulation import Manipulation
from .Information import Information
from .OtherMolecules import OtherMolecules
from .Geometry import Geometry
13
import copy
jdurrant's avatar
jdurrant committed
14 15 16


class Molecule: # here's the actual Molecule class
17
    """
pjropp's avatar
pjropp committed
18
    Loads, saves, and manupulates molecuar models. The main scoria
19
    class. Contains Wrapper functions for subclasses.
20 21 22

    Examples assume::

pjropp's avatar
pjropp committed
23
        >>> import scoria
24 25
        >>> PSF = "./test_file.psf"
        >>> DCD = "./test_file.dcd"
pjropp's avatar
pjropp committed
26
        >>> mol = scoria.Molecule()
pjropp's avatar
pjropp committed
27
        >>> mol.load_MDAnalysis_into(PSF, DCD)
28
    """
jdurrant's avatar
jdurrant committed
29

pjropp's avatar
pjropp committed
30
    def __init__(self, *args):
pjropp's avatar
pjropp committed
31 32
        """
        Initializes the variables of the Molecule class.
33 34 35

        :param files args: Additional files added to the end of the paramter
            will be input with the method indicated by the fileType parameter.
pjropp's avatar
pjropp committed
36
        """
jdurrant's avatar
jdurrant committed
37 38 39 40 41 42

        self.fileio = FileIO(self)
        self.atoms_and_bonds = AtomsAndBonds(self)
        self.selections = Selections(self)
        self.manipulation = Manipulation(self)
        self.information = Information(self)
43
        self.other_molecules = OtherMolecules(self)
jdurrant's avatar
jdurrant committed
44 45
        self.geometry = Geometry(self)

pjropp's avatar
pjropp committed
46
        # Based on the file type, we will attempt to open the file.
47
        # If the type is not one we recognize, we'll attempt to use MDAnalysis.
pjropp's avatar
pjropp committed
48 49 50 51 52 53
        if len(args) > 0:
            if len(args) == 1:
                file = args[0]
                file_type = file.split('.')[-1].upper()

                if file_type == 'PDB':
pjropp's avatar
pjropp committed
54
                    self.load_pdb_trajectory_into(file)
pjropp's avatar
pjropp committed
55
                elif file_type == 'PDBQT':
pjropp's avatar
pjropp committed
56
                    self.load_pdbqt_trajectory_into(file)
pjropp's avatar
pjropp committed
57 58
                elif file_type == 'PYM':
                    self.load_pym_into(file)
pjropp's avatar
pjropp committed
59
                else:
pjropp's avatar
pjropp committed
60
                    self.load_MDAnalysis_into(file)
61
            else:
pjropp's avatar
pjropp committed
62
                self.load_MDAnalysis_into(*args)
pjropp's avatar
pjropp committed
63

jdurrant's avatar
jdurrant committed
64
    # Information methods
65
    ### Wrappers ###
jdurrant's avatar
jdurrant committed
66
    # Gets
67
    def get_coordinates(self, frame = None):
68 69
        """
        Returns the set of coordinates from the specified frame.
70

pjropp's avatar
pjropp committed
71
        Wrapper function for :meth:`~scoria.Information.Information.get_coordinates`
72

73 74
        :param int frame: The timestep from which the coordinates shoule be
                        returned. If ommitted, it defaults to the first
75 76 77 78 79 80 81
                        frame of the trajectory.
        
        :returns: The set of coordinates from the specified frame.
                    ::

                    [[x1, y1, z1], ... [xn, yn, zn]]

pjropp's avatar
pjropp committed
82
        :rtype: :any:`numpy.array`
83 84 85

        ::

jdurrant's avatar
jdurrant committed
86
            >>> print(mol.get_coordinates())
87 88 89
            [[ -30.85199928  -81.45800018  365.05499268]
             [ -31.99500084  -80.69300079  365.66900635]
             [ -32.0530014   -81.13200378  367.18200684]
90
             ...,
91 92 93
             [ -27.54199982  -96.25099945  402.83700562]
             [ -23.54199982  -94.7539978   400.41900635]
             [ -22.86100006  -93.72499847  400.55300903]]
94

jdurrant's avatar
jdurrant committed
95
            >>> print(mol.get_coordinates(2))
96 97 98
            [[ -28.88899994  -80.45700073  365.51699829]
             [ -30.20000076  -79.73699951  365.99700928]
             [ -30.90699959  -80.5510025   367.13000488]
99
             ...,
100 101 102 103
             [ -26.0189991   -97.28099823  403.52600098]
             [ -23.2140007   -94.73999786  400.94699097]
             [ -22.52899933  -93.73300171  400.81399536]]
        """
104
        
105 106
        return self.information.get_coordinates(frame)

107
    def get_trajectory_coordinates(self):
108 109
        """
        Returns the trajectory for the molecule.
110

pjropp's avatar
pjropp committed
111
        Wrapper function for :meth:`~scoria.Information.Information.get_trajectory_coordinates`
112 113 114 115 116 117 118 119
        
        :returns: The set of all coordinates.
                    ::
                
                        [[[x11, y11, z11], ... [x1n, y1n, z1n]],
                         ...,
                         [[xm1, ym1, zm1], ... [xmn, ymn, zmn]]] 

pjropp's avatar
pjropp committed
120
        :rtype: :any:`numpy.array`
121 122 123

        ::

124
            >>> for coord in mol.get_trajectory_coordinates():
jdurrant's avatar
jdurrant committed
125 126
            >>>     print(coord)
            >>>     print()
127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143
            [[ -30.85199928  -81.45800018  365.05499268]
             [ -31.99500084  -80.69300079  365.66900635]
             [ -32.0530014   -81.13200378  367.18200684]
             ..., 
             [ -27.54199982  -96.25099945  402.83700562]
             [ -23.54199982  -94.7539978   400.41900635]
             [ -22.86100006  -93.72499847  400.55300903]]

            [[ -30.6779995   -81.32499695  365.73199463]
             [ -31.88100052  -80.38600159  366.0289917 ]
             [ -32.40399933  -80.62799835  367.45700073]
             ..., 
             [ -27.44400024  -96.71099854  402.64700317]
             [ -23.79199982  -94.58899689  400.63598633]
             [ -23.10700035  -93.56300354  400.79598999]]
             <more>
        """
144

145
        return self.information.get_trajectory_coordinates()
jdurrant's avatar
jdurrant committed
146 147

    def get_filename(self):
148 149
        """
        Returns the filename that the molecule was originally loaded from.
150

pjropp's avatar
pjropp committed
151
        Wrapper function for :meth:`~scoria.Information.Information.get_filename`
152 153 154
        
        :returns: The name of the file.

pjropp's avatar
pjropp committed
155
        :rtype: :any:`str`
156 157 158

        ::

pjropp's avatar
pjropp committed
159
            >>> mol = scoria.Molecule()
160
            >>> mol.load_pdb_into("single_frame.pdb")
jdurrant's avatar
jdurrant committed
161
            >>> print(mol.get_filename())
162 163
            single_frame.pdb
        """
164
        
jdurrant's avatar
jdurrant committed
165 166 167
        return self.information.get_filename()

    def get_remarks(self):
168 169
        """
        Returns the remarks from the file the molecule was loaded from.
170

pjropp's avatar
pjropp committed
171
        Wrapper function for :meth:`~scoria.Information.Information.get_remarks`
172 173 174
        
        :returns: The remarks from the file an a list of strings.

pjropp's avatar
pjropp committed
175
        :rtype: :any:`list`
176 177 178

        ::

pjropp's avatar
pjropp committed
179
            >>> mol = scoria.Molecule()
180
            >>> mol.load_pdb_into("single_frame.pdb")
jdurrant's avatar
jdurrant committed
181
            >>> print(mol.get_remarks())
182 183
            [' This is a remark.']
        """
184
        
jdurrant's avatar
jdurrant committed
185 186 187
        return self.information.get_remarks()

    def get_atom_information(self):
188
        """
189
        Retreives the atomic information for the molecule.
190

pjropp's avatar
pjropp committed
191
        Wrapper function for :meth:`~scoria.Information.Information.get_atom_information`
192 193 194

        :returns: A masked array containing the atom information.

pjropp's avatar
pjropp committed
195
        :rtype: :any:`numpy.ma.MaskedArray` 
196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220

        The contents of the array are as follows:

        ================ ===== ================= ==============================
        member name      dtype Full Type         Description
        ================ ===== ================= ==============================
        record_name      S6    six char string   What the atom belongs to
        serial           <i8   64-bit integer    The index of the atom
        name             S5    five char string  The atom name
        resname          S5    five char string  The residue name
        chainid          S1    one char string   The chain identifier
        resseq           <i8   64-bit integer    The Residue sequence number   
        occupancy        <f8   64-bit float      Occupancy of atom
        tempfactor       <f8   64-bit float      Tempature Factor
        element          S2    two char string   The element symbol
        charge           S3    three char string Charge on the atom
        name_stripped    S5    five char string  Atom name without space
        resname_stripped S5    five char string  Residue name without space
        chainid_stripped S1    one char string   Chain identifier without space
        element_stripped S2    two char string   Element symbol without space
        ================ ===== ================= ==============================

        An example for printing the elemental symbols of the first five atoms::

            >>> atom_info = mol.get_atom_information()
221
            >>> print(atom_info['element'][0:5])
222 223 224
            ['N' 'C' 'C' 'O' 'C']
        """

jdurrant's avatar
jdurrant committed
225 226 227
        return self.information.get_atom_information()

    def get_coordinates_undo_point(self):
228 229 230
        """
        NEEDS CLARIFICATION.
        Retreives a previously save set of coordinates to revert to.
231

pjropp's avatar
pjropp committed
232
        Wrapper function for :meth:`~scoria.Information.Information.get_coordinates_undo_point`
233 234 235

        :returns: A set of coordinates from which to return to.

pjropp's avatar
pjropp committed
236
        :rtype: :any:`numpy.array` or :any:`None`
237 238
        """

jdurrant's avatar
jdurrant committed
239 240 241
        return self.information.get_coordinates_undo_point()

    def get_bonds(self):
242 243
        """
        Retreives the bonds beteween atoms as a n x n matrix.
244
        
pjropp's avatar
pjropp committed
245
        Wrapper function for :meth:`~scoria.Information.Information.get_bonds`
246 247 248

        :returns: A binary n x n matrix, where bonds are represented by 1.

pjropp's avatar
pjropp committed
249
        :rtype: :any:`numpy.array`
250 251 252 253

        An example for finding all atoms bonded with atom 153::

            >>> bonds = mol.get_bonds()
pjropp's avatar
pjropp committed
254
            >>> for i in range(0,len(bonds)):
255
            ...     if bonds[153][i] == 1:
jdurrant's avatar
jdurrant committed
256
            ...             print(153,"-",i)
257 258 259 260
            153 - 152
            153 - 154
            153 - 155
        """
261
        
jdurrant's avatar
jdurrant committed
262 263 264
        return self.information.get_bonds()

    def get_hierarchy(self):
265 266
        """
        NEEDS CLARIFICATION.
267

pjropp's avatar
pjropp committed
268
        Wrapper function for :meth:`~scoria.Information.Information.get_hierarchy`
269 270 271

        :returns: A dictionary?

pjropp's avatar
pjropp committed
272
        :rtype: :any:`dict`
273
        """
274
        
jdurrant's avatar
jdurrant committed
275 276 277
        return self.information.get_hierarchy()

    def get_constants(self):
278 279
        """
        Returns a dictionary containing the constants assumed for the molecular model.
280
        
pjropp's avatar
pjropp committed
281
        Wrapper function for :meth:`~scoria.Information.Information.get_constants`
282 283 284

        :returns: The constants assumed by the model.

pjropp's avatar
pjropp committed
285
        :rtype: :any:`dict`
286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302

        ============================== =============== ===============================
        Dictionary Keys                Value Type      Contains
        ============================== =============== ===============================
        mass_dict                      dict{str:float} The mass of elements
        rna_residues                   list(str)       RNA residue names
        f8_fields                      list(str)       Atom Information floats
        vdw_dict                       dict{str:float} Van der Waals force of elements
        i8_fields                      list(str)       Atom Information integers
        protein_residues               list(str)       Protein residue names
        bond_length_dict               dict{str:float} Element-pair bond length 
        element_names_with_two_letters list(str)       Element symbols with 2 letters
        max_number_of_bonds_permitted  dict{str:int}   Max bonds per element
        dna_residues                   list(str)       DNA reside names
        ============================== =============== ===============================

        """
303
        
jdurrant's avatar
jdurrant committed
304 305
        return self.information.get_constants()

306
    def get_center_of_mass(self, selection = None, frame = None):
307
        """
308 309
        Determines the center of mass.

pjropp's avatar
pjropp committed
310
        Wrapper function for :meth:`~scoria.Information.Information.get_center_of_mass`
311 312 313

        :param numpy.array selection: The indices of
                          the atoms to consider when calculating the center of mass. 
pjropp's avatar
pjropp committed
314
                          If ommitted, all atoms of the scoria.Molecule object 
315 316
                          will be considered.

317
        :param int frame: The timestep at which the center of mass
318 319 320
                      should be calculated. If ommitted, it defaults to the first 
                      frame of the trajectory.
        
321
        :returns: The x, y, and z coordinates of the center of mass.
322

pjropp's avatar
pjropp committed
323
        :rtype: :any:`numpy.ma.MaskedArray`
324 325 326

        ::

pjropp's avatar
pjropp committed
327
            >>> mol = scoria.Molecule()
328
            >>> mol.load_pdb_into("single_frame.pdb")
jdurrant's avatar
jdurrant committed
329
            >>> print(mol.get_center_of_mass())
330
            [33.0643089093134 19.135747088722564 16.05629867850796]
331
        """
332
        
333
        return self.information.get_center_of_mass(selection, frame)
jdurrant's avatar
jdurrant committed
334

335
    def get_geometric_center(self, selection = None, frame = None):
336 337
        """
        Determines the geometric center of the molecule.
338

pjropp's avatar
pjropp committed
339
        Wrapper function for :meth:`~scoria.Information.Information.get_geometric_center`
340 341

        :param numpy.array selection: The indices of
342
                          the atoms to consider when calculating the geometric.
pjropp's avatar
pjropp committed
343
                          If ommitted, all atoms of the scoria.Molecule object
344 345
                          will be considered.

346 347
        :param int frame: The timestep at which the geometric center
                      should be calculated. If ommitted, it defaults to the first
348
                      frame of the trajectory.
349
        
350 351
        :returns: The x, y, and z coordinates of the geometric center.

pjropp's avatar
pjropp committed
352
        :rtype: :any:`numpy.array`
353 354 355

        ::

pjropp's avatar
pjropp committed
356
            >>> mol = scoria.Molecule()
357
            >>> mol.load_pdb_into("single_frame.pdb")
jdurrant's avatar
jdurrant committed
358
            >>> print(mol.get_geometric_center())
359 360 361
            [ 33.09860848  19.1221197   16.0426808 ]
        """

362
        return self.information.get_geometric_center(selection, frame)
jdurrant's avatar
jdurrant committed
363 364

    def get_total_mass(self, selection = None):
365 366 367
        """
        Returns the total mass of all atoms within the molecule, or of a given 
        selection. 
368

pjropp's avatar
pjropp committed
369
        Wrapper function for :meth:`~scoria.Information.Information.get_total_mass`
370 371 372

        :param numpy.array selection: The indices of
                        the atoms to consider when calculating the geometric. 
pjropp's avatar
pjropp committed
373
                        If ommitted, all atoms of the scoria.Molecule object
374 375 376 377
                        will be considered.

        :returns: The total mass of the atom or selection

pjropp's avatar
pjropp committed
378
        :rtype: :any:`float`
379

380 381
        ::

jdurrant's avatar
jdurrant committed
382
            >>> print(mol.get_total_mass())
383 384 385
            5289.1729999999998

        """
386
        
jdurrant's avatar
jdurrant committed
387 388 389
        return self.information.get_total_mass(selection)

    def get_total_number_of_atoms(self, selection = None):
390 391 392 393
        """
        Counts the number of atoms.
        
        Wrapper function for 
pjropp's avatar
pjropp committed
394
        :meth:`~scoria.Information.Information.get_total_number_of_atoms`
395 396 397

        :param numpy.array selection: An optional numpy.array containing the indices of
                    the atoms to count. If ommitted, all atoms of the
pjropp's avatar
pjropp committed
398
                    scoria.Molecule object will be considered.
399 400 401 402 403
        :param int frame: An integer indicating at which timestep the center of
                    mass should be calculated. If ommitted, it defaults to the 
                    first frame of the trajectory.

        :returns:  The total number of atoms.
pjropp's avatar
pjropp committed
404
        :rtype: :any:`int`
405
        """
406
        
jdurrant's avatar
jdurrant committed
407 408 409
        return self.information.get_total_number_of_atoms(selection)

    def get_total_number_of_heavy_atoms(self, selection = None):
410 411 412 413 414
        """
        Counts the number of heavy atoms (i.e., atoms that are not
        hydrogens). 

        Wrapper function for 
pjropp's avatar
pjropp committed
415
        :meth:`~scoria.Information.Information.get_total_number_of_heavy_atoms`
416 417 418

        :param numpy.array selection: An optional numpy.array containing the indices of
                    the atoms to count. If ommitted, all atoms of the
pjropp's avatar
pjropp committed
419
                    scoria.Molecule object will be considered.
420 421

        :returns: The total number of heavy (non-hydrogen) atoms.
pjropp's avatar
pjropp committed
422
        :rtype: :any:`int`
423
        """
424
        
jdurrant's avatar
jdurrant committed
425 426
        return self.information.get_total_number_of_heavy_atoms(selection)

427
    def get_bounding_box(self, selection = None, padding = 0.0, frame = None):
428 429 430
        """
        Calculates a box that bounds (encompasses) a set of atoms.

pjropp's avatar
pjropp committed
431
        Wrapper function for :meth:`~scoria.Information.Information.get_bounding_box`
432 433 434

        :param numpy.array selection: An optional numpy.array containing the indices of
                    the atoms to consider. If ommitted, all atoms of the
pjropp's avatar
pjropp committed
435
                    scoria.Molecule object will be considered.
436 437 438 439 440 441 442 443
        :param float padding: An optional float. The bounding box will extend this
                    many angstroms beyond the atoms being considered.
        :param int frame: An integer indicating at which timestep the center of
                    mass should be calculated. If ommitted, it defaults to the 
                    first frame of the trajectory.

        :returns: A numpy array representing two 3D points, (min_x, min_y, min_z)
                    and (max_x, max_y, max_z), that bound the molecule.
pjropp's avatar
pjropp committed
444
        :rtype: :any:`numpy.array`
445
        """
446
        
447
        return self.information.get_bounding_box(selection, padding, frame)
jdurrant's avatar
jdurrant committed
448

449
    def get_bounding_sphere(self, selection = None, padding = 0.0, frame = None):
450 451
        """
        Calculates a sphere that bounds (encompasses) a set of atoms.
452 453 454

        Requires the :any:`numpy` and :any:`scipy<scipy.spatial>` libraries.

pjropp's avatar
pjropp committed
455
        Wrapper function for :meth:`~scoria.Information.Information.get_bounding_sphere`
456 457 458

        :param numpy.array selection: An optional numpy.array containing the indices of
                    the atoms to consider. If ommitted, all atoms of the
pjropp's avatar
pjropp committed
459
                    scoria.Molecule object will be considered.
460 461 462 463 464 465 466 467 468
        :param float padding: An optional float. The bounding sphere will extend
                    this many angstroms beyond the atoms being considered.
        :param int frame: An integer indicating at which timestep the center of
                    mass should be calculated. If ommitted, it defaults to the 
                    first frame of the trajectory.

        :returns: A tuple containing two elements. The first is a numpy.array
                    representing a 3D point, the (x, y, z) center of the
                    sphere. The second is a float, the radius of the sphere.
pjropp's avatar
pjropp committed
469
        :rtype: :any:`tuple` (:any:`numpy.array`, :any:`float`)
470 471 472
        """
        
        return self.information.get_bounding_sphere(selection, padding, frame)
jdurrant's avatar
jdurrant committed
473

474 475 476 477
    def get_default_trajectory_frame(self):
        """
        Retreives the default trajectory frame index.

pjropp's avatar
pjropp committed
478
        Wrapper function for :meth:`~scoria.Information.Information.get_default_trajectory_frame`
479 480 481 482 483 484 485

        :returns: An *int* representing the index of the default trajectory frame.
        """

        return self.information.get_default_trajectory_frame()


jdurrant's avatar
jdurrant committed
486 487
    # Set
    def set_filename(self, filename):
488 489 490 491
        """
        Sets the __filename variable. Note: this does not reload or modify the
        molecule in anyway.
        
pjropp's avatar
pjropp committed
492
        Wrapper function for :meth:`~scoria.Information.Information.set_filename`
493 494 495
         
        :param str filename: String representation of the filename.
        """
496
        
jdurrant's avatar
jdurrant committed
497 498 499
        self.information.set_filename(filename)

    def set_remarks(self, remarks):
500 501 502
        """
        Sets the __remarks variable.
        
pjropp's avatar
pjropp committed
503
        Wrapper function for :meth:`~scoria.Information.Information.set_remarks`
504 505 506

        :param list(str) remarks: List containing remarks.
        """
507
        
jdurrant's avatar
jdurrant committed
508 509 510
        self.information.set_remarks(remarks)

    def set_atom_information(self, atom_information):
511 512
        """
        Sets the __atom_information variable. See 
pjropp's avatar
pjropp committed
513
        :meth:`~scoria.Molecule.Molecule.get_atom_information` for
514 515
        information on the numpy.array structure.
        
pjropp's avatar
pjropp committed
516
        Wrapper function for :meth:`~scoria.Information.Information.set_atom_information`
517 518 519 520

        :param numpy.array atom_information: An array containing details
                            on the constituent atoms. 
        """
521
        
jdurrant's avatar
jdurrant committed
522 523
        self.information.set_atom_information(atom_information)

524
    def set_coordinates(self, coordinates, frame = None):
525 526 527
        """
        Sets a specified frame of the __trajectory variable.
        
pjropp's avatar
pjropp committed
528
        Wrapper function for :meth:`~scoria.Information.Information.set_coordinates`
529 530 531 532
        
        :param numpy.array coordinates: An array of atomic coordinates.
        :param int frame: An integer represeting the frame of the trajectory to be modified
        """
533
        
534 535
        self.information.set_coordinates(coordinates, frame)

536
    def set_trajectory_coordinates(self, trajectory):
537 538 539
        """
        Sets the __trajectory variable.
        
pjropp's avatar
pjropp committed
540
        Wrapper function for :meth:`~scoria.Information.Information.set_trajectory_coordinates`
541 542 543

        :param numpy.array trajectory: An array of atomic coordinates.
        """
544

545
        self.information.set_trajectory_coordinates(trajectory)
jdurrant's avatar
jdurrant committed
546 547

    def set_coordinates_undo_point(self, coordinates_undo_point):
548 549 550
        """
        Sets the __coordinates_undo_point variable.
        
pjropp's avatar
pjropp committed
551
        Wrapper function for :meth:`~scoria.Information.Information.set_coordinates_undo_point`
552 553 554 555
        
        :param numpy.array coordinates_undo_point: A coordinate set to revert 
            to after modification.
        """
556
        
jdurrant's avatar
jdurrant committed
557 558 559
        self.information.set_coordinates_undo_point(coordinates_undo_point)

    def set_bonds(self, bonds):
560 561
        """
        Sets the __bonds variable. See 
pjropp's avatar
pjropp committed
562
        :meth:`~scoria.Molecule.Molecule.get_bonds` for additional 
563 564
        information.
        
pjropp's avatar
pjropp committed
565
        Wrapper function for :meth:`~scoria.Information.Information.set_bonds`
566 567 568 569
        
        :param numpy.array bonds: A binary n x n matrix containing bonding 
            information.
        """
570
        
jdurrant's avatar
jdurrant committed
571 572 573
        self.information.set_bonds(bonds)

    def set_hierarchy(self, hierarchy):
574 575 576
        """
        DEPRECIATED?
        
pjropp's avatar
pjropp committed
577
        Wrapper function for :meth:`~scoria.Information.Information.set_hierarchy`
578
        """
579
        
jdurrant's avatar
jdurrant committed
580 581
        self.information.set_hierarchy(hierarchy)

582 583 584 585
    def set_default_trajectory_frame(self, frame):
        """
        Set's the default trajectory frame for various calculations. 

pjropp's avatar
pjropp committed
586
        Wrapper function for :meth:`~scoria.Information.Information.set_default_trajectory_frame`
587 588 589 590 591 592

        :param int frame: The default frame for coordinate selection.
        """

        self.information.set_default_trajectory_frame(frame)

jdurrant's avatar
jdurrant committed
593 594
    # Information functions
    def assign_masses(self):
595
        """
pjropp's avatar
pjropp committed
596
        Assigns masses to the atoms of the scoria.Molecule object. 
597

pjropp's avatar
pjropp committed
598
        Wrapper function for :meth:`~scoria.Information.Information.assign_masses`
599

pjropp's avatar
pjropp committed
600
        ``Note``:
601 602 603
        This will autopopulate the masses according to their element 
        identification and takes no input.
        """
604
        
jdurrant's avatar
jdurrant committed
605 606 607
        self.information.assign_masses()

    def assign_elements_from_atom_names(self, selection = None):
608 609 610 611 612 613
        """
        Determines the elements of all atoms from the atom names. Note that
        this will overwrite any existing element assignments, including those
        explicitly specified in loaded files. Note that this doesn't populate
        elements_stripped.

pjropp's avatar
pjropp committed
614
        Wrapper function for :meth:`~scoria.Information.Information.assign_elements_from_atom_names`
615 616 617

        :param numpy.array selection: An optional numpy.array containing the indices of
                    the atoms to consider when calculating the center of mass.
pjropp's avatar
pjropp committed
618
                    If ommitted, all atoms of the scoria.Molecule object
619 620
                    will be considered.
        """
621
        
jdurrant's avatar
jdurrant committed
622 623 624
        self.information.assign_elements_from_atom_names(selection)

    def define_molecule_chain_residue_spherical_boundaries(self):
625 626 627
        """
        Identifies spheres that bound (encompass) the entire molecule, the
        chains, and the residues. This information is stored in
pjropp's avatar
pjropp committed
628
        scoria.Information.Information.hierarchy.
629

630 631
        Requires the :any:`numpy` and :any:`scipy<scipy.spatial>` libraries.

632
        Wrapper function for 
pjropp's avatar
pjropp committed
633
        :meth:`~scoria.Information.Information.define_molecule_chain_residue_spherical_boundaries`
634
        """
635
        
jdurrant's avatar
jdurrant committed
636 637 638
        self.information.define_molecule_chain_residue_spherical_boundaries()

    def serial_reindex(self):
639 640 641 642
        """
        Reindexes the serial field of the atoms in the molecule, starting
        with 1.
        
pjropp's avatar
pjropp committed
643
        Wrapper function for :meth:`~scoria.Information.Information.serial_reindex`
644
        """
645
        
jdurrant's avatar
jdurrant committed
646 647 648
        self.information.serial_reindex()

    def resseq_reindex(self):
649 650 651 652
        """
        Reindexes the resseq field of the atoms in the molecule, starting
        with 1.

pjropp's avatar
pjropp committed
653
        Wrapper function for :meth:`~scoria.Information.Information.resseq_reindex`
654
        """
655
        
jdurrant's avatar
jdurrant committed
656
        self.information.resseq_reindex()
657 658
    
    def belongs_to_protein(self, atom_index):
659 660 661 662
        """
        Checks if the atom is part of a protein. Taken primarily from Amber
        residue names.

pjropp's avatar
pjropp committed
663
        Wrapper function for :meth:`~scoria.Information.Information.belongs_to_protein`
664 665 666 667 668
        
        :param int atom_index: An int, the index of the atom to consider.

        :returns: A boolean. True if part of protein, False if not.
        """
669 670 671 672
        
        return self.information.belongs_to_protein(atom_index)

    def belongs_to_rna(self, atom_index):
673 674 675
        """
        Checks if the atom is part of RNA.

pjropp's avatar
pjropp committed
676
        Wrapper function for :meth:`~scoria.Information.Information.belongs_to_rna`
677 678 679 680 681 682

        :param int atom_index: An int, the index of the atom to consider.

        :returns: A boolean. True if part of rna, False if not.

        """
683 684 685 686
        
        return self.information.belongs_to_rna(atom_index)

    def belongs_to_dna(self, atom_index):
687 688 689
        """
        Checks if the atom is part of DNA.

pjropp's avatar
pjropp committed
690
        Wrapper function for :meth:`~scoria.Information.Information.belongs_to_dna`
691 692 693 694 695

        :param int atom_index: An int, the index of the atom to consider.

        :returns: A boolean. True if part of dna, False if not.
        """
696 697
        
        return self.information.belongs_to_dna(atom_index)
jdurrant's avatar
jdurrant committed
698

699
    def insert_trajectory_frame(self, index, coordinates):
700 701 702
        """
        Inserts a new coordinate frame at the end of the trajectory.

pjropp's avatar
pjropp committed
703
        Wrapper function for :meth:`~scoria.Information.Information.insert_trajectory_frame`
704 705 706 707

        :param numpy.array coordinates: A single frame of coordinates to append.
        :param int index: The location where the frame should be added.
        """
708 709 710 711

        return self.information.insert_trajectory_frame(index, coordinates)
    
    def delete_trajectory_frame(self, index):
712 713 714
        """
        Removes a given frame from the trajectory.
  
pjropp's avatar
pjropp committed
715
        Wrapper function for :meth:`~scoria.Information.Information.delete_trajectory_frame`
716 717 718

        :param int index: Integer of the frame to remove.
        """
719 720 721 722

        return self.information.delete_trajectory_frame(index)

    def get_trajectory_frame_count(self):
723 724 725
        """
        Returns the number of frames in __trajectory.

pjropp's avatar
pjropp committed
726
        Wrapper function for :meth:`~scoria.Information.Information.get_trajectory_frame_count`
727 728

        :returns: The number of frames in the trajectory.
pjropp's avatar
pjropp committed
729
        :rtype: :any:`int`
730
        """
731 732 733

        return self.information.get_trajectory_frame_count()

jdurrant's avatar
jdurrant committed
734 735
    # File I/O class methods
    def load_pym_into(self, filename):
736 737
        """
        Loads the molecular data contained in a pym file into the current
pjropp's avatar
pjropp committed
738
        scoria.Molecule object.
739

740 741
        Requires the :any:`numpy` library.

pjropp's avatar
pjropp committed
742
        Wrapper function for :meth:`~scoria.FileIO.FileIO.load_pym_into`
743 744 745

        :param str filename: A string, the filename of the pym file.
        """
746
        
jdurrant's avatar
jdurrant committed
747 748
        self.fileio.load_pym_into(filename)

749
    def load_pdb_into(self, filename, bonds_by_distance = True,
750 751
                      serial_reindex = True, resseq_reindex = False,
                      is_trajectory = False):
752 753
        """
        Loads the molecular data contained in a pdb file into the current
pjropp's avatar
pjropp committed
754
        scoria.Molecule object.
755

pjropp's avatar
pjropp committed
756
        Wrapper function for :meth:`~scoria.FileIO.FileIO.load_pdb_into`
757 758 759

        :param str filename: A string, the filename of the pdb file.
        :param bool bonds_by_distance: An optional boolean, whether or not to
760
                    determine atomic bonds based on atom proximity. True by
761 762 763 764 765
                    default.
        :param bool serial_reindex: An optional boolean, whether or not to
                    reindex the pdb serial field. True by default.
        :param bool resseq_reindex: An optional boolean, whether or not to
                    reindex the pdb resseq field. False by default.
766 767
        :param bool is_trajectory: An optional boolean, whether or not the PDB
                    is multi-frame.
768
        """
jdurrant's avatar
jdurrant committed
769 770

        self.fileio.load_pdb_into(
771 772
            filename, bonds_by_distance, serial_reindex,
            resseq_reindex, is_trajectory
jdurrant's avatar
jdurrant committed
773 774 775
        )

    def load_pdb_into_using_file_object(self, file_obj,
776
                                        bonds_by_distance = True,
jdurrant's avatar
jdurrant committed
777
                                        serial_reindex = True,
778 779
                                        resseq_reindex = False,
                                        is_trajectory = False):
780 781
        """
        Loads molecular data from a python file object (pdb formatted) into
pjropp's avatar
pjropp committed
782
        the current scoria.Molecule object. Note that most users will want
783 784 785
        to use the load_pdb_into() function instead, which is identical except
        that it accepts a filename string instead of a python file object.

786 787
        Requires the :any:`numpy` library.

pjropp's avatar
pjropp committed
788
        Wrapper function for :meth:`~scoria.FileIO.FileIO.load_pdb_into_using_file_object`
789 790 791 792

        :param file file_obj: A python file object, containing pdb-formatted
                    data.
        :param bool bonds_by_distance: An optional boolean, whether or not to
793
                    determine atomic bonds based on atom proximity. True by
794 795 796 797 798
                    default.
        :param bool serial_reindex: An optional boolean, whether or not to
                    reindex the pdb serial field. True by default.
        :param bool resseq_reindex: An optional boolean, whether or not to
                    reindex the pdb resseq field. False by default.
799 800
        :param bool is_trajectory: An optional boolean, whether or not the PDB
                    is multi-frame.
801
        """
jdurrant's avatar
jdurrant committed
802 803

        self.fileio.load_pdb_into_using_file_object(
804 805
            file_obj, bonds_by_distance, serial_reindex,
            resseq_reindex, is_trajectory
jdurrant's avatar
jdurrant committed
806 807
        )

808
    def load_pdbqt_into(self, filename, bonds_by_distance = False,
809 810
                      serial_reindex = True, resseq_reindex = False,
                      is_trajectory = False):
811 812
        """
        Loads the molecular data contained in a pdbqt file into the current
pjropp's avatar
pjropp committed
813
        scoria.Molecule object. Note that this implementation is
814
        incomplete. It doesn't save atomic charges, for example. The atom
815
        types are stored in the "element_padded" and "element" columns.
816

pjropp's avatar
pjropp committed
817
        Wrapper function for :meth:`~scoria.FileIO.FileIO.load_pdbqt_into`
818 819 820 821 822 823 824 825 826

        :param str filename: A string, the filename of the pdbqt file.
        :param bool bonds_by_distance: An optional boolean, whether or not to
                    determine atomic bonds based on atom proximity. False by
                    default, unlike for PDB.
        :param bool serial_reindex: An optional boolean, whether or not to
                    reindex the pdb serial field. True by default.
        :param bool resseq_reindex: An optional boolean, whether or not to
                    reindex the pdbqt resseq field. False by default.
827 828
        :param bool is_trajectory: An optional boolean, whether or not the PDB
                    is multi-frame. Defaults of False.
829
        """
830 831

        self.fileio.load_pdbqt_into(
832 833
            filename, bonds_by_distance, serial_reindex, resseq_reindex,
            is_trajectory = is_trajectory
834 835
        )

836
    def load_pdbqt_into_using_file_object(self, file_obj,
jdurrant's avatar
jdurrant committed
837
                                        bonds_by_distance = False,
838
                                        serial_reindex = True,
839 840
                                        resseq_reindex = False,
                                        is_trajectory = False):
841 842
        """
        Loads molecular data from a python file object (pdbqt formatted)
pjropp's avatar
pjropp committed
843
        into the current scoria.Molecule object. Note that most users will
844 845 846 847
        want to use the load_pdb_into() function instead, which is identical
        except that it accepts a filename string instead of a python file
        object.

848 849
        Requires the :any:`numpy` library.

pjropp's avatar
pjropp committed
850
        Wrapper function for :meth:`~scoria.FileIO.FileIO.load_pdbqt_into_using_file_object`
851 852 853 854 855 856 857 858 859 860

        :param file file_obj: A python file object, containing pdb-formatted
                    data.
        :param bool bonds_by_distance: An optional boolean, whether or not to
                    determine atomic bonds based on atom proximity. False by
                    default, unlike for PDB.
        :param bool serial_reindex: An optional boolean, whether or not to
                    reindex the pdb serial field. True by default.
        :param bool resseq_reindex: An optional boolean, whether or not to
                    reindex the pdb resseq field. False by default.
861 862
        :param bool is_trajectory: An optional boolean, whether or not the PDB
                    is multi-frame. Defaults of False.
863
        """
864 865

        self.fileio.load_pdbqt_into_using_file_object(
866 867
            file_obj, bonds_by_distance, serial_reindex, resseq_reindex,
            is_trajectory = is_trajectory
868
        )
869

jdurrant's avatar
jdurrant committed
870 871 872
    def save_pym(self, filename, save_bonds = False, save_filename = False,
                 save_remarks = False, save_hierarchy = False,
                 save_coordinates_undo_point = False):
873
        """
pjropp's avatar
pjropp committed
874
        Saves the molecular data contained in a scoria.Molecule object
875 876
        to a pym file.

877 878
        Requires the :any:`numpy` library.

pjropp's avatar
pjropp committed
879
        Wrapper function for :meth:`~scoria.FileIO.FileIO.save_pym`
880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895

        :param str filename: An string, the filename to use for saving. (Note
                    that this is actually a directory, not a file.)
        :param bool save_bonds: An optional boolean, whether or not to save
                    information about atomic bonds. False by default.
        :param bool save_filename: An optional boolean, whether or not to save
                    the original (pdb) filename. False by default.
        :param bool save_remarks: An optional boolean, whether or not to save
                    remarks associated with the molecule. False by default.
        :param bool save_hierarchy: An optional boolean, whether or not to save
                    information about spheres the bound (encompass) the whole
                    molecule, the chains, and the residues. False by default.
        :param bool save_coordinates_undo_point: An optional boolean, whether or
                    not to save the last coordinate undo point. False by
                    default.
        """
jdurrant's avatar
jdurrant committed
896 897 898 899 900 901 902

        self.fileio.save_pym(
            filename, save_bonds, save_filename, save_remarks,
            save_hierarchy, save_coordinates_undo_point
        )

    def save_pdb(self, filename = "", serial_reindex = True,
903
                 resseq_reindex = False, return_text = False, frame = None):
904
        """
pjropp's avatar
pjropp committed
905
        Saves the molecular data contained in a scoria.Molecule object
906 907
        to a pdb file.

pjropp's avatar
pjropp committed
908
        Wrapper function for :meth:`~scoria.FileIO.FileIO.save_pdb`
909 910 911 912 913 914 915 916 917

        :param str filename: An string, the filename to use for saving.
        :param bool serial_reindex: An optional boolean, whether or not to
                    reindex the pdb serial field. True by default.
        :param bool resseq_reindex: An optional boolean, whether or not to
                    reindex the pdb resseq field. False by default.
        :param bool return_text: An optional boolean, whether or not to return
                    text instead of writing to a file. If True, the filename
                    variable is ignored.
918 919 920 921 922
        :param int frame: If specified, a single-frame PDB will be generated.
                    If not specified, a multi-frame PDB will be generated if 
                    the Molecule has multiple frames. Otherwise, the single
                    existing frame will be used.

923 924 925

        :returns: If return_text is True, a PDB-formatted string. Otherwise,
                returns nothing.
pjropp's avatar
pjropp committed
926
        :rtype: :any:`str` or :any:`None`
927
        """
jdurrant's avatar
jdurrant committed
928

929
        return self.fileio.save_pdb(
930
            filename, serial_reindex, resseq_reindex, return_text, frame
jdurrant's avatar
jdurrant committed
931 932
        )

933
    def load_pdbqt_trajectory_into(self, filename, bonds_by_distance = True,
934 935 936 937
                                   serial_reindex = True, 
                                   resseq_reindex = False):
        """
        Loads the molecular data contained in a pdbqt trajectoy file (e.g., an
pjropp's avatar
pjropp committed
938
        AutoDock Vina output file) into the current scoria.Molecule
939 940
        object.

pjropp's avatar
pjropp committed
941
        Should be called via the wrapper function :meth:`scoria.Molecule.Molecule.load_pdbqt_trajectory_into`
942 943 944

        :param str filename: A string, the filename of the pdbqt file.
        :param bool bonds_by_distance: An optional boolean, whether or not to
945
                    determine atomic bonds based on atom proximity. True by
946 947 948 949 950 951 952 953 954 955 956 957 958
                    default.
        :param bool serial_reindex: An optional boolean, whether or not to
                    reindex the pdb serial field. True by default.
        :param bool resseq_reindex: An optional boolean, whether or not to
                    reindex the pdb resseq field. False by default.
        """

        return self.fileio.load_pdbqt_trajectory_into(filename, 
                                             bonds_by_distance, 
                                             serial_reindex, 
                                             resseq_reindex)
        
    def load_pdbqt_trajectory_into_using_file_object(self, file_obj,
959
                                                     bonds_by_distance = True,
960 961 962 963
                                                     serial_reindex = True,
                                                     resseq_reindex = False):
        """
        Loads molecular data from a python file object (pdbqt trajectory
pjropp's avatar
pjropp committed
964
        formatted) into the current scoria.Molecule object. Note that most
965 966 967 968 969
        users will want to use the load_pdbqt_trajectory_into() function
        instead, which is identical except that it accepts a filename string
        instead of a python file object.

        Wrapper function for
pjropp's avatar
pjropp committed
970
        :meth:`~scoria.FileIO.FileIO.load_pdbqt_trajectory_into_using_file_object`
971 972 973 974

        :param file file_obj: A python file object, containing pdbqt-formatted
                    trajectory data.
        :param bool bonds_by_distance: An optional boolean, whether or not to
975
                    determine atomic bonds based on atom proximity. True by
976 977 978 979 980 981 982 983 984 985 986 987
                    default.
        :param bool serial_reindex: An optional boolean, whether or not to
                    reindex the pdb serial field. True by default.
        :param bool resseq_reindex: An optional boolean, whether or not to
                    reindex the pdb resseq field. False by default.
        """

        return self.fileio.load_pdbqt_trajectory_into_using_file_object(file_obj,
                                                     bonds_by_distance,
                                                     serial_reindex,
                                                     resseq_reindex)