doc fixes (especially new topology system) (MDAnalysis#1077)

- added missing docs for new topology system (MDAnalysis#363)
- removed some of the obviously old outdated topology discussions (but  still need proper discussion of MDAnalysis#363 changes – see issue MDAnalysis#1078 )
- added rst  sphinx stubs for new modules in core
- updated rst docs (added links, reformatted, fixed, found out that
  Napoleon REQUIRES two lines before .. versionchanged/versionadded)
- removed AtomGroup.rst
- restructured core_modules
- fixed Universe and AtomGroup reST references (core changes in MDAnalysis#363)

    find . -name '*.rst' -print0 | xargs -0 perl -wpi~ -e 's(MDAnalysis\.core\.AtomGroup\.Universe (MDAnalysis.core.universe.Universe)g'
    find . -name '*.py' -print0 | xargs -0 perl -wpi~ -e 's(MDAnalysis\.core\.AtomGroup\.Universe)(MDAnalysis.core.universe.Universe)g'
    find . -name '*.rst' -print0 | xargs -0 perl -wpi~ -e 's(MDAnalysis\.core\.AtomGroup\.AtomGroup)(MDAnalysis.core.groups.AtomGroup)g'
    find . -name '*.py' -print0 | xargs -0 perl -wpi~ -e 's(MDAnalysis\.core\.AtomGroup\.AtomGroup)(MDAnalysis.core.groups.AtomGroup)g'

- fixed reST links for other changes in core (MDAnalysis#363)
   - AtomGroup.Atom --> groups.Atom
   - AtomGroup.Merge --> universe.Merge
   - AtomGroup.ResidueGroup --> groups.ResidueGroup (no SegmentGroup needed to be fixed, no Residue or Segment found)
   - core.Selection --> core.selection

   find . \( -name '*.py' -o -name '*.rst' \) -print0 | xargs -0 perl -wpi~ -e 's(MDAnalysis\.core\.AtomGroup\.Atom)(MDAnalysis.core.groups.Atom)g'
   find . \( -name '*.py' -o -name '*.rst' \) -print0 | xargs -0 perl -wpi~ -e 's(MDAnalysis\.core\.AtomGroup\.Merge)(MDAnalysis.core.universe.Merge)g'
   find . \( -name '*.py' -o -name '*.rst' \) -print0 | xargs -0 perl -wpi~ -e 's(MDAnalysis\.core\.AtomGroup\.ResidueGroup)(MDAnalysis.core.universe.ResidueGroup)g'

- many more doc fixes everywhere
   - broken reST links
   - added more cross references and SeeAlso

package/MDAnalysis/__init__.py

@@ -107,7 +107,7 @@
    9.72062
   ....
 
-.. SeeAlso:: :class:`MDAnalysis.core.AtomGroup.Universe` for details
+.. SeeAlso:: :class:`MDAnalysis.core.universe.Universe` for details
 
 
 Examples

package/MDAnalysis/analysis/align.py

@@ -193,25 +193,24 @@
 
 
 def rotation_matrix(a, b, weights=None):
-    r"""Returns the 3x3 rotation matrix for RMSD fitting coordinate sets *a* and
-    *b*.
+    r"""Returns the 3x3 rotation matrix `R` for RMSD fitting coordinate
+    sets `a` and `b`.
 
-    The rotation matrix *R* transforms *a* to overlap with *b* (i.e. *b* is the
-    reference structure):
+    The rotation matrix `R` transforms vector `a` to overlap with
+    vector `b` (i.e., `b` is the reference structure):
 
     .. math::
-
-        \vec{b} = \bold{R} \dot \vec{a}
+       \mathbf{b} = \mathsf{R} \cdot \mathbf{a}
 
     Parameters
     ----------
     a : array-like
           coordinates that are to be rotated ("mobile set"); array of N atoms
           of shape N*3 as generated by, e.g.,
-          :meth:`MDAnalysis.core.AtomGroup.AtomGroup.coordinates`.
+          :attr:`MDAnalysis.core.groups.AtomGroup.positions`.
     b : array-like
           reference coordinates; array of N atoms of shape N*3 as generated by,
-          e.g., :meth:`MDAnalysis.core.AtomGroup.AtomGroup.coordinates`.
+          e.g., :attr:`MDAnalysis.core.groups.AtomGroup.positions`.
     weights : array-like (optional)
           array of floats of size N for doing weighted RMSD fitting (e.g. the
           masses of the atoms)
@@ -221,13 +220,13 @@ def rotation_matrix(a, b, weights=None):
     R : ndarray
         rotation matrix
     rmsd : float
-        RMSD between *a* and *b* before rotation
+        RMSD between `a` and `b` before rotation
     ``(R, rmsd)`` rmsd and rotation matrix *R*
 
     Example
     -------
-    *R* can be used as an argument for
-    :meth:`MDAnalysis.core.AtomGroup.AtomGroup.rotate` to generate a rotated
+    `R` can be used as an argument for
+    :meth:`MDAnalysis.core.groups.AtomGroup.rotate` to generate a rotated
     selection, e.g. ::
 
     >>> R = rotation_matrix(A.select_atoms('backbone').positions,
@@ -316,7 +315,7 @@ def alignto(mobile, reference, select="all", mass_weighted=False,
        coincides with the one of *reference*. (See below for explanation of
        how *sel1* and *sel2* are derived from *select*.)
 
-    2. All atoms in :class:`~MDAnalysis.core.AtomGroup.Universe` that
+    2. All atoms in :class:`~MDAnalysis.core.universe.Universe` that
        contains *mobile* are shifted and rotated. (See below for how
        to change this behavior through the *subselection* keyword.)
 
@@ -336,14 +335,14 @@ def alignto(mobile, reference, select="all", mass_weighted=False,
     ----------
       mobile : Universe or AtomGroup
          structure to be aligned, a
-         :class:`~MDAnalysis.core.AtomGroup.AtomGroup` or a whole
-         :class:`~MDAnalysis.core.AtomGroup.Universe`
+         :class:`~MDAnalysis.core.groups.AtomGroup` or a whole
+         :class:`~MDAnalysis.core.universe.Universe`
       reference : Universe or AtomGroup
-         reference structure, a :class:`~MDAnalysis.core.AtomGroup.AtomGroup`
-         or a whole :class:`~MDAnalysis.core.AtomGroup.Universe`
+         reference structure, a :class:`~MDAnalysis.core.groups.AtomGroup`
+         or a whole :class:`~MDAnalysis.core.universe.Universe`
       select: string or dict, optional
          1. any valid selection string for
-            :meth:`~MDAnalysis.core.AtomGroup.AtomGroup.select_atoms` that
+            :meth:`~MDAnalysis.core.groups.AtomGroup.select_atoms` that
             produces identical selections in *mobile* and *reference*; or
          2. dictionary ``{'mobile':sel1, 'reference':sel2}``.
             (the :func:`fasta2select` function returns such a
@@ -376,7 +375,7 @@ def alignto(mobile, reference, select="all", mass_weighted=False,
              protein, ligands and the surrounding water)
          *selection-string*
              Apply to `mobile.select_atoms(selection-string)`
-         :class:`~MDAnalysis.core.AtomGroup.AtomGroup`
+         :class:`~MDAnalysis.core.groups.AtomGroup`
              Apply to the arbitrary group of atoms
 
     Returns
@@ -619,7 +618,7 @@ def rms_fit_trj(
          (uses the current time step of the object)
       *select*
          1. any valid selection string for
-            :meth:`~MDAnalysis.core.AtomGroup.AtomGroup.select_atoms` that
+            :meth:`~MDAnalysis.core.groups.AtomGroup.select_atoms` that
             produces identical selections in *mobile* and *reference*; or
          2. a dictionary ``{'mobile':sel1, 'reference':sel2}`` (the
             :func:`fasta2select` function returns such a
@@ -1070,7 +1069,7 @@ def resid(nseq, ipos, t=t):
 def get_matching_atoms(ag1, ag2, tol_mass=0.1, strict=False):
     """Return two atom groups with one-to-one matched atoms.
 
-    The function takes two :class:`~MDAnalysis.core.AtomGroup.AtomGroup`
+    The function takes two :class:`~MDAnalysis.core.groups.AtomGroup`
     instances *ag1* and *ag2* and returns two atom groups *g1* and *g2* that
     consist of atoms so that the mass of atom ``g1[0]`` is the same as the mass
     of atom ``g2[0]``, ``g1[1]`` and ``g2[1]`` etc.
@@ -1089,10 +1088,10 @@ def get_matching_atoms(ag1, ag2, tol_mass=0.1, strict=False):
     Parameters
     ----------
     ag1 : AtomGroup
-        First :class:`~MDAnalysis.core.AtomGroup.AtomGroup` instance that is
+        First :class:`~MDAnalysis.core.groups.AtomGroup` instance that is
         compared
     ag2 : AtomGroup
-        Second :class:`~MDAnalysis.core.AtomGroup.AtomGroup` instance that is
+        Second :class:`~MDAnalysis.core.groups.AtomGroup` instance that is
         compared
     tol_mass : float, optional
          Reject if the atomic masses for matched atoms differ by more than
@@ -1109,7 +1108,7 @@ def get_matching_atoms(ag1, ag2, tol_mass=0.1, strict=False):
     Returns
     -------
     ``(g1, g2)``
-        Tuple with :class:`~MDAnalysis.core.AtomGroup.AtomGroup` instances
+        Tuple with :class:`~MDAnalysis.core.groups.AtomGroup` instances
         that match, atom by atom. The groups are either the original groups if all matches
         or slices of the original groups.
 

package/MDAnalysis/analysis/contacts.py

@@ -842,7 +842,7 @@ class ContactAnalysis1(object):
     is, is which percentage of the contacts between A and B persist during the
     simulation.
 
-    First prepare :class:`~MDAnalysis.core.AtomGroup.AtomGroup` selections for
+    First prepare :class:`~MDAnalysis.core.groups.AtomGroup` selections for
     the reference atoms; this example uses some arbitrary selections::
 
       ref = Universe('crystal.pdb')
@@ -915,7 +915,7 @@ def __init__(self, *args, **kwargs):
             B*"]
           *refgroup*
             reference group, either a single
-            :class:`~MDAnalysis.core.AtomGroup.AtomGroup` (if there is only a
+            :class:`~MDAnalysis.core.groups.AtomGroup` (if there is only a
             single *selection*) or a list of two such groups. The reference
             contacts are directly computed from *refgroup* and hence the atoms
             in the reference group(s) must be equivalent to the ones produced

package/MDAnalysis/analysis/density.py

@@ -601,7 +601,7 @@ def notwithin_coordinates(cutoff=cutoff):
                 # must update every time step
                 ns_w = NS.AtomNeighborSearch(solvent)  # build kd-tree on solvent (N_w > N_protein)
                 solvation_shell = ns_w.search_list(protein, cutoff)  # solvent within CUTOFF of protein
-                group = MDAnalysis.core.AtomGroup.AtomGroup(set_solvent - set(solvation_shell))  # bulk
+                group = MDAnalysis.core.groups.AtomGroup(set_solvent - set(solvation_shell))  # bulk
                 return group.positions
         else:
             def notwithin_coordinates(cutoff=cutoff):

package/MDAnalysis/analysis/diffusionmap.py

@@ -203,15 +203,15 @@ def __init__(self, u, select='all', metric=rmsd, cutoff=1E0-5,
         """
         Parameters
         ----------
-        u : universe `~MDAnalysis.core.AtomGroup.Universe`
+        u : universe `~MDAnalysis.core.universe.Universe`
             The MD Trajectory for dimension reduction, remember that
             computational cost of eigenvalue decomposition
             scales at O(N^3) where N is the number of frames.
             Cost can be reduced by increasing step interval or specifying a
             start and stop.
         select: str, optional
             Any valid selection string for
-            :meth:`~MDAnalysis.core.AtomGroup.AtomGroup.select_atoms`
+            :meth:`~MDAnalysis.core.groups.AtomGroup.select_atoms`
             This selection of atoms is used to calculate the RMSD between
             different frames. Water should be excluded.
         metric : function, optional

package/MDAnalysis/analysis/distances.py

@@ -23,7 +23,7 @@
 atoms or groups of atoms.
 
 :func:`dist` and :func:`between` can take atom groups that do not even
-have to be from the same :class:`~MDAnalysis.core.AtomGroup.Universe`.
+have to be from the same :class:`~MDAnalysis.core.universe.Universe`.
 
 .. SeeAlso:: :mod:`MDAnalysis.lib.distances`
 """
@@ -127,7 +127,7 @@ def dist(A, B, offset=0):
     Arguments
     ---------
     A, B : AtomGroup
-       :class:`~MDAnalysis.core.AtomGroup.AtomGroup` with the
+       :class:`~MDAnalysis.core.groups.AtomGroup` with the
        same number of atoms
     offset : integer or tuple, optional, default 0
        An integer `offset` is added to *resids_A* and *resids_B* (see
@@ -174,7 +174,7 @@ def between(group, A, B, distance):
     group : AtomGroup
         Find members of `group` that are between `A` and `B`
     A, B : AtomGroups
-        `A` and `B` are :class:`~MDAnalysis.core.AtomGroup.AtomGroup`
+        `A` and `B` are :class:`~MDAnalysis.core.groups.AtomGroup`
         instances.  Works best if `group` is bigger than either `A` or
         `B`.
     distance : float
@@ -184,7 +184,7 @@ def between(group, A, B, distance):
     Returns
     -------
     AtomGroup
-        :class:`~MDAnalysis.core.AtomGroup.AtomGroup` of atoms that
+        :class:`~MDAnalysis.core.groups.AtomGroup` of atoms that
         fulfill the criterion
 
 

package/MDAnalysis/analysis/encore/confdistmatrix.py

@@ -352,7 +352,7 @@ def get_distance_matrix(ensemble,
     """
     Retrieves or calculates the conformational distance (RMSD)
     matrix. The distance matrix is calculated between all the frames of all
-    the :class:`~MDAnalysis.core.AtomGroup.Universe` objects given as input.
+    the :class:`~MDAnalysis.core.universe.Universe` objects given as input.
     The order of the matrix elements depends on the order of the coordinates
     of the ensembles and on the order of the input ensembles themselves,
     therefore the order of the input list is significant.

package/MDAnalysis/analysis/encore/similarity.py

@@ -315,13 +315,13 @@ def clustering_ensemble_similarity(cc, ens1, ens1_id, ens2, ens2_id,
         Collection from cluster calculated by a clustering algorithm
         (e.g. Affinity propagation)
 
-    ens1 : :class:`~MDAnalysis.core.AtomGroup.Universe`
+    ens1 : :class:`~MDAnalysis.core.universe.Universe`
         First ensemble to be used in comparison
 
     ens1_id : int
         First ensemble id as detailed in the ClustersCollection metadata
 
-    ens2 : :class:`~MDAnalysis.core.AtomGroup.Universe`
+    ens2 : :class:`~MDAnalysis.core.universe.Universe`
         Second ensemble to be used in comparison
 
     ens2_id : int
@@ -689,7 +689,7 @@ def prepare_ensembles_for_convergence_increasing_window(ensemble,
     Parameters
     ----------
 
-    ensemble : :class:`~MDAnalysis.core.AtomGroup.Universe` object
+    ensemble : :class:`~MDAnalysis.core.universe.Universe` object
         Input ensemble
 
     window_size : int
@@ -1531,7 +1531,7 @@ def ces_convergence(original_ensemble,
     Parameters
     ----------
 
-    original_ensemble : :class:`~MDAnalysis.core.AtomGroup.Universe` object
+    original_ensemble : :class:`~MDAnalysis.core.universe.Universe` object
         ensemble containing the trajectory whose convergence has to estimated
 
     window_size : int
@@ -1635,7 +1635,7 @@ def dres_convergence(original_ensemble,
     Parameters
     ----------
 
-    original_ensemble : :class:`~MDAnalysis.core.AtomGroup.Universe` object
+    original_ensemble : :class:`~MDAnalysis.core.universe.Universe` object
         ensemble containing the trajectory whose convergence has to estimated
 
     window_size : int

package/MDAnalysis/analysis/hbonds/hbond_analysis.py

@@ -24,7 +24,7 @@
 :Copyright: GNU Public License v3
 
 
-Given a :class:`~MDAnalysis.core.AtomGroup.Universe` (simulation
+Given a :class:`~MDAnalysis.core.universe.Universe` (simulation
 trajectory with 1 or more frames) measure all hydrogen bonds for each
 frame between selections 1 and 2.
 
@@ -677,7 +677,7 @@ def _get_bonded_hydrogens(self, atom, **kwargs):
         :class:`HydrogenBondAnalysis`.
 
         :Returns: list of hydrogens (can be a
-                  :class:`~MDAnalysis.core.AtomGroup.AtomGroup`) or empty list
+                  :class:`~MDAnalysis.core.groups.AtomGroup`) or empty list
                   ``[]`` if none were found.
 
         .. SeeAlso::
@@ -1240,7 +1240,7 @@ def _donor_lookup_table_byindex(self):
         .. Note::
 
            *index* is the 0-based MDAnalysis index
-           (:attr:`MDAnalysis.core.AtomGroup.Atom.index`).  The
+           (:attr:`MDAnalysis.core.groups.Atom.index`).  The
            tables generated by :class:`HydrogenBondAnalysis` contain
            1-based indices and zero-based indices.
 

package/MDAnalysis/analysis/helanal.py

@@ -166,7 +166,7 @@ def helanal_trajectory(universe, selection="name CA", start=None, end=None, begi
 
     :Arguments:
        *universe*
-          :class:`~MDAnalysis.core.AtomGroup.Universe`
+          :class:`~MDAnalysis.core.universe.Universe`
 
     :Keywords:
        *selection*

package/MDAnalysis/analysis/hole.py

@@ -68,7 +68,7 @@
 
 One can also run :program:`hole` on frames in a trajectory with
 :class:`HOLEtraj`. In this case, provide a
-:class:`~MDAnalysis.core.AtomGroup.Universe`::
+:class:`~MDAnalysis.core.universe.Universe`::
 
    import MDAnalysis as mda
    from MDAnalysis.analysis.hole import HOLEtraj
@@ -1188,9 +1188,9 @@ def __init__(self, universe, **kwargs):
 
         Parameters
         ----------
-        universe : :class:`~MDAnalysis.core.AtomGroup.Universe`
+        universe : :class:`~MDAnalysis.core.universe.Universe`
              The input trajectory is taken from a
-             :class:`~MDAnalysis.core.AtomGroup.Universe`. The trajectory is
+             :class:`~MDAnalysis.core.universe.Universe`. The trajectory is
              converted to a sequence of PDB files and :class:`HOLE` is run on
              each individual file.
         orderparameters : array_like or string, optional
@@ -1202,15 +1202,15 @@ def __init__(self, universe, **kwargs):
              so that the whole trajectory is analyzed
         selection : string, optional
              selection string for
-             :meth:`~MDAnalysis.core.AtomGroup.Universe.select_atoms` to select
+             :meth:`~MDAnalysis.core.universe.Universe.select_atoms` to select
              the group of atoms that is to be analysed by HOLE. The default is
              "protein" to include all protein residues.
         cpoint : bool or array_like, optional
              Point inside the pore to start the HOLE search procedure. The
              default is ``None`` to select HOLE's internal search procedure.
 
              If set to ``True`` then *cpoint* is guessed as the
-             :meth:`~MDAnalysis.core.AtomGroup.AtomGroup.center_of_geometry` of
+             :meth:`~MDAnalysis.core.groups.AtomGroup.center_of_geometry` of
              the `selection` from the first frame of the trajectory.
 
              If `cpoint` is not set or set to ``None`` then HOLE guesses it

package/MDAnalysis/analysis/leaflet.py

@@ -31,12 +31,12 @@
 One can use this information to identify
 
 * the upper and lower leaflet of a *planar membrane* by comparing the
-  the :meth:`~MDAnalysis.core.AtomGroup.AtomGroup.center_of_geometry` of
+  the :meth:`~MDAnalysis.core.groups.AtomGroup.center_of_geometry` of
   the leaflet groups, or
 
 * the outer and inner leaflet of a *vesicle* by comparing histograms
   of distances from the centre of geometry (or possibly simply the
-  :meth:`~MDAnalysis.core.AtomGroup.AtomGroup.radius_of_gyration`).
+  :meth:`~MDAnalysis.core.groups.AtomGroup.radius_of_gyration`).
 
 See example scripts in the MDAnalysisCookbook_ on how to use
 :class:`LeafletFinder`. The function :func:`optimize_cutoff` implements a
@@ -78,7 +78,7 @@ class LeafletFinder(object):
 
        leaflet0.residues
 
-    provides a :class:`~MDAnalysis.core.AtomGroup.ResidueGroup`
+    provides a :class:`~MDAnalysis.core.groups.ResidueGroup`
     instance. Similarly, all atoms in the first leaflet are then ::
 
        leaflet0.residues.atoms
@@ -91,7 +91,7 @@ def __init__(self, universe, selectionstring, cutoff=15.0, pbc=False, sparse=Non
              *universe*
                  :class:`MDAnalysis.Universe` or a PDB file name.
              *selection*
-                 :class:`MDAnalysis.core.AtomGroup.AtomGroup` or a
+                 :class:`MDAnalysis.core.groups.AtomGroup` or a
                  :meth:`MDAnalysis.Universe.select_atoms` selection string
                  for atoms that define the lipid head groups, e.g.
                  universe.atoms.PO4 or "name PO4" or "name P*"
@@ -178,7 +178,7 @@ def sizes(self):
         return dict(((idx, len(component)) for idx, component in enumerate(self.components)))
 
     def groups(self, component_index=None):
-        """Return a :class:`MDAnalysis.core.AtomGroup.AtomGroup` for *component_index*.
+        """Return a :class:`MDAnalysis.core.groups.AtomGroup` for *component_index*.
 
         If no argument is supplied, then a list of all leaflet groups is returned.
 
@@ -190,7 +190,7 @@ def groups(self, component_index=None):
             return self.group(component_index)
 
     def group(self, component_index):
-        """Return a :class:`MDAnalysis.core.AtomGroup.AtomGroup` for *component_index*."""
+        """Return a :class:`MDAnalysis.core.groups.AtomGroup` for *component_index*."""
         # maybe cache this?
         indices = [i for i in self.components[component_index]]
         return self.selection[indices]