Source code for MDAnalysis.coordinates.PQR

# -*- Mode: python; tab-width: 4; indent-tabs-mode:nil; coding:utf-8 -*-
# vim: tabstop=4 expandtab shiftwidth=4 softtabstop=4
#
# MDAnalysis --- https://www.mdanalysis.org
# Copyright (c) 2006-2017 The MDAnalysis Development Team and contributors
# (see the file AUTHORS for the full list of names)
#
# Released under the GNU Public Licence, v2 or any higher version
#
# Please cite your use of MDAnalysis in published work:
#
# R. J. Gowers, M. Linke, J. Barnoud, T. J. E. Reddy, M. N. Melo, S. L. Seyler,
# D. L. Dotson, J. Domanski, S. Buchoux, I. M. Kenney, and O. Beckstein.
# MDAnalysis: A Python package for the rapid analysis of molecular dynamics
# simulations. In S. Benthall and S. Rostrup editors, Proceedings of the 15th
# Python in Science Conference, pages 102-109, Austin, TX, 2016. SciPy.
# doi: 10.25080/majora-629e541a-00e
#
# N. Michaud-Agrawal, E. J. Denning, T. B. Woolf, and O. Beckstein.
# MDAnalysis: A Toolkit for the Analysis of Molecular Dynamics Simulations.
# J. Comput. Chem. 32 (2011), 2319--2327, doi:10.1002/jcc.21787
#


"""
PQR file format --- :mod:`MDAnalysis.coordinates.PQR`
=====================================================

Read atoms with charges from a PQR_ file (as written by PDB2PQR_). The
following is adopted from the description of the PQR_ format as used by APBS_:

*MDAnalysis* reads very loosely-formatted PQR files: all fields are
**whitespace-delimited** rather than the strict column formatting mandated
by the PDB_ format. This more liberal formatting allows coordinates
which are larger/smaller than ±999 Å.

MDAnalysis reads data on a per-line basis from PQR files using the following format::

   recordName serial atomName residueName chainID residueNumber X Y Z charge radius

If this fails it is assumed that the *chainID* was omitted and the shorter
format is read::

   recordName serial atomName residueName residueNumber X Y Z charge radius

Anything else will raise a :exc:`ValueError`.

The whitespace is the most important feature of this format: fields
*must* be separated by at least one space or tab character. The fields
are:

*recordName*
    A string which specifies the type of PQR entry and should either be ATOM or
    HETATM.
*serial*
    An integer which provides the atom index (but note that MDAnalysis renumbers
    atoms so one cannot rely on the *serial*)
*atomName*
    A string which provides the atom name.
*residueName*
    A string which provides the residue name.
*chainID*
    An optional string which provides the chain ID of the atom.
*residueNumber*
    An integer which provides the residue index.
*X Y Z*
    Three floats which provide the atomic coordiantes.
*charge*
    A float which provides the atomic charge (in electrons).
*radius*
    A float which provides the atomic radius (in Å).

Clearly, this format can deviate wildly from PDB_ due to the use of whitespaces
rather than specific column widths and alignments. This deviation can be
particularly significant when large coordinate values are used.

Output should look like this (although the only real requirement is
*whitespace* separation between *all* entries). The chainID is optional
and can be omitted::

  ATOM      1  N    MET     1     -11.921   26.307   10.410 -0.3000 1.8500
  ATOM     36  NH1  ARG     2      -6.545   25.499    3.854 -0.8000 1.8500
  ATOM     37 HH11  ARG     2      -6.042   25.480    4.723  0.4600 0.2245


.. Warning:: Fields *must be white-space separated* or data are read
             incorrectly. PDB formatted files are *not* guaranteed to be
             white-space separated so extra care should be taken when quickly
             converting PDB files into PQR files using simple scripts.

For example, PQR files created with PDB2PQR_ and the `--whitespace`
option are guaranteed to conform to the above format::

   pdb2pqr --ff=charmm --whitespace 4ake.pdb 4ake.pqr


Notes
-----
The PQR format does not provide a means by which to provide box information.
In all cases the `dimensions` attribute will be set to `None`.


.. _PQR:     https://apbs-pdb2pqr.readthedocs.io/en/latest/formats/pqr.html
.. _APBS:    https://apbs-pdb2pqr.readthedocs.io/en/latest/apbs/index.html
.. _PDB2PQR: https://apbs-pdb2pqr.readthedocs.io/en/latest/pdb2pqr/index.html
.. _PDB:     http://www.wwpdb.org/documentation/file-format
"""
import itertools
import numpy as np
import warnings

from ..lib import util
from . import base


[docs]class PQRReader(base.SingleFrameReaderBase): """Read a PQR_ file into MDAnalysis. .. _PQR: https://apbs-pdb2pqr.readthedocs.io/en/latest/formats/pqr.html .. versionchanged:: 0.11.0 Frames now 0-based instead of 1-based """ format = 'PQR' units = {'time': None, 'length': 'Angstrom'} # how to slice fields[x:y] to grab coordinates _SLICE_INDICES = { 'ORIGINAL': (-5, -2), 'NO_CHAINID': (-5, -2), 'GROMACS': (-6, -3), } def _read_first_frame(self): from ..topology.PQRParser import PQRParser flavour = None coords = [] with util.openany(self.filename) as pqrfile: for line in pqrfile: if line.startswith(('ATOM', 'HETATM')): if flavour is None: flavour = PQRParser.guess_flavour(line) x, y = self._SLICE_INDICES[flavour] fields = line.split() # convert all entries at the end once for optimal speed coords.append(fields[x:y]) self.n_atoms = len(coords) self.ts = self._Timestep.from_coordinates( coords, **self._ts_kwargs) self.ts.frame = 0 # 0-based frame number if self.convert_units: # in-place ! self.convert_pos_from_native(self.ts._pos)
[docs] def Writer(self, filename, **kwargs): """Returns a PQRWriter for *filename*. Parameters ---------- filename : str filename of the output PQR file Returns ------- :class:`PQRWriter` """ return PQRWriter(filename, **kwargs)
[docs]class PQRWriter(base.WriterBase): """Write a single coordinate frame in whitespace-separated PQR format. Charges ("Q") are taken from the :attr:`MDAnalysis.core.groups.Atom.charge` attribute while radii are obtaine from the :attr:`MDAnalysis.core.groups.Atom.radius` attribute. * If the segid is 'SYSTEM' then it will be set to the empty string. Otherwise the first letter will be used as the chain ID. * The serial number always starts at 1 and increments sequentially for the atoms. The output format is similar to ``pdb2pqr --whitespace``. .. versionadded:: 0.9.0 .. versionchanged:: 2.6.0 Files are now written in `wt` mode, and keep extensions, allowing for files to be written under compressed formats """ format = 'PQR' units = {'time': None, 'length': 'Angstrom'} # serial, atomName, residueName, chainID, residueNumber, XYZ, charge, radius fmt_ATOM = ("ATOM {serial:6d} {name:<4} {resname:<3} {chainid:1.1}" " {resid:4d} {pos[0]:-8.3f} {pos[1]:-8.3f}" " {pos[2]:-8.3f} {charge:-7.4f} {radius:6.4f}\n") fmt_remark = "REMARK {0} {1}\n" def __init__(self, filename, convert_units=True, **kwargs): """Set up a PQRWriter with full whitespace separation. Parameters ---------- filename : str output filename convert_units: bool (optional) units are converted to the MDAnalysis base format; [``True``] remarks : str (optional) remark lines (list of strings) or single string to be added to the top of the PQR file """ self.filename = util.filename(filename, ext='pqr', keep=True) self.convert_units = convert_units # convert length and time to base units self.remarks = kwargs.pop('remarks', "PQR file written by MDAnalysis")
[docs] def write(self, selection, frame=None): """Write selection at current trajectory frame to file. Parameters ---------- selection : AtomGroup or Universe MDAnalysis AtomGroup or Universe frame : int (optional) optionally move to frame index `frame`; by default, write the current frame .. versionchanged:: 0.11.0 Frames now 0-based instead of 1-based """ # write() method that complies with the Trajectory API try: u = selection.universe except AttributeError: errmsg = "Input obj is neither an AtomGroup or Universe" raise TypeError(errmsg) from None if frame is not None: u.trajectory[frame] # advance to frame else: try: frame = u.trajectory.ts.frame except AttributeError: frame = 0 # should catch cases when we are analyzing a single frame(?) atoms = selection.atoms # make sure to use atoms (Issue 46) coordinates = atoms.positions # can write from selection == Universe (Issue 49) if self.convert_units: self.convert_pos_to_native(coordinates) # inplace because coordinates is already a copy # Check atom attributes # required: # - name # - resname # - chainid # - resid # - position # - charge # - radius attrs = {} missing_topology = [] for attr, dflt in ( ('names', itertools.cycle(('X',))), ('resnames', itertools.cycle(('UNK',))), ('resids', itertools.cycle((1,))), ('charges', itertools.cycle((0.0,))), ('radii', itertools.cycle((1.0,))), ): try: attrs[attr] = getattr(atoms, attr) except AttributeError: attrs[attr] = dflt missing_topology.append(attr) # chainids require special handling # try chainids, then segids # if neither, use ' ' # if 'SYSTEM', use ' ' try: attrs['chainids'] = atoms.chainids except AttributeError: try: attrs['chainids'] = atoms.segids except AttributeError: pass if not 'chainids' in attrs or all(attrs['chainids'] == 'SYSTEM'): attrs['chainids'] = itertools.cycle((' ',)) if 'charges' in missing_topology: total_charge = 0.0 else: total_charge = atoms.total_charge() if missing_topology: warnings.warn( "Supplied AtomGroup was missing the following attributes: " "{miss}. These will be written with default values. " "".format(miss=', '.join(missing_topology))) with util.openany(self.filename, 'wt') as pqrfile: # Header / Remarks # The *remarknumber* is typically 1 but :program:`pdb2pgr` # also uses 6 for the total charge and 5 for warnings. for rem in util.asiterable(self.remarks): pqrfile.write(self.fmt_remark.format(rem, 1)) pqrfile.write(self.fmt_remark.format( "Input: frame {0} of {1}".format(frame, u.trajectory.filename), 5)) pqrfile.write(self.fmt_remark.format( "total charge: {0:+8.4f} e".format(total_charge), 6)) # Atom descriptions and coords for atom_index, (pos, name, resname, chainid, resid, charge, radius) in enumerate(zip( coordinates, attrs['names'], attrs['resnames'], attrs['chainids'], attrs['resids'], attrs['charges'], attrs['radii']), start=1): # pad so that only 4-letter atoms are left-aligned name = " " + name if len(name) < 4 else name pqrfile.write(self.fmt_ATOM.format( serial=atom_index, name=name, resname=resname, chainid=chainid, resid=resid, pos=pos, charge=charge, radius=radius))