From 98c568cd029db76e2829126307c96ff663dfe997 Mon Sep 17 00:00:00 2001 From: Jonathan Barnoud Date: Fri, 22 Jul 2016 13:28:03 +0200 Subject: [PATCH] Fix some documentation rendering issues Minor missformatting of docstring can cause part of the documentation not to be rendered. This commit fixes some of this formatting issues. In some occurences, it also updates some docstring refering to deprecated methods. The commit also restores the documentation for gromacs trajectory formats. Fixes 855 --- package/MDAnalysis/analysis/align.py | 16 +- package/MDAnalysis/analysis/base.py | 11 +- package/MDAnalysis/analysis/contacts.py | 23 +- package/MDAnalysis/analysis/distances.py | 20 +- .../analysis/hbonds/hbond_autocorrel.py | 10 +- package/MDAnalysis/analysis/lineardensity.py | 26 +- package/MDAnalysis/analysis/rms.py | 8 +- package/MDAnalysis/coordinates/TRR.py | 19 +- package/MDAnalysis/coordinates/XTC.py | 21 +- package/MDAnalysis/lib/distances.py | 426 ++++++++++-------- package/MDAnalysis/topology/TPRParser.py | 13 +- .../documentation_pages/analysis_modules.rst | 10 +- .../documentation_pages/coordinates/TRR.rst | 1 + .../documentation_pages/coordinates/XTC.rst | 1 + .../coordinates/xdrfile.rst | 30 -- .../coordinates/xdrfile/TRR.rst | 1 - .../coordinates/xdrfile/XTC.rst | 1 - .../coordinates/xdrfile/core.rst | 1 - .../coordinates/xdrfile/libxdrfile2.rst | 1 - .../coordinates/xdrfile/statno.rst | 1 - .../coordinates_modules.rst | 1 - .../source/documentation_pages/overview.rst | 32 +- 22 files changed, 349 insertions(+), 324 deletions(-) delete mode 100644 package/doc/sphinx/source/documentation_pages/coordinates/xdrfile.rst delete mode 100644 package/doc/sphinx/source/documentation_pages/coordinates/xdrfile/TRR.rst delete mode 100644 package/doc/sphinx/source/documentation_pages/coordinates/xdrfile/XTC.rst delete mode 100644 package/doc/sphinx/source/documentation_pages/coordinates/xdrfile/core.rst delete mode 100644 package/doc/sphinx/source/documentation_pages/coordinates/xdrfile/libxdrfile2.rst delete mode 100644 package/doc/sphinx/source/documentation_pages/coordinates/xdrfile/statno.rst diff --git a/package/MDAnalysis/analysis/align.py b/package/MDAnalysis/analysis/align.py index 29be6e85018..f336a370a51 100644 --- a/package/MDAnalysis/analysis/align.py +++ b/package/MDAnalysis/analysis/align.py @@ -165,6 +165,7 @@ The following functions are used by the other functions in this module. They are probably of more interest to developers than to normal users. + .. autofunction:: _fit_to .. autofunction:: fasta2select .. autofunction:: get_matching_atoms @@ -198,6 +199,7 @@ def rotation_matrix(a, b, weights=None): reference structure): .. math:: + \vec{b} = \bold{R} \dot \vec{a} Parameters @@ -239,9 +241,10 @@ def rotation_matrix(a, b, weights=None): See Also -------- - :func:`rmsd` calculates the RMSD between *a* and *b*; for fitting a whole - trajectory it is more efficient to use :func:`rms_fit_trj`. A complete fit - of two structures can be done with :func:`alignto`. """ + MDAnalysis.analysis.rms.rmsd: Calculates the RMSD between *a* and *b*. + alignto: A complete fit of two structures. + AlignTraj: Fit a whole trajectory. + """ a = np.asarray(a, dtype=np.float64) b = np.asarray(b, dtype=np.float64) @@ -382,8 +385,10 @@ def alignto(mobile, reference, select="all", mass_weighted=False, new_rmsd RMSD after spatial alignment. - .. SeeAlso:: For RMSD-fitting trajectories it is more efficient to - use :class:`AlignTraj`. + See Also + -------- + AlignTraj: More efficient method for RMSD-fitting trajectories. + .. versionchanged:: 0.8 Added check that the two groups describe the same atoms including @@ -393,7 +398,6 @@ def alignto(mobile, reference, select="all", mass_weighted=False, Uses :func:`get_matching_atoms` to work with incomplete selections and new *strict* keyword. The new default is to be lenient whereas the old behavior was the equivalent of *strict* = ``True``. - """ if select in ('all', None): # keep the EXACT order in the input AtomGroups; select_atoms('all') diff --git a/package/MDAnalysis/analysis/base.py b/package/MDAnalysis/analysis/base.py index 3d7d5efe79f..b76618b4f60 100644 --- a/package/MDAnalysis/analysis/base.py +++ b/package/MDAnalysis/analysis/base.py @@ -31,10 +31,11 @@ class AnalysisBase(object): - """Base class for defining multi frame analysis, it is designed as a - template for creating multiframe analysis. This class will automatically - take care of setting up the trajectory reader for iterating and offers to - show a progress meter. + """Base class for defining multi frame analysis + + The class it is designed as a template for creating multiframe analyses. + This class will automatically take care of setting up the trajectory + reader for iterating, and it offers to show a progress meter. To define a new Analysis, `AnalysisBase` needs to be subclassed `_single_frame` must be defined. It is also possible to define @@ -42,6 +43,7 @@ class AnalysisBase(object): below. .. code-block:: python + class NewAnalysis(AnalysisBase): def __init__(self, atomgroup, parameter, **kwargs): super(NewAnalysis, self).__init__(atomgroup.universe.trajectory, @@ -70,6 +72,7 @@ def _conclude(self): Afterwards the new analysis can be run like this. .. code-block:: python + na = NewAnalysis(u.select_atoms('name CA'), 35).run() print(na.result) diff --git a/package/MDAnalysis/analysis/contacts.py b/package/MDAnalysis/analysis/contacts.py index ede234f5b93..b8b5bbf00ff 100644 --- a/package/MDAnalysis/analysis/contacts.py +++ b/package/MDAnalysis/analysis/contacts.py @@ -14,7 +14,7 @@ # J. Comput. Chem. 32 (2011), 2319--2327, doi:10.1002/jcc.21787 # -"""\ +""" ================================================================ Native contacts analysis --- :mod:`MDAnalysis.analysis.contacts` ================================================================ @@ -97,8 +97,8 @@ Suggested cutoff distances for different simulations -* For all-atom simulations, cutoff = 4.5 A -* For coarse-grained simulations, cutoff = 6.0 A +* For all-atom simulations, cutoff = 4.5 Å +* For coarse-grained simulations, cutoff = 6.0 Å Two-dimensional contact analysis (q1-q2) @@ -377,8 +377,7 @@ class Contacts(AnalysisBase): """ def __init__(self, u, selection, refgroup, method="hard_cut", radius=4.5, kwargs=None, **basekwargs): - """Initialization - + """ Parameters ---------- u : Universe @@ -565,13 +564,12 @@ class ContactAnalysis(object): def __init__(self, topology, trajectory, ref1=None, ref2=None, radius=8.0, targetdir=os.path.curdir, infix="", force=False, selection="name CA", centroids=False): - """Calculate native contacts from two reference structures. - + """ Parameters ---------- - topology : filename + topology : filename as str topology file - trajectory : filename + trajectory : filename as str trajectory ref1 : filename or ``None``, optional structure of the reference conformation 1 (pdb); if ``None`` the @@ -1026,6 +1024,7 @@ def run(self, store=True, force=False, start=0, stop=None, step=1, Stores results in :attr:`ContactAnalysis1.timeseries` (if store=True) and writes them to a data file. The average q is written to a second data file. + *start* The value of the first frame index in the trajectory to be used (default: index 0) @@ -1150,9 +1149,7 @@ def load(self, filename): def plot(self, filename=None, **kwargs): """Plot q(t). - .. function:: ContactAnalysis1.plot([filename, ...]) - - If *filename* is supplied then the figure is also written to file (the + If `filename` is supplied then the figure is also written to file (the suffix determines the file type, e.g. pdf, png, eps, ...). All other keyword arguments are passed on to :func:`pylab.plot`. """ @@ -1197,8 +1194,6 @@ def _plot_qavg_pcolor(self, filename=None, **kwargs): def plot_qavg(self, filename=None, **kwargs): """Plot :attr:`ContactAnalysis1.qavg`, the matrix of average native contacts. - .. function:: ContactAnalysis1.plot_qavg([filename, ...]) - If *filename* is supplied then the figure is also written to file (the suffix determines the file type, e.g. pdf, png, eps, ...). All other keyword arguments are passed on to :func:`pylab.imshow`. diff --git a/package/MDAnalysis/analysis/distances.py b/package/MDAnalysis/analysis/distances.py index af9d0014648..f4718ed03c0 100644 --- a/package/MDAnalysis/analysis/distances.py +++ b/package/MDAnalysis/analysis/distances.py @@ -25,10 +25,11 @@ :func:`dist` and :func:`between` can take atom groups that do not even have to be from the same :class:`~MDAnalysis.core.AtomGroup.Universe`. -.. SeeAlso:: :mod:`MDAnalysis.lib.distances` +.. SeeAlso:: :mod:`MDAnalysis.lib.distances` """ -__all__ = ['distance_array', 'self_distance_array', 'contact_matrix', 'dist'] +__all__ = ['distance_array', 'self_distance_array', + 'contact_matrix', 'dist', 'between'] import numpy as np @@ -84,12 +85,12 @@ def contact_matrix(coord, cutoff=15.0, returntype="numpy", box=None): Note ---- - :module:`scipy.sparse` is require for using *sparse* matrices; if it cannot + :mod:`scipy.sparse` is require for using *sparse* matrices; if it cannot be imported then an `ImportError` is raised. + .. versionchanged:: 0.11.0 Keyword *suppress_progmet* and *progress_meter_freq* were removed. - ''' if returntype == "numpy": @@ -124,8 +125,7 @@ def dist(A, B, offset=0): Arguments --------- - - A, B: AtomGroup instances + A, B : AtomGroup :class:`~MDAnalysis.core.AtomGroup.AtomGroup` with the same number of atoms offset : integer or tuple, optional, default 0 @@ -145,7 +145,6 @@ def dist(A, B, offset=0): residue ids of the `B` group (possibly changed with `offset`) distances : array distances between the atoms - """ if A.atoms.n_atoms != B.atoms.n_atoms: raise ValueError("AtomGroups A and B do not have the same number of atoms") @@ -171,7 +170,6 @@ def between(group, A, B, distance): Parameters ---------- - group : AtomGroup Find members of `group` that are between `A` and `B` A, B : AtomGroups @@ -185,11 +183,11 @@ def between(group, A, B, distance): Returns ------- AtomGroup - :class:`~MDAnalysis.core.AtomGroup.AtomGroup` of atoms that - fulfill the criterion + :class:`~MDAnalysis.core.AtomGroup.AtomGroup` of atoms that + fulfill the criterion - .. versionadded: 0.7.5 + .. versionadded: 0.7.5 """ from MDAnalysis.core.AtomGroup import AtomGroup diff --git a/package/MDAnalysis/analysis/hbonds/hbond_autocorrel.py b/package/MDAnalysis/analysis/hbonds/hbond_autocorrel.py index 463fb78dae9..31e4efabe1e 100644 --- a/package/MDAnalysis/analysis/hbonds/hbond_autocorrel.py +++ b/package/MDAnalysis/analysis/hbonds/hbond_autocorrel.py @@ -32,7 +32,8 @@ then the lifetime of these bonds is monitored over time. Multiple passes through the trajectory are used to build an average of the behaviour. - :math:`C_x(t) = \\left \\langle \\frac{h_{ij}(t_0) h_{ij}(t_0 + t)}{h_{ij}(t_0)^2} \\right\\rangle` +.. math:: + C_x(t) = \\left \\langle \\frac{h_{ij}(t_0) h_{ij}(t_0 + t)}{h_{ij}(t_0)^2} \\right\\rangle The subscript :math:`x` refers to the definition of lifetime being used, either continuous or intermittent. The continuous definition measures the time that @@ -41,7 +42,8 @@ be counted again. The relevent lifetime, :math:`\\tau_x`, can then be found via integration of this function - :math:`\\tau_x = \\int_0^\\infty C_x(t) dt` +.. math:: + \\tau_x = \\int_0^\\infty C_x(t) dt` For this, the observed behaviour is fitted to a multi exponential function, using 2 exponents for the continuous lifetime and 3 for the intermittent @@ -277,8 +279,8 @@ def _slice_traj(self, sample_time): def run(self, force=False): """Run all the required passes - Parameters: - ----------- + Parameters + ---------- force : bool, optional Will overwrite previous results if they exist """ diff --git a/package/MDAnalysis/analysis/lineardensity.py b/package/MDAnalysis/analysis/lineardensity.py index d0c54bd784b..498c6e3381b 100644 --- a/package/MDAnalysis/analysis/lineardensity.py +++ b/package/MDAnalysis/analysis/lineardensity.py @@ -35,20 +35,15 @@ class LinearDensity(AnalysisBase): Parameters ---------- - selection : `AtomGroup` object + selection : AtomGroup Any atomgroup - - Keywords - -------- grouping : str {'atoms', 'residues', 'segments', 'fragments'} Density profiles will be computed on the center of geometry of a selected group of atoms ['atoms'] - binsize : float Bin width in Angstrom used to build linear density histograms. Defines the resolution of the resulting density profile (smaller --> higher resolution) [0.25] - start : int The frame to start at [0] stop : int @@ -59,14 +54,17 @@ class LinearDensity(AnalysisBase): Example ------- First create a LinearDensity object by supplying a selection, - then use the `run` method: + then use the :meth:`run` method:: + ldens = LinearDensity(selection) ldens.run() - Density profiles can be written to file through the `save` method: + Density profiles can be written to file through the `save` method:: + ldens.save(description='mydensprof', form='txt') + which will output the density profiles in a file named - .mydensprof_.ldens + `.mydensprof_.ldens`. Results can be saved in npz format by specifying `form='npz'` .. versionadded:: 0.14.0 @@ -188,8 +186,8 @@ def save(self, description='', form='txt'): binary numpy npz file. Output file has extension 'ldens' and begins with the name of the trajectory file. - Keywords - -------- + Parameters + ---------- description : str An arbitrary description added to the output filename. Can be useful form : str {'txt', 'npz'} @@ -199,10 +197,12 @@ def save(self, description='', form='txt'): Example ------- After initializing and running a `LinearDensity` object, results can be - written to file as follows: + written to file as follows:: + ldens.save(description='mydensprof', form='txt') + which will output the linear density profiles in a file named - .mydensprof_.ldens + `.mydensprof_.ldens`. """ # Take root of trajectory filename for output file naming diff --git a/package/MDAnalysis/analysis/rms.py b/package/MDAnalysis/analysis/rms.py index d26130ccd7e..f644bf63a6e 100644 --- a/package/MDAnalysis/analysis/rms.py +++ b/package/MDAnalysis/analysis/rms.py @@ -96,7 +96,6 @@ fig.savefig("rmsd_all_CORE_LID_NMP_ref1AKE.pdf") - Functions --------- @@ -325,13 +324,13 @@ def __init__(self, traj, reference=None, select='all', ref_frame : int (optional) frame index to select frame from `reference` + .. _ClustalW: http://www.clustal.org/ .. _STAMP: http://www.compbio.dundee.ac.uk/manuals/stamp.4.2/ .. versionadded:: 0.7.7 .. versionchanged:: 0.8 *groupselections* added - """ self.universe = traj if reference is None: @@ -580,8 +579,9 @@ def run(self, start=0, stop=-1, step=1, progout=10, quiet=False): References ---------- - [Welford1962] B. P. Welford (1962). "Note on a Method for Calculating - Corrected Sums of Squares and Products." Technometrics 4(3):419-420. + .. [Welford1962] B. P. Welford (1962). "Note on a Method for + Calculating Corrected Sums of Squares and Products." Technometrics + 4(3):419-420. """ sumsquares = np.zeros((self.atomgroup.n_atoms, 3)) means = np.array(sumsquares) diff --git a/package/MDAnalysis/coordinates/TRR.py b/package/MDAnalysis/coordinates/TRR.py index 67a9764cb74..8c13541b38b 100644 --- a/package/MDAnalysis/coordinates/TRR.py +++ b/package/MDAnalysis/coordinates/TRR.py @@ -13,6 +13,17 @@ # MDAnalysis: A Toolkit for the Analysis of Molecular Dynamics Simulations. # J. Comput. Chem. 32 (2011), 2319--2327, doi:10.1002/jcc.21787 # +""" +TRR trajectory files --- :mod:`MDAnalysis.coordinates.TRR` +========================================================== + +Read and write GROMACS TRR trajectories. + +See Also +-------- +MDAnalysis.coordinates.XTC: Read and write GROMACS XTC trajectory files. +""" + from .XDR import XDRBaseReader, XDRBaseWriter from ..lib.formats.libmdaxdr import TRRFile from ..lib.mdamath import triclinic_vectors, triclinic_box @@ -28,8 +39,8 @@ class TRRWriter(XDRBaseWriter): corresponding value will be used as the lambda value for written TRR file. If None is found the lambda is set to 0. - Parameter - --------- + Parameters + ---------- filename : str filename of the trajectory n_atoms : int @@ -100,8 +111,8 @@ class TRRReader(XDRBaseReader): The lambda value is written in the data dictionary of the returned TimeStep - Parameter - --------- + Parameters + ---------- filename : str filename of the trajectory convert_units : bool (optional) diff --git a/package/MDAnalysis/coordinates/XTC.py b/package/MDAnalysis/coordinates/XTC.py index 7644b09c1e4..6d67650a05f 100644 --- a/package/MDAnalysis/coordinates/XTC.py +++ b/package/MDAnalysis/coordinates/XTC.py @@ -13,6 +13,17 @@ # MDAnalysis: A Toolkit for the Analysis of Molecular Dynamics Simulations. # J. Comput. Chem. 32 (2011), 2319--2327, doi:10.1002/jcc.21787 # +""" +XTC trajectory files --- :mod:`MDAnalysis.coordinates.XTC` +========================================================== + +Read and write GROMACS XTC trajectories. + +See Also +-------- +MDAnalysis.coordinates.TRR: Read and write GROMACS TRR trajectory files. +""" + from .XDR import XDRBaseReader, XDRBaseWriter from ..lib.formats.libmdaxdr import XTCFile from ..lib.mdamath import triclinic_vectors, triclinic_box @@ -26,8 +37,8 @@ class XTCWriter(XDRBaseWriter): they require significantly less disk space and the loss of precision is usually not a problem. - Parameter - --------- + Parameters + ---------- filename : str filename of the trajectory n_atoms : int @@ -52,7 +63,7 @@ def write_next_timestep(self, ts): Parameters ---------- - ts : TimeStep + ts: TimeStep See Also -------- @@ -83,8 +94,8 @@ class XTCReader(XDRBaseReader): require significantly less disk space and the loss of precision is usually not a problem. - Parameter - --------- + Parameters + ---------- filename : str filename of the trajectory convert_units : bool (optional) diff --git a/package/MDAnalysis/lib/distances.py b/package/MDAnalysis/lib/distances.py index 6ad2a21e110..c7aceef39a8 100644 --- a/package/MDAnalysis/lib/distances.py +++ b/package/MDAnalysis/lib/distances.py @@ -115,18 +115,24 @@ def _box_check(box): """Take a box input and deduce what type of system it represents based on the shape of the array and whether all angles are 90. - :Arguments: - *box* - box information of unknown format - - :Returns: - * ``ortho`` orthogonal box - * ``tri_vecs`` triclinic box vectors - * ``tri_box`` triclinic box lengths and angles - - :Raises: - * ``TypeError`` if box is not float32 - * ``ValueError`` if box type not detected + Parameters + ---------- + box : array + Box information of unknown format. + + Returns + ------- + boxtype : str + * ``ortho`` orthogonal box + * ``tri_vecs`` triclinic box vectors + * ``tri_box`` triclinic box lengths and angles + + Raises + ------ + TypeError + If box is not float32. + ValueError + If box type not detected. """ if box.dtype != np.float32: raise TypeError("Box must be of type float32") @@ -203,34 +209,38 @@ def distance_array(reference, configuration, box=None, result=None, backend="ser len(configuration))`` is provided in *result* then this preallocated array is filled. This can speed up calculations. - d = distance_array(reference, configuration[,box[,result=d]]) - - :Arguments: - *reference* - reference coordinate array (must be numpy.float32) - *configuration* - configuration coordinate array (must be numpy.float32) - *box* - cell dimensions (minimum image convention is applied) - or None [``None``]. - Cell dimensions must be in an identical to format to those returned - by :attr:`MDAnalysis.coordinates.base.Timestep.dimensions`, - [lx, ly, lz, alpha, beta, gamma] - *result* - optional preallocated result array which must have the - shape (len(ref), len(conf)) and dtype=numpy.float64. - Avoids creating the array which saves time when the function - is called repeatedly. [``None``] - *backend* - select the type of acceleration; "serial" is always available. Other - possibilities are "OpenMP" (OpenMP). - :Returns: - *d* - (len(reference),len(configuration)) numpy array with the distances d[i,j] - between reference coordinates i and configuration coordinates j - - .. Note:: This method is slower than it could be because internally we need to - make copies of the ref and conf arrays. + Parameters + ---------- + reference : numpy.array of numpy.float32 + Reference coordinate array. + configuration : numpy.array of numpy.float32 + Configuration coordinate array. + box : numpy.array or None + Dimensions of the cell; if provided, the minimum image convention is + applied. The dimensions must be provided in the same format as returned + by by :attr:`MDAnalysis.coordinates.base.Timestep.dimensions`: ``[lx, + ly, lz, alpha, beta, gamma]``. + result : numpy.array of numpy.float64, optional + Preallocated result array which must have the + shape ``(len(ref), len(conf))`` and ``dtype=numpy.float64``. + Avoids creating the array which saves time when the function + is called repeatedly. [``None``] + backend + Select the type of acceleration; "serial" is always available. Other + possibilities are "OpenMP" (OpenMP). + + Returns + ------- + d : numpy.array + ``(len(reference),len(configuration))`` numpy array with the distances + ``d[i,j]`` between reference coordinates `i` and configuration + coordinates `j`. + + Note + ---- + This method is slower than it could be because internally we need to make + copies of the ref and conf arrays. + .. versionchanged:: 0.13.0 Added *backend* keyword. @@ -285,35 +295,42 @@ def self_distance_array(reference, box=None, result=None, backend="serial"): ``(N*(N-1)/2)`` is provided in *result* then this preallocated array is filled. This can speed up calculations. - :Arguments: - *ref* - reference coordinate array with N=len(ref) coordinates - *box* - cell dimensions (minimum image convention is applied) - or None [``None``] - Cell dimensions must be in an identical to format to those returned - by :attr:`MDAnalysis.coordinates.base.Timestep.dimensions`, - [lx, ly, lz, alpha, beta, gamma] - *result* - optional preallocated result array which must have the shape - (N*(N-1)/2,) and dtype ``numpy.float64``. Avoids creating - the array which saves time when the function is called - repeatedly. [``None``] - *backend* - select the type of acceleration; "serial" is always available. Other - possibilities are "OpenMP" (OpenMP). - :Returns: - *d* - N*(N-1)/2 numpy 1D array with the distances dist[i,j] between ref - coordinates i and j at position d[k]. Loop through d:: - - for i in range(N): - for j in range(i+1, N): - k += 1 - dist[i,j] = d[k] - - .. Note:: This method is slower than it could be because internally we need to - make copies of the coordinate arrays. + Parameters + ---------- + reference : array + Reference coordinate array with ``N=len(ref)`` coordinates. + box : array or None + Dimensions of the cell; if provided, the minimum image convention is + applied. The dimensions must be provided in the same format as returned + by :attr:`MDAnalysis.coordinates.base.Timestep.dimensions`: ``[lx, + ly, lz, alpha, beta, gamma]``. + result : array, optional + Preallocated result array which must have the shape + ``(N*(N-1)/2,)`` and dtype ``numpy.float64``. Avoids creating + the array which saves time when the function is called + repeatedly. [``None``] + backend + Select the type of acceleration; "serial" is always available. Other + possibilities are "OpenMP" (OpenMP). + + Returns + ------- + d : array + ``N*(N-1)/2`` numpy 1D array with the distances dist[i,j] between ref + coordinates i and j at position d[k]. Loop through d: + + .. code-block:: python + + for i in range(N): + for j in range(i+1, N): + k += 1 + dist[i,j] = d[k] + + Note + ---- + This method is slower than it could be because internally we need to make + copies of the coordinate arrays. + .. versionchanged:: 0.13.0 Added *backend* keyword. @@ -364,21 +381,23 @@ def transform_RtoS(inputcoords, box, backend="serial"): Reciprocal operation to :meth:`transform_StoR` - :Arguments: - *inputcoords* - An n x 3 array of coordinate data, of type np.float32 - *box* - The unitcell dimesions for this system - Cell dimensions must be in an identical to format to those returned - by :attr:`MDAnalysis.coordinates.base.Timestep.dimensions`, - [lx, ly, lz, alpha, beta, gamma] - *backend* - select the type of acceleration; "serial" is always available. Other - possibilities are "OpenMP" (OpenMP). - - :Returns: - *outcoords* - An n x 3 array of fractional coordiantes + Parameters + ---------- + inputcoords : array + A n x 3 array of coordinate data, of type ``np.float32``. + box : array + The unitcell dimesions for this system. + The dimensions must be provided in the same format as returned + by :attr:`MDAnalysis.coordinates.base.Timestep.dimensions`: ``[lx, + ly, lz, alpha, beta, gamma]``. + backend + Select the type of acceleration; "serial" is always available. Other + possibilities are "OpenMP" (OpenMP). + + Returns + ------- + outcoords : array + A n x 3 array of fractional coordiantes. .. versionchanged:: 0.13.0 Added *backend* keyword. @@ -415,21 +434,24 @@ def transform_StoR(inputcoords, box, backend="serial"): Reciprocal operation to :meth:`transform_RtoS` - :Arguments: - *inputcoords* - An n x 3 array of coordinate data, of type np.float32 - *box* - The unitcell dimesions for this system - Cell dimensions must be in an identical to format to those returned - by :attr:`MDAnalysis.coordinates.base.Timestep.dimensions`, - [lx, ly, lz, alpha, beta, gamma] - *backend* - select the type of acceleration; "serial" is always available. Other - possibilities are "OpenMP" (OpenMP). - - :Returns: - *outcoords* - An n x 3 array of fracional coordiantes + Parameters + ---------- + inputcoords : array + A n x 3 array of coordinate data, of type np.float32 + box : array + The unitcell dimesions for this system. + The dimensions must be provided in the same format as returned + by :attr:`MDAnalysis.coordinates.base.Timestep.dimensions`: ``[lx, + ly, lz, alpha, beta, gamma]``. + backend + Select the type of acceleration; "serial" is always available. Other + possibilities are "OpenMP" (OpenMP). + + Returns + ------- + outcoords : array + A n x 3 array of fracional coordiantes. + .. versionchanged:: 0.13.0 Added *backend* keyword. @@ -473,27 +495,30 @@ def calc_bonds(coords1, coords2, box=None, result=None, backend="serial"): bondlengths = calc_bonds(coords1, coords2 [, box [,result=bondlengths]]) - :Arguments: - *coords1* - An array of coordinates for one half of the bond - *coords2* - An array of coordinates for the other half of bond - *box* - Unit cell information if periodic boundary conditions are required [None] - Cell dimensions must be in an identical to format to those returned - by :attr:`MDAnalysis.coordinates.base.Timestep.dimensions`, - [lx, ly, lz, alpha, beta, gamma] - *result* - optional preallocated result array which must be same length as coord - arrays and dtype=numpy.float64. Avoids creating the - array which saves time when the function is called repeatedly. [None] - *backend* - select the type of acceleration; "serial" is always available. Other - possibilities are "OpenMP" (OpenMP). - - :Returns: - *bondlengths* - numpy array with the length between each pair in coords1 and coords2 + Parameters + ---------- + coords1 : array + An array of coordinates for one half of the bond. + coords2 : array + An array of coordinates for the other half of bond + box : array + The unitcell dimesions for this system. + The dimensions must be provided in the same format as returned + by :attr:`MDAnalysis.coordinates.base.Timestep.dimensions`: ``[lx, + ly, lz, alpha, beta, gamma]``. + result : array, optional + Preallocated result array which must be same length as coord + arrays and ``dtype=numpy.float64``. Avoids creating the + array which saves time when the function is called repeatedly. [None] + backend + Select the type of acceleration; "serial" is always available. Other + possibilities are "OpenMP" (OpenMP). + + Returns + ------- + bondlengths : array + The length between each pair in coords1 and coords2 + .. versionadded:: 0.8 .. versionchanged:: 0.13.0 @@ -555,30 +580,32 @@ def calc_angles(coords1, coords2, coords3, box=None, result=None, backend="seria angles = calc_angles(coords1, coords2, coords3, [[box=None],result=angles]) - :Arguments: - *coords1* - coordinate array of one side of angles - *coords2* - coordinate array of apex of angles - *coords3* - coordinate array of other side of angles - *box* - optional unit cell information. This ensures that the connecting vectors between - atoms respect minimum image convention. This is import when the angle might - be between atoms in different images. - Cell dimensions must be in an identical to format to those returned - by :attr:`MDAnalysis.coordinates.base.Timestep.dimensions`, - [lx, ly, lz, alpha, beta, gamma] - *result* - optional preallocated results array which must have same length as coordinate - array and dtype=numpy.float64. - *backend* - select the type of acceleration; "serial" is always available. Other - possibilities are "OpenMP" (OpenMP). - - :Returns: - *angles* - A numpy.array of angles in radians + Parameters + ---------- + coords1 : array + Coordinate array of one side of angles. + coords2 : array + Coordinate array of apex of angles. + coords3 : array + Coordinate array of other side of angles. + box : array + The unitcell dimesions for this system. + The dimensions must be provided in the same format as returned + by :attr:`MDAnalysis.coordinates.base.Timestep.dimensions`: ``[lx, + ly, lz, alpha, beta, gamma]``. + result : array, optional + Preallocated result array which must be same length as coord + arrays and ``dtype=numpy.float64``. Avoids creating the + array which saves time when the function is called repeatedly. [None] + backend + Select the type of acceleration; "serial" is always available. Other + possibilities are "OpenMP" (OpenMP). + + Returns + ------- + angles : array + A numpy.array of angles in radians. + .. versionadded:: 0.8 .. versionchanged:: 0.9.0 @@ -641,42 +668,45 @@ def calc_dihedrals(coords1, coords2, coords3, coords4, box=None, result=None, / 0 - If a 1D numpy array of dtype ``numpy.float64`` with ``len(atom1)`` elements is - provided in *result* then this preallocated array is filled. This can speed - up calculations. + If a 1D numpy array of dtype ``numpy.float64`` with ``len(atom1)`` elements + is provided in *result* then this preallocated array is filled. This can + speed up calculations. + + The optional argument ``box`` ensures that periodic boundaries are taken + into account when constructing the connecting vectors between atoms, ie + that the vector between atoms 1 & 2 goes between coordinates in the same + image:: + + angles = calc_dihedrals(coords1, coords2, coords3, coords4 [,box=box, result=angles]) + + Parameters + ---------- + coords1 : array + Coordinate array of 1st atom in dihedrals. + coords2 : array + Coordinate array of 2nd atom in dihedrals. + coords3 : array + Coordinate array of 3rd atom in dihedrals. + coords4 : array + Coordinate array of 4th atom in dihedrals. + box : array + The unitcell dimesions for this system. + The dimensions must be provided in the same format as returned + by :attr:`MDAnalysis.coordinates.base.Timestep.dimensions`: ``[lx, + ly, lz, alpha, beta, gamma]``. + result : array, optional + Preallocated result array which must be same length as coord + arrays and ``dtype=numpy.float64``. Avoids creating the + array which saves time when the function is called repeatedly. [None] + backend + Select the type of acceleration; "serial" is always available. Other + possibilities are "OpenMP" (OpenMP). + + Returns + ------- + angles : array + A numpy.array of angles in radians. - The optional argument ``box`` ensures that periodic boundaries are taken into - account when constructing the connecting vectors between atoms, ie that the vector - between atoms 1 & 2 goes between coordinates in the same image:: - - angles = calc_dihedrals(coords1, coords2, coords3, coords4 [,box=box, result=angles]) - - :Arguments: - *coords1* - coordinate array of 1st atom in dihedrals - *coords2* - coordinate array of 2nd atom in dihedrals - *coords3* - coordinate array of 3rd atom in dihedrals - *coords4* - coordinate array of 4th atom in dihedrals - *box* - optional unit cell information. This ensures that the connecting vectors - between atoms respect minimum image convention. This is import when the - angle might be between atoms in different images. - Cell dimensions must be in an identical to format to those returned - by :attr:`MDAnalysis.coordinates.base.Timestep.dimensions`, - [lx, ly, lz, alpha, beta, gamma] - *result* - optional preallocated results array which must have same length as - coordinate array and dtype=numpy.float64. - *backend* - select the type of acceleration; "serial" is always available. Other - possibilities are "OpenMP" (OpenMP). - - :Returns: - *angles* - A numpy.array of angles in radians .. versionadded:: 0.8 .. versionchanged:: 0.9.0 @@ -729,6 +759,7 @@ def calc_dihedrals(coords1, coords2, coords3, coords4, box=None, result=None, return angles + calc_torsions = deprecate(calc_dihedrals, old_name='calc_torsions', new_name='calc_dihedrals', @@ -740,22 +771,26 @@ def apply_PBC(incoords, box, backend="serial"): newcoords = apply_PBC(coords, box) - :Arguments: - *coords* - coordinate array (of type numpy.float32) - *box* - box dimensions, can be either orthogonal or triclinic information - Cell dimensions must be in an identical to format to those returned - by :attr:`MDAnalysis.coordinates.base.Timestep.dimensions`, - [lx, ly, lz, alpha, beta, gamma] - *backend* - select the type of acceleration; "serial" is always available. Other - possibilities are "OpenMP" (OpenMP). - - :Returns: - *newcoords* - coordinates that are now all within the primary unit cell, - as defined by box + Parameters + ---------- + coords : array + Coordinate array (of type numpy.float32). + box : array + The unitcell dimesions for this system; can be either orthogonal or + triclinic information. The dimensions must be provided in the same + format as returned by + :attr:`MDAnalysis.coordinates.base.Timestep.dimensions`: ``[lx, ly, lz, + alpha, beta, gamma]``. + backend + Select the type of acceleration; "serial" is always available. Other + possibilities are "OpenMP" (OpenMP). + + Returns + ------- + newcoords : array + Coordinates that are now all within the primary unit cell, as defined + by box. + .. versionadded:: 0.8 .. versionchanged:: 0.13.0 @@ -793,6 +828,7 @@ def apply_PBC(incoords, box, backend="serial"): return coords + applyPBC = deprecate(apply_PBC, old_name='applyPBC', new_name='apply_PBC', diff --git a/package/MDAnalysis/topology/TPRParser.py b/package/MDAnalysis/topology/TPRParser.py index feb6c5722fa..65adfd8c058 100644 --- a/package/MDAnalysis/topology/TPRParser.py +++ b/package/MDAnalysis/topology/TPRParser.py @@ -1,8 +1,9 @@ # -*- Mode: python; tab-width: 4; indent-tabs-mode:nil; coding:utf-8 -*- -# vim: tabstop=4 expandtab shiftwidth=4 softtabstop=4 +# vim: tabstop=4 expandtab shiftwidth=4 softtabstop=4 # # MDAnalysis --- http://www.MDAnalysis.org -# Copyright (c) 2006-2015 Naveen Michaud-Agrawal, Elizabeth J. Denning, Oliver Beckstein +# Copyright (c) 2006-2015 Naveen Michaud-Agrawal, Elizabeth J. Denning, +# Oliver Beckstein # and contributors (see AUTHORS for the full list) # # Released under the GNU Public Licence, v2 or any higher version @@ -78,7 +79,7 @@ Classes ---------- +------- .. autoclass:: TPRParser :members: @@ -142,8 +143,6 @@ class TPRParser(TopologyReader): """Read topology information from a Gromacs_ TPR_ file. - .. SeeAlso:: :mod:`MDAnalysis.topology.TPR` - .. _Gromacs: http://www.gromacs.org .. _TPR file: http://manual.gromacs.org/current/online/tpr.html """ @@ -152,7 +151,9 @@ class TPRParser(TopologyReader): def parse(self): """Parse a Gromacs TPR file into a MDAnalysis internal topology structure. - :Returns: ``structure`` dict + Returns + ------- + structure : dict """ #ndo_int = U.ndo_int ndo_real = U.ndo_real diff --git a/package/doc/sphinx/source/documentation_pages/analysis_modules.rst b/package/doc/sphinx/source/documentation_pages/analysis_modules.rst index 3d6a3ec12b0..d4e241cd6a9 100644 --- a/package/doc/sphinx/source/documentation_pages/analysis_modules.rst +++ b/package/doc/sphinx/source/documentation_pages/analysis_modules.rst @@ -21,14 +21,12 @@ has to import them from :mod:`MDAnalysis.analysis`, for instance :: .. Note:: - Some of the modules require additional Python packages such as - :mod:`scipy` from the SciPy_ package or :mod:`networkx` from - NetworkX_. These package are *not automatically installed* (although - one can add the ``[analysis]`` requirement to the - :program:`easy_install` command line to force their installation. + Some of the modules require additional Python packages such as :mod:`scipy` + from the SciPy_ package. These package are *not automatically installed* + (although one can add the ``[analysis]`` requirement to the :program:`pip` + command line to force their installation. .. _scipy: http://www.scipy.org/ -.. _networkx: http://networkx.lanl.gov/ Building blocks for Analysis diff --git a/package/doc/sphinx/source/documentation_pages/coordinates/TRR.rst b/package/doc/sphinx/source/documentation_pages/coordinates/TRR.rst index fdd582b3699..aa2b6a1117c 100644 --- a/package/doc/sphinx/source/documentation_pages/coordinates/TRR.rst +++ b/package/doc/sphinx/source/documentation_pages/coordinates/TRR.rst @@ -1 +1,2 @@ .. automodule:: MDAnalysis.coordinates.TRR + :members: diff --git a/package/doc/sphinx/source/documentation_pages/coordinates/XTC.rst b/package/doc/sphinx/source/documentation_pages/coordinates/XTC.rst index 866c80a06d2..9e2f6d05c26 100644 --- a/package/doc/sphinx/source/documentation_pages/coordinates/XTC.rst +++ b/package/doc/sphinx/source/documentation_pages/coordinates/XTC.rst @@ -1 +1,2 @@ .. automodule:: MDAnalysis.coordinates.XTC + :members: diff --git a/package/doc/sphinx/source/documentation_pages/coordinates/xdrfile.rst b/package/doc/sphinx/source/documentation_pages/coordinates/xdrfile.rst deleted file mode 100644 index 95d59a3ba25..00000000000 --- a/package/doc/sphinx/source/documentation_pages/coordinates/xdrfile.rst +++ /dev/null @@ -1,30 +0,0 @@ -NumPy access to Gromacs XDR trajectories --- :mod:`MDAnalysis.coordinates.xdrfile` -================================================================================== - -Gromacs_ trajectory formats are based on the XDR_ (eXternal Data -Representation) format. Within this module, classes are provided to -access frames of Gromacs :mod:`~MDAnalysis.coordinates.XTC` or -:mod:`~MDAnalysis.coordinates.TRR` trajectories. Relevant data -(positions, velocities, forces, box dimensions) are made available as -NumPy_ arrays. The module also contains low-level code in -:mod:`~MDAnalysis.coordinates.xdrfile.libxdrfile2` that performs the -actual file access and includes some additions such as trajectory -indices that provide random access for the Gromacs trajectories (which -is not available with current standard Gromacs tools). - -.. _Gromacs: http://www.gromacs.org -.. _XDR: http://en.wikipedia.org/wiki/External_Data_Representation -.. _numpy: http://www.numpy.org/ - -.. rubric:: Contents - -.. toctree:: - :maxdepth: 1 - - xdrfile/XTC - xdrfile/TRR - xdrfile/core - xdrfile/libxdrfile2 - xdrfile/statno - - diff --git a/package/doc/sphinx/source/documentation_pages/coordinates/xdrfile/TRR.rst b/package/doc/sphinx/source/documentation_pages/coordinates/xdrfile/TRR.rst deleted file mode 100644 index fdcc6f56a5c..00000000000 --- a/package/doc/sphinx/source/documentation_pages/coordinates/xdrfile/TRR.rst +++ /dev/null @@ -1 +0,0 @@ -.. automodule:: MDAnalysis.coordinates.xdrfile.TRR diff --git a/package/doc/sphinx/source/documentation_pages/coordinates/xdrfile/XTC.rst b/package/doc/sphinx/source/documentation_pages/coordinates/xdrfile/XTC.rst deleted file mode 100644 index 0be332cc167..00000000000 --- a/package/doc/sphinx/source/documentation_pages/coordinates/xdrfile/XTC.rst +++ /dev/null @@ -1 +0,0 @@ -.. automodule:: MDAnalysis.coordinates.xdrfile.XTC diff --git a/package/doc/sphinx/source/documentation_pages/coordinates/xdrfile/core.rst b/package/doc/sphinx/source/documentation_pages/coordinates/xdrfile/core.rst deleted file mode 100644 index 639a19dee7a..00000000000 --- a/package/doc/sphinx/source/documentation_pages/coordinates/xdrfile/core.rst +++ /dev/null @@ -1 +0,0 @@ -.. automodule:: MDAnalysis.coordinates.xdrfile.core diff --git a/package/doc/sphinx/source/documentation_pages/coordinates/xdrfile/libxdrfile2.rst b/package/doc/sphinx/source/documentation_pages/coordinates/xdrfile/libxdrfile2.rst deleted file mode 100644 index 9a25ff2c9da..00000000000 --- a/package/doc/sphinx/source/documentation_pages/coordinates/xdrfile/libxdrfile2.rst +++ /dev/null @@ -1 +0,0 @@ -.. automodule:: MDAnalysis.coordinates.xdrfile.libxdrfile2 diff --git a/package/doc/sphinx/source/documentation_pages/coordinates/xdrfile/statno.rst b/package/doc/sphinx/source/documentation_pages/coordinates/xdrfile/statno.rst deleted file mode 100644 index 711d4a327aa..00000000000 --- a/package/doc/sphinx/source/documentation_pages/coordinates/xdrfile/statno.rst +++ /dev/null @@ -1 +0,0 @@ -.. automodule:: MDAnalysis.coordinates.xdrfile.statno diff --git a/package/doc/sphinx/source/documentation_pages/coordinates_modules.rst b/package/doc/sphinx/source/documentation_pages/coordinates_modules.rst index 44a4dff49b7..1b0ecf45d8b 100644 --- a/package/doc/sphinx/source/documentation_pages/coordinates_modules.rst +++ b/package/doc/sphinx/source/documentation_pages/coordinates_modules.rst @@ -49,6 +49,5 @@ functionality should first read the :ref:`Trajectory API`. coordinates/base coordinates/core - coordinates/xdrfile coordinates/pdbextensions diff --git a/package/doc/sphinx/source/documentation_pages/overview.rst b/package/doc/sphinx/source/documentation_pages/overview.rst index 5f138ffbdae..bc8c352ff2f 100644 --- a/package/doc/sphinx/source/documentation_pages/overview.rst +++ b/package/doc/sphinx/source/documentation_pages/overview.rst @@ -22,18 +22,18 @@ A typical usage pattern is to iterate through a trajectory and analyze coordinates for every frame. In the following example the end-to-end distance of a protein and the radius of gyration of the backbone atoms are calculated:: - import MDAnalysis - from MDAnalysis.tests.datafiles import PSF,DCD # test trajectory - import numpy.linalg - u = MDAnalysis.Universe(PSF,DCD) # always start with a Universe - nterm = u.s4AKE.N[0] # can access structure via segid (s4AKE) and atom name - cterm = u.s4AKE.C[-1] # ... takes the last atom named 'C' - bb = u.select_atoms('protein and backbone') # a selection (a AtomGroup) - for ts in u.trajectory: # iterate through all frames - r = cterm.pos - nterm.pos # end-to-end vector from atom positions - d = numpy.linalg.norm(r) # end-to-end distance - rgyr = bb.radius_of_gyration() # method of a AtomGroup; updates with each frame - print "frame = %d: d = %f Angstroem, Rgyr = %f Angstroem" % (ts.frame, d, rgyr) + import MDAnalysis + from MDAnalysis.tests.datafiles import PSF,DCD # test trajectory + import numpy.linalg + u = MDAnalysis.Universe(PSF,DCD) # always start with a Universe + nterm = u.s4AKE.N[0] # can access structure via segid (s4AKE) and atom name + cterm = u.s4AKE.C[-1] # ... takes the last atom named 'C' + bb = u.select_atoms('protein and backbone') # a selection (a AtomGroup) + for ts in u.trajectory: # iterate through all frames + r = cterm.pos - nterm.pos # end-to-end vector from atom positions + d = numpy.linalg.norm(r) # end-to-end distance + rgyr = bb.radius_of_gyration() # method of a AtomGroup; updates with each frame + print "frame = %d: d = %f Angstroem, Rgyr = %f Angstroem" % (ts.frame, d, rgyr) .. _NumPy: http://numpy.scipy.org @@ -56,12 +56,12 @@ from within the interpreter:: from MDAnalysis import * or :: - + import MDAnalysis The idea behind MDAnalysis is to get trajectory data into NumPy_ :class:`numpy.ndarray` arrays, where it can then be easily manipulated using -all the power in NumPy_ and SciPy_. +all the power in NumPy_ and SciPy_. MDAnalysis works well both in scripts and in interactive use. The developers very much recommend using MDAnalysis from within the IPython_ Python shell. It @@ -90,7 +90,7 @@ as :class:`MDAnalysis.Universe`):: For the remainder of this introduction we are using a short example trajectory that is provided with MDAnalysis (as part of the `MDAnalysis test suite`_). The trajectory is loaded with :: - + >>> from MDAnalysis import Universe >>> from MDAnalysis.tests.datafiles import PSF,DCD >>> u = Universe(PSF, DCD) @@ -169,7 +169,7 @@ Code snippets The source code distribution comes with a directory `examples`_ that contains a number of code snippets that show how to use certain -aspects of MDAnalysis. +aspects of MDAnalysis. For instance, there is code that shows how to