.. Contains the formatted docstrings for the core modules located in 'mdanalysis/MDAnalysis/core'

.. _`Selection exporters`:

*******************
Selection exporters
*******************

The classes in this module allow writing a selection to a file that can be read by
*another program* to select the atoms in a MDAnalysis
:class:`MDAnalysis.core.groups.AtomGroup`. Such cross-package interoperability
allows a user to combine their favourite tools with MDAnalysis for further
visualization or simulation.


.. _Supported selection exporters:

.. table:: Table of supported exporters and recognized file name extensions.

   +---------------+-----------+-------+--------------------------------------------+
   |Name           | extension |  IO   | remarks                                    |
   +===============+===========+=======+============================================+
   | vmd           | tcl       | w     | VMD_ macros, available in Representations; |
   |               |           |       | module :mod:`MDAnalysis.selections.vmd`    |
   +---------------+-----------+-------+--------------------------------------------+
   | pymol         | pml       | w     | simple PyMOL_ selection string;            |
   |               | 	       |       | module :mod:`MDAnalysis.selections.pymol`  |
   +---------------+-----------+-------+--------------------------------------------+
   | gromacs       | ndx       | w     | Gromacs_ index file;                       |
   |               |           |       | module :mod:`MDAnalysis.selections.gromacs`|
   +---------------+-----------+-------+--------------------------------------------+
   | charmm        | str       | w     | CHARMM_ selection of individual atoms;     |
   |               |           |       | module :mod:`MDAnalysis.selections.charmm` |
   +---------------+-----------+-------+--------------------------------------------+
   | jmol          | spt       | w     | Jmol_ selection commands;                  |
   |               |           |       | module :mod:`MDAnalysis.selections.jmol`   |
   +---------------+-----------+-------+--------------------------------------------+

How to write selections
=======================

Single AtomGroup
----------------

The typical situation is that one has an
:class:`~MDAnalysis.core.groups.AtomGroup` and wants to work with the
same selection of atoms in a different package, for example, to
visualize the atoms in VMD_. First create an :class:`AtomGroup` (named
``g`` in the example below) and then use its
:class:`~MDAnalysis.core.groups.AtomGroup.write` method with the
appropriate *file extension* (see :ref:`Supported selection
exporters` for the recognized *extension*)::

  g = u.select_atoms('protein")
  g.write("selections.vmd", name="mda_protein")

In VMD_, sourcing the file ``selections.vmd`` (written in Tcl) defines
the "macro" ``mda_protein`` that contains the atom indices to select

.. code-block:: tcl

   source selection.vmd
   set sel [atomselect top mda_mdanalysis]

and in the GUI the macro appears in the :menuselection:`Graphics -->
Representations` window in the list :guilabel:`Selections: Singlewords` as
"mda_protein".


Multiple selections
-------------------

The :class:`~MDAnalysis.core.groups.AtomGroup.write` method can take
additional keyword arguments, including ``mode``. The default is
``mode="w"``, which will overwrite the provided file. If ``mode="a"``
then the selection is *appended* to the file. 

Alternatively, one may use the
:class:`~MDAnalysis.selections.base.SelectionWriter` itself as a
context manager and write each :class:`AtomGroup` inside the
context. For example, to write multiple groups that were selected to
mark different parts of a lipid bilayer to Gromacs_ index file named
"leaflets.ndx"::

   with mda.selections.gromacs.SelectionWriter('leaflets.ndx', mode='w') as ndx:
       ndx.write(upper_saturated, name='upper_sat')
       ndx.write(lower_saturated, name='lower_sat')
       ndx.write(upper_unsaturated, name='upper_unsat')
       ndx.write(lower_unsaturated, name='lower_unsat')

There is a separate :class:`SelectionWriter` for each format, as
described next.


Selection writers
=================

There exist different :class:`~MDAnalysis.selections.base.SelectionWriterBase`
classes for different packages. The
:func:`~MDAnalysis.selections.get_writer` function can automatically pick
the appropriate one, based on the file name extension in the :ref:`Supported
selection exporters`.

.. autofunction:: MDAnalysis.selections.get_writer


.. rubric:: Formats

Each module implements a :class:`SelectionWriter` for a specific format.

.. toctree::
   :maxdepth: 1

   selections/vmd
   selections/pymol
   selections/gromacs
   selections/charmm
   selections/jmol
   selections/base

.. _CHARMM: http://www.charmm.org
.. _Gromacs: http://www.gromacs.org
.. _VMD: http://www.ks.uiuc.edu/Research/vmd/
.. _PyMOL: http://www.pymol.org
.. _Jmol: http://wiki.jmol.org/
