From 269c824ab15fb52ebace877f56b7edbad6ff8023 Mon Sep 17 00:00:00 2001 From: Oliver Beckstein Date: Fri, 18 Nov 2016 22:43:00 -0500 Subject: [PATCH] doc fixes (especially new topology system) (#1077) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - added missing docs for new topology system (#363) - removed some of the obviously old outdated topology discussions (but still need proper discussion of #363 changes – see issue #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 #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 (#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 | 2 +- package/MDAnalysis/analysis/align.py | 45 ++- package/MDAnalysis/analysis/contacts.py | 4 +- package/MDAnalysis/analysis/density.py | 2 +- package/MDAnalysis/analysis/diffusionmap.py | 4 +- package/MDAnalysis/analysis/distances.py | 8 +- .../analysis/encore/confdistmatrix.py | 2 +- .../MDAnalysis/analysis/encore/similarity.py | 10 +- .../analysis/hbonds/hbond_analysis.py | 6 +- package/MDAnalysis/analysis/helanal.py | 2 +- package/MDAnalysis/analysis/hole.py | 10 +- package/MDAnalysis/analysis/leaflet.py | 12 +- package/MDAnalysis/analysis/legacy/x3dna.py | 2 +- package/MDAnalysis/analysis/nuclinfo.py | 32 +- package/MDAnalysis/analysis/psa.py | 26 +- package/MDAnalysis/analysis/rms.py | 29 +- package/MDAnalysis/coordinates/DCD.py | 2 +- package/MDAnalysis/coordinates/MMTF.py | 7 +- package/MDAnalysis/coordinates/base.py | 2 +- package/MDAnalysis/coordinates/memory.py | 36 +- package/MDAnalysis/core/AtomGroup.py | 4 +- package/MDAnalysis/core/groups.py | 292 ++++++++++----- package/MDAnalysis/core/levels.py | 42 ++- package/MDAnalysis/core/selection.py | 24 +- package/MDAnalysis/core/topology.py | 42 ++- package/MDAnalysis/core/topologyattrs.py | 10 +- package/MDAnalysis/core/topologyobjects.py | 14 +- package/MDAnalysis/core/universe.py | 123 ++++-- package/MDAnalysis/lib/mdamath.py | 2 +- package/MDAnalysis/lib/util.py | 14 +- package/MDAnalysis/selections/__init__.py | 2 +- package/MDAnalysis/selections/base.py | 2 +- package/MDAnalysis/selections/charmm.py | 2 +- package/MDAnalysis/selections/gromacs.py | 2 +- package/MDAnalysis/selections/jmol.py | 2 +- package/MDAnalysis/selections/pymol.py | 2 +- package/MDAnalysis/selections/vmd.py | 2 +- .../MDAnalysis/topology/ExtendedPDBParser.py | 2 +- package/MDAnalysis/topology/PDBParser.py | 2 +- .../MDAnalysis/topology/PrimitivePDBParser.py | 2 +- package/MDAnalysis/topology/__init__.py | 82 ++-- package/MDAnalysis/topology/guessers.py | 37 +- .../coordinates_modules.rst | 2 +- .../documentation_pages/core/AtomGroup.rst | 1 - .../documentation_pages/core/Selection.rst | 2 - .../documentation_pages/core/groups.rst | 1 + .../documentation_pages/core/levels.rst | 1 + .../documentation_pages/core/selection.rst | 2 + .../documentation_pages/core/topology.rst | 1 + .../core/topologyattrs.rst | 2 + .../documentation_pages/core/universe.rst | 1 + .../documentation_pages/core_modules.rst | 58 ++- .../source/documentation_pages/overview.rst | 24 +- .../source/documentation_pages/selections.rst | 350 ++++++++++-------- .../selections_modules.rst | 2 +- .../documentation_pages/topology_modules.rst | 2 +- 56 files changed, 844 insertions(+), 554 deletions(-) delete mode 100644 package/doc/sphinx/source/documentation_pages/core/AtomGroup.rst delete mode 100644 package/doc/sphinx/source/documentation_pages/core/Selection.rst create mode 100644 package/doc/sphinx/source/documentation_pages/core/groups.rst create mode 100644 package/doc/sphinx/source/documentation_pages/core/levels.rst create mode 100644 package/doc/sphinx/source/documentation_pages/core/selection.rst create mode 100644 package/doc/sphinx/source/documentation_pages/core/topology.rst create mode 100644 package/doc/sphinx/source/documentation_pages/core/topologyattrs.rst create mode 100644 package/doc/sphinx/source/documentation_pages/core/universe.rst diff --git a/package/MDAnalysis/__init__.py b/package/MDAnalysis/__init__.py index 8554960c006..6f20a7f493b 100644 --- a/package/MDAnalysis/__init__.py +++ b/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 diff --git a/package/MDAnalysis/analysis/align.py b/package/MDAnalysis/analysis/align.py index 1ae8115699f..118737d4025 100644 --- a/package/MDAnalysis/analysis/align.py +++ b/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. diff --git a/package/MDAnalysis/analysis/contacts.py b/package/MDAnalysis/analysis/contacts.py index f84b03a3b41..18de1340882 100644 --- a/package/MDAnalysis/analysis/contacts.py +++ b/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 diff --git a/package/MDAnalysis/analysis/density.py b/package/MDAnalysis/analysis/density.py index 59505cafc8c..893d4afc39e 100644 --- a/package/MDAnalysis/analysis/density.py +++ b/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): diff --git a/package/MDAnalysis/analysis/diffusionmap.py b/package/MDAnalysis/analysis/diffusionmap.py index 3cf95771578..fbe60e28e2b 100644 --- a/package/MDAnalysis/analysis/diffusionmap.py +++ b/package/MDAnalysis/analysis/diffusionmap.py @@ -203,7 +203,7 @@ 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. @@ -211,7 +211,7 @@ def __init__(self, u, select='all', metric=rmsd, cutoff=1E0-5, 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 diff --git a/package/MDAnalysis/analysis/distances.py b/package/MDAnalysis/analysis/distances.py index d1da5080ca5..5ad4bf22a7f 100644 --- a/package/MDAnalysis/analysis/distances.py +++ b/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 diff --git a/package/MDAnalysis/analysis/encore/confdistmatrix.py b/package/MDAnalysis/analysis/encore/confdistmatrix.py index 061c8484cfe..165162f3ba9 100644 --- a/package/MDAnalysis/analysis/encore/confdistmatrix.py +++ b/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. diff --git a/package/MDAnalysis/analysis/encore/similarity.py b/package/MDAnalysis/analysis/encore/similarity.py index 9b4152b40b5..13d2e76549e 100644 --- a/package/MDAnalysis/analysis/encore/similarity.py +++ b/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 diff --git a/package/MDAnalysis/analysis/hbonds/hbond_analysis.py b/package/MDAnalysis/analysis/hbonds/hbond_analysis.py index 0918206ce91..2d45eba1545 100644 --- a/package/MDAnalysis/analysis/hbonds/hbond_analysis.py +++ b/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. diff --git a/package/MDAnalysis/analysis/helanal.py b/package/MDAnalysis/analysis/helanal.py index af987bcd81c..17c2f495a82 100644 --- a/package/MDAnalysis/analysis/helanal.py +++ b/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* diff --git a/package/MDAnalysis/analysis/hole.py b/package/MDAnalysis/analysis/hole.py index 1608c206885..9a41b20a20a 100644 --- a/package/MDAnalysis/analysis/hole.py +++ b/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,7 +1202,7 @@ 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 @@ -1210,7 +1210,7 @@ def __init__(self, universe, **kwargs): 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 diff --git a/package/MDAnalysis/analysis/leaflet.py b/package/MDAnalysis/analysis/leaflet.py index 39b59c4eb15..7b5045eec0e 100644 --- a/package/MDAnalysis/analysis/leaflet.py +++ b/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] diff --git a/package/MDAnalysis/analysis/legacy/x3dna.py b/package/MDAnalysis/analysis/legacy/x3dna.py index 5d3b734d5df..97abd9a10f0 100644 --- a/package/MDAnalysis/analysis/legacy/x3dna.py +++ b/package/MDAnalysis/analysis/legacy/x3dna.py @@ -654,7 +654,7 @@ def __init__(self, universe, **kwargs): *universe* The input trajectory as part of a - :class:`~MDAnalysis.core.AtomGroup.Universe`. trajectory is + :class:`~MDAnalysis.core.universe.Universe`. trajectory is converted to a sequence of PDB files and X3DNA is run on each individual file. (Use the *start*, *stop*, and *step* keywords to slice the trajectory.) diff --git a/package/MDAnalysis/analysis/nuclinfo.py b/package/MDAnalysis/analysis/nuclinfo.py index a4244d4e2c7..5bf1cbe1f81 100644 --- a/package/MDAnalysis/analysis/nuclinfo.py +++ b/package/MDAnalysis/analysis/nuclinfo.py @@ -35,7 +35,7 @@ For applications of this kind of analysis see [Denning2011]_ and [Denning2012]_. -All functions take a :class:`~MDAnalysis.core.AtomGroup.Universe` as an +All functions take a :class:`~MDAnalysis.core.universe.Universe` as an argument together with further parameters that specify the base or bases in question. Angles are in degrees. The functions use standard CHARMM names for nucleic acids and atom names. @@ -114,7 +114,7 @@ def wc_pair(universe, i, bp, seg1="SYSTEM", seg2="SYSTEM"): :Arguments: *universe* - :class:`~MDAnalysis.core.AtomGroup.Universe` containing the trajectory + :class:`~MDAnalysis.core.universe.Universe` containing the trajectory *seg1* segment id for first base *i* @@ -147,7 +147,7 @@ def minor_pair(universe, i, bp, seg1="SYSTEM", seg2="SYSTEM"): :Arguments: *universe* - :class:`~MDAnalysis.core.AtomGroup.Universe` containing the trajectory + :class:`~MDAnalysis.core.universe.Universe` containing the trajectory *seg1* segment id for first base *i* @@ -180,7 +180,7 @@ def major_pair(universe, i, bp, seg1="SYSTEM", seg2="SYSTEM"): :Arguments: *universe* - :class:`~MDAnalysis.core.AtomGroup.Universe` containing the + :class:`~MDAnalysis.core.universe.Universe` containing the trajectory *i* *seg1* segment id for first base @@ -219,7 +219,7 @@ def phase_cp(universe, seg, i): :Arguments: *universe* - :class:`~MDAnalysis.core.AtomGroup.Universe` containing the trajectory + :class:`~MDAnalysis.core.universe.Universe` containing the trajectory *segid* segment identity of resid @@ -287,7 +287,7 @@ def phase_as(universe, seg, i): :Arguments: *universe* - :class:`~MDAnalysis.core.AtomGroup.Universe` containing the trajectory + :class:`~MDAnalysis.core.universe.Universe` containing the trajectory *segid* segment identity of resid *i* @@ -353,7 +353,7 @@ def tors(universe, seg, i): :Arguments: *universe* - :class:`~MDAnalysis.core.AtomGroup.Universe` containing the trajectory + :class:`~MDAnalysis.core.universe.Universe` containing the trajectory *segid* segid of resid *i* @@ -431,7 +431,7 @@ def tors_alpha(universe, seg, i): :Arguments: *universe* - :class:`~MDAnalysis.core.AtomGroup.Universe` containing the trajectory + :class:`~MDAnalysis.core.universe.Universe` containing the trajectory *segid* segid of resid *i* @@ -456,7 +456,7 @@ def tors_beta(universe, seg, i): :Arguments: *universe* - :class:`~MDAnalysis.core.AtomGroup.Universe` containing the trajectory + :class:`~MDAnalysis.core.universe.Universe` containing the trajectory *segid* segid of resid *i* @@ -481,7 +481,7 @@ def tors_gamma(universe, seg, i): :Arguments: *universe* - :class:`~MDAnalysis.core.AtomGroup.Universe` containing the trajectory + :class:`~MDAnalysis.core.universe.Universe` containing the trajectory *segid* segid of resid *i* @@ -506,7 +506,7 @@ def tors_delta(universe, seg, i): :Arguments: *universe* - :class:`~MDAnalysis.core.AtomGroup.Universe` containing the trajectory + :class:`~MDAnalysis.core.universe.Universe` containing the trajectory *segid* segid of resid *i* @@ -531,7 +531,7 @@ def tors_eps(universe, seg, i): :Arguments: *universe* - :class:`~MDAnalysis.core.AtomGroup.Universe` containing the trajectory + :class:`~MDAnalysis.core.universe.Universe` containing the trajectory *segid* segid of resid *i* @@ -556,7 +556,7 @@ def tors_zeta(universe, seg, i): :Arguments: *universe* - :class:`~MDAnalysis.core.AtomGroup.Universe` containing the trajectory + :class:`~MDAnalysis.core.universe.Universe` containing the trajectory *segid* segid of resid *i* @@ -581,7 +581,7 @@ def tors_chi(universe, seg, i): :Arguments: *universe* - :class:`~MDAnalysis.core.AtomGroup.Universe` containing the + :class:`~MDAnalysis.core.universe.Universe` containing the trajectory *segid* segid of resid @@ -613,7 +613,7 @@ def hydroxyl(universe, seg, i): :Arguments: *universe* - :class:`~MDAnalysis.core.AtomGroup.Universe` containing the + :class:`~MDAnalysis.core.universe.Universe` containing the trajectory *segid* segid of resid @@ -647,7 +647,7 @@ def pseudo_dihe_baseflip(universe, bp1, bp2, i, :Arguments: *universe* - :class:`~MDAnalysis.core.AtomGroup.Universe` containing the + :class:`~MDAnalysis.core.universe.Universe` containing the trajectory *segid1* segid of resid base pairing with bp2 diff --git a/package/MDAnalysis/analysis/psa.py b/package/MDAnalysis/analysis/psa.py index 2f17232145b..94c779281dd 100644 --- a/package/MDAnalysis/analysis/psa.py +++ b/package/MDAnalysis/analysis/psa.py @@ -98,13 +98,13 @@ .. attribute:: ref_select string, selection for - :meth:`~MDAnalysis.core.AtomGroup.AtomGroup.select_atoms` to select frame + :meth:`~MDAnalysis.core.groups.AtomGroup.select_atoms` to select frame from :attr:`Path.u_reference` .. attribute:: path_select string, selection for - :meth:`~MDAnalysis.core.AtomGroup.AtomGroup.select_atoms` to select atoms + :meth:`~MDAnalysis.core.groups.AtomGroup.select_atoms` to select atoms to compose :attr:`Path.path` .. attribute:: ref_frame @@ -161,13 +161,13 @@ .. attribute:: ref_select string, selection for - :meth:`~MDAnalysis.core.AtomGroup.AtomGroup.select_atoms` to select frame + :meth:`~MDAnalysis.core.groups.AtomGroup.select_atoms` to select frame from :attr:`PSAnalysis.u_reference` .. attribute:: path_select string, selection for - :meth:`~MDAnalysis.core.AtomGroup.AtomGroup.select_atoms` to select atoms + :meth:`~MDAnalysis.core.groups.AtomGroup.select_atoms` to select atoms to compose :attr:`Path.path` .. attribute:: ref_frame @@ -267,7 +267,7 @@ def get_msd_matrix(P, Q, axis=None): *P* (*Q*) is a :class:`numpy.ndarray` of :math:`N_p` (:math:`N_q`) time steps, :math:`N` atoms, and :math:`3N` coordinates (e.g., - :meth:`MDAnalysis.core.AtomGroup.AtomGroup.coordinates`). The pairwise MSD + :meth:`MDAnalysis.core.groups.AtomGroup.coordinates`). The pairwise MSD matrix has dimensions :math:`N_p` by :math:`N_q`. :Arguments: @@ -327,7 +327,7 @@ def hausdorff(P, Q): *P* (*Q*) is a :class:`numpy.ndarray` of :math:`N_p` (:math:`N_q`) time steps, :math:`N` atoms, and :math:`3N` coordinates (e.g., - :meth:`MDAnalysis.core.AtomGroup.AtomGroup.coordinates`). *P* (*Q*) has + :meth:`MDAnalysis.core.groups.AtomGroup.coordinates`). *P* (*Q*) has either shape |3Dp| (|3Dq|), or |2Dp| (|2Dq|) in flattened form. :Arguments: @@ -366,7 +366,7 @@ def hausdorff_wavg(P, Q): *P* (*Q*) is a :class:`numpy.ndarray` of :math:`N_p` (:math:`N_q`) time steps, :math:`N` atoms, and :math:`3N` coordinates (e.g., - :meth:`MDAnalysis.core.AtomGroup.AtomGroup.coordinates`). *P* (*Q*) has + :meth:`MDAnalysis.core.groups.AtomGroup.coordinates`). *P* (*Q*) has either shape |3Dp| (|3Dq|), or |2Dp| (|2Dq|) in flattened form. The nearest neighbor distances for *P* (to *Q*) and those of *Q* (to *P*) are averaged individually to get the average nearest neighbor distance for *P* and @@ -410,7 +410,7 @@ def hausdorff_avg(P, Q): *P* (*Q*) is a :class:`numpy.ndarray` of :math:`N_p` (:math:`N_q`) time steps, :math:`N` atoms, and :math:`3N` coordinates (e.g., - :meth:`MDAnalysis.core.AtomGroup.AtomGroup.coordinates`). *P* (*Q*) has + :meth:`MDAnalysis.core.groups.AtomGroup.coordinates`). *P* (*Q*) has either shape |3Dp| (|3Dq|), or |2Dp| (|2Dq|) in flattened form. The nearest neighbor distances for *P* (to *Q*) and those of *Q* (to *P*) are all averaged together to get a mean nearest neighbor distance. This measure @@ -453,7 +453,7 @@ def hausdorff_neighbors(P, Q): *P* (*Q*) is a :class:`numpy.ndarray` of :math:`N_p` (:math:`N_q`) time steps, :math:`N` atoms, and :math:`3N` coordinates (e.g., - :meth:`MDAnalysis.core.AtomGroup.AtomGroup.coordinates`). *P* (*Q*) has + :meth:`MDAnalysis.core.groups.AtomGroup.coordinates`). *P* (*Q*) has either shape |3Dp| (|3Dq|), or |2Dp| (|2Dq|) in flattened form. :Arguments: @@ -484,7 +484,7 @@ def discrete_frechet(P, Q): *P* (*Q*) is a :class:`numpy.ndarray` of :math:`N_p` (:math:`N_q`) time steps, :math:`N` atoms, and :math:`3N` coordinates (e.g., - :meth:`MDAnalysis.core.AtomGroup.AtomGroup.coordinates`). *P* (*Q*) has + :meth:`MDAnalysis.core.groups.AtomGroup.coordinates`). *P* (*Q*) has either shape |3Dp| (|3Dq|), or :|2Dp| (|2Dq|) in flattened form. :Arguments: @@ -613,7 +613,7 @@ def __init__(self, universe, reference, ref_select='name CA', The selection to operate on for rms fitting; can be one of: 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:`MDAnalysis.analysis.align.fasta2select` function returns @@ -709,7 +709,7 @@ def to_path(self, fitted=False, select=None, flat=False): :Returns: :class:`numpy.ndarray` representing a time series of atomic positions - of an :class:`MDAnalysis.core.AtomGroup.AtomGroup` selection from + of an :class:`MDAnalysis.core.groups.AtomGroup` selection from :attr:`Path.u_fitted.trajectory` """ select = select if select is not None else self.path_select @@ -1060,7 +1060,7 @@ def __init__(self, universes, reference=None, ref_select='name CA', The selection to operate on; can be one of: 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:`MDAnalysis.analysis.align.fasta2select` function returns diff --git a/package/MDAnalysis/analysis/rms.py b/package/MDAnalysis/analysis/rms.py index 1ed037f0598..e65d3bc1930 100644 --- a/package/MDAnalysis/analysis/rms.py +++ b/package/MDAnalysis/analysis/rms.py @@ -145,7 +145,7 @@ def rmsd(a, b, weights=None, center=False, superposition=False): `a` and `b` are arrays of the coordinates of N atoms of shape N*3 as generated by, e.g., - :meth:`MDAnalysis.core.AtomGroup.AtomGroup.coordinates`. + :meth:`MDAnalysis.core.groups.AtomGroup.coordinates`. Parameters ---------- @@ -288,24 +288,24 @@ def __init__(self, atomgroup, reference=None, select='all', mass_weighted=False, tol_mass=0.1, ref_frame=0, **kwargs): """Setting up the RMSD analysis. - The RMSD will be computed between *select* and *reference* for - all frames in the trajectory in *universe*. + The RMSD will be computed between `select` and `reference` for + all frames in the trajectory belonging to `atomgroup`. Parameters ---------- - atomgroup : :class:`MDAnalysis.AtomGroup` or - :class:`MDAnalysis.Universe` - MDAnlysis AtomGroup or Universe with an associated Trajectory + atomgroup : :class:`~MDAnalysis.core.groups.AtomGroup` or + :class:`~MDAnalysis.core.universe.Universe` + MDAnalysis `AtomGroup` or `Universe` with an associated trajectory to be RMSD fit. - reference : :class:`MDAnalysis.AtomGroup` or - :class:`MDAnalysis.Universe`, optional - Reference coordinates, if ``None`` current frame of *atomgroup* is + reference : :class:`~MDAnalysis.core.groups.AtomGroup` or + :class:`~MDAnalysis.core.universe.Universe`, optional + Reference coordinates, if ``None`` current frame of `atomgroup` is used select : str / dict / tuple (optional) The selection to operate on; can be one of: 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 @@ -319,13 +319,14 @@ def __init__(self, atomgroup, reference=None, select='all', AtomGroup with defined atom order as described under :ref:`ordered-selections-label`). groupselections : list (optional) - A list of selections as described for *select*. Each selection + A list of selections as described for `select` Each selection describes additional RMSDs to be computed *after the structures - have be superpositioned* according to *select*. The output contains + have be superpositioned* according to `select`. The output contains one additional column for each selection. [``None``] .. Note:: Experimental feature. Only limited error checking implemented. + filename : str (optional) write RSMD into file file :meth:`RMSD.save` mass_weighted : bool (optional) @@ -342,9 +343,9 @@ def __init__(self, atomgroup, reference=None, select='all', .. versionadded:: 0.7.7 .. versionchanged:: 0.8 - *groupselections* added + `groupselections` added .. versionchanged: 0.15.1 - Refactor to fit with AnalysisBase API + Refactor to fit with AnalysisBase API """ super(RMSD, self).__init__(atomgroup.universe.trajectory, **kwargs) diff --git a/package/MDAnalysis/coordinates/DCD.py b/package/MDAnalysis/coordinates/DCD.py index 25c24edd869..3476a53ccfe 100644 --- a/package/MDAnalysis/coordinates/DCD.py +++ b/package/MDAnalysis/coordinates/DCD.py @@ -506,7 +506,7 @@ def timeseries(self, asel=None, start=None, stop=None, step=None, skip=None, :Arguments: *asel* - :class:`~MDAnalysis.core.AtomGroup.AtomGroup` object + :class:`~MDAnalysis.core.groups.AtomGroup` object Defaults to None, in which case the full set of coordinate data is returned. *start*, *stop*, *step* diff --git a/package/MDAnalysis/coordinates/MMTF.py b/package/MDAnalysis/coordinates/MMTF.py index 4e7e3ed4a8c..ebe2e71432f 100644 --- a/package/MDAnalysis/coordinates/MMTF.py +++ b/package/MDAnalysis/coordinates/MMTF.py @@ -1,5 +1,5 @@ # -*- 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 @@ -45,6 +45,11 @@ def _parse_mmtf(fn): class MMTFReader(base.SingleFrameReader): + """Topology parser for the MMTF_ format. + + .. _Macromolecular Transmission Format (MMTF) format: + https://mmtf.rcsb.org/ + """ format = 'MMTF' def _read_first_frame(self): diff --git a/package/MDAnalysis/coordinates/base.py b/package/MDAnalysis/coordinates/base.py index afd5b4aff40..a76c43686a5 100644 --- a/package/MDAnalysis/coordinates/base.py +++ b/package/MDAnalysis/coordinates/base.py @@ -1971,7 +1971,7 @@ def write(self, obj): """Write current timestep, using the supplied *obj*. The argument should be a :class:`~MDAnalysis.core.groups.AtomGroup` or - a :class:`~MDAnalysis.Universe` or a :class:`Timestep` instance. + a :class:`~MDAnalysis.core.universe.Universe` or a :class:`Timestep` instance. .. Note:: diff --git a/package/MDAnalysis/coordinates/memory.py b/package/MDAnalysis/coordinates/memory.py index 1fedeac407a..54cba77f4e7 100644 --- a/package/MDAnalysis/coordinates/memory.py +++ b/package/MDAnalysis/coordinates/memory.py @@ -13,7 +13,8 @@ # MDAnalysis: A Toolkit for the Analysis of Molecular Dynamics Simulations. # J. Comput. Chem. 32 (2011), 2319--2327, doi:10.1002/jcc.21787 # -"""========================================================================= +"""\ +========================================================================= Reading trajectories from memory --- :mod:`MDAnalysis.coordinates.memory` ========================================================================= @@ -30,7 +31,7 @@ operate on raw coordinate using existing MDAnalysis tools. In addition, it allows the user to make changes to the coordinates in a trajectory (e.g. through -:attr:`MDAnalysis.core.AtomGroup.AtomGroup.positions`) without having +:attr:`MDAnalysis.core.groups.AtomGroup.positions`) without having to write the entire state to file. @@ -50,7 +51,7 @@ The most straightforward use of the :class:`MemoryReader` is to simply use the ``in_memory=True`` flag for the -:class:`~MDAnalysis.core.AtomGroup.Universe` class, which +:class:`~MDAnalysis.core.universe.Universe` class, which automatically transfers a trajectory to memory:: import MDAnalysis as mda @@ -67,8 +68,8 @@ The decision to transfer the trajectory to memory can be made at any time with the -:meth:`~MDAnalysis.core.AtomGroup.Universe.transfer_to_memory` method -of a :class:`~MDAnalysis.core.AtomGroup.Universe`:: +:meth:`~MDAnalysis.core.universe.Universe.transfer_to_memory` method +of a :class:`~MDAnalysis.core.universe.Universe`:: universe = mda.Universe(TPR, XTC) universe.transfer_to_memory() @@ -82,7 +83,7 @@ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The :class:`MemoryReader` provides great flexibility because it -becomes possible to create a :class:`~MDAnalysis.Universe` directly +becomes possible to create a :class:`~MDAnalysis.core.universe.Universe` directly from a numpy array. A simple example consists of a new universe created from the array @@ -126,6 +127,7 @@ ``results.swapaxes(0, 1)``. This might be changed in the future. +.. _creating-in-memory-trajectory-label: Creating an in-memory trajectory of a sub-system ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -133,9 +135,9 @@ Creating a trajectory for just a selection of an existing trajectory requires the transfer of the appropriate coordinates as well as creation of a topology of the sub-system. For the latter one can use -the :func:`~MDAnalysis.core.AtomGroup.Merge` function, for the former -the :meth:`~MDAnalysis.core.AtomGroup.Universe.load_new` method of a -:class:`~MDAnalysis.Universe` together with the +the :func:`~MDAnalysis.core.universe.Merge` function, for the former +the :meth:`~MDAnalysis.core.universe.Universe.load_new` method of a +:class:`~MDAnalysis.core.universe.Universe` together with the :class:`MemoryReader`. In the following, an in-memory trajectory of only the protein is created:: @@ -153,8 +155,18 @@ u2 = mda.Merge(protein) # create the protein-only Universe u2.load_new(coordinates, format=MemoryReader) -The new :class:`~MDAnalysis.Universe` can be used to, for instance, -write out a new trajectory or perform fast analysis on the sub-system. +The protein coordinates are extracted into ``coordinates`` and then +the in-memory trajectory is loaded from these coordinates. In +principle, this could have all be done in one line:: + + u2 = mda.Merge(protein).load_new( + AnalysisFromFunction(lambda ag: ag.positions.copy(), + protein).run().results.swapaxes(0, 1), + format=MemoryReader) + +The new :class:`~MDAnalysis.core.universe.Universe` ``u2`` can be used +to, for instance, write out a new trajectory or perform fast analysis +on the sub-system. Classes @@ -291,7 +303,7 @@ def timeseries(self, asel=None, start=0, stop=-1, step=1, format='afc'): Parameters --------- - asel : :class:`~MDAnalysis.core.AtomGroup.AtomGroup` object + asel : :class:`~MDAnalysis.core.groups.AtomGroup` object Atom selection. Defaults to None, in which case the full set of coordinate data is returned. Note that in this case, a view of the underlying numpy array is returned, while a copy of the diff --git a/package/MDAnalysis/core/AtomGroup.py b/package/MDAnalysis/core/AtomGroup.py index a5c93604f8f..4284c0fe0c6 100644 --- a/package/MDAnalysis/core/AtomGroup.py +++ b/package/MDAnalysis/core/AtomGroup.py @@ -19,11 +19,11 @@ def __init__(self, *args, **kwargs): Universe = deprecate_class( universe.Universe, "MDAnalysis.core.AtomGroup.Universe has been removed." - "Please use MDAnalaysis.Universe." + "Please use MDAnalysis.Universe." "This stub will be removed in 1.0") _group_message = ("MDAnalysis.core.AtomGroup.{0} has been removed." - "Please use MDAnalaysis.groups.{0}" + "Please use MDAnalysis.groups.{0}" "This stub will be removed in 1.0") Atom = deprecate_class(Atom, message=_group_message.format('Atom')) diff --git a/package/MDAnalysis/core/groups.py b/package/MDAnalysis/core/groups.py index e4523e8c290..318d43652d8 100644 --- a/package/MDAnalysis/core/groups.py +++ b/package/MDAnalysis/core/groups.py @@ -13,8 +13,53 @@ # J. Comput. Chem. 32 (2011), 2319--2327, doi:10.1002/jcc.21787 # -"""Containers for objects in MDA - +"""\ +========================================================== +Core objects: Containers --- :mod:`MDAnalysis.core.groups` +========================================================== + +The :class:`~MDAnalysis.core.universe.Universe` instance contains all +the particles in the system (which MDAnalysis calls +:class:`Atom`). Groups of atoms are handled as :class:`AtomGroup` +instances. The :class:`AtomGroup` is probably the most important +object in MDAnalysis because virtually everything can be accessed +through it. `AtomGroup` instances can be easily created (e.g., from a +:meth:`AtomGroup.select_atoms` selection or just by slicing). + +For convenience, chemically meaningful groups of atoms such as a +:class:`Residue` or a :class:`Segment` (typically a whole molecule or +all of the solvent) also exist as containers, as well as groups of +these units ((:class:`ResidueGroup`, :class:`SegmentGroup`). + + +Classes +======= + +Collections +----------- + +.. autoclass:: AtomGroup + :members: + :inherited-members: +.. autoclass:: ResidueGroup + :members: + :inherited-members: +.. autoclass:: SegmentGroup + :members: + :inherited-members: + +Chemical units +-------------- + +.. autoclass:: Atom + :members: + :inherited-members: +.. autoclass:: Residue + :members: + :inherited-members: +.. autoclass:: Segment + :members: + :inherited-members: """ from six.moves import zip @@ -309,9 +354,12 @@ def universe(self): def ix(self): """Unique indices of the components in the Group. - If this Group is an AtomGroup, these are the indices of the atoms. - If it is a ResidueGroup, these are the indices of the residues. - If it is a SegmentGroup, these are the indices of the segments. + - If this Group is an :class:`AtomGroup`, these are the + indices of the :class:`Atom` instances. + - If it is a :class:`ResidueGroup`, these are the indices of + the :class:`Residue` instances. + - If it is a :class:`SegmentGroup`, these are the indices of + the :class:`Segment` instances. """ return self._ix @@ -323,18 +371,19 @@ def dimensions(self): def center_of_geometry(self, **kwargs): """Center of geometry (also known as centroid) of the selection. - Keywords - -------- - *pbc* + Parameters + ---------- + pbc : boolean, optional ``True``: Move all atoms within the primary unit cell - before calculation [``False``] + before calculation [``False``] Notes ----- - The :class:`MDAnalysis.core.flags` flag *use_pbc* when set to - ``True`` allows the *pbc* flag to be used by default. + If the :class:`MDAnalysis.core.flags` flag *use_pbc* is set to + ``True`` then the `pbc` keyword is used by default. - .. versionchanged:: 0.8 Added *pbc* keyword + + .. versionchanged:: 0.8 Added `pbc` keyword """ atomgroup = self.atoms @@ -370,6 +419,7 @@ def bbox(self, **kwargs): 2x3 array giving corners of bounding box as [[xmin, ymin, zmin], [xmax, ymax, zmax]]. + .. versionadded:: 0.7.2 .. versionchanged:: 0.8 Added *pbc* keyword """ @@ -405,6 +455,7 @@ def bsphere(self, **kwargs): center : array Coordinates of sphere center as ``[xcen,ycen,zcen]``. + .. versionadded:: 0.7.3 .. versionchanged:: 0.8 Added *pbc* keyword """ @@ -423,7 +474,7 @@ def bsphere(self, **kwargs): return R, centroid def transform(self, M): - """Apply homogenous transformation matrix `M` to the coordinates. + r"""Apply homogenous transformation matrix `M` to the coordinates. Parameters ---------- @@ -454,7 +505,7 @@ def transform(self, M): return self.rotate(R, [0, 0, 0]).translate(t) def translate(self, t): - """Apply translation vector `t` to the selection's coordinates. + r"""Apply translation vector `t` to the selection's coordinates. Atom coordinates are translated in-place. @@ -473,8 +524,9 @@ def translate(self, t): Notes ----- - The method applies a translation to the AtomGroup from current - coordinates :math:`\mathbf{x}` to new coordinates :math:`\mathbf{x}'`: + The method applies a translation to the :class:`AtomGroup` + from current coordinates :math:`\mathbf{x}` to new coordinates + :math:`\mathbf{x}'`: .. math:: @@ -488,31 +540,27 @@ def translate(self, t): return self def rotate(self, R, point=None): - """Apply a rotation matrix `R` to the selection's coordinates. - - No translation is done before the rotation is applied, so coordinates - are rotated about the origin. This differs from the behavior of - ``rotateby``. + r"""Apply a rotation matrix `R` to the selection's coordinates. Parameters ---------- R : array_like 3x3 rotation matrix to use for applying rotation. - point : array_like (optional) + point : array_like, optional Center of rotation. If ``None`` then the center of geometry of this group is used. Returns ------- - self - - See Also - -------- - rotateby : rotate around given axis and angle - MDAnalysis.lib.transformations : module of all coordinate transforms + self : AtomGroup Notes ----- + By default (``point=None``) the rotation is performed around + the centroid of the group (:meth:`center_of_geometry`). In + order to perform a rotation around, say, the origin, use + ``point=[0, 0, 0]``. + :math:`\mathsf{R}` is a 3x3 orthogonal matrix that transforms a vector :math:`\mathbf{x} \rightarrow \mathbf{x}'`: @@ -520,6 +568,11 @@ def rotate(self, R, point=None): \mathbf{x}' = \mathsf{R}\mathbf{x} + See Also + -------- + rotateby : rotate around given axis and angle + MDAnalysis.lib.transformations : module of all coordinate transforms + """ R = np.asarray(R) point = np.asarray(point) if point is not None else self.centroid() @@ -534,7 +587,7 @@ def rotate(self, R, point=None): return self def rotateby(self, angle, axis, point=None): - """Apply a rotation to the selection's coordinates. + r"""Apply a rotation to the selection's coordinates. Parameters ---------- @@ -542,13 +595,13 @@ def rotateby(self, angle, axis, point=None): Rotation angle in degrees. axis : array_like Rotation axis vector. - point : array_like (optional) + point : array_like, optional Center of rotation. If ``None`` then the center of geometry of this group is used. Returns ------- - self + self : AtomGroup Notes ----- @@ -559,8 +612,12 @@ def rotateby(self, angle, axis, point=None): \mathbf{x}' = \mathsf{R}\,(\mathbf{x}-\mathbf{p}) + \mathbf{p} - where :math:`\mathsf{R}` is the rotation by *angle* around the - *axis* going through *point* :math:`\mathbf{p}`. + where :math:`\mathsf{R}` is the rotation by `angle` around the + `axis` going through `point` :math:`\mathbf{p}`. + + See Also + -------- + MDAnalysis.lib.transformations.rotation_matrix : calculate :math:`\mathsf{R}` """ alpha = np.radians(angle) @@ -570,7 +627,7 @@ def rotateby(self, angle, axis, point=None): return self.transform(M) def pack_into_box(self, box=None, inplace=True): - """Shift all atoms in this group to be within the primary unit cell. + r"""Shift all atoms in this group to be within the primary unit cell. Parameters ---------- @@ -600,12 +657,13 @@ def pack_into_box(self, box=None, inplace=True): The default is to take unit cell information from the underlying :class:`~MDAnalysis.coordinates.base.Timestep` instance. The optional - argument *box* can be used to provide alternative unit cell information + argument `box` can be used to provide alternative unit cell information (in the MDAnalysis standard format ``[Lx, Ly, Lz, alpha, beta, gamma]``). Works with either orthogonal or triclinic box types. + .. versionadded:: 0.8 """ @@ -669,6 +727,7 @@ def wrap(self, compound="atoms", center="com", box=None): .. note:: wrap with all default keywords is identical to :meth:`pack_into_box` + .. versionadded:: 0.9.2 """ atomgroup = self.atoms.unique @@ -788,24 +847,20 @@ def __getattr__(self, attr): @property def atoms(self): - """Get another AtomGroup identical to this one. - - """ + """Get another AtomGroup identical to this one.""" return self._u.atoms[self.ix] @property def n_atoms(self): - """Number of atoms in AtomGroup. Equivalent to ``len(self)``. + """Number of atoms in AtomGroup. - """ + Equivalent to ``len(self)``.""" return len(self) @property def residues(self): - """Get sorted ResidueGroup of the (unique) residues represented in the - AtomGroup. - - """ + """Get sorted :class:`ResidueGroup` of the (unique) residues + represented in the AtomGroup.""" return self._u.residues[np.unique(self.resindices)] @residues.setter @@ -846,10 +901,8 @@ def n_residues(self): @property def segments(self): - """Get sorted SegmentGroup of the (unique) segments represented in the - AtomGroup. - - """ + """Get sorted :class:`SegmentGroup` of the (unique) segments + represented in the AtomGroup.""" return self._u.segments[np.unique(self.segindices)] @segments.setter @@ -868,9 +921,7 @@ def n_segments(self): @property def unique(self): - """Return an AtomGroup containing sorted and unique atoms only. - - """ + """Return an AtomGroup containing sorted and unique atoms only.""" return self._u.atoms[np.unique(self.ix)] @property @@ -882,9 +933,12 @@ def positions(self): the *same* coordinate to all atoms (e.g. ``ag.positions = array([0,0,0])`` will move all particles to the origin). - .. note:: changing the position is not reflected in any files; reading - any frame from the trajectory will replace the change with - that from the file + .. note:: Changing the position is not reflected in any files; + reading any frame from the trajectory will replace + the change with that from the file *except* if the + trajectory is held in memory, e.g., when the + :class:`~MDAnalysis.core.universe.Universe.transfer_to_memory` + method was used. """ return self._u.trajectory.ts.positions[self._ix] @@ -967,18 +1021,21 @@ def ts(self): return trj_ts.copy_slice(self.indices) def select_atoms(self, sel, *othersel, **selgroups): - """Select atoms using a CHARMM selection string. + """Select atoms using a selection string. - Returns an :class:`AtomGroup` with atoms sorted according to their - index in the psf (this is to ensure that there aren't any duplicates, - which can happen with complicated selections). + Returns an :class:`AtomGroup` with atoms sorted according to + their index in the topology (this is to ensure that there + are not any duplicates, which can happen with complicated + selections). Existing :class:`AtomGroup` objects can be passed as named arguments, which will then be available to the selection parser. Subselections can be grouped with parentheses. - Example:: + Examples + -------- + >>> sel = universe.select_atoms("segid DMPC and not ( name H* or name O* )") >>> sel @@ -986,18 +1043,28 @@ def select_atoms(self, sel, *othersel, **selgroups): >>> universe.select_atoms("around 10 group notHO", notHO=sel) - .. Note:: + Notes + ----- + + If exact ordering of atoms is required (for instance, for + :meth:`~AtomGroup.angle` or :meth:`~AtomGroup.dihedral` + calculations) then one supplies selections *separately* in the + required order. Also, when multiple :class:`AtomGroup` + instances are concatenated with the ``+`` operator then the + order of :class:`Atom` instances is preserved and duplicates + are not removed. + + + See Also + -------- + :ref:`selection-commands-label` for further details and examples. + - If exact ordering of atoms is required (for instance, for - :meth:`~AtomGroup.angle` or :meth:`~AtomGroup.dihedral` - calculations) then one supplies selections *separately* in the - required order. Also, when multiple :class:`AtomGroup` instances are - concatenated with the ``+`` operator then the order of :class:`Atom` - instances is preserved and duplicates are not removed. + .. rubric:: Selection syntax - .. SeeAlso:: :ref:`selection-commands-label` for further details and examples. - The selection parser understands the following CASE SENSITIVE *keywords*: + The selection parser understands the following CASE SENSITIVE + *keywords*: **Simple selections** @@ -1115,6 +1182,7 @@ def select_atoms(self, sel, *othersel, **selgroups): therefore have atoms that were initially absent from the instance :meth:`~select_atoms` was called from. + .. versionchanged:: 0.7.4 Added *resnum* selection. .. versionchanged:: 0.8.1 @@ -1123,6 +1191,7 @@ def select_atoms(self, sel, *othersel, **selgroups): Added *bonded* selection .. versionchanged:: 0.16.0 Resid selection now takes icodes into account where present. + """ atomgrp = selection.Parser.parse(sel, selgroups).apply(self) if othersel: @@ -1138,6 +1207,7 @@ def split(self, level): ---------- level : {'atom', 'residue', 'segment'} + .. versionadded:: 0.9.0 """ accessors = {'segment': 'segindices', @@ -1165,12 +1235,14 @@ def guess_bonds(self, vdwradii=None): vdwradii : dict, optional Dict relating atom type: vdw radii + See Also -------- - :func:`MDAnalysis.topology.core.guess_bonds` for details on the - algorithm used to guess bonds. + :func:`MDAnalysis.topology.guessers.guess_bonds` + .. versionadded:: 0.10.0 + """ from ..topology.core import guess_bonds, guess_angles, guess_dihedrals from .topologyattrs import Bonds, Angles, Dihedrals @@ -1209,6 +1281,7 @@ def bond(self): ------ `ValueError` if the AtomGroup is not length 2 + .. versionadded:: 0.11.0 """ if len(self) != 2: @@ -1228,6 +1301,7 @@ def angle(self): ------ `ValueError` if the AtomGroup is not length 3 + .. versionadded:: 0.11.0 """ if len(self) != 3: @@ -1247,6 +1321,7 @@ def dihedral(self): ------ `ValueError` if the AtomGroup is not length 4 + .. versionadded:: 0.11.0 """ if len(self) != 4: @@ -1266,6 +1341,7 @@ def improper(self): ------ `ValueError` if the AtomGroup is not length 4 + .. versionadded:: 0.11.0 """ if len(self) != 4: @@ -1275,31 +1351,41 @@ def improper(self): def write(self, filename=None, file_format="PDB", filenamefmt="{trjname}_{frame}", **kwargs): - """Write AtomGroup to a file. - - AtomGroup.write(filename[,format]) - - :Keywords: - *filename* - ``None``: create TRJNAME_FRAME.FORMAT from filenamefmt [``None``] - *format* - PDB, CRD, GRO, VMD (tcl), PyMol (pml), Gromacs (ndx) CHARMM (str) - Jmol (spt); case-insensitive and can also be supplied as the - filename extension [PDB] - *filenamefmt* - format string for default filename; use substitution tokens - 'trjname' and 'frame' ["%(trjname)s_%(frame)d"] - *bonds* - how to handle bond information, especially relevant for PDBs; - default is ``"conect"``. - * ``"conect"``: write only the CONECT records defined in the original - file - * ``"all"``: write out all bonds, both the original defined and those - guessed by MDAnalysis - * ``None``: do not write out bonds + """Write `AtomGroup` to a file. + + The output can either be a coordinate file or a selection, depending on + the `format`. Only single-frame coordinate files are supported. If you + need to write out a trajectory, see :mod:`MDAnalysis.coordinates`. + + Parameters + ---------- + filename : str, optional + ``None``: create TRJNAME_FRAME.FORMAT from filenamefmt [``None``] + + format : str, optional + PDB, CRD, GRO, VMD (tcl), PyMol (pml), Gromacs (ndx) CHARMM (str) + Jmol (spt); case-insensitive and can also be supplied as the + filename extension [PDB] + + filenamefmt : str, optional + format string for default filename; use substitution tokens + 'trjname' and 'frame' ["%(trjname)s_%(frame)d"] + + bonds : str, optional + how to handle bond information, especially relevant for PDBs; + default is ``"conect"``. + + * ``"conect"``: write only the CONECT records defined in the original + file + * ``"all"``: write out all bonds, both the original defined and those + guessed by MDAnalysis + * ``None``: do not write out bonds + + .. versionchanged:: 0.9.0 Merged with write_selection. This method can now write both selections out. + """ import MDAnalysis.coordinates import MDAnalysis.selections @@ -1346,26 +1432,28 @@ def write(self, filename=None, file_format="PDB", class ResidueGroup(GroupBase): """ResidueGroup base class. - This class is used by a Universe for generating its Topology-specific - ResidueGroup class. All the TopologyAttr components are obtained from - GroupBase, so this class only includes ad-hoc methods specific to - ResidueGroups. + This class is used by a :class:`Universe` for generating its + Topology-specific :class:`ResidueGroup` class. All the + :class:`TopologyAttr` components are obtained from + :class:`GroupBase`, so this class only includes ad-hoc methods + specific to ResidueGroups. """ @property def atoms(self): - """Get an AtomGroup of atoms represented in this ResidueGroup. + """Get an :class:`AtomGroup` of atoms represented in this + :class:`ResidueGroup`. - The atoms are ordered locally by residue in the ResidueGroup. - No duplicates are removed. + The atoms are ordered locally by residue in the + :class:`ResidueGroup`. No duplicates are removed. """ return self._u.atoms[np.concatenate(self.indices)] @property def n_atoms(self): - """Number of atoms represented in ResidueGroup, including duplicate - residues. + """Number of atoms represented in :class:`ResidueGroup`, including + duplicate residues. Equivalent to ``len(self.atoms)``. @@ -1374,7 +1462,7 @@ def n_atoms(self): @property def residues(self): - """Get another ResidueGroup identical to this one. + """Get another :class:`ResidueGroup` identical to this one. """ return self._u.residues[self.ix] diff --git a/package/MDAnalysis/core/levels.py b/package/MDAnalysis/core/levels.py index aea8453de0b..eb617700c1a 100644 --- a/package/MDAnalysis/core/levels.py +++ b/package/MDAnalysis/core/levels.py @@ -14,23 +14,32 @@ # J. Comput. Chem. 32 (2011), 2319--2327, doi:10.1002/jcc.21787 # -""" +"""\ Hierarchy levels --- :mod:`MDAnalysis.core.levels` ================================================== -Levels are used to define the relationships between different containers in -MDAnalysis +:class:`Level` instances are used to define the relationships between +different containers (see :mod:`MDAnalysis.core.groups`) in +MDAnalysis. + +Levels can be navigated between using the :attr:`.child` and +:attr:`.parent` attributes of the containers. Classes for containers +at a given level are accessed using the :attr:`.singular` and +:attr:`.plural` attributes:: + + Level: + .singular ===================== .plural + Atom <- Atomlevel ^ .child -> AtomGroup + Residue <- Residuelevel ! -> ResidueGroup + Segment <- Segmentlevel v .parent -> SegmentGroup + +.. SeeAlso:: + :mod:`MDAnalysis.core.groups` -Levels can be navigated between using the .child and .parent attributes -Classes for containers at a given level are accessed using the .singular -and .plural attributes +.. autoclass:: Level - Level: - .singular ===================== .plural -Atom <- Atomlevel ^ .child -> AtomGroup -Residue <- Residuelevel ! -> ResidueGroup -Segment <- Segmentlevel v .parent -> SegmentGroup """ + import functools @@ -43,11 +52,14 @@ class Level(object): Can do comparisons with either - .singular gives the Class for Components of this Level - .plural gives the Class for Groups of this Level + - :attr:`.singular` gives the Class for Components of this Level + - :attr:`.plural` gives the Class for Groups of this Level + + or + + - :attr:`.parent` gives the :class:`Level` object above this + - :attr:`.child` gives the :class:`Level` object below this - .parent gives the Level object above this - .child gives the Level object below this """ def __init__(self, name, singular, plural): self.name = name diff --git a/package/MDAnalysis/core/selection.py b/package/MDAnalysis/core/selection.py index a47bee877d4..b60f7893bc2 100644 --- a/package/MDAnalysis/core/selection.py +++ b/package/MDAnalysis/core/selection.py @@ -1,5 +1,5 @@ -# -*- Mode: python; tab-width: 4; indent-tabs-mode:nil; coding:utf-8 -*- -# vim: tabstop=4 expandtab shiftwidth=4 softtabstop=4 +# -*- Mode: python; tab-width: 4; indent-tabs-mode:nil; coding: utf-8 -*- +# 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 @@ -14,20 +14,22 @@ # J. Comput. Chem. 32 (2011), 2319--2327, doi:10.1002/jcc.21787 # - -""" -Atom selection Hierarchy --- :mod:`MDAnalysis.core.selection` +"""Atom selection Hierarchy --- :mod:`MDAnalysis.core.selection` ============================================================= -These objects are constructed and applied to the group +This module contains objects that represent selections. They are +constructed and then applied to the group. -In general, Parser.parse() creates a Selection object -from a selection string. +In general, :meth:`Parser.parse` creates a :class:`Selection` object +from a selection string. This :class:`Selection` object is then passed +an :class:`~MDAnalysis.core.groups.AtomGroup` through its +:meth:`~MDAnalysis.core.groups.AtomGroup.apply` method to apply the +``Selection`` to the ``AtomGroup``. -This Selection object is then passed an AtomGroup through its -apply method to apply the Selection to the AtomGroup. +This is all invisible to the user through the +:meth:`~MDAnalysis.core.groups.AtomGroup.select_atoms` method of an +:class:`~MDAnalysis.core.groups.AtomGroup`. -This is all invisible to the user through ag.select_atoms """ import six from six.moves import zip diff --git a/package/MDAnalysis/core/topology.py b/package/MDAnalysis/core/topology.py index 4e34672f879..7fc23992668 100644 --- a/package/MDAnalysis/core/topology.py +++ b/package/MDAnalysis/core/topology.py @@ -13,9 +13,39 @@ # J. Comput. Chem. 32 (2011), 2319--2327, doi:10.1002/jcc.21787 # -""" -Topology object --- :mod:`MDAnalysis.core.topology' -=================================================================== +"""\ +Core Topology object --- :mod:`MDAnalysis.core.topology` +======================================================== + +.. versionadded:: 0.16.0 + +:class:`Topology` is the core object that holds all topology information. + +TODO: Add in-depth discussion. + +Notes +----- +For developers: In MDAnalysis 0.16.0 this new topology system was +introduced and discussed as issue `#363`_; this issue contains key +information and discussions on the new system. The issue number *363* +is also being used as a short-hand in discussions to refer to the new +topology system. + + +.. _`#363`: https://github.com/MDAnalysis/mdanalysis/issues/363 + +Classes +------- + +.. autoclass:: Topology + :members: +.. autoclass:: TransTable + :members: + +Helper functions +---------------- + +.. autofunction:: make_downshift_arrays """ @@ -69,8 +99,10 @@ def make_downshift_arrays(upshift, nparents): Notes ----- The final entry in the return array will be ``None`` to ensure that the - dtype of the array is object. This means negative indexing should - not be used ever with these arrays. + dtype of the array is :class:`object`. + + .. warning:: This means negative indexing should **never** + be used with these arrays. """ order = np.argsort(upshift) diff --git a/package/MDAnalysis/core/topologyattrs.py b/package/MDAnalysis/core/topologyattrs.py index 5f1a9f0dad8..1ce40b069c6 100644 --- a/package/MDAnalysis/core/topologyattrs.py +++ b/package/MDAnalysis/core/topologyattrs.py @@ -13,17 +13,17 @@ # J. Comput. Chem. 32 (2011), 2319--2327, doi:10.1002/jcc.21787 # -""" -Topology attribute objects --- :mod:`MDAnalysis.core.topologyattrs' +"""\ +Topology attribute objects --- :mod:`MDAnalysis.core.topologyattrs` =================================================================== -Common TopologyAttrs used by most topology parsers. +Common :class:`TopologyAttr` instances that are used by most topology +parsers. TopologyAttrs are used to contain attributes such as atom names or resids. These are usually read by the TopologyParser. - - """ + from six.moves import zip from collections import defaultdict import itertools diff --git a/package/MDAnalysis/core/topologyobjects.py b/package/MDAnalysis/core/topologyobjects.py index 5282b7c5b64..50e23811e6e 100644 --- a/package/MDAnalysis/core/topologyobjects.py +++ b/package/MDAnalysis/core/topologyobjects.py @@ -148,7 +148,7 @@ def __len__(self): class Bond(TopologyObject): - """A bond between two :class:`~MDAnalysis.core.AtomGroup.Atom` instances. + """A bond between two :class:`~MDAnalysis.core.groups.Atom` instances. Two :class:`Bond` instances can be compared with the ``==`` and ``!=`` operators. A bond is equal to another if the same atom @@ -173,7 +173,7 @@ def partner(self, atom): Returns ------- - the other :class:`~MDAnalysis.core.AtomGroup.Atom` in this + the other :class:`~MDAnalysis.core.groups.Atom` in this bond """ if atom == self.atoms[0]: @@ -202,7 +202,7 @@ def length(self, pbc=False): class Angle(TopologyObject): - """An angle between three :class:`~MDAnalysis.core.AtomGroup.Atom` instances. + """An angle between three :class:`~MDAnalysis.core.groups.Atom` instances. Atom 2 is the apex of the angle .. versionadded:: 0.8 @@ -240,7 +240,7 @@ def angle(self): class Dihedral(TopologyObject): """Dihedral (dihedral angle) between four - :class:`~MDAnalysis.core.AtomGroup.Atom` instances. + :class:`~MDAnalysis.core.groups.Atom` instances. The dihedral is defined as the angle between the planes formed by Atoms (1, 2, 3) and (2, 3, 4). @@ -289,7 +289,7 @@ def dihedral(self): class ImproperDihedral(Dihedral): """ Improper Dihedral (improper dihedral angle) between four - :class:`~MDAnalysis.core.AtomGroup.Atom` instances. + :class:`~MDAnalysis.core.groups.Atom` instances. MDAnalysis treats the improper dihedral angle as the angle between the planes formed by Atoms (1, 2, 3) and (2, 3, 4). @@ -467,12 +467,12 @@ class TopologyGroup(object): tg2 = tg.select_bonds([key]) Where *key* describes the desired bond as a tuple of the involved - :class:`~MDAnalysis.AtomGroup.Atom` types, as defined by the .type Atom + :class:`~MDAnalysis.core.groups.Atom` types, as defined by the .type Atom attribute). A list of available keys can be displayed using the :meth:`types` method. Alternatively, all the bonds which are in a given - :class:`~MDAnalysis.AtomGroup.AtomGroup` can be extracted using + :class:`~MDAnalysis.core.groups.AtomGroup` can be extracted using :meth:`atomgroup_intersection`:: tg2 = tg.atomgroup_intersection(ag) diff --git a/package/MDAnalysis/core/universe.py b/package/MDAnalysis/core/universe.py index c38502672c5..b02a5ef5794 100644 --- a/package/MDAnalysis/core/universe.py +++ b/package/MDAnalysis/core/universe.py @@ -1,3 +1,52 @@ +# -*- Mode: python; tab-width: 4; indent-tabs-mode:nil; coding: utf-8 -*- +# 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 +# and contributors (see AUTHORS for the full list) +# +# Released under the GNU Public Licence, v2 or any higher version +# +# Please cite your use of MDAnalysis in published work: +# +# N. Michaud-Agrawal, E. J. Denning, T. B. Woolf, and O. Beckstein. +# MDAnalysis: A Toolkit for the Analysis of Molecular Dynamics Simulations. +# J. Comput. Chem. 32 (2011), 2319--2327, doi:10.1002/jcc.21787 +# + +"""\ +========================================================= +Core object: Universe --- :mod:`MDAnalysis.core.universe` +========================================================= + +The :class:`~MDAnalysis.core.universe.Universe` class ties a topology +and a trajectory together. Almost all code in MDAnalysis starts with a +``Universe``. + +Normally, a ``Universe`` is created from files:: + + import MDAnalysis as mda + u = mda.Universe("topology.psf", "trajectory.dcd") + +In order to construct new simulation system it is also convenient to +construct a ``Universe`` from existing +:class:`~MDAnalysis.core.group.AtomGroup` instances with the +:func:`Merge` function. + + +Classes +======= + +.. autoclass:: Universe + :members: + +Functions +========= + +.. autofunction:: Merge + +""" + import numpy as np import logging import copy @@ -84,16 +133,16 @@ class Universe(object): atom type which are used in guessing bonds. is_anchor When unpickling instances of - :class:`MDAnalysis.core.AtomGroup.AtomGroup` existing Universes are + :class:`MDAnalysis.core.groups.AtomGroup` existing Universes are searched for one where to anchor those atoms. Set to ``False`` to prevent this Universe from being considered. [``True``] anchor_name Setting to other than ``None`` will cause - :class:`MDAnalysis.core.AtomGroup.AtomGroup` instances pickled from the + :class:`MDAnalysis.core.groups.AtomGroup` instances pickled from the Universe to only unpickle if a compatible Universe with matching *anchor_name* is found. *is_anchor* will be ignored in this case but will still be honored when unpickling - :class:`MDAnalysis.core.AtomGroup.AtomGroup` instances pickled with + :class:`MDAnalysis.core.groups.AtomGroup` instances pickled with *anchor_name*==``None``. [``None``] in_memory After reading in the trajectory, transfer it to an in-memory @@ -256,24 +305,26 @@ def load_new(self, filename, format=None, in_memory=False, **kwargs): :class:`MDAnalysis.coordinates.base.Reader` to define a custom reader to be used on the trajectory file. in_memory : bool (optional) - Directly load trajectory into memory - kwargs : dict + Directly load trajectory into memory with the + :class:`~MDAnalysis.coordinates.memory.MemoryReader` + + .. versionadded:: 0.16.0 + + **kwargs : dict Other kwargs are passed to the trajectory reader (only for advanced use) - - # TODO: check what happens if filename is None Returns ------- filename : str trajectory_format : str - # TODO: look up raises doc formating Raises ------ TypeError if trajectory format can not be determined or no appropriate trajectory reader found + .. versionchanged:: 0.8 If a list or sequence that is provided for *filename* only contains a single entry then it is treated as single coordinate file. This @@ -284,6 +335,13 @@ def load_new(self, filename, format=None, in_memory=False, **kwargs): :class:`~MDAnalysis.coordinates.base.ChainReader`. """ + # the following was in the doc string: + # TODO + # ---- + # - check what happens if filename is ``None`` + # - look up raises doc formating + # + # # TODO: is this really sensible? Why not require a filename arg? if filename is None: return @@ -353,6 +411,7 @@ def transfer_to_memory(self, frame_interval=1, quiet=True): Will print the progress of loading trajectory to memory, if set to True. Default value is quiet. + .. versionadded:: 0.16.0 """ from ..coordinates.memory import MemoryReader @@ -688,7 +747,7 @@ def as_Universe(*args, **kwargs): as_Universe(PSF, DCD, **kwargs) --> Universe(PSF, DCD, **kwargs) as_Universe(*args, **kwargs) --> Universe(*args, **kwargs) - :Returns: an instance of :class:`~MDAnalaysis.AtomGroup.Universe` + :Returns: an instance of :class:`~MDAnalysis.core.groups.Universe` """ if len(args) == 0: raise TypeError("as_Universe() takes at least one argument (%d given)" % len(args)) @@ -698,33 +757,43 @@ def as_Universe(*args, **kwargs): def Merge(*args): - """Return a :class:`Universe` from two or more :class:`AtomGroup` instances. - - The resulting universe will only inherit the common topology attributes - that all merged universes share. - - :class:`AtomGroup` instances can come from different Universes, or come - directly from a :meth:`~Universe.select_atoms` call. - - It can also be used with a single :class:`AtomGroup` if the user wants to, - for example, re-order the atoms in the Universe. - - If multiple :class:`AtomGroup` instances from the same Universe are given, - the merge will first simply "add" together the :class:`AtomGroup` - instances. + """Create a new new :class:`Universe` from one or more + :class:`~MDAnalysis.core.groups.AtomGroup` instances. Parameters ---------- - args : One or more :class:`AtomGroup` instances. + *args : :class:`~MDAnalysis.core.groups.AtomGroup` + One or more AtomGroups. Returns ------- - universe : An instance of :class:`~MDAnalaysis.AtomGroup.Universe` + universe : :class:`Universe` :Raises: :exc:`ValueError` for too few arguments or if an AtomGroup is empty and :exc:`TypeError` if arguments are not :class:`AtomGroup` instances. + Notes + ----- + The resulting :class:`Universe` will only inherit the common topology + attributes that all merged universes share. + + :class:`AtomGroup` instances can come from different Universes, or can come + directly from a :meth:`~Universe.select_atoms` call. + + :class:`Merge` can also be used with a single :class:`AtomGroup` if the + user wants to, for example, re-order the atoms in the :class:`Universe`. + + If multiple :class:`AtomGroup` instances from the same :class:`Universe` + are given, the merge will first simply "add" together the + :class:`AtomGroup` instances. + + Merging does not create a full trajectory but only a single structure even + if the input consists of one or more trajectories. However, one can use + the :class:`~MDAnalysis.coordinates.memory.MemoryReader` to construct a + trajectory for the new Universe as described under + :ref:`creating-in-memory-trajectory-label`. + Example ------- In this example, protein, ligand, and solvent were externally prepared in @@ -741,10 +810,6 @@ def Merge(*args): The complete system is then written out to a new PDB file. - Note - ---- - Merging does not create a full trajectory but only a single - structure even if the input consists of one or more trajectories. .. versionchanged 0.9.0:: Raises exceptions instead of assertion errors. diff --git a/package/MDAnalysis/lib/mdamath.py b/package/MDAnalysis/lib/mdamath.py index be41ee42517..43cf44b7f2d 100644 --- a/package/MDAnalysis/lib/mdamath.py +++ b/package/MDAnalysis/lib/mdamath.py @@ -266,7 +266,7 @@ def make_whole(atomgroup, reference_atom=None): :Arguments: *atomgroup* - The :class:`MDAnalysis.core.AtomGroup.AtomGroup` to work with. + The :class:`MDAnalysis.core.groups.AtomGroup` to work with. The positions of this are modified in place. All these atoms must belong in the same molecule or fragment. diff --git a/package/MDAnalysis/lib/util.py b/package/MDAnalysis/lib/util.py index 3b0bea94270..72655e305a2 100644 --- a/package/MDAnalysis/lib/util.py +++ b/package/MDAnalysis/lib/util.py @@ -45,7 +45,7 @@ instances (essentially, a memory buffer) by wrapping these instances into a :class:`NamedStream`. This :class:`NamedStream` can then be used in place of an ordinary file name (typically, with a -class:`~MDAnalysis.core.AtomGroup.Universe` but it is also possible to +class:`~MDAnalysis.core.universe.Universe` but it is also possible to *write* to such a stream using :func:`MDAnalysis.Writer`). .. rubric: Examples @@ -67,7 +67,7 @@ (".pdb") to :class:`NamedStream` because the file type recognition uses the extension of the file name to determine the file format or alternatively provide the ``format="pdb"`` keyword argument to the -:class:`~MDAnalysis.core.AtomGroup.Universe`. +:class:`~MDAnalysis.core.universe.Universe`. The use of streams becomes more interesting when MDAnalysis is used as glue between different analysis packages and when one can arrange things so that @@ -750,7 +750,7 @@ def __eq__(self, x): def __ne__(self, x): return not self == x - + def __lt__(self, x): return self.name < x @@ -1082,7 +1082,7 @@ def fixedwidth_bins(delta, xmin, xmax): #: The table is used for :func:`convert_aa_code`. amino_acid_codes = {one: three for three, one in canonical_inverse_aa_codes.items()} #: non-default charge state amino acids or special charge state descriptions -#: (Not fully synchronized with :class:`MDAnalysis.core.Selection.ProteinSelection`.) +#: (Not fully synchronized with :class:`MDAnalysis.core.selection.ProteinSelection`.) alternative_inverse_aa_codes = { 'HISA': 'H', 'HISB': 'H', 'HSE': 'H', 'HSD': 'H', 'HID': 'H', 'HIE': 'H', 'HIS1': 'H', 'HIS2': 'H', @@ -1251,7 +1251,7 @@ def unique_rows(arr, return_index=False): u = np.unique(arr.view( dtype=np.dtype([(str(i), arr.dtype) for i in xrange(m)]) )) - return u.view(arr.dtype).reshape(-1, m) + return u.view(arr.dtype).reshape(-1, m) def blocks_of(a, n, m): @@ -1320,7 +1320,7 @@ def blocks_of(a, n, m): class Namespace(object): """Class to allow storing attributes in new namespace. """ def __getattr__(self, key): - # a.this causes a __getattr__ call for key = 'this' + # a.this causes a __getattr__ call for key = 'this' return self.__dict__[key] def __setattr__(self, key, value): # a.this = 10 causes a __setattr__ call for key='this' value=10 @@ -1342,4 +1342,4 @@ def __getitem__(self, key): return self.__dict__[key] def __iter__(self): for i in self.__dict__: - yield i + yield i diff --git a/package/MDAnalysis/selections/__init__.py b/package/MDAnalysis/selections/__init__.py index b5fa501da43..cc179fc38e9 100644 --- a/package/MDAnalysis/selections/__init__.py +++ b/package/MDAnalysis/selections/__init__.py @@ -19,7 +19,7 @@ Selection exporters =================== -Functions to write a :class:`MDAnalysis.AtomGroup.AtomGroup` selection +Functions to write a :class:`MDAnalysis.core.groups.AtomGroup` selection to a file so that it can be used in another programme. :mod:`MDAnalysis.selections.vmd` diff --git a/package/MDAnalysis/selections/base.py b/package/MDAnalysis/selections/base.py index c6ac5146994..8267cccce03 100644 --- a/package/MDAnalysis/selections/base.py +++ b/package/MDAnalysis/selections/base.py @@ -142,7 +142,7 @@ def write(self, selection, number=None, name=None, frame=None, mode=None): :Arguments: *selection* - a :class:`MDAnalysis.core.AtomGroup.AtomGroup` + a :class:`MDAnalysis.core.groups.AtomGroup` *number* selection will be named "mdanalysis" (``None`` auto increments between writes; useful diff --git a/package/MDAnalysis/selections/charmm.py b/package/MDAnalysis/selections/charmm.py index b55caaa88c9..353817fc746 100644 --- a/package/MDAnalysis/selections/charmm.py +++ b/package/MDAnalysis/selections/charmm.py @@ -19,7 +19,7 @@ CHARMM selections ================= -Write :class:`MDAnalysis.core.AtomGroup.AtomGroup` selection to a `str` file +Write :class:`MDAnalysis.core.groups.AtomGroup` selection to a `str` file that defines a `CHARMM selection`_. To be used in CHARMM_ like this:: stream macro.str diff --git a/package/MDAnalysis/selections/gromacs.py b/package/MDAnalysis/selections/gromacs.py index 89baa9acdd9..5d59ad7d243 100644 --- a/package/MDAnalysis/selections/gromacs.py +++ b/package/MDAnalysis/selections/gromacs.py @@ -19,7 +19,7 @@ Gromacs selections ================== -Write :class:`MDAnalysis.core.AtomGroup.AtomGroup` selection to a `ndx`_ file +Write :class:`MDAnalysis.core.groups.AtomGroup` selection to a `ndx`_ file that defines a Gromacs_ index group. To be used in Gromacs like this:: -n macro.ndx diff --git a/package/MDAnalysis/selections/jmol.py b/package/MDAnalysis/selections/jmol.py index fa566418e55..c2ce52340ee 100644 --- a/package/MDAnalysis/selections/jmol.py +++ b/package/MDAnalysis/selections/jmol.py @@ -18,7 +18,7 @@ Jmol selections ================= -Write :class:`MDAnalysis.core.AtomGroup.AtomGroup` selection to a `str` file +Write :class:`MDAnalysis.core.groups.AtomGroup` selection to a `str` file that defines a `Jmol selection`_. To be used in Jmol_ like this:: script macro.spt diff --git a/package/MDAnalysis/selections/pymol.py b/package/MDAnalysis/selections/pymol.py index 65e8beebdff..9a159748eeb 100644 --- a/package/MDAnalysis/selections/pymol.py +++ b/package/MDAnalysis/selections/pymol.py @@ -19,7 +19,7 @@ PyMOL selections ================= -Write :class:`MDAnalysis.core.AtomGroup.AtomGroup` selection to a +Write :class:`MDAnalysis.core.groups.AtomGroup` selection to a script `pml`_ file that defines PyMOL_ atomselect macros. To be used in PyMOL like this:: diff --git a/package/MDAnalysis/selections/vmd.py b/package/MDAnalysis/selections/vmd.py index 459058af9fe..b20f9e4621d 100644 --- a/package/MDAnalysis/selections/vmd.py +++ b/package/MDAnalysis/selections/vmd.py @@ -19,7 +19,7 @@ VMD selections ============== -Write :class:`MDAnalysis.core.AtomGroup.AtomGroup` selection to a VMD_ `tcl` file +Write :class:`MDAnalysis.core.groups.AtomGroup` selection to a VMD_ `tcl` file that defines `atomselect macros`_. To be used in VMD like this:: source macros.vmd diff --git a/package/MDAnalysis/topology/ExtendedPDBParser.py b/package/MDAnalysis/topology/ExtendedPDBParser.py index 3972e775257..4e581eb2611 100644 --- a/package/MDAnalysis/topology/ExtendedPDBParser.py +++ b/package/MDAnalysis/topology/ExtendedPDBParser.py @@ -34,7 +34,7 @@ * :mod:`MDAnalysis.topology.PDBParser` * :class:`MDAnalysis.coordinates.PDB.ExtendedPDBReader` - * :class:`MDAnalysis.core.AtomGroup.Universe` + * :class:`MDAnalysis.core.universe.Universe` Classes ------- diff --git a/package/MDAnalysis/topology/PDBParser.py b/package/MDAnalysis/topology/PDBParser.py index 3417de93473..b7e9ccc1fe8 100644 --- a/package/MDAnalysis/topology/PDBParser.py +++ b/package/MDAnalysis/topology/PDBParser.py @@ -37,7 +37,7 @@ * :mod:`MDAnalysis.topology.ExtendedPDBParser` * :class:`MDAnalysis.coordinates.PDB.PDBReader` - * :class:`MDAnalysis.core.AtomGroup.Universe` + * :class:`MDAnalysis.core.universe.Universe` Classes ------- diff --git a/package/MDAnalysis/topology/PrimitivePDBParser.py b/package/MDAnalysis/topology/PrimitivePDBParser.py index 7e2e16dbf35..bd107527370 100644 --- a/package/MDAnalysis/topology/PrimitivePDBParser.py +++ b/package/MDAnalysis/topology/PrimitivePDBParser.py @@ -31,7 +31,7 @@ * :mod:`MDAnalysis.topology.ExtendedPDBParser` * :class:`MDAnalysis.coordinates.PDB.PDBReader` - * :class:`MDAnalysis.core.AtomGroup.Universe` + * :class:`MDAnalysis.core.universe.Universe` Classes ------- diff --git a/package/MDAnalysis/topology/__init__.py b/package/MDAnalysis/topology/__init__.py index 38d4dce9531..170dcd2ec13 100644 --- a/package/MDAnalysis/topology/__init__.py +++ b/package/MDAnalysis/topology/__init__.py @@ -12,7 +12,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` =============================================== @@ -62,9 +62,9 @@ XPDB [#a]_ pdb As PDB except Extended PDB format (can use 5-digit residue icodes numbers). To use, specify the format "XPBD" - explicitly: - ``Universe(..., topology_format="XPDB")``. - Module :mod:`MDAnalysis.coordinates.PDB` + explicitly: + ``Universe(..., topology_format="XPDB")``. + Module :mod:`MDAnalysis.coordinates.PDB` PQR [#a]_ pqr names, charges, PDB-like but whitespace-separated files with charge types, and radius information; @@ -92,7 +92,7 @@ masses, charges, the atom and bond records); chainids, resids, :mod:`MDAnalysis.topology.DMSParser` resnames, segids, - radii, + radii, TPR [#b]_ tpr names, types, Gromacs portable run input reader (limited resids, resnames, experimental support for some of the more recent @@ -129,7 +129,7 @@ dihedrals :mod:`MDAnalysis.topology.HoomdXMLParser` Macromolecular mmtf altLocs, `Macromolecular Transmission Format (MMTF)`_. - transmission bfactors, bonds, An efficient compact format for biomolecular + transmission bfactors, bonds, An efficient compact format for biomolecular format charges, masses, structures. names, occupancies, @@ -139,11 +139,11 @@ ================= ========= ================= =================================================== .. [#a] This format can also be used to provide *coordinates* so that - it is possible to create a full - :mod:`~MDAnalysis.core.AtomGroup.Universe` by simply providing a - file of this format as the sole argument to - :mod:`~MDAnalysis.core.AtomGroup.Universe`: ``u = - Universe(filename)`` + it is possible to create a full + :mod:`~MDAnalysis.core.universe.Universe` by simply providing + a file of this format as the sole argument to + :mod:`~MDAnalysis.core.universe.Universe`: ``u = + Universe(filename)`` .. [#b] The Gromacs TPR format contains coordinate information but parsing coordinates from a TPR file is currently not implemented @@ -154,10 +154,15 @@ .. _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 --------------- .. versionadded:: 0.8 +.. versionchanged:: 0.16.0 + The new array-based topology system completely replaced the old + system that was based on a list of Atom instances. Topology information consists of data that do not change over time, i.e. information that is the same for all time steps of a @@ -165,7 +170,7 @@ * identity of atoms (name, type, number, partial charge, ...) and to which residue and segment they belong; atoms are identified in - MDAnalysis by their :attr:`~MDAnalysis.core.AtomGroup.Atom.index`, + MDAnalysis by their :attr:`~MDAnalysis.core.groups.Atom.index`, an integer number starting at 0 and incremented in the order of atoms found in the topology. @@ -176,50 +181,26 @@ * dihedral angles (quadruplets of atoms) — proper and improper dihedrals should be treated separately -At the moment, only the identity of atoms is mandatory and at its most -basic, the topology is simply a list of atoms to be associated with a -list of coordinates. - -The current implementation contains submodules for different topology -file types. Each submodule *must* contain a function :func:`parse`: - -.. function: parse(filename) - - Read a topology from *filename* and return the structure dict. - -The function returns the basic MDAnalysis representation of the -topology. At the moment, this is simply a dictionary with keys -*atoms*, *bonds*, *angles*, *dihedrals*, *impropers*. The dictionary is -stored as :attr:`MDAnalysis.AtomGroup.Universe._topology`. +Topology readers are generally called "parsers" in MDAnalysis (for +historical reasons and in order to distinguish them from coordinate +"readers"). All parsers are derived from +:class:`MDAnalysis.topology.base.TopologyReader` and have a +:meth:`~MDAnalysis.topology.base.TopologyReader.parse` method that +returns a :class:`MDAnalysis.core.topology.Topology` instance. -.. warning:: - - The internal dictionary representation is subject to change. User - code should *not* access this dictionary directly. The information - provided here is solely for developers who need to work with the - existing parsers. - -.. SeeAlso:: `Topology Data Structures Wiki page`_ - -.. _`Topology Data Structures Wiki page`: - https://github.com/MDAnalysis/mdanalysis/wiki/TopologyDataStructures - -The format of the individual keys is the following (see -:mod:`PSFParser` for a reference implementation): atoms ~~~~~~ -The **atoms** are represented as a :class:`list` of -:class:`~MDAnalysis.core.AtomGroup.Atom` instances. The parser needs -to initialize the :class:`~MDAnalysis.core.AtomGroup.Atom` objects -with the data read from the topology file. - -The order of atoms in the list must correspond to the sequence of -atoms in the topology file. The atom's -:attr:`~MDAnalysis.core.AtomGroup.Atom.index` corresponds to its -index in this list. +The **atoms** appear to the user as an array of +:class:`~MDAnalysis.core.groups.Atom` instances. However, under the +hood this is essentially only an array of atom indices that are used +to index the various components of the topology database +:class:`~MDAnalysis.core.topology.Topology`. The parser needs to +initialize the :class:`~MDAnalysis.core.topology.Topology` with the +data read from the topology file. +.. SeeAlso:: :ref:`topology-system-label` bonds ~~~~~~ @@ -294,4 +275,3 @@ from . import DLPolyParser from . import HoomdXMLParser from . import MMTFParser - diff --git a/package/MDAnalysis/topology/guessers.py b/package/MDAnalysis/topology/guessers.py index 10fd7ea439b..7ae1211749f 100644 --- a/package/MDAnalysis/topology/guessers.py +++ b/package/MDAnalysis/topology/guessers.py @@ -46,7 +46,7 @@ def guess_masses(atom_types): warnings.warn("Failed to guess the mass for the following atom types: {}" "".format(', '.join(misses))) return masses - + def guess_types(atom_names): """Guess the atom type of many atoms based on atom name @@ -105,13 +105,13 @@ def guess_atom_element(atomname): def guess_bonds(atoms, coords, **kwargs): - """Guess if bonds exist between two atoms based on their distance. + r"""Guess if bonds exist between two atoms based on their distance. Bond between two atoms is created, if the two atoms are within .. math:: - d < f * (R_1 + R_2) + d < f \cdot (R_1 + R_2) of each other, where :math:`R_1` and :math:`R_2` are the VdW radii of the atoms and :math:`f` is an ad-hoc *fudge_factor*. This is @@ -119,37 +119,46 @@ def guess_bonds(atoms, coords, **kwargs): Parameters ---------- - *fudge_factor* + atoms : AtomGroup + atoms for which bonds should be guessed + coords : array + coordinates of the atoms (i.e., `AtomGroup.positions)`) + fudge_factor : float, optional The factor by which atoms must overlap eachother to be considered a bond. Larger values will increase the number of bonds found. [0.72] - *vdwradii* + vdwradii : dict, optional To supply custom vdwradii for atoms in the algorithm. Must be a dict of format {type:radii}. The default table of van der Waals radii is hard-coded as :data:`MDAnalysis.topology.tables.vdwradii`. Any user defined vdwradii passed as an argument will supercede the table values. [``None``] - *lower_bound* + lower_bound : float, optional The minimum bond length. All bonds found shorter than this length will be ignored. This is useful for parsing PDB with altloc records where atoms with altloc A and B maybe very close together and there should be no chemical bond between them. [0.1] - *box* + box : dimensions, optional Bonds are found using a distance search, if unit cell information is given, periodic boundary conditions will be considered in the distance search. [``None``] - :Returns: - List of tuples suitable for use in Universe topology building. + Returns + ------- + list + List of tuples suitable for use in Universe topology building. + + Warnings + -------- + No check is done after the bonds are guessed to see if Lewis + structure is correct. This is wrong and will burn somebody. - .. warning:: - No check is done after the bonds are guessed to see if Lewis - structure is correct. This is wrong and will burn somebody. + Raises + ------ + :exc:`ValueError` if inputs are malformed or `vdwradii` data is missing. - :Raises: - ValueError if inputs are malformed or *vdwradii* data is missing. .. _`same algorithm that VMD uses`: http://www.ks.uiuc.edu/Research/vmd/vmd-1.9.1/ug/node26.html diff --git a/package/doc/sphinx/source/documentation_pages/coordinates_modules.rst b/package/doc/sphinx/source/documentation_pages/coordinates_modules.rst index 223b4d9c12b..9a4aa15e77d 100644 --- a/package/doc/sphinx/source/documentation_pages/coordinates_modules.rst +++ b/package/doc/sphinx/source/documentation_pages/coordinates_modules.rst @@ -11,7 +11,7 @@ formats` by the file extension and hence most users probably do not need to concern themselves with classes and functions described here. However, if MDAnalysis fails to recognize a coordinate file then the user can provide the format in the keyword argument *format* to -:class:`~MDAnalysis.core.AtomGroup.Universe` to force the format. +:class:`~MDAnalysis.core.universe.Universe` to force the format. .. rubric:: Coordinate formats diff --git a/package/doc/sphinx/source/documentation_pages/core/AtomGroup.rst b/package/doc/sphinx/source/documentation_pages/core/AtomGroup.rst deleted file mode 100644 index d0606383eda..00000000000 --- a/package/doc/sphinx/source/documentation_pages/core/AtomGroup.rst +++ /dev/null @@ -1 +0,0 @@ -.. automodule:: MDAnalysis.core.AtomGroup diff --git a/package/doc/sphinx/source/documentation_pages/core/Selection.rst b/package/doc/sphinx/source/documentation_pages/core/Selection.rst deleted file mode 100644 index 18ed855065c..00000000000 --- a/package/doc/sphinx/source/documentation_pages/core/Selection.rst +++ /dev/null @@ -1,2 +0,0 @@ -.. automodule:: MDAnalysis.core.Selection - :members: diff --git a/package/doc/sphinx/source/documentation_pages/core/groups.rst b/package/doc/sphinx/source/documentation_pages/core/groups.rst new file mode 100644 index 00000000000..0ea31cda4ad --- /dev/null +++ b/package/doc/sphinx/source/documentation_pages/core/groups.rst @@ -0,0 +1 @@ +.. automodule:: MDAnalysis.core.groups diff --git a/package/doc/sphinx/source/documentation_pages/core/levels.rst b/package/doc/sphinx/source/documentation_pages/core/levels.rst new file mode 100644 index 00000000000..29b128d0f44 --- /dev/null +++ b/package/doc/sphinx/source/documentation_pages/core/levels.rst @@ -0,0 +1 @@ +.. automodule:: MDAnalysis.core.levels diff --git a/package/doc/sphinx/source/documentation_pages/core/selection.rst b/package/doc/sphinx/source/documentation_pages/core/selection.rst new file mode 100644 index 00000000000..8f3e40ecffc --- /dev/null +++ b/package/doc/sphinx/source/documentation_pages/core/selection.rst @@ -0,0 +1,2 @@ +.. automodule:: MDAnalysis.core.selection + :members: diff --git a/package/doc/sphinx/source/documentation_pages/core/topology.rst b/package/doc/sphinx/source/documentation_pages/core/topology.rst new file mode 100644 index 00000000000..9d9dfa242a8 --- /dev/null +++ b/package/doc/sphinx/source/documentation_pages/core/topology.rst @@ -0,0 +1 @@ +.. automodule:: MDAnalysis.core.topology diff --git a/package/doc/sphinx/source/documentation_pages/core/topologyattrs.rst b/package/doc/sphinx/source/documentation_pages/core/topologyattrs.rst new file mode 100644 index 00000000000..9eda33222c8 --- /dev/null +++ b/package/doc/sphinx/source/documentation_pages/core/topologyattrs.rst @@ -0,0 +1,2 @@ +.. automodule:: MDAnalysis.core.topologyattrs + :members: diff --git a/package/doc/sphinx/source/documentation_pages/core/universe.rst b/package/doc/sphinx/source/documentation_pages/core/universe.rst new file mode 100644 index 00000000000..4aff509154d --- /dev/null +++ b/package/doc/sphinx/source/documentation_pages/core/universe.rst @@ -0,0 +1 @@ +.. automodule:: MDAnalysis.core.universe diff --git a/package/doc/sphinx/source/documentation_pages/core_modules.rst b/package/doc/sphinx/source/documentation_pages/core_modules.rst index cf9f63e5c27..f0273a35028 100644 --- a/package/doc/sphinx/source/documentation_pages/core_modules.rst +++ b/package/doc/sphinx/source/documentation_pages/core_modules.rst @@ -6,18 +6,62 @@ Core modules The :mod:`MDAnalysis.core` modules contain functionality essential for MDAnalysis, such as the central data structures in -:mod:`MDAnalysis.core.AtomGroup` or the selection definitions and -parsing in :mod:`MDAnalysis.core.Selection`. +:mod:`MDAnalysis.core.universe` and :mod:`MDAnalysis.core.groups` or +the selection definitions and parsing in +:mod:`MDAnalysis.core.selection`. -.. rubric:: Contents +Important objects for users +=========================== + +All users of MDAnalysis need to understand the two most important +classes in this section, namely the +:class:`~MDAnalysis.core.universe.Universe` and the +:class:`~MDAnalysis.core.groups.AtomGroup`. .. toctree:: :maxdepth: 1 - core/init - core/AtomGroup - core/Selection - core/topologyobjects + core/universe + core/groups core/Timeseries + +.. _topology-system-label: + +Topology system +=============== + +The topology system is primarily of interest to developers. + +.. toctree:: + :maxdepth: 1 + + core/topology + core/levels + core/topologyobjects + core/topologyattrs + +.. SeeAlso:: :ref:`Developer notes for Topology + Parsers ` + +Selection system +================ + +The selection system is primarily of interest to developers. + +.. toctree:: + :maxdepth: 1 + + core/selection + +Flag system +============ + +The flag system contains the global behavior of MDAnalysis. It is +normally not necessary to change anything here. + +.. toctree:: + :maxdepth: 1 + + core/init diff --git a/package/doc/sphinx/source/documentation_pages/overview.rst b/package/doc/sphinx/source/documentation_pages/overview.rst index bc8c352ff2f..f0afff09433 100644 --- a/package/doc/sphinx/source/documentation_pages/overview.rst +++ b/package/doc/sphinx/source/documentation_pages/overview.rst @@ -8,15 +8,15 @@ treats atoms, groups of atoms, trajectories, etc as different objects. Each object has a number of operations defined on itself (also known as "methods") and also contains values describing the object ("attributes"). For example, a -:class:`~MDAnalysis.core.AtomGroup.AtomGroup` object has a -:meth:`~MDAnalysis.core.AtomGroup.AtomGroup.center_of_mass` method that +:class:`~MDAnalysis.core.groups.AtomGroup` object has a +:meth:`~MDAnalysis.core.groups.AtomGroup.center_of_mass` method that returns the center of mass of the group of atoms. It also contains an -attribute called :attr:`~MDAnalysis.core.AtomGroup.AtomGroup.residues` +attribute called :attr:`~MDAnalysis.core.groups.AtomGroup.residues` that lists all the residues that belong to the group. Using methods -such as :meth:`~MDAnalysis.core.AtomGroup.AtomGroup.select_atoms` +such as :meth:`~MDAnalysis.core.groups.AtomGroup.select_atoms` (which uses `CHARMM-style`_ atom :ref:`selection-commands-label`) one can create new objects (in this case, another -:class:`~MDAnalysis.core.AtomGroup.AtomGroup`). +:class:`~MDAnalysis.core.groups.AtomGroup`). 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 @@ -70,7 +70,7 @@ online help), do analysis and immediately plot results. The examples in this man are typically run from an interactive :program:`ipython` session. Invariably, a MDAnalysis session starts with loading data into the -:class:`~MDAnalysis.core.AtomGroup.Universe` class (which can be accessed +:class:`~MDAnalysis.core.universe.Universe` class (which can be accessed as :class:`MDAnalysis.Universe`):: from MDAnalysis import * @@ -98,17 +98,17 @@ trajectory is loaded with :: (The ``>>>`` signs are the Python input prompt and are not to be typed; they just make clear in the examples what is input and what is output.) -The :class:`~MDAnalysis.core.AtomGroup.Universe` contains a number of important attributes, +The :class:`~MDAnalysis.core.universe.Universe` contains a number of important attributes, the most important ones of which is -:attr:`~MDAnalysis.core.AtomGroup.Universe.atoms`:: +:attr:`~MDAnalysis.core.universe.Universe.atoms`:: >>> print u.atoms :attr:`Universe.atoms` is a -:class:`~MDAnalysis.core.AtomGroup.AtomGroup` and can be thought of as -list consisting of :class:`~MDAnalysis.core.AtomGroup.Atom` -objects. The :class:`~MDAnalysis.core.AtomGroup.Atom` is the +:class:`~MDAnalysis.core.groups.AtomGroup` and can be thought of as +list consisting of :class:`~MDAnalysis.core.groups.Atom` +objects. The :class:`~MDAnalysis.core.groups.Atom` is the elementary and fundamental object in MDAnalysis. The :attr:`MDAnalysis.Universe.trajectory` attribute gives access to the coordinates @@ -118,7 +118,7 @@ over time:: < DCDReader '/..../MDAnalysis/tests/data/adk_dims.dcd' with 98 frames of 3341 atoms (0 fixed) > Finally, the :meth:`MDAnalysis.Universe.select_atoms` method generates a new -:class:`~MDAnalysis.core.AtomGroup.AtomGroup` according to a selection criterion +:class:`~MDAnalysis.core.groups.AtomGroup` according to a selection criterion >>> calphas = u.select_atoms("name CA") >>> print calphas diff --git a/package/doc/sphinx/source/documentation_pages/selections.rst b/package/doc/sphinx/source/documentation_pages/selections.rst index b41f8d02376..b5376787363 100644 --- a/package/doc/sphinx/source/documentation_pages/selections.rst +++ b/package/doc/sphinx/source/documentation_pages/selections.rst @@ -5,7 +5,7 @@ Selection Commands ==================== -Once you have the :meth:`~MDAnalysis.core.AtomGroup.Universe` object, you can +Once you have the :meth:`~MDAnalysis.core.universe.Universe` object, you can select atoms (using a syntax very similar to `CHARMM's atom selection syntax`_):: @@ -14,12 +14,14 @@ syntax`_):: .. _`CHARMM's atom selection syntax`: http://www.charmm.org/documentation/c37b1/select.html -The :meth:`~MDAnalysis.core.AtomGroup.Universe.select_atoms` of a -:class:`~MDAnalysis.core.AtomGroup.Universe` returns a -:class:`~MDAnalysis.core.AtomGroup.AtomGroup`, so you can use all the methods -defined for AtomGroups on them. Selections always return an :class:`AtomGroup` with -atoms sorted according to their index in the topology (this is to ensure that -there aren't any duplicates, which can happen with complicated selections). +The :meth:`~MDAnalysis.core.groups.AtomGroup.select_atoms` method of a +:class:`~MDAnalysis.core.groups.AtomGroup` or a +:class:`~MDAnalysis.core.universe.Universe` returns a +:class:`~MDAnalysis.core.groups.AtomGroup`, so you can use all the methods +defined for AtomGroups on them. Selections always return an +:class:`~MDAnalysis.core.groups.AtomGroup` with atoms sorted according to their +index in the topology (this is to ensure that there are not any duplicates, +which can happen with complicated selections). One can group subselections using parentheses:: @@ -39,8 +41,8 @@ The following describes all selection keywords currently understood by the selection parser. The following applies to all selections: * Keywords are case sensitive. -* Atoms are automatically sequentially ordered in a resulting selection - (see notes below on :ref:`ordered-selections-label` for how to circumvent this if +* Atoms are automatically sequentially ordered in a resulting selection (see + notes below on :ref:`ordered-selections-label` for how to circumvent this if necessary). * Selections are parsed left to right and parentheses can be used for grouping. @@ -52,96 +54,121 @@ selection parser. The following applies to all selections: Simple selections ----------------- - protein, backbone, nucleic, nucleicbackbone - selects all atoms that belong to a standard set of residues; a protein - is identfied by a hard-coded set of residue names so it may not - work for esoteric residues. - segid *seg-name* - select by segid (as given in the topology), e.g. ``segid 4AKE`` or ``segid DMPC`` - resid *residue-number-range* - resid can take a single residue number or a range of numbers. A range - consists of two numbers separated by a colon (inclusive) such - as ``resid 1:5``. A residue number ("resid") is taken directly from the - topology. - resnum *resnum-number-range* - resnum is the canonical residue number; typically it is set to the residue id - in the original PDB structure. - resname *residue-name* - select by residue name, e.g. ``resname LYS`` - name *atom-name* - select by atom name (as given in the topology). Often, this is force - field dependent. Example: ``name CA`` (for Cα atoms) or ``name OW`` (for SPC water oxygen) - type *atom-type* - select by atom type; this is either a string or a number and depends on - the force field; it is read from the topology file (e.g. the CHARMM PSF - file contains numeric atom types). It has non-sensical values when a - PDB or GRO file is used as a topology. - atom *seg-name* *residue-number* *atom-name* - a selector for a single atom consisting of segid resid atomname, - e.g. ``DMPC 1 C2`` selects the C2 carbon of the first residue of the DMPC - segment +protein, backbone, nucleic, nucleicbackbone + selects all atoms that belong to a standard set of residues; a protein + is identfied by a hard-coded set of residue names so it may not + work for esoteric residues. + +segid *seg-name* + select by segid (as given in the topology), e.g. ``segid 4AKE`` or + ``segid DMPC`` + +resid *residue-number-range* + resid can take a single residue number or a range of numbers. A range + consists of two numbers separated by a colon (inclusive) such + as ``resid 1:5``. A residue number ("resid") is taken directly from the + topology. + +resnum *resnum-number-range* + resnum is the canonical residue number; typically it is set to the + residue id in the original PDB structure. + +resname *residue-name* + select by residue name, e.g. ``resname LYS`` + +name *atom-name* + select by atom name (as given in the topology). Often, this is force + field dependent. Example: ``name CA`` (for Cα atoms) or ``name + OW`` (for SPC water oxygen) + +type *atom-type* + select by atom type; this is either a string or a number and depends on + the force field; it is read from the topology file (e.g. the CHARMM PSF + file contains numeric atom types). It has non-sensical values when a + PDB or GRO file is used as a topology. + +atom *seg-name* *residue-number* *atom-name* + a selector for a single atom consisting of segid resid atomname, + e.g. ``DMPC 1 C2`` selects the C2 carbon of the first residue of the + DMPC segment Boolean ------- - not - all atoms not in the selection, e.g. ``not protein`` selects all atoms that aren't part of a protein - and, or - combine two selections according to the rules of boolean algebra, - e.g. ``protein and not (resname ALA or resname LYS)`` selects all atoms - that belong to a protein, but are not in a lysine or alanine residue +not + all atoms not in the selection, e.g. ``not protein`` selects all atoms + that aren't part of a protein + +and, or + combine two selections according to the rules of boolean algebra, + e.g. ``protein and not (resname ALA or resname LYS)`` selects all atoms + that belong to a protein, but are not in a lysine or alanine residue Geometric --------- - around *distance* *selection* - selects all atoms a certain cutoff away from another selection, - e.g. ``around 3.5 protein`` selects all atoms not belonging to protein - that are within 3.5 Angstroms from the protein - sphlayer *innerRadius* *externalRadius* *selection* - selects all atoms within a spherical layer centered in the center of geometry (COG) of a given selection, - e.g. ``sphlayer 2.4 6.0 ( protein and ( resid 130 or resid 80 ) )`` selects the center of geometry of protein, resid 130, resid 80 - and creates a spherical layer of inner radius 2.4 and external radius 6.0 around the COG. - sphzone *externalRadius* *selection* - selects all atoms within a spherical zone centered in the center of geometry (COG) of a given selection, - e.g. ``sphzone 6.0 ( protein and ( resid 130 or resid 80 ) )`` selects the center of geometry of protein, resid 130, - resid 80 and creates a sphere of radius 6.0 around the COG. - cylayer *innerRadius* *externalRadius* *zMax* *zMin* *selection* - selects all atoms within a cylindric layer centered in the center of geometry (COG) of a given selection, - e.g. ``cylayer 5 10 10 -8 protein`` selects the center of geometry of protein, - and creates a cylindrical layer of inner radius 5, external radius 10 centered on the COG. In z, the cylinder - extends from 10 above the COG to 8 below. Positive values for *zMin*, or negative ones for *zMax*, - are allowed. - cyzone *externalRadius* *zMax* *zMin* *selection* - selects all atoms within a cylindric zone centered in the center of geometry (COG) of a given selection, - e.g. ``cyzone 15 4 -8 protein and resid 42`` selects the center of geometry of protein and resid 42, - and creates a cylinder of external radius 15 centered on the COG. In z, the cylinder - extends from 4 above the COG to 8 below. Positive values for *zMin*, or negative ones for *zMax*, - are allowed. - .. versionchanged:: 0.10.0 - keywords *cyzone* and *cylayer* now take *zMax* and *zMin* to be relative to the COG of - *selection*, instead of absolute z-values in the box. - point *x* *y* *z* *distance* - selects all atoms within a cutoff of a point in space, make sure - coordinate is separated by spaces, e.g. ``point 5.0 5.0 5.0 3.5`` selects - all atoms within 3.5 Angstroms of the coordinate (5.0, 5.0, 5.0) - prop [abs] *property* *operator* *value* - selects atoms based on position, using *property* **x**, **y**, or - **z** coordinate. Supports the **abs** keyword (for absolute value) and - the following *operators*: **<, >, <=, >=, ==, !=**. For example, ``prop z >= 5.0`` - selects all atoms with z coordinate greater than 5.0; ``prop abs z <= 5.0`` - selects all atoms within -5.0 <= z <= 5.0. - -From version 0.6 onwards, some geometrics selections (around, sphlayer, sphzone, point) -can use a k-d tree based, fast search algorithm (about three times faster than the -previous version). However, it does not take periodicity into -account. The fast algorithm is the default for *around*. Periodicity -is only taken into account with the -:func:`~MDAnalysis.analysis.distances.distance_array` functions via a -minimum image convention (and this only works for rectangular -simulation cells). If periodic boundary conditions should be taken -into account then change the default behaviour of MDAnalysis by setting -these two flags:: +around *distance* *selection* + selects all atoms a certain cutoff away from another selection, + e.g. ``around 3.5 protein`` selects all atoms not belonging to protein + that are within 3.5 Angstroms from the protein + +sphlayer *innerRadius* *externalRadius* *selection* + selects all atoms within a spherical layer centered in the center of + geometry (COG) of a given selection, e.g., ``sphlayer 2.4 6.0 ( protein + and ( resid 130 or resid 80 ) )`` selects the center of geometry of + protein, resid 130, resid 80 and creates a spherical layer of inner + radius 2.4 and external radius 6.0 around the COG. + +sphzone *externalRadius* *selection* + selects all atoms within a spherical zone centered in the center of + geometry (COG) of a given selection, e.g. ``sphzone 6.0 ( protein and ( + resid 130 or resid 80 ) )`` selects the center of geometry of protein, + resid 130, resid 80 and creates a sphere of radius 6.0 around the COG. + +cylayer *innerRadius* *externalRadius* *zMax* *zMin* *selection* + selects all atoms within a cylindric layer centered in the center of + geometry (COG) of a given selection, e.g. ``cylayer 5 10 10 -8 + protein`` selects the center of geometry of protein, and creates a + cylindrical layer of inner radius 5, external radius 10 centered on the + COG. In z, the cylinder extends from 10 above the COG to 8 + below. Positive values for *zMin*, or negative ones for *zMax*, are + allowed. + +cyzone *externalRadius* *zMax* *zMin* *selection* + selects all atoms within a cylindric zone centered in the center of + geometry (COG) of a given selection, e.g. ``cyzone 15 4 -8 protein and + resid 42`` selects the center of geometry of protein and resid 42, and + creates a cylinder of external radius 15 centered on the COG. In z, the + cylinder extends from 4 above the COG to 8 below. Positive values for + *zMin*, or negative ones for *zMax*, are allowed. + + .. versionchanged:: 0.10.0 + keywords *cyzone* and *cylayer* now take *zMax* and *zMin* to be + relative to the COG of *selection*, instead of absolute z-values + in the box. + +point *x* *y* *z* *distance* + selects all atoms within a cutoff of a point in space, make sure + coordinate is separated by spaces, e.g. ``point 5.0 5.0 5.0 3.5`` + selects all atoms within 3.5 Angstroms of the coordinate (5.0, 5.0, + 5.0) + +prop [abs] *property* *operator* *value* + selects atoms based on position, using *property* **x**, **y**, or + **z** coordinate. Supports the **abs** keyword (for absolute value) and + the following *operators*: **<, >, <=, >=, ==, !=**. For example, + ``prop z >= 5.0`` selects all atoms with z coordinate greater than 5.0; + ``prop abs z <= 5.0`` selects all atoms within -5.0 <= z <= 5.0. + +From version 0.6 onwards, some geometric selections (around, sphlayer, +sphzone, point) can use a k-d tree based, fast search algorithm (about three +times faster than the previous version). However, it does not take periodicity +into account. The fast algorithm is the default for *around*. Periodicity is +only taken into account with the +:func:`~MDAnalysis.lib.distances.distance_array` functions via a minimum +image convention (and this only works for rectangular simulation cells). If +periodic boundary conditions should be taken into account then change the +default behaviour of MDAnalysis by setting these two flags:: MDAnalysis.core.flags['use_periodic_selections'] = True MDAnalysis.core.flags['use_KDTree_routines'] = False @@ -150,54 +177,62 @@ these two flags:: Similarity and connectivity --------------------------- - same *subkeyword* as *selection* - selects all atoms that have the same *subkeyword* value as any atom in - *selection*. Allowed *subkeyword* values are the atom properties: ``name, type, resname, resid, segid, mass, charge, radius, bfactor, resnum``, - the groups an atom belong to: ``residue, segment, fragment``, and the atom - coordinates ``x, y, z``. +same *subkeyword* as *selection* + selects all atoms that have the same *subkeyword* value as any atom in + *selection*. Allowed *subkeyword* values are the atom properties: ``name, + type, resname, resid, segid, mass, charge, radius, bfactor, resnum``, the + groups an atom belong to: ``residue, segment, fragment``, and the atom + coordinates ``x, y, z``. - byres *selection* - selects all atoms that are in the same segment and residue as - selection, e.g. specify the subselection after the byres keyword. - ``byres`` is a shortcut to ``same residue as`` +byres *selection* + selects all atoms that are in the same segment and residue as selection, + e.g. specify the subselection after the byres keyword. ``byres`` is a + shortcut to ``same residue as`` Index ----- - bynum *index-range* - selects all atoms within a range of (1-based) inclusive indices, - e.g. ``bynum 1`` selects the first atom in the universe; ``bynum 5:10`` - selects atoms 5 through 10 inclusive. All atoms in the - :class:`MDAnalysis.Universe` are consecutively numbered, and the index - runs from 1 up to the total number of atoms. +bynum *index-range* + selects all atoms within a range of (1-based) inclusive indices, + e.g. ``bynum 1`` selects the first atom in the universe; ``bynum 5:10`` + selects atoms 5 through 10 inclusive. All atoms in the + :class:`MDAnalysis.Universe` are consecutively numbered, and the index + runs from 1 up to the total number of atoms. Preexisting selections and modifiers ------------------------------------ - group *group-name* - selects the atoms in the :class:`AtomGroup` passed to the function as an - argument named *group-name*. Only the atoms common to *group-name* and the - instance :meth:`~select_atoms` was called from will be considered. - *group-name* will be included in the parsing just by comparison of atom indices. - This means that it is up to the user to make sure they were defined in an - appropriate :class:`Universe`. - - fullgroup *group-name* - just like the ``group`` keyword with the difference that all the atoms of - *group-name* are included. The resulting selection may therefore have atoms - that were initially absent from the instance :meth:`~select_atoms` was - called from. +group *group-name* + selects the atoms in the :class:`AtomGroup` passed to the function as an + argument named *group-name*. Only the atoms common to *group-name* and the + instance :meth:`~select_atoms` was called from will be considered. + *group-name* will be included in the parsing just by comparison of atom + indices. This means that it is up to the user to make sure they were + defined in an appropriate :class:`Universe`. + +fullgroup *group-name* + just like the ``group`` keyword with the difference that all the atoms of + *group-name* are included. The resulting selection may therefore have atoms + that were initially absent from the instance :meth:`~select_atoms` was + called from. + .. deprecated:: 0.11 - The use of ``fullgroup`` has been deprecated in favor of the equivalent ``global group``. - - global *selection* - by default, when issuing :meth:`~select_atoms` from an :class:`~MDAnalysis.AtomGroup.AtomGroup` - selections and subselections are returned intersected with the atoms of that instance. - Prefixing a selection term with ``global`` causes its selection to be returned in its entirety. - As an exmaple, the ``global`` keyword allows for ``lipids.select_atoms("around 10 global protein")`` --- - where ``lipids`` is a group that does not contain any proteins. Were ``global`` it absent the result - would be an empty selection since the ``protein`` subselection would itself be empty. - When issuing :meth:`~select_atoms` from a :class:`~MDAnalysis.Universe` ``global`` is ignored. + The use of ``fullgroup`` has been deprecated in favor of the equivalent + ``global group``. + +global *selection* + by default, when issuing + :meth:`~MDAnalysis.core.groups.AtomGroup.select_atoms` from an + :class:`~MDAnalysis.core.groups.AtomGroup`, selections and subselections + are returned intersected with the atoms of that instance. Prefixing a + selection term with ``global`` causes its selection to be returned in its + entirety. As an example, the ``global`` keyword allows for + ``lipids.select_atoms("around 10 global protein")`` --- where ``lipids`` is + a group that does not contain any proteins. Were ``global`` absent, the + result would be an empty selection since the ``protein`` subselection would + itself be empty. When issuing + :meth:`~MDAnalysis.core.groups.AtomGroup.select_atoms` from a + :class:`~MDAnalysis.core.universe.Universe`, ``global`` is ignored. @@ -206,21 +241,21 @@ Instant selectors For interactive work it becomes rather tedious to type common selection strings repeatedly. MDAnalysis automatically generates a number of *instant selectors* -as attributes of the :class:`~MDAnalysis.Universe` and number of other levels -of the structural hierarchy, namely for -:class:`~MDAnalysis.AtomGroup.AtomGroup`, -:class:`~MDAnalysis.AtomGroup.Residue`, -:class:`~MDAnalysis.AtomGroup.ResidueGroup`, -:class:`~MDAnalysis.AtomGroup.Segment` and -:class:`~MDAnalysis.AtomGroup.SegmentGroup`. +as attributes of the :class:`~MDAnalysis.core.universe.Universe` and number of +other levels of the structural hierarchy, namely for +:class:`~MDAnalysis.core.groups.AtomGroup`, +:class:`~MDAnalysis.core.groups.Residue`, +:class:`~MDAnalysis.core.groups.ResidueGroup`, +:class:`~MDAnalysis.core.groups.Segment` and +:class:`~MDAnalysis.core.groups.SegmentGroup`. Segment selector ---------------- - ``universe.`` or ``universe.s`` (if ** starts with a number) -- returns a :class:`~MDAnalysis.AtomGroup.Segment` -- works for :class:`~MDAnalysis.Universe` and :class:`~MDAnalysis.AtomGroup.SegmentGroup` +- returns a :class:`~MDAnalysis.core.groups.Segment` +- works for :class:`~MDAnalysis.core.universe.Universe` and :class:`~MDAnalysis.core.groups.SegmentGroup` - example >>> u.s4AKE @@ -229,8 +264,8 @@ Resid selector -------------- - ``seg.r`` selects residue with number ```` -- returns a :class:`~MDAnalysis.AtomGroup.Residue` -- works for :class:`~MDAnalysis.AtomGroup.Segment` and :class:`~MDAnalysis.AtomGroup.SegmentGroup` +- returns a :class:`~MDAnalysis.core.groups.Residue` +- works for :class:`~MDAnalysis.core.groups.Segment` and :class:`~MDAnalysis.core.groups.SegmentGroup` - example >>> u.s4AKE.r100 @@ -239,8 +274,8 @@ Residue name selector --------------------- - ``seg.`` selects residues with residue name ```` -- returns a :class:`~MDAnalysis.AtomGroup.ResidueGroup` -- works for :class:`~MDAnalysis.AtomGroup.Segment` and :class:`~MDAnalysis.AtomGroup.SegmentGroup` +- returns a :class:`~MDAnalysis.core.groups.ResidueGroup` +- works for :class:`~MDAnalysis.core.groups.Segment` and :class:`~MDAnalysis.core.groups.SegmentGroup` - examples >>> u.s4AKE.MET , , , , , ]> @@ -248,7 +283,7 @@ Residue name selector ]> >>> u.s4AKE.TRP NoDataError: No atoms defined for AtomGroup -- The result is always a :class:`~MDAnalysis.AtomGroup.ResidueGroup`; if no +- The result is always a :class:`~MDAnalysis.core.groups.ResidueGroup`; if no residues can be found then a :exc:`MDAnalysis.NoDataError` is raised. Atom name selector @@ -257,11 +292,11 @@ Atom name selector - ``g.`` selects a single atom or a group of atoms with name ```` - returns - - a :class:`~MDAnalysis.AtomGroup.Atom` if only a single atom was found, - - a :class:`~MDAnalysis.AtomGroup.AtomGroup` if more than one atom was + - a :class:`~MDAnalysis.core.groups.Atom` if only a single atom was found, + - a :class:`~MDAnalysis.core.groups.AtomGroup` if more than one atom was found, or - raises a :exc:`MDAnalysis.SelectionError` if no atom was found. -- works for any group derived from :class:`~MDAnalysis.AtomGroup.AtomGroup` +- works for any group derived from :class:`~MDAnalysis.core.groups.AtomGroup` (i.e. all the ones mentioned above) - examples >>> u.atoms.CG @@ -279,15 +314,16 @@ Atom name selector Ordered selections ================== -:meth:`~MDAnalysis.Universe.select_atoms` sorts the atoms in the -:class:`~MDAnalysis.core.AtomGroup.AtomGroup` by atom index before returning them (this is to -eliminate possible duplicates in the selection). If the ordering of atoms is -crucial (for instance when describing angles or dihedrals) or if duplicate -atoms are required then one has to concatenate multiple AtomGroups, which does -not sort them. +:meth:`~MDAnalysis.core.groups.AtomGroup.select_atoms` sorts the atoms +in the :class:`~MDAnalysis.core.groups.AtomGroup` by atom index before +returning them (this is to eliminate possible duplicates in the +selection). If the ordering of atoms is crucial (for instance when +describing angles or dihedrals) or if duplicate atoms are required +then one has to concatenate multiple AtomGroups, which does not sort +them. The most straightforward way to concatentate two AtomGroups is by using the -**+** operator:: +``+`` operator:: >>> ordered = u.select_atoms("segid DMPC and resid 3 and name P") + u.select_atoms("segid DMPC and resid 2 and name P") >>> print list(ordered) @@ -295,15 +331,15 @@ The most straightforward way to concatentate two AtomGroups is by using the < Atom 452: name 'P' of type '180' of resid 'DMPC', 2 and 'DMPC'>] A shortcut is to provide *two or more* selections to -:meth:`~MDAnalysis.Universe.select_atoms`, which then does the concatenation -automatically:: +:meth:`~MDAnalysis.core.universe.Universe.select_atoms`, which then +does the concatenation automatically:: >>> print list(universe.select_atoms("segid DMPC and resid 3 and name P", "segid DMPC and resid 2 and name P")) [< Atom 570: name 'P' of type '180' of resid 'DMPC', 3 and 'DMPC'>, < Atom 452: name 'P' of type '180' of resid 'DMPC', 2 and 'DMPC'>] -Just for comparison to show that a single selection string does not work as one -might expect:: +Just for comparison to show that a single selection string does not +work as one might expect:: # WRONG! >>> print list(universe.select_atoms("segid DMPC and ( resid 3 or resid 2 ) and name P")) diff --git a/package/doc/sphinx/source/documentation_pages/selections_modules.rst b/package/doc/sphinx/source/documentation_pages/selections_modules.rst index ada1363e777..7aaa4a0790d 100644 --- a/package/doc/sphinx/source/documentation_pages/selections_modules.rst +++ b/package/doc/sphinx/source/documentation_pages/selections_modules.rst @@ -8,7 +8,7 @@ Selection exporters The classes in this module allow writing a selection to a file that can be read by *another programme* to select the atoms in a MDAnalysis -:class:`MDAnalysis.core.AtomGroup.AtomGroup`. Such cross-package interoperability +:class:`MDAnalysis.core.groups.AtomGroup`. Such cross-package interoperability allows a user to combine their favourite tools with MDAnalysis for further visualization or simulation. diff --git a/package/doc/sphinx/source/documentation_pages/topology_modules.rst b/package/doc/sphinx/source/documentation_pages/topology_modules.rst index c5420b995c8..41fbfcab0e8 100644 --- a/package/doc/sphinx/source/documentation_pages/topology_modules.rst +++ b/package/doc/sphinx/source/documentation_pages/topology_modules.rst @@ -17,7 +17,7 @@ hence most users probably do not need to concern themselves with classes and functions described here. However, if MDAnalysis does not properly recognize a file format then a user can explicitly set the topology file format in the *topology_format* keyword argument to -:class:`~MDAnalysis.core.AtomGroup.Universe`. +:class:`~MDAnalysis.core.universe.Universe`. .. rubric:: Topology formats