Visualizing SILCS FragMaps
--------------------------

Whether you used the SilcsBIO GUI or the ``2c_fragmap`` command line
utility to create SILCS FragMaps from your SILCS simulation trajectories,
you will have a folder ``silcs_fragmap_<protein PDB>/maps`` that
contains SILCS grid free energy (GFE) FragMaps for you system.
SILCS FragMaps are defined using non-hydrogen atoms, and for certain solute
types (imidazole, formamide) there are multiple FragMaps. FragMaps for water
oxygen atoms (tipo) are created to identify water molecules that can be
difficult to displace. Generic FragMaps for apolar (benzene+propane),
H-bond donor (neutral H-bond donors), and H-bond acceptor (neutral
H-bond acceptors) probe types are included to simplify visual analysis.

The easiest way to visualize FragMaps is with the SilcsBio GUI. SilcsBio also 
provides convenient FragMap visualization using MOE, PyMOL, and VMD.

FragMaps in the SilcsBio GUI
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

If you have used the SilcsBio GUI to run your SILCS simulations, once the
simulations are complete, you will click the "Generate FragMap"
button to automatically create FragMaps from the SILCS simulations,
download them onto your local computer, and load them, along with the input
PDB file, for visualization. Alternatively, you can load SILCS FragMaps
from the Home page of the SilcsBio GUI:

.. figure:: images/silcs-gui-home-visualize_marked_border.png
   :width: 100%

If you are loading SILCS FragMaps from the Home page, you will be asked
to select your FragMap directory (see :ref:`File and directory selection`).
This directory has a standard name, ``silcs_fragmaps_<protein PDB>``, where
``<protein PDB>`` is the name of the input PDB file. This directory was
created on the server where you ran the SILCS jobs either when you clicked
the "Generate FragMap" button or when you ran the
``${SILCSBIODIR}/silcs/2c_fragmap prot=<protein PDB>`` command.

.. note::

   In addition to the FragMaps, the ``silcs_fragmaps_<protein PDB>``
   directory contains the PDB file used to run the SILCS simulations.
   The SilcsBio GUI will automatically detect and load this PDB file.
   Additionally, if you have run Halogen SILCS, this directory will also
   contain the Halogen SILCS FragMaps, which will be automatically
   detected and loaded by the GUI.

.. figure:: images/silcs-gui-visualize_marked_border.png
   :width: 100%

.. figure:: images/silcs-gui-visualize-hide-some_marked_border.png
   :width: 100%

.. figure:: images/silcs-gui-visualize-hide-some-adjust-gfe_marked_border.png
   :width: 100%

.. figure:: images/silcs-gui-visualize-ball-stick_marked_border.png
   :width: 100%

When adding an additional representation, the default is to apply it to
all atoms. It is possible to apply it to only a select set of atoms by
typing the atom selection in the blank box above the "cancel" and "confirm"
buttons. The selection syntax is the same as for the NGL molecular
structure viewer (see :doc:`../atom_selection`).

It is also possible to load ligands for visualization. If the ligand file
was the output of a SILCS-MC calculation, GFE values for the ligand
atoms will be embedded within that file. These values can be visualized and
their sum automatically computed by first loading the ligand file, and then
using the "GFE" tab as detailed at the end of the section
:ref:`Running SILCS-MC ligand optimization from the SilcsBio GUI`.

.. figure:: images/silcs-gui-visualize-gfe_marked_border.png
   :width: 100%


FragMaps in MOE
^^^^^^^^^^^^^^^

To visualize your SILCS FragMaps with MOE, first create FragMaps in the
MOE-readable CNS format. For this example, if your jobs ran on your
server in the directory ``~/silcsbio/projects/silcs.5tGP``:

::

   cd ~/silcsbio/projects/silcs.5tGP
   $SILCSBIODIR/silcs/2c_fragmap prot=<protein PDB> cns=true

.. note::

   This step is required ONLY for visualization with MOE. CNS
   format grid files are approximately 10x the size of the 
   default-format grid files generated and used by your SilcsBio
   software. PyMol and VMD are capable of reading the default-format
   files, and, to save disk space, CNS format files are not generated
   unless specifically specified using the above command.

Running this command will create CNS format FragMap files in the
``silcs_fragmap_<protein PDB>/maps`` directory. It will also create the
file ``silcs_fragmap_<protein PDB>/view_maps.svl``. First, copy the entire
``silcs_fragmap_<protein PDB>`` directory from your server to a convenient
location on the desktop or laptop machine where you will be doing the
visualization. For example, on Linux or MacOS, you may use a command like

::

   scp -rp silcsbio@silcsserver:~/silcsbio/projects/silcs.5tGP/silcs_fragmaps_3fly_fixed ~/Desktop

Then, use MOE to open the ``silcs_fragmap_<protein PDB>/view_maps.svl`` file
by selecting :menuselection:`File --> Open`, which will bring up the
"Open" window. In this window, browse to the ``silcs_fragmap_<protein PDB>``
directory, which, in this example, was downloaded from the server to the
Desktop of the machine on which we are doing the visualization. Click the
"CWD" button in the upper right corner to set this directory as the
"Working Folder." Then, select the ``view_maps.svl`` file and click
the "Open" button:

.. figure:: images/moe-set_cwd.png

MOE will process the ``view_maps.svl`` file to load your input
PDB structure ``<protein PDB>.pdb`` used for the SILCS simulations, the
CNS format FragMap files ``<protein PDB>.<fragmaptype>.map.cns``, and the
Exclusion Map ``<protein PDB>.excl.map.cns``. The visualization of the
FragMaps and Exclusion Map can be controlled in the "Surfaces and Maps"
window, which is also automatically loaded by ``view_maps.svl``.

.. figure:: images/moe-loaded.png

FragMaps in PyMol
^^^^^^^^^^^^^^^^^

First, copy the entire ``silcs_fragmap_<protein PDB>`` directory from your
server to a convenient location on the desktop or laptop machine where you
will be doing the visualization. For example, on Linux or MacOS, you may
use a command like

::

   scp -rp silcsbio@silcsserver:~/silcsbio/projects/silcs.5tGP/silcs_fragmaps_3fly_fixed ~/Desktop

If your operating system associates the ``.pml`` extension with PyMol, simply
double click on the ``view_maps.pml`` file in the
``silcs_fragmaps_<protein PDB>`` folder. Otherwise, open PyMol,
select :menuselection:`File --> Open...`, and open the ``view_maps.pml``
file. It is also possible to do this by typing commands into the PyMol
console. For the ``silcs_fragmaps_3fly_fixed`` example here, the commands
would be

::

   cd /Users/silcsbio/Desktop/silcs_fragmaps_3fly_fixed

which sets the working directory, and

::

   run view_maps.pml

which runs the ``view_maps.pml`` file in that directory.

.. figure:: images/pymol-console_run.png


Whichever of these three methods you use to load ``view_maps.pml``,
PyMol wil load the PDB structure ``<protein PDB>.pdb`` used for the SILCS
simulations, the FragMap files, and the Exclusion Map. The visualization of
the FragMaps and Exclusion Map can be controlled in the "PyMol FragMap
Tools" window, which is also automatically loaded by ``view_maps.pml``.

.. figure:: images/pymol-loaded.png

FragMaps in VMD
^^^^^^^^^^^^^^^

First, copy the entire ``silcs_fragmap_<protein PDB>`` directory from your
server to a convenient location on the desktop or laptop machine where you
will be doing the visualization. For example, on Linux or MacOS, you may
use a command like

::

   scp -rp silcsbio@silcsserver:~/silcsbio/projects/silcs.5tGP/silcs_fragmaps_3fly_fixed ~/Desktop

Open VMD, select :menuselection:`File --> Load Visualization State...`, and
open the ``view_maps.vmd`` file located in the ``silcs_fragmap_<protein PDB>``
directory you downloaded. A new window will pop up that says, "Select
the folder where silcs_fragmap folder is downloaded". Click the "OK"
button and select the ``silcs_fragmap_<protein PDB>`` you downloaded.

.. figure:: images/vmd-select_folder.png

.. tip::

   Be careful to select the ``silcs_fragmap_<protein PDB>`` folder and
   NOT the ``silcs_fragmap_<protein PDB>/maps`` folder.

VMD wil load the PDB structure ``<protein PDB>.pdb`` used for the SILCS
simulations, the FragMap files, and the Exclusion Map. The visualization of
the FragMaps and Exclusion Map can be controlled in the "VMD FragMap
Tools" window, which is also automatically loaded by ``view_maps.vmd``.

.. figure:: images/vmd-loaded.png