diff --git a/package/MDAnalysis/__init__.py b/package/MDAnalysis/__init__.py index 85fc15f171b..86fcc76ec0c 100644 --- a/package/MDAnalysis/__init__.py +++ b/package/MDAnalysis/__init__.py @@ -113,7 +113,9 @@ 9.72062 .... -.. SeeAlso:: :class:`MDAnalysis.core.universe.Universe` for details +See Also +-------- +:class:`MDAnalysis.core.universe.Universe` for details Examples diff --git a/package/MDAnalysis/analysis/align.py b/package/MDAnalysis/analysis/align.py index d4d24f78fbf..21ba11ee501 100644 --- a/package/MDAnalysis/analysis/align.py +++ b/package/MDAnalysis/analysis/align.py @@ -43,13 +43,13 @@ The :ref:`RMS-fitting-tutorial` shows how to do the individual steps manually and explains the intermediate steps. -.. SeeAlso:: - - :mod:`MDAnalysis.analysis.rms` - contains functions to compute RMSD (when structural alignment is not - required) - :mod:`MDAnalysis.lib.qcprot` - implements the fast RMSD algorithm. +See Also +-------- +:mod:`MDAnalysis.analysis.rms` + contains functions to compute RMSD (when structural alignment is not + required) +:mod:`MDAnalysis.lib.qcprot` + implements the fast RMSD algorithm. .. _RMS-fitting-tutorial: @@ -401,8 +401,9 @@ def alignto(mobile, reference, select="all", mass_weighted=None, weights=None, new_rmsd : float RMSD after spatial alignment - .. SeeAlso:: - AlignTraj: More efficient method for RMSD-fitting trajectories. + See Also + -------- + AlignTraj: More efficient method for RMSD-fitting trajectories. .. _ClustalW: http://www.clustal.org/ @@ -985,9 +986,10 @@ def fasta2select(fastafilename, is_aligned=False, ``select=select_dict``. - .. SeeAlso:: - :func:`sequence_alignment`, which does not require external - programs. + See Also + -------- + :func:`sequence_alignment`, which does not require external + programs. .. _ClustalW: http://www.clustal.org/ diff --git a/package/MDAnalysis/analysis/distances.py b/package/MDAnalysis/analysis/distances.py index 88e25d268d9..c6473ccd3ae 100644 --- a/package/MDAnalysis/analysis/distances.py +++ b/package/MDAnalysis/analysis/distances.py @@ -31,7 +31,9 @@ :func:`dist` and :func:`between` can take atom groups that do not even have to be from the same :class:`~MDAnalysis.core.universe.Universe`. -.. SeeAlso:: :mod:`MDAnalysis.lib.distances` +See Also +-------- +:mod:`MDAnalysis.lib.distances` """ from __future__ import absolute_import diff --git a/package/MDAnalysis/analysis/hbonds/hbond_analysis.py b/package/MDAnalysis/analysis/hbonds/hbond_analysis.py index 88d8880486d..fc118762632 100644 --- a/package/MDAnalysis/analysis/hbonds/hbond_analysis.py +++ b/package/MDAnalysis/analysis/hbonds/hbond_analysis.py @@ -388,7 +388,10 @@ class HydrogenBondAnalysis(object): *GLYCAM06* N,NT,O,O2,OH,OS,OW,OY,P,S,SM - .. SeeAlso:: Table :ref:`Default atom names for hydrogen bonding analysis` + See Also + -------- + :ref:`Default atom names for hydrogen bonding analysis` + .. versionchanged:: 0.7.6 DEFAULT_DONORS/ACCEPTORS is now embedded in a dict to switch between @@ -541,6 +544,7 @@ def __init__(self, universe, selection1='protein', selection2='all', selection1_ is raised for each static selection without the required donors and/or acceptors. + .. versionchanged:: 0.7.6 New *verbose* keyword (and per-frame debug logging disabled by default). @@ -704,9 +708,11 @@ def _get_bonded_hydrogens(self, atom, **kwargs): :class:`~MDAnalysis.core.groups.AtomGroup`) or empty list ``[]`` if none were found. - .. SeeAlso:: + See Also + -------- + :meth:`_get_bonded_hydrogens_dist` + :meth:`_get_bonded_hydrogens_list` - :meth:`_get_bonded_hydrogens_dist` and :meth:`_get_bonded_hydrogens_list` .. versionchanged:: 0.7.6 Can switch algorithm by using the *detect_hydrogens* keyword to the @@ -848,8 +854,10 @@ def run(self, **kwargs): :class:`~MDAnalysis.lib.log.ProgressMeter`) and *debug* which can be used to change the debug value provided to the class constructor. - .. SeeAlso:: :meth:`HydrogenBondAnalysis.generate_table` for processing - the data into a different format. + Note + ---- + Use :meth:`HydrogenBondAnalysis.generate_table` for processing the data into a different format. + .. versionchanged:: 0.7.6 Results are not returned, only stored in @@ -1068,7 +1076,6 @@ def save_table(self, filename="hbond_table.pickle"): import cPickle table = cPickle.load(open(filename)) - .. SeeAlso:: :mod:`cPickle` module and :class:`numpy.recarray` """ if self.table is None: self.generate_table() @@ -1270,12 +1277,12 @@ def _donor_lookup_table_byindex(self): heavy_atom_name = h2donor[index] - .. Note:: - - *index* is the 0-based MDAnalysis index - (:attr:`MDAnalysis.core.groups.Atom.index`). The - tables generated by :class:`HydrogenBondAnalysis` contain - 1-based indices and zero-based indices. + Note + ---- + *index* is the 0-based MDAnalysis index + (:attr:`MDAnalysis.core.groups.Atom.index`). The + tables generated by :class:`HydrogenBondAnalysis` contain + 1-based indices and zero-based indices. .. deprecated:: 0.15.0 The 1-based indices are deprecated in favor of the zero-based indices diff --git a/package/MDAnalysis/analysis/hole.py b/package/MDAnalysis/analysis/hole.py index e99d73303b8..e129c3f07fb 100644 --- a/package/MDAnalysis/analysis/hole.py +++ b/package/MDAnalysis/analysis/hole.py @@ -166,11 +166,12 @@ keyword argument and load an arbitrary order parameter for each frame. In that case, the key becomes the orderparameter. -.. Note:: - The profiles dict is not ordered and hence one typically needs to manually - order the keys first. Furthermore, duplicate keys are not possible: - In the case of *duplicate orderparameters*, the last one read will - be stored in the dict. +Notes +----- +The profiles dict is not ordered and hence one typically needs to manually +order the keys first. Furthermore, duplicate keys are not possible: +In the case of *duplicate orderparameters*, the last one read will +be stored in the dict. Analysis @@ -624,7 +625,6 @@ def __init__(self, filename, **kwargs): are read. Note that if water molecules or ions are present in the channel these can be ignored on read by the use of the `ignore_residues` keyword. - **Wildcard pattern**. A new feature (in release 2.1 of HOLE) was the option to include a wild card (``*``) in the filename. e.g., ``filename="ab*.pdb"`` will apply hole to all files in the @@ -639,18 +639,10 @@ def __init__(self, filename, **kwargs): atoms or atom order etc. (though they should be sufficiently similar for a HOLE run from identical starting conditions to be useful). - - .. SeeAlso:: - - An alternative way to load in multiple files is a direct read - from a CHARMM binary dynamics DCD coordinate file - using the - `dcd` keyword or use :class:`HOLEtraj`. - dcd : string, optional File name of DCD trajectory (must be supplied together with a matching PDB file `filename`) and then HOLE runs its analysis on each frame. - It does multiple HOLE runs on positions taken from a CHARMM binary dynamics format DCD trajectory file. The `dcd` file must have exactly the same number of atoms in exactly the same order as the @@ -663,21 +655,12 @@ def __init__(self, filename, **kwargs): controlled by the `step` keyword and/or setting :attr:`HOLE.dcd_iniskip` to the number of frames to be skipped initially. - - .. Note:: - - HOLE is very picky and does not read all DCD-like - formats [#HOLEDCD]_. If in doubt, look into the `logfile` for - error diagnostics. - logfile : string, optional file name of the file collecting HOLE's output (which can be parsed using :meth:`HOLE.collect`); the default is "hole.out". - sphpdb : string, optional path to the HOLE sph file, a PDB-like file containig the coordinates of the pore centers; the default is "hole.sph". - This keyword specifies the filename for output of the sphere centre information in pdb form. Its typical suffix is ".sph". The co-ordinates are set to the sphere centres and the occupancies are @@ -689,20 +672,16 @@ def __init__(self, filename, **kwargs): objects are best displayed as "Points". Displaying .sph objects rather than rendered or dot surfaces can be useful to analyze the distance of particular atoms from the sphere-centre line. - Most usefully .sph files can be used to produce molecular graphical output from a hole run. This is achieved by using the :program:`sph_process` program to read the .sph file. - step : int, optional step size for going through the trajectory (skips `step` - 1 frames); the default is 1. - cpoint : array_like, optional coordinates of a point inside the pore, e.g. ``[12.3, 0.7, 18.55]``. If set to ``None`` (the default) then HOLE's own search algorithm is used. - `cpoint` specifies a point which lies within the channel. For simple channels such as gramicidin results do not show great sensitivity to the exact point taken. An easy way to produce an @@ -712,7 +691,6 @@ def __init__(self, filename, **kwargs): then take the coordinates of one of these (and use the `ignore_residues` keyword to ignore them in the pore radius calculation). - If this card is not specified then HOLE now (from version 2.2) attempts to make a guess where the channel will be. The procedure assumes the channel is reasonably symmetric. The initial guess on @@ -721,12 +699,10 @@ def __init__(self, filename, **kwargs): Å from the original position. This procedure works most of the time but is clearly far from infallible — results should be careful checked (with molecular graphics) if it is used. - cvect : array_like, optional Search direction, should be parallel to the pore axis, e.g. ``[0,0,1]`` for the z-axis. The default is ``None`` so that HOLE's built-in procedure is used. - If this keyword is ``None`` then HOLE attempts to make a guess where the channel will be. The procedure assumes the channel is reasonably symmetric. The guess will be either along the X axis @@ -734,22 +710,17 @@ def __init__(self, filename, **kwargs): aligned on one of these axis the results will clearly be approximate. If a guess is used then results should be carefully checked. - sample : float, optional distance of sample points in Å; the default is 0.2 Å. - Specifies the distance between the planes used in the HOLE procedure. The default value should be reasonable for most purposes. However, if you wish to visualize a very tight constriction then specify a smaller value. - This value determines how many points in the pore profile are calculated. - dotden : int, optional density of facettes for generating a 3D pore representation; default is 15. - This number controls the density of dots which will be used by the program. A sphere of dots is placed on each centre determined in the Monte Carlo procedure. Only dots which do not @@ -757,38 +728,32 @@ def __init__(self, filename, **kwargs): dots written is therefore controlled by `dotden` and `sample`. `dotden` should be set to between 5 (few dots per sphere) and 35 (large number of dots per sphere). - endrad : float, optional Radius which is considered to be the end of the pore. This keyword can be used to specify the radius above which the program regards a result as indicating that the end of the pore has been reached. The default value is 22.0 Å. This may need to be increased for large channels or reduced for small. - shorto : int, optional Determines the output of output in the `logfile`; for automated processing this must be < 3. The default is 0, which shows all output. - - - 0: Full text output - - 1: All text output given except "run in progress" (i.e., - detailed contemporary description of what HOLE is doing). - - 2: Ditto plus no graph type output - only leaving minimum - radius and conductance calculations. - - 3: All text output other than input card mirroring and error messages - turned off. - + 0: Full text output, + 1: All text output given except "run in progress" (i.e., + detailed contemporary description of what HOLE is doing). + 2: Ditto plus no graph type output - only leaving minimum + radius and conductance calculations. + 3: All text output other than input card mirroring and error messages + turned off. ignore_residues : array_like, optional sequence of three-letter residues that are not taken into account during the calculation; wildcards are *not* supported. The default is ``["SOL","WAT", "TIP", "HOH", "K ", "NA ", "CL "]``. - radius : string, optional path to the file specifying van der Waals radii for each atom. If set to ``None`` (the default) then a set of default radii, :data:`SIMPLE2_RAD`, is used (an extension of ``simple.rad`` from the HOLE distribution) - executable : string, optional Path to the :program:`hole` executable (e.g. ``~/hole2/exe/hole``); the other programs @@ -796,13 +761,22 @@ def __init__(self, filename, **kwargs): to live in the same directory as :program:`hole`. If :program:`hole` is found on the :envvar:`PATH` then the bare executable name is sufficient. The default is "hole". - raseed : int, optional integer number to start the random number generator; by default, :program:`hole` will use the time of the day (default value ``None``) but for reproducible runs (e.g., for testing) set it to an integer. + + Notes + ----- + - An alternative way to load in multiple files is a direct read + from a CHARMM binary dynamics DCD coordinate file - using the + `dcd` keyword or use :class:`HOLEtraj`. + - HOLE is very picky and does not read all DCD-like + formats [#HOLEDCD]_. If in doubt, look into the `logfile` for + error diagnostics. + """ # list of temporary files, to be cleaned up on __del__ diff --git a/package/MDAnalysis/analysis/leaflet.py b/package/MDAnalysis/analysis/leaflet.py index 71595045cb1..1ac460fc633 100644 --- a/package/MDAnalysis/analysis/leaflet.py +++ b/package/MDAnalysis/analysis/leaflet.py @@ -203,7 +203,10 @@ def groups(self, component_index=None): If no argument is supplied, then a list of all leaflet groups is returned. - .. SeeAlso:: :meth:`LeafletFinder.group` and :meth:`LeafletFinder.groups_iter` + See Also + -------- + :meth:`LeafletFinder.group` + :meth:`LeafletFinder.groups_iter` """ if component_index is None: return list(self.groups_iter()) diff --git a/package/MDAnalysis/analysis/legacy/x3dna.py b/package/MDAnalysis/analysis/legacy/x3dna.py index 3efa4d52277..76acb3d0560 100644 --- a/package/MDAnalysis/analysis/legacy/x3dna.py +++ b/package/MDAnalysis/analysis/legacy/x3dna.py @@ -509,7 +509,9 @@ def __init__(self, filename, **kwargs): Write output from X3DNA to `logfile` (default: "bp_step.par") - .. SeeAlso:: :class:`X3DNAtraj` + See Also + -------- + :class:`X3DNAtraj` """ # list of temporary files, to be cleaned up on __del__ self.tempfiles = [ @@ -755,7 +757,9 @@ def __init__(self, universe, **kwargs): for description). - .. SeeAlso:: :class:`X3DNA` + See Also + -------- + :class:`X3DNA` """ self.universe = universe diff --git a/package/MDAnalysis/analysis/psa.py b/package/MDAnalysis/analysis/psa.py index e5c8a68b533..b20acdace37 100644 --- a/package/MDAnalysis/analysis/psa.py +++ b/package/MDAnalysis/analysis/psa.py @@ -52,10 +52,12 @@ metrics; using the best-fit rmsd on a pairwise basis does not generally preserve the triangle inequality. -.. SeeAlso:: The `PSAnalysisTutorial`_ outlines a typical application of PSA to - a set of trajectories, including doing proper alignment, - performing distance comparisons, and generating heat - map-dendrogram plots from hierarchical clustering. +Note +---- +The `PSAnalysisTutorial`_ outlines a typical application of PSA to +a set of trajectories, including doing proper alignment, +performing distance comparisons, and generating heat +map-dendrogram plots from hierarchical clustering. .. Rubric:: References @@ -358,6 +360,8 @@ def hausdorff(P, Q): :attr:`MDAnalysis.core.groups.AtomGroup.positions`). *P* (*Q*) has either shape |3Dp| (|3Dq|), or |2Dp| (|2Dq|) in flattened form. + Note that reversing the path does not change the Hausdorff distance. + Parameters ---------- P : numpy.ndarray @@ -389,21 +393,16 @@ def hausdorff(P, Q): >>> hausdorff(P,Q[::-1]) # hausdorff distance w/ reversed 2nd trajectory 4.7786639840135905 - Note that reversing the path does not change the Hausdorff distance. Notes ----- - The Hausdorff distance is calculated in a brute force manner from the - distance matrix without further optimizations, essentially following - [Huttenlocher1993]_. - - .. SeeAlso:: - - :func:`scipy.spatial.distance.directed_hausdorff` is an optimized - implementation of the early break algorithm of [Taha2015]_; note that - one still has to calculate the *symmetric* Hausdorff distance as - `max(directed_hausdorff(P, Q)[0], directed_hausdorff(Q, P)[0])`. - + - The Hausdorff distance is calculated in a brute force manner from the + distance matrix without further optimizations, essentially following + [Huttenlocher1993]_. + - :func:`scipy.spatial.distance.directed_hausdorff` is an optimized + implementation of the early break algorithm of [Taha2015]_; note that + one still has to calculate the *symmetric* Hausdorff distance as + `max(directed_hausdorff(P, Q)[0], directed_hausdorff(Q, P)[0])`. References ---------- @@ -560,14 +559,11 @@ def hausdorff_neighbors(P, Q): Notes ----- - Hausdorff neighbors are those points on the two paths that are separated by - the Hausdorff distance. They are the farthest nearest neighbors and are - maximally different in the sense of the Hausdorff distance [Seyler2015]_. - - .. SeeAlso:: - - :func:`scipy.spatial.distance.directed_hausdorff` can also provide the - Hausdorff neighbors. + - Hausdorff neighbors are those points on the two paths that are separated by + the Hausdorff distance. They are the farthest nearest neighbors and are + maximally different in the sense of the Hausdorff distance [Seyler2015]_. + - :func:`scipy.spatial.distance.directed_hausdorff` can also provide the + hausdorff neighbors. """ N, axis = get_coord_axes(P) diff --git a/package/MDAnalysis/analysis/rms.py b/package/MDAnalysis/analysis/rms.py index a89da12ab5b..dad0e3c1975 100644 --- a/package/MDAnalysis/analysis/rms.py +++ b/package/MDAnalysis/analysis/rms.py @@ -44,12 +44,14 @@ When using this module in published work please cite [Theobald2005]_. -.. SeeAlso:: - :mod:`MDAnalysis.analysis.align` - aligning structures based on RMSD - :mod:`MDAnalysis.lib.qcprot` - implements the fast RMSD algorithm. +See Also +-------- +:mod:`MDAnalysis.analysis.align` + aligning structures based on RMSD +:mod:`MDAnalysis.lib.qcprot` + implements the fast RMSD algorithm. + Example applications -------------------- diff --git a/package/MDAnalysis/coordinates/DCD.py b/package/MDAnalysis/coordinates/DCD.py index e8e44ebf572..c55aca47298 100644 --- a/package/MDAnalysis/coordinates/DCD.py +++ b/package/MDAnalysis/coordinates/DCD.py @@ -38,21 +38,24 @@ trajectories with other tools you might need to watch out that time and unitcell dimensions are correctly interpreted. -.. Note:: - - The DCD file format is not well defined. In particular, NAMD and - CHARMM use it differently. Currently, MDAnalysis tries to guess the - correct **format for the unitcell representation** but it can be - wrong. **Check the unitcell dimensions**, especially for triclinic - unitcells (see `Issue 187`_ and :attr:`Timestep.dimensions`). A - second potential issue are the units of time which are AKMA for the - :class:`DCDReader` (following CHARMM) but ps for NAMD. As a - workaround one can employ the configurable - :class:`MDAnalysis.coordinates.LAMMPS.DCDReader` for NAMD - trajectories. - -.. SeeAlso:: The :mod:`MDAnalysis.coordinates.LAMMPS` module provides - a more flexible DCD reader/writer. +Note +---- +The DCD file format is not well defined. In particular, NAMD and +CHARMM use it differently. Currently, MDAnalysis tries to guess the +correct **format for the unitcell representation** but it can be +wrong. **Check the unitcell dimensions**, especially for triclinic +unitcells (see `Issue 187`_ and :attr:`Timestep.dimensions`). A +second potential issue are the units of time which are AKMA for the +:class:`DCDReader` (following CHARMM) but ps for NAMD. As a +workaround one can employ the configurable +:class:`MDAnalysis.coordinates.LAMMPS.DCDReader` for NAMD +trajectories. + +See Also +-------- +:mod:`MDAnalysis.coordinates.LAMMPS` + module provides a more flexible DCD reader/writer. + The classes in this module are the reference implementations for the Trajectory API. @@ -337,7 +340,9 @@ def write_next_timestep(self, ts=None): def convert_dimensions_to_unitcell(self, ts, _ts_order=Timestep._ts_order): """Read dimensions from timestep *ts* and return appropriate native unitcell. - .. SeeAlso:: :attr:`Timestep.dimensions` + See Also + -------- + :attr:`Timestep.dimensions` """ # unitcell is A,B,C,alpha,beta,gamma - convert to order expected by low level DCD routines lengths, angles = ts.dimensions[:3], ts.dimensions[3:] @@ -618,7 +623,9 @@ def Writer(self, filename, **kwargs): according to the CHARMM format. The time between two frames would be *delta* * *step* ! - .. SeeAlso:: :class:`DCDWriter` has detailed argument description + See Also + -------- + :class:`DCDWriter` """ n_atoms = kwargs.pop('n_atoms', self.n_atoms) kwargs.setdefault('start', self.start_timestep) diff --git a/package/MDAnalysis/coordinates/PDB.py b/package/MDAnalysis/coordinates/PDB.py index 6f2318cc0dd..4bd225fa3c8 100644 --- a/package/MDAnalysis/coordinates/PDB.py +++ b/package/MDAnalysis/coordinates/PDB.py @@ -135,6 +135,9 @@ .. autoclass:: MultiPDBWriter :members: +.. autoclass:: ExtendedPDBReader + :members: + :inherited-members: ..deprecated:: 0.15.0 The "permissive" flag is not used anymore (and effectively defaults to True); @@ -221,9 +224,13 @@ class PDBReader(base.ReaderBase): ============= ============ =========== ============================================= - .. SeeAlso:: :class:`PDBWriter`; :class:`PDBReader` - implements a larger subset of the header records, - which are accessible as :attr:`PDBReader.metadata`. + See Also + -------- + :class:`PDBWriter` + :class:`PDBReader` + implements a larger subset of the header records, + which are accessible as :attr:`PDBReader.metadata`. + .. versionchanged:: 0.11.0 * Frames now 0-based instead of 1-based @@ -416,10 +423,12 @@ class PDBWriter(base.WriterBase): .. _ENDMDL: http://www.wwpdb.org/documentation/format32/sect9.html#ENDMDL .. _CONECT: http://www.wwpdb.org/documentation/format32/sect10.html#CONECT - .. SeeAlso:: - This class is identical to :class:`MultiPDBWriter` with the one - exception that it defaults to writing single-frame PDB files as if - *multiframe* = ``False`` was selected. + Note + ---- + This class is identical to :class:`MultiPDBWriter` with the one + exception that it defaults to writing single-frame PDB files as if + *multiframe* = ``False`` was selected. + .. versionchanged:: 0.7.5 Initial support for multi-frame PDB files. @@ -513,16 +522,6 @@ def __init__(self, filename, bonds="conect", n_atoms=None, start=0, step=1, the value of :data:`MDAnalysis.core.flags` ['convert_lengths'] *bonds* write bonds to the PDB file as CONECT_ records [``False``] - - .. Note:: - - Currently only works when writing a whole :class:`Universe` and - if bond information is available in the topology. (For selections - smaller than the whole :class:`Universe`, the atom numbering in - the CONECT_ records would not match the numbering of the atoms in - the new PDB file and therefore a :exc:`NotImplementedError` is - raised.) - *multiframe* ``False``: write a single frame to the file; ``True``: create a multi frame PDB file in which frames are written as MODEL_ ... ENDMDL_ @@ -532,6 +531,15 @@ def __init__(self, filename, bonds="conect", n_atoms=None, start=0, step=1, .. _MODEL: http://www.wwpdb.org/documentation/format32/sect9.html#MODEL .. _ENDMDL: http://www.wwpdb.org/documentation/format32/sect9.html#ENDMDL + Note + ---- + Writing bonds currently only works when writing a whole + :class:`Universe` and if bond information is available in the topology. + (For selections smaller than the whole :class:`Universe`, the atom + numbering in the CONECT_ records would not match the numbering of the + atoms in the new PDB file and therefore a :exc:`NotImplementedError` is + raised.) + """ # n_atoms = None : dummy keyword argument # (not used, but Writer() always provides n_atoms as the second argument) @@ -1007,15 +1015,17 @@ def CONECT(self, conect): class ExtendedPDBReader(PDBReader): """PDBReader that reads a PDB-formatted file with five-digit residue numbers. - This reader does not conform to the `PDB standard`_ because it allows + This reader does not conform to the `PDB 3.2 standard`_ because it allows five-digit residue numbers that may take up columns 23 to 27 (inclusive) instead of being confined to 23-26 (with column 27 being reserved for the insertion code in the PDB standard). PDB files in this format are written by popular programs such as VMD_. - .. SeeAlso:: :class:`PDBReader` + See Also + -------- + :class:`PDBReader` + - .. _PDB standard: http://www.wwpdb.org/documentation/format32/sect9.html .. _VMD: http://www.ks.uiuc.edu/Research/vmd/ .. versionadded:: 0.8 @@ -1039,10 +1049,12 @@ class MultiPDBWriter(PDBWriter): .. _CONECT: http://www.wwpdb.org/documentation/format32/sect10.html#CONECT - .. SeeAlso:: - This class is identical to :class:`PDBWriter` with the one - exception that it defaults to writing multi-frame PDB files instead of - single frames. + See Also + -------- + This class is identical to :class:`PDBWriter` with the one + exception that it defaults to writing multi-frame PDB files instead of + single frames. + .. versionadded:: 0.7.6 diff --git a/package/MDAnalysis/coordinates/TRJ.py b/package/MDAnalysis/coordinates/TRJ.py index 973fd723c0e..d484671795d 100644 --- a/package/MDAnalysis/coordinates/TRJ.py +++ b/package/MDAnalysis/coordinates/TRJ.py @@ -408,7 +408,9 @@ class NCDFReader(base.ReaderBase): .. _AMBER NETCDF format: http://ambermd.org/netcdf/nctraj.html - .. SeeAlso:: :class:`NCDFWriter` + See Also + -------- + :class:`NCDFWriter` .. versionadded: 0.7.6 .. versionchanged:: 0.10.0 @@ -604,7 +606,9 @@ class NCDFWriter(base.WriterBase): .. _AMBER NETCDF format: http://ambermd.org/netcdf/nctraj.html - .. SeeAlso:: :class:`NCDFReader` + See Also + -------- + :class:`NCDFReader` .. versionadded: 0.7.6 diff --git a/package/MDAnalysis/coordinates/base.py b/package/MDAnalysis/coordinates/base.py index bd81f66bb59..3da3437cdef 100644 --- a/package/MDAnalysis/coordinates/base.py +++ b/package/MDAnalysis/coordinates/base.py @@ -710,8 +710,10 @@ def triclinic_dimensions(self): array([ 15. , 15.81138802, 16.58312416, 67.58049774, 72.45159912, 71.56504822], dtype=float32) - .. SeeAlso:: - :func:`MDAnalysis.lib.mdamath.triclinic_vectors` + See Also + -------- + :func:`MDAnalysis.lib.mdamath.triclinic_vectors` + .. versionadded:: 0.11.0 """ @@ -1060,7 +1062,9 @@ class ProtoReader(six.with_metaclass(_Readermeta, IOBase)): :mod:`MDAnalysis.coordinates.__init__` for the required attributes and methods. - .. SeeAlso:: :class:`ReaderBase` + See Also + -------- + :class:`ReaderBase` .. versionchanged:: 0.11.0 Frames now 0-based instead of 1-based @@ -1146,7 +1150,9 @@ def OtherWriter(self, filename, **kwargs): Sets the default keywords *start*, *step* and *dt* (if available). *n_atoms* is always set from :attr:`Reader.n_atoms`. - .. SeeAlso:: :meth:`Reader.Writer` and :func:`MDAnalysis.Writer` + See Also + -------- + :meth:`Reader.Writer` and :func:`MDAnalysis.Writer` """ kwargs['n_atoms'] = self.n_atoms # essential kwargs.setdefault('start', self.frame) @@ -1618,7 +1624,9 @@ class ReaderBase(ProtoReader): :mod:`MDAnalysis.coordinates.__init__` for the required attributes and methods. - .. SeeAlso:: :class:`ProtoReader` + See Also + -------- + :class:`ProtoReader` .. versionchanged:: 0.11.0 Most of the base Reader class definitions were offloaded to diff --git a/package/MDAnalysis/coordinates/core.py b/package/MDAnalysis/coordinates/core.py index fbd918b03fe..91ded0e5b0d 100644 --- a/package/MDAnalysis/coordinates/core.py +++ b/package/MDAnalysis/coordinates/core.py @@ -67,15 +67,15 @@ def reader(filename, **kwargs): ------- A Reader object - .. SeeAlso:: For trajectory formats: :class:`~DCD.DCDReader`, - :class:`~XTC.XTCReader`, :class:`~TRR.TRRReader`, - :class:`~XYZ.XYZReader`. For single frame formats: - :class:`~CRD.CRDReader`, and - :class:`~PDB.PDBReader`, :class:`~GRO.GROReader`, + See Also + -------- + :ref:`Supported coordinate formats` + .. deprecated:: 0.15.0 - The "permissive" flag is not used anymore (and effectively - defaults to True); it will be completely removed in 0.16.0. + The "permissive" flag is not used anymore (and effectively + defaults to True); it will be completely removed in 0.16.0. + """ if isinstance(filename, tuple): Reader = get_reader_for(filename[0], @@ -114,9 +114,7 @@ def writer(filename, n_atoms=None, **kwargs): See Also -------- - MDAnalysis.coordinates.DCD.DCDWriter : DCD trajectories - MDAnalysis.coordinates.XTC.XTCWriter : Gromacs XTC trajectories - MDAnalysis.coordinates.TRR.TRRWriter : Gromacs TRR trajectories + :ref:`Supported coordinate formats` .. versionchanged:: 0.7.6 diff --git a/package/MDAnalysis/core/groups.py b/package/MDAnalysis/core/groups.py index 6ec7b43dffd..fab774af10f 100644 --- a/package/MDAnalysis/core/groups.py +++ b/package/MDAnalysis/core/groups.py @@ -1483,7 +1483,9 @@ class AtomGroup(GroupBase): AtomGroup instances are always bound to a :class:`MDAnalysis.core.universe.Universe`. They cannot exist in isolation. - .. SeeAlso:: :class:`MDAnalysis.core.universe.Universe` + See Also + -------- + :class:`MDAnalysis.core.universe.Universe` """ def __getitem__(self, item): diff --git a/package/MDAnalysis/core/selection.py b/package/MDAnalysis/core/selection.py index 06b51766cf5..e86fe8e9630 100644 --- a/package/MDAnalysis/core/selection.py +++ b/package/MDAnalysis/core/selection.py @@ -822,7 +822,9 @@ class ProteinSelection(Selection): * still missing: Amber N- and C-terminal residue names - .. SeeAlso:: :func:`MDAnalysis.lib.util.convert_aa_code` + See Also + -------- + :func:`MDAnalysis.lib.util.convert_aa_code` """ token = 'protein' diff --git a/package/MDAnalysis/lib/log.py b/package/MDAnalysis/lib/log.py index 8541f37aca6..a0a04d2b2b2 100644 --- a/package/MDAnalysis/lib/log.py +++ b/package/MDAnalysis/lib/log.py @@ -21,8 +21,7 @@ # -""" -Setting up logging --- :mod:`MDAnalysis.lib.log` +"""Setting up logging --- :mod:`MDAnalysis.lib.log` ==================================================== Configure logging for MDAnalysis. Import this module if logging is @@ -58,8 +57,10 @@ .. _logging to multiple destinations: http://docs.python.org/library/logging.html?#logging-to-multiple-destinations -.. SeeAlso:: The :mod:`logging` module in the standard library contains - in depth documentation about using logging. +Note +---- +The :mod:`logging` module in the standard library contains in depth +documentation about using logging. Convenience functions @@ -76,6 +77,7 @@ ------------------------------------------------ .. autogenerated, see Online Docs + """ from __future__ import print_function, division, absolute_import diff --git a/package/MDAnalysis/lib/mdamath.py b/package/MDAnalysis/lib/mdamath.py index 0be25c70ae5..a20d3fb4e47 100644 --- a/package/MDAnalysis/lib/mdamath.py +++ b/package/MDAnalysis/lib/mdamath.py @@ -164,7 +164,9 @@ def triclinic_box(x, y, z): * beta = angle(x,z) * gamma = angle(x,y) - .. SeeAlso:: Definition of angles: http://en.wikipedia.org/wiki/Lattice_constant + Note + ---- + Definition of angles: http://en.wikipedia.org/wiki/Lattice_constant """ A, B, C = [norm(v) for v in (x, y, z)] alpha = _angle(y, z) diff --git a/package/MDAnalysis/lib/util.py b/package/MDAnalysis/lib/util.py index 85284ca98bc..f8d10bb084b 100644 --- a/package/MDAnalysis/lib/util.py +++ b/package/MDAnalysis/lib/util.py @@ -30,11 +30,7 @@ --------------------- .. autofunction:: filename -.. function:: openany(directory[,mode='r']) - - Context manager to open a compressed (bzip2, gzip) or plain file - (uses :func:`anyopen`). - +.. autofunction:: openany .. autofunction:: anyopen .. autofunction:: greedy_splitext .. autofunction:: which @@ -237,29 +233,33 @@ def openany(datasource, mode='r', reset=True): compressed files) to open file objects to sockets and strings---as long as they have a file-like interface. - :Arguments: - *datasource* - a file or a stream - *mode* - 'r' or 'w' - *reset* + Parameters + ---------- + datasource : a file or a stream + mode : str + `r` or `w` + reset : bool try to read (*mode* 'r') the stream from the start [``True``] - .. rubric:: Examples - + Examples + -------- Open a gzipped file and process it line by line:: - with openany("input.pdb.gz") as pdb: - for line in pdb: - if line.startswith('ATOM'): print(line) + with openany("input.pdb.gz") as pdb: + for line in pdb: + if line.startswith('ATOM'): + print(line) Open a URL and read it:: import urllib2 with openany(urllib2.urlopen("http://www.MDAnalysis.org/")) as html: - print(html.read()) + print(html.read()) - .. SeeAlso:: :func:`anyopen` + + See Also + -------- + :func:`anyopen` """ stream = anyopen(datasource, mode=mode, reset=reset) try: @@ -309,7 +309,11 @@ def anyopen(datasource, mode='r', reset=True): :Returns: tuple ``stream`` which is a file-like object - .. SeeAlso:: :func:`openany` to be used with the :keyword:`with` statement. + See Also + -------- + :func:`openany` + to be used with the :keyword:`with` statement. + .. versionchanged:: 0.9.0 Only returns the ``stream`` and tries to set ``stream.name = filename`` instead of the previous @@ -447,7 +451,10 @@ def isstream(obj): - ``read()``, ``readline()``, ``readlines()`` - ``write()``, ``writeline()``, ``writelines()`` - .. SeeAlso:: :mod:`io` + See Also + -------- + :mod:`io` + :Arguments: *obj* @@ -997,7 +1004,9 @@ def read(self, line): :Raises: :exc:`ValueError` if any of the conversions cannot be made (e.g. space for an int) - .. SeeAlso:: :meth:`FORTRANReader.number_of_matches` + See Also + -------- + :meth:`FORTRANReader.number_of_matches` """ return [e.read(line) for e in self.entries] @@ -1115,7 +1124,9 @@ def fixedwidth_bins(delta, xmin, xmax): def convert_aa_code(x): """Converts between 3-letter and 1-letter amino acid codes. - .. SeeAlso:: Data are defined in :data:`amino_acid_codes` and :data:`inverse_aa_codes`. + Note + ---- + Data are defined in :data:`amino_acid_codes` and :data:`inverse_aa_codes`. """ if len(x) == 1: d = amino_acid_codes diff --git a/package/MDAnalysis/topology/ExtendedPDBParser.py b/package/MDAnalysis/topology/ExtendedPDBParser.py index 96490833c2e..2888eb2164f 100644 --- a/package/MDAnalysis/topology/ExtendedPDBParser.py +++ b/package/MDAnalysis/topology/ExtendedPDBParser.py @@ -37,11 +37,12 @@ least 100,000 residues then you need to use a different file format that can handle such residue numbers. -.. SeeAlso:: +See Also +-------- +* :mod:`MDAnalysis.topology.PDBParser` +* :class:`MDAnalysis.coordinates.PDB.ExtendedPDBReader` +* :class:`MDAnalysis.core.universe.Universe` - * :mod:`MDAnalysis.topology.PDBParser` - * :class:`MDAnalysis.coordinates.PDB.ExtendedPDBReader` - * :class:`MDAnalysis.core.universe.Universe` Classes ------- @@ -74,7 +75,9 @@ class ExtendedPDBParser(PDBParser.PDBParser): - resnames - segids - .. SeeAlso:: :class:`MDAnalysis.coordinates.PDB.ExtendedPDBReader` + See Also + -------- + :class:`MDAnalysis.coordinates.PDB.ExtendedPDBReader` .. versionadded:: 0.8 """ diff --git a/package/MDAnalysis/topology/GROParser.py b/package/MDAnalysis/topology/GROParser.py index 9ea4ab0e755..60758b0c41d 100644 --- a/package/MDAnalysis/topology/GROParser.py +++ b/package/MDAnalysis/topology/GROParser.py @@ -29,7 +29,10 @@ Atom types and masses are guessed. -.. SeeAlso:: :mod:`MDAnalysis.coordinates.GRO` +See Also +-------- +:mod:`MDAnalysis.coordinates.GRO` + Classes ------- diff --git a/package/MDAnalysis/topology/PDBParser.py b/package/MDAnalysis/topology/PDBParser.py index 1a14d224d7e..b90b637dee8 100644 --- a/package/MDAnalysis/topology/PDBParser.py +++ b/package/MDAnalysis/topology/PDBParser.py @@ -40,11 +40,12 @@ The parser processes atoms and their names. Masses are guessed and set to 0 if unknown. Partial charges are not set. -.. SeeAlso:: +See Also +-------- +* :mod:`MDAnalysis.topology.ExtendedPDBParser` +* :class:`MDAnalysis.coordinates.PDB.PDBReader` +* :class:`MDAnalysis.core.universe.Universe` - * :mod:`MDAnalysis.topology.ExtendedPDBParser` - * :class:`MDAnalysis.coordinates.PDB.PDBReader` - * :class:`MDAnalysis.core.universe.Universe` Classes ------- diff --git a/package/MDAnalysis/topology/PDBQTParser.py b/package/MDAnalysis/topology/PDBQTParser.py index d1438a91721..c87c479ecb1 100644 --- a/package/MDAnalysis/topology/PDBQTParser.py +++ b/package/MDAnalysis/topology/PDBQTParser.py @@ -31,23 +31,28 @@ * Reads a PDBQT file line by line and does not require sequential atom numbering. * Multi-model PDBQT files are not supported. -.. Note:: Only reads atoms and their names; connectivity is not - deduced. Masses are guessed and set to 0 if unknown. +Notes +----- +Only reads atoms and their names; connectivity is not +deduced. Masses are guessed and set to 0 if unknown. -.. SeeAlso:: `MDAnalysis.coordinates.PDBQT` -.. _PDBQT: - http://autodock.scripps.edu/faqs-help/faq/what-is-the-format-of-a-pdbqt-file -.. _AutoDock: - http://autodock.scripps.edu/ +See Also +-------- +`MDAnalysis.coordinates.PDBQT` + Classes ------- - .. autoclass:: PDBQTParser :members: :inherited-members: + +.. _PDBQT: + http://autodock.scripps.edu/faqs-help/faq/what-is-the-format-of-a-pdbqt-file +.. _AutoDock: + http://autodock.scripps.edu/ """ from __future__ import absolute_import diff --git a/package/MDAnalysis/topology/PQRParser.py b/package/MDAnalysis/topology/PQRParser.py index 1828a00b9c8..17fc9f6be4d 100644 --- a/package/MDAnalysis/topology/PQRParser.py +++ b/package/MDAnalysis/topology/PQRParser.py @@ -27,12 +27,10 @@ Read atoms with charges from a PQR_ file (as written by PDB2PQR_). No connectivity is deduced. -.. SeeAlso:: The file format is described in :mod:`MDAnalysis.coordinates.PQR`. +Note +---- +The file format is described in :mod:`MDAnalysis.coordinates.PQR`. -.. _PQR: http://www.poissonboltzmann.org/file-formats/biomolecular-structurw/pqr -.. _APBS: http://www.poissonboltzmann.org/apbs -.. _PDB2PQR: http://www.poissonboltzmann.org/pdb2pqr -.. _PDB: http://www.rcsb.org/pdb/info.html#File_Formats_and_Standards Classes ------- @@ -41,6 +39,12 @@ :members: :inherited-members: + +.. _PQR: http://www.poissonboltzmann.org/file-formats/biomolecular-structurw/pqr +.. _APBS: http://www.poissonboltzmann.org/apbs +.. _PDB2PQR: http://www.poissonboltzmann.org/pdb2pqr +.. _PDB: http://www.rcsb.org/pdb/info.html#File_Formats_and_Standards + """ from __future__ import absolute_import diff --git a/package/MDAnalysis/topology/TPRParser.py b/package/MDAnalysis/topology/TPRParser.py index 90cb748425a..616d7cd0172 100644 --- a/package/MDAnalysis/topology/TPRParser.py +++ b/package/MDAnalysis/topology/TPRParser.py @@ -92,7 +92,10 @@ :members: :inherited-members: -.. SeeAlso:: :mod:`MDAnalysis.topology.tpr` +See Also +-------- +:mod:`MDAnalysis.topology.tpr` + Development notes ----------------- diff --git a/package/MDAnalysis/topology/__init__.py b/package/MDAnalysis/topology/__init__.py index af4253bf6ed..5e92d6393da 100644 --- a/package/MDAnalysis/topology/__init__.py +++ b/package/MDAnalysis/topology/__init__.py @@ -19,7 +19,7 @@ # MDAnalysis: A Toolkit for the Analysis of Molecular Dynamics Simulations. # J. Comput. Chem. 32 (2011), 2319--2327, doi:10.1002/jcc.21787 # -"""\ +""" Topology readers --- :mod:`MDAnalysis.topology` =============================================== @@ -156,13 +156,16 @@ parsing coordinates from a TPR file is currently not implemented in :mod:`~MDAnalysis.topology.TPRParser`. -.. SeeAlso:: :ref:`Coordinates` with the :ref:`Supported coordinate formats` +Note +---- +:ref:`Coordinates` with the :ref:`Supported coordinate formats` + .. _HOOMD XML: http://codeblue.umich.edu/hoomd-blue/doc/page_xml_file_format.html .. _Macromolecular Transmission Format (MMTF): https://mmtf.rcsb.org/ - .. _topology-parsers-developer-notes: + Developer Notes --------------- @@ -207,7 +210,11 @@ initialize the :class:`~MDAnalysis.core.topology.Topology` with the data read from the topology file. -.. SeeAlso:: :ref:`topology-system-label` + +See Also +-------- +:ref:`topology-system-label` + bonds ~~~~~~ diff --git a/package/MDAnalysis/topology/core.py b/package/MDAnalysis/topology/core.py index 11c029c73aa..fa3d1351c39 100644 --- a/package/MDAnalysis/topology/core.py +++ b/package/MDAnalysis/topology/core.py @@ -19,16 +19,17 @@ # MDAnalysis: A Toolkit for the Analysis of Molecular Dynamics Simulations. # J. Comput. Chem. 32 (2011), 2319--2327, doi:10.1002/jcc.21787 # -""" -Common functions for topology building --- :mod:`MDAnalysis.topology.core` +"""Common functions for topology building --- :mod:`MDAnalysis.topology.core` ========================================================================== The various topology parsers make use of functions and classes in this module. They are mostly of use to developers. -.. SeeAlso:: :mod:`MDAnalysis.topology.tables` for some hard-coded atom - information that is used by functions such as :func:`guess_atom_type` and - :func:`guess_atom_mass`. +See Also +-------- +:mod:`MDAnalysis.topology.tables` + for some hard-coded atom information that is used by functions such as + :func:`guess_atom_type` and :func:`guess_atom_mass`. """ diff --git a/package/MDAnalysis/topology/guessers.py b/package/MDAnalysis/topology/guessers.py index 68fc1f84fe2..d349ce027e3 100644 --- a/package/MDAnalysis/topology/guessers.py +++ b/package/MDAnalysis/topology/guessers.py @@ -79,8 +79,11 @@ def guess_atom_type(atomname): At the moment, this function simply returns the element, as guessed by :func:`guess_atom_element`. - .. SeeAlso:: :func:`guess_atom_element` and - :mod:`MDAnalysis.topology.tables` + See Also + -------- + :func:`guess_atom_element` + :mod:`MDAnalysis.topology.tables` + """ return guess_atom_element(atomname) @@ -96,8 +99,10 @@ def guess_atom_element(atomname): .. Warning: The translation table is incomplete. This will probably result in some mistakes, but it still better than nothing! - .. SeeAlso:: :func:`guess_atom_type` and - :mod:`MDAnalysis.topology.tables` (where the data are stored) + See Also + -------- + :func:`guess_atom_type` + :mod:`MDAnalysis.topology.tables` """ if atomname == '': return '' @@ -238,11 +243,15 @@ def guess_angles(bonds): Works by assuming that if atoms 1 & 2 are bonded, and 2 & 3 are bonded, then (1,2,3) must be an angle. - :Returns: - List of tuples defining the angles. - Suitable for use in u._topology + Returns + ------- + List of tuples defining the angles. + Suitable for use in u._topology + + See Also + -------- + :meth:`guess_bonds` - .. seeAlso:: :meth:`guess_bonds` .. versionadded 0.9.0 """ diff --git a/package/MDAnalysis/units.py b/package/MDAnalysis/units.py index 95e9235cf01..a26f2f6dc28 100644 --- a/package/MDAnalysis/units.py +++ b/package/MDAnalysis/units.py @@ -112,7 +112,10 @@ from `rho/rho0 = n/(N_A * M**-1) / rho0` where `[n] = 1/Volume`, `[rho] = mass/Volume` -.. SeeAlso:: Maybe we should simply use Quantities_ or :mod:`scipy.constants`? +Note +---- +Maybe we should simply use Quantities_ or :mod:`scipy.constants`? + .. _Quantities: http://packages.python.org/quantities/