diff --git a/package/MDAnalysis/coordinates/PQR.py b/package/MDAnalysis/coordinates/PQR.py index 886b5e27d52..2b8917995e9 100644 --- a/package/MDAnalysis/coordinates/PQR.py +++ b/package/MDAnalysis/coordinates/PQR.py @@ -25,77 +25,6 @@ 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 - -.. _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 """ from __future__ import absolute_import from six.moves import zip diff --git a/package/doc/sphinx/source/documentation_pages/loading_files/apbs.rst b/package/doc/sphinx/source/documentation_pages/loading_files/apbs.rst index 3af7c6cc539..2572dbac02d 100644 --- a/package/doc/sphinx/source/documentation_pages/loading_files/apbs.rst +++ b/package/doc/sphinx/source/documentation_pages/loading_files/apbs.rst @@ -4,8 +4,84 @@ Loading Poisson Boltzmann files in MDAnalysis ############################################# +MDAnalysis is able to read and write PQR files produced by +Poisson Boltzmann. .. _load_pqr: Loading PQR files ----------------- + +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 + +.. seealso:: For implementation details, see :mod:`MDAnalysis.coordinates.PQR` + +.. _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