Skip to content

clean API pages batch 1to4 #4999

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: develop
Choose a base branch
from
Open

clean API pages batch 1to4 #4999

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c0bf205
clean API pages batch 1to4
namiroues Mar 29, 2025
cff9772
Address PR review comments
namiroues Apr 2, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 18 additions & 31 deletions package/doc/sphinx/source/documentation_pages/analysis_modules.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,51 +2,40 @@

.. module:: MDAnalysis.analysis

.. _analysis-label:

****************
Analysis modules
****************

The :mod:`MDAnalysis.analysis` module contains code to carry out specific
analysis functionality for MD trajectories. It is based on the core
functionality (i.e. trajectory I/O, selections etc). The analysis modules can
be used as examples for how to use MDAnalysis but also as working code for
research projects; typically all contributed code has been used by the authors
in their own work.

Getting started with analysis
=============================
The :mod:`MDAnalysis.analysis` module provides a wide collection of analysis tools for
molecular dynamics trajectories. These modules build upon MDAnalysis core functionality
(trajectory I/O, selections, etc.) and are designed both for reuse in research workflows
and as examples of using the MDAnalysis API. Each module typically defines an analysis
class that follows a standard interface.

.. SeeAlso::
See the `User Guide Analysis section`_ for interactive examples and additional context.

The `User Guide: Analysis`_ contains extensive documentation of the analysis
capabilities with user-friendly examples.
.. _User Guide Analysis section: https://userguide.mdanalysis.org/stable/examples/analysis/README.html

.. _`User Guide: Analysis`:
https://userguide.mdanalysis.org/stable/examples/analysis/README.html

Using the analysis classes
--------------------------
Getting started with analysis
=============================

Most analysis tools in MDAnalysis are written as a single class. An analysis
usually follows the same pattern:
Most analysis tools are implemented as single classes and follow this usage pattern:

#. Import the desired module, since analysis modules are not imported
by default.
#. Initialize the analysis class instance from the previously imported module.
#. Run the analysis with the :meth:`~MDAnalysis.analysis.base.AnalysisBase.run`
method, optionally for specific trajectory slices.
#. Access the analysis from the
:attr:`~MDAnalysis.analysis.base.AnalysisBase.results` attribute
#. Import the module (e.g., :mod:`MDAnalysis.analysis.rms`).
#. Initialize the analysis class with required arguments.
#. Run the analysis with :meth:`~MDAnalysis.analysis.base.AnalysisBase.run` method.
#. Access results via the :attr:`~MDAnalysis.analysis.base.AnalysisBase.results` attribute.

.. code-block:: python

from MDAnalysis.analysis import ExampleAnalysisModule # (e.g. RMSD)

analysis_obj = ExampleAnalysisModule.AnalysisClass(universe, ...)
analysis_obj.run(start=start_frame, stop=stop_frame, step=step)
print(analysis_obj.results)


Please see the individual module documentation for any specific caveats
and also read and cite the reference papers associated with these algorithms.

Expand Down Expand Up @@ -95,10 +84,8 @@ for maximum available on your machine):
rmsd = RMSD(u, ref, select='backbone')
rmsd.run(backend='multiprocessing', n_workers=multiprocessing.cpu_count())

For now, you have to be explicit and specify both ``backend`` and ``n_workers``,
since the feature is new and there are no good defaults for it. For example,
if you specify a too big `n_workers`, and your trajectory frames are big,
you might get and out-of-memory error when executing your run.
Be explicit and specify both ``backend`` and ``n_workers``. Choosing too many
workers or using large trajectory frames may lead to an out-of-memory error.

You can also implement your own backends -- see :mod:`MDAnalysis.analysis.backends`.

Expand Down
233 changes: 31 additions & 202 deletions package/doc/sphinx/source/documentation_pages/overview.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,219 +1,48 @@
.. _overview-label:

==========================
Overview over MDAnalysis
Overview of MDAnalysis
==========================

**MDAnalysis** is a Python package that provides classes to access
data in molecular dynamics trajectories. It is object oriented so it
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.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.groups.AtomGroup.residues`
that lists all the residues that belong to the group. Using methods
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.groups.AtomGroup`).
MDAnalysis is a Python package for the analysis of molecular dynamics simulations.
It provides an object-oriented interface to molecular structures and trajectories,
with direct access to atomic coordinates as :class:`numpy.ndarray` objects for seamless
integration with `NumPy`_ and `SciPy`_.

A typical usage pattern is to iterate through a trajectory and analyze
coordinates for every frame. In the following example the end-to-end distance
of a protein and the radius of gyration of the backbone atoms are calculated::
This page gives a high-level overview of the most important public classes and modules.
For usage examples and tutorials, refer to the `User Guide`_.

import MDAnalysis as mda
from MDAnalysis.tests.datafiles import PSF,DCD # test trajectory
import numpy.linalg
u = mda.Universe(PSF,DCD) # always start with a Universe
nterm = u.select_atoms('segid 4AKE and name N')[0] # can access structure via segid (s4AKE) and atom name
cterm = u.select_atoms('segid 4AKE and name C')[-1] # ... takes the last atom named 'C'
bb = u.select_atoms('protein and backbone') # a selection (a AtomGroup)
for ts in u.trajectory: # iterate through all frames
r = cterm.position - nterm.position # end-to-end vector from atom positions
d = numpy.linalg.norm(r) # end-to-end distance
rgyr = bb.radius_of_gyration() # method of a AtomGroup; updates with each frame
print(f"frame = {ts.frame}: d = {d} Angstroem, Rgyr = {rgyr} Angstroem")
.. _User Guide: https://userguide.mdanalysis.org/stable/index.html
.. _NumPy: https://numpy.org/
.. _SciPy: https://scipy.org/

Key Classes
===========

.. _NumPy: https://numpy.org/
.. _CHARMM: http://www.charmm.org/
.. _LAMMPS: http://lammps.sandia.gov/
.. _NAMD: http://www.ks.uiuc.edu/Research/namd/
.. _Gromacs: http://www.gromacs.org/
The core of MDAnalysis revolves around the :class:`~MDAnalysis.core.universe.Universe` class,
which serves as the central data structure that loads and connects topology and coordinate data.
From a :class:`~MDAnalysis.core.universe.Universe`, users typically interact with :class:`~MDAnalysis.core.groups.AtomGroup`
objects — flexible collections of atoms that support structural selections and analysis operations. These selections
are created using `CHARMM-style`_ selection syntax via the :meth:`~MDAnalysis.core.groups.AtomGroup.select_atoms` method,
allowing users to query atoms based on names, residue numbers, segments, and more.

.. _CHARMM-style:
http://www.charmm.org/documentation/c37b1/select.html
Individual atoms are represented by the :class:`~MDAnalysis.core.groups.Atom` class, while residues and segments (or chains) are modeled using the
:class:`~MDAnalysis.core.groups.Residue` and :class:`~MDAnalysis.core.groups.Segment` classes, respectively. Together, these
classes form an intuitive, object-oriented hierarchy that makes it easy to navigate and analyze molecular systems.

.. TODO: more about philosophy etc... copy and paste from paper
.. _CHARMM-style: http://www.charmm.org/documentation/c37b1/select.html

Using MDAnalysis in python
==========================

If you've installed MDAnalysis in the standard python modules location, load
from within the interpreter::

from MDAnalysis import *

or ::

import MDAnalysis as mda

The idea behind MDAnalysis is to get trajectory data into NumPy_
:class:`numpy.ndarray` arrays, where it can then be easily manipulated using
all the power in NumPy_ and SciPy_.

MDAnalysis works well both in scripts and in interactive use. The developers
very much recommend using MDAnalysis from within the IPython_ Python shell. It
allows one to interactively explore the objects (using TAB-completion and
online help), do analysis and immediately plot results. The examples in this manual
are typically run from an interactive :program:`ipython` session.

Invariably, a MDAnalysis session starts with loading data into the
:class:`~MDAnalysis.core.universe.Universe` class (which can be accessed
as :class:`MDAnalysis.Universe`)::

import MDAnalysis as mda
universe = mda.Universe(topology, trajectory)

- The *topology* file lists the atoms and residues (and also their
connectivity). It can be a CHARMM/XPLOR/NAMD PSF file or a coordinate file
such as a Protein Databank Brookhaven PDB file, a CHARMM card coordinate file
(CRD), or a GROMOS/Gromacs GRO file.

- The *trajectory* contains a list of coordinates in the order defined in the
*topology*. It can either be a single frame (PDB, CRD, and GRO are all read)
or a time series of coordinate frames such as a CHARMM/NAMD/LAMMPS DCD
binary file, a Gromacs XTC/TRR trajectory, or a XYZ trajectory (possibly
compressed with gzip or bzip2).

For the remainder of this introduction we are using a short example trajectory
that is provided with MDAnalysis (as part of the `MDAnalysis test suite`_). The
trajectory is loaded with ::

>>> from MDAnalysis import Universe
>>> from MDAnalysis.tests.datafiles import PSF,DCD
>>> u = Universe(PSF, DCD)

(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.universe.Universe` contains a number of important attributes,
the most important ones of which is
:attr:`~MDAnalysis.core.universe.Universe.atoms`::

>>> print(u.atoms)
<AtomGroup with 3341 atoms>

:attr:`Universe.atoms` is a
: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
over time::

>>> print(u.trajectory)
< 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.groups.AtomGroup` according to a selection criterion::

>>> calphas = u.select_atoms("name CA")
>>> print(calphas)
<AtomGroup with 214 atoms>

as described in :ref:`selection-commands-label`.

.. _SciPy: http://www.scipy.org/
.. _IPython: https://ipython.org/
.. _MDAnalysis test suite: https://github.com/MDAnalysis/mdanalysis/wiki/UnitTests


Examples
========

The easiest way to get started with MDAnalysis is to read this introduction and the chapters on :ref:`topology-label` and :ref:`selection-commands-label`, then explore the package interactively in IPython_ or another interactive Python interpreter.

Included trajectories
---------------------

MDAnalysis comes with a number of real trajectories for testing. You
can also use them to explore the functionality and ensure that
everything is working properly::

import MDAnalysis as mda
from MDAnalysis.tests.datafiles import PSF,DCD, PDB,XTC
u_dims_adk = mda.Universe(PSF,DCD)
u_eq_adk = mda.Universe(PDB, XTC)

The PSF and DCD file are a closed-form-to-open-form transition of
Adenylate Kinase (from [Beckstein2009]_) and the PDB+XTC file are ten
frames from a Gromacs simulation of AdK solvated in TIP4P water with
the OPLS/AA force field.

.. [Beckstein2009] O. Beckstein, E.J. Denning, J.R. Perilla, and
T.B. Woolf. Zipping and Unzipping of Adenylate
Kinase: Atomistic Insights into the Ensemble of
Open <--> Closed Transitions. *J Mol Biol* **394**
(2009), 160--176, doi:`10.1016/j.jmb.2009.09.009`_

.. _`10.1016/j.jmb.2009.09.009`: http://dx.doi.org/10.1016/j.jmb.2009.09.009

Code snippets
-------------

The source code distribution comes with a directory `examples`_ that
contains a number of code snippets that show how to use certain
aspects of MDAnalysis.

For instance, there is code that shows how to

* fit a trajectory to a reference structure using the QCP
RMSD-alignment code in :mod:`MDAnalysis.core.qcprot`
(`rmsfit_qcp.py`_);

* do a block-averaging error analysis (`blocks.py`_);

* calculate a potential profile across a membrane (`potential_profile.py`_);

* do a native contact analysis using :mod:`MDAnalysis.analysis.contacts` (`nativecontacts.py`_)

* get the lipid composition of the individual leaflets of a bilayer
using :mod:`MDAnalysis.analysis.leaflet` (`membrane-leaflets.py`_);

* define the multimeric states of a number of transmembrane peptides
via clustering (`multimers-analysis.py`_);

* convert between trajectory formats (e.g. `dcd2xtc.py`_ or `amber2dcd.py`_)
Core modules
============

* use MDAnalysis for simple model building (`make_MthK_tetramer.py`_);
MDAnalysis is organized into several core modules that provide specialized functionality for
handling and analyzing molecular dynamics data. The :mod:`MDAnalysis.core` module defines the
essential data structures such as :class:`~MDAnalysis.core.universe.Universe`, :class:`~MDAnalysis.core.groups.AtomGroup`,
and related objects. The :mod:`MDAnalysis.analysis` module contains a collection of analysis tools for tasks like RMSD calculation,
diffusion analysis, contact maps, and more. The :mod:`MDAnalysis.selections` module implements the flexible selection language used
to query atoms based on structural properties. Finally, :mod:`MDAnalysis.topology` manages topology parsing and representation,
supporting a wide range of file formats for loading molecular structures.

and more.

.. Links to the stable git repository:

.. _examples:
https://github.com/MDAnalysis/MDAnalysisCookbook/tree/master/examples/

.. _`rmsfit_qcp.py`:
https://github.com/MDAnalysis/MDAnalysisCookbook/blob/master/examples/rmsfit_qcp.py
.. _`blocks.py`:
https://github.com/MDAnalysis/MDAnalysisCookbook/blob/master/examples/blocks.py
.. _`potential_profile.py`:
https://github.com/MDAnalysis/MDAnalysisCookbook/blob/master/examples/potential_profile.py
.. _`nativecontacts.py`:
https://github.com/MDAnalysis/MDAnalysisCookbook/blob/master/examples/nativecontacts.py
.. _`membrane-leaflets.py`:
https://github.com/MDAnalysis/MDAnalysisCookbook/blob/master/examples/membrane-leaflets.py
.. _`multimers-analysis.py`:
https://github.com/MDAnalysis/MDAnalysisCookbook/blob/master/examples/multimers-analysis.py
.. _`dcd2xtc.py`:
https://github.com/MDAnalysis/MDAnalysisCookbook/blob/master/examples/dcd2xtc.py
.. _`amber2dcd.py`:
https://github.com/MDAnalysis/MDAnalysisCookbook/blob/master/examples/amber2dcd.py
.. _`make_MthK_tetramer.py`:
https://github.com/MDAnalysis/MDAnalysisCookbook/blob/master/examples/make_MthK_tetramer.py
11 changes: 5 additions & 6 deletions package/doc/sphinx/source/documentation_pages/topology.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,11 +5,10 @@
The topology system
=====================

As shown briefly in :ref:`overview-label`, the :class:`~MDAnalysis.core.universe.Universe` class is the primary object and core interface to molecular dynamics data in MDAnalysis.
When loading topology information from a file, as with ::
See :mod:`MDAnalysis.topology` for details on topology parsing, format support, and
the :class:`~MDAnalysis.core.topology.Topology` object.

>>> from MDAnalysis import Universe
>>> from MDAnalysis.tests.datafiles import PSF
>>> u = Universe(PSF)
User-level documentation can be found in the `topology section of the User Guide`_.

.. _topology section of the User Guide: https://userguide.mdanalysis.org/stable/topology_system.html

the file is read, the contents parsed, and a :class:`~MDAnalysis.core.topology.Topology` object is constructed from these contents.
Loading