.. |organization| replace:: scipion-chem
.. |repository| replace:: scipion-chem

.. figure:: ../../../_static/images/logo.png
  :alt: pwchem logo

.. _pwchem-index:

###############################################################
scipion-chem
###############################################################
`scipion-chem <https://github.com/scipion-chem/scipion-chem>`_ is the core plugin for Virtual Drug Screening (VDS) in
the Scipion platform (the rest of scipion-chem-\* plugins). It is designed to manage and make interoperable all the the 
satellite plugins (Autodock, fpocket,...). It also includes several tools for:

- Managing small molecules, protein structures or molecular dynamics simulations.
- Consensus tools that extract the most relevant results from protein pocket search and docking.
- Visualization of the results for each of the VDS steps.
- Filter and operate the different sets obtained at each step of the workflow.

To do so, scipion-chem automatically installs several util third-party software for the management and visualization of the
tasks in a typical bioinformatics and VDS workflow. These include:

  - `OpenBabel <https://github.com/openbabel/openbabel>`_ and `RDKit <https://github.com/rdkit/rdkit>`_: the main small molecule handlers and converters.
  - `MGLTools <https://ccsb.scripps.edu/mgltools/>`_: utadditional utils for small molecules, docking, ... (includes `AutoDockTools <https://autodocksuite.scripps.edu/adt/>`_).
  - `JChemPaint <https://jchempaint.github.io/>`_: Java program to manually draw small molecules.
  - `Pymol <https://pymol.org/2/>`_: main viewer of Scipion Chem for small molecules and structures.
  - `VMD <https://www.ks.uiuc.edu/Research/vmd/>`_: secondary viewer of Scipion-Chem for structures and Molecular Dynamics.
  - `AliView <https://github.com/AliView/AliView>`_: main viewer for sequences.
  - `PLIP <https://github.com/pharmai/plip>`_: specialized viewer for docking interactions in `Pymol <https://pymol.org/2/>`_.

These programs are managed through conda environments, which also includes different util Python modules.

==========================================
Installation
==========================================
A) Requirements
~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: ../../templates/plugins/installation/scipion3-requirement.rst

B) Installation steps
~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: ../../templates/plugins/installation/installation-steps.rst
.. include:: ../../templates/plugins/installation/only-devel.rst

C) Packages & enviroments
~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: ../../templates/plugins/installation/packages-header.rst

- rdkit-``version``
- shape-it-``version``
- mgltools-``version``
- jchempaint-``version``
- pymol-``version``
- aliview-``version``
- vmd-``version``
- mdtraj-``version``

.. include:: ../../templates/plugins/installation/packages-footer.rst

**TODO: COMPLETE THIS PART**

The code inside this plugin also includes the python objects, viewers, wizards and other
utils for the rest of the scipion-chem plugins. We give these python objects special importance since the
interoperability of scipion-chem relies on them.

==========================================
Protocols
==========================================
scipion-chem includes around 40 different protocols subdivided in 4 groups of protocols according to their function:

.. note::
   The user will notice that many protocols have a wand icon next to some of the parameters. 
   We call this button ``wizard`` and they are designed to help the user to use the protocol.
   
   One of the most common types of wizard will help the user to fill a parameter with the proper string.
   
   We strongly recommend to use the wizards to fill these parameters (for some protocols, it is even compulsory), 
   since inappropriate use of the parameters might lead the protocol to fail.

A) General
~~~~~~~~~~~~~~~~~~~~~~~~~~~
It includes protocols for managing the objects or files generated by Scipion.

- :ref:`pwchem-convert-structure`: Converts the format of the files stored for a set of Small Molecules, an Atom Structure or a Molecular dynamics system.
- :ref:`pwchem-operate-set`: Includes several functionalities to modify any Scipion Set inside the project.
- :ref:`pwchem-add-attribute`: Allows the user to add an attribute to an item or set object inside Scipion.
- :ref:`pwchem-export-csv`: Allows the user to export the SQLite table of a set as a CSV file, containing the values of each attribute for each column and each item in a row.

B) Database
~~~~~~~~~~~~~~~~~~~~~~~~~~~
It includes protocols related to the main databases for protein sequences, structures or small molecules.

- :ref:`pwchem-import-database-ids`: Imports a set of database IDs from a file and stores them as a Scipion object.
- :ref:`pwchem-identify-ligands`: Tries to identify a set of Small Molecules based on the `SMILES <https://es.wikipedia.org/wiki/SMILES>`_ string for each of them.
- :ref:`pwchem-uniprot-crossref`: Searches in the `UniProt <https://www.uniprot.org/>`_ cross reference database for related entries of a set of UniProt IDs for specified databases.
- :ref:`pwchem-zinc-filter`: Filters a ``SetOfSmallMolecules`` by the presence/absence of each of the molecules in the specified ZINC subset(s).
- :ref:`pwchem-fetch-ligands`: Extracts the ligands related to a ``SetOfDatabaseIDs``.

C) Sequence
~~~~~~~~~~~~~~~~~~~~~~~~~~~
It incorporates protocols for managing biological sequences, including tools for defining sequence regions of interest.

- :ref:`pwchem-import-set-of-sequences`: Imports a set of sequences from one or several fasta files or from a database like `UniProt <https://www.uniprot.org/>`_ using a ``SetOfDatabaseIDs`` as input.
- :ref:`pwchem-pairwise-alignment`: Performs a pairwise alignment using clustal omega over two input sequences.
- :ref:`pwchem-multiple-sequence-alignment`: Performs a multiple sequence alignment (MSA) over a set of input sequences.
- :ref:`pwchem-define-set-of-sequences`: Allows the user to manually build a set of small molecules from individual elements.
- :ref:`pwchem-import-variants`: Imports a set of sequence variants.
- :ref:`pwchem-generate-variant-sequences`: Generates a set of sequences from a list of specified variants from a ``SequenceVariants`` object.
- :ref:`pwchem-import-sequence-rois`: Imports a ``SetOfSequenceROIs``, meaning a set of Regions Of Interest (ROI) in a sequence.
- :ref:`pwchem-define-sequence-rois`: Defines a ``SetOfSequenceROIs`` from a ``Sequence`` or ``SequenceVariants`` object.
- :ref:`pwchem-operate-sequence-rois`: Allows the user to operate sets of sequence ROIs, similarly to the operate sets.
- :ref:`pwchem-extract-sequence-rois`: Defines a ``SetOfSequenceROIs`` from an input set of sequences based on the conservation of each position in the alignment.
- :ref:`pwchem-map-sequence-rois`: Maps a set of sequence ROIs to an atomic structure where the sequence can be mapped.

D) Virtual Drug Screening
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Main group of protocols that incorporates most of the functionalities related to the VDS workflow.

- :ref:`pwchem-import-small-molecules`: Imports a set of small molecules from one or several files or from default database libraries like `ECBL <https://www.eu-openscreen.eu/services/compound-collection/european-chemical-biology-library-ecbl-diversity-library.html>`_ or `ZINC <https://zinc.docking.org/>`_.
- :ref:`pwchem-extract-small-molecules`: Extract the small molecules present in a ``AtomStruct`` object.
- :ref:`pwchem-draw-small-molecules`: Runs `JChemPaint <https://jchempaint.github.io/>`_ java program and allows the user to draw their own molecules.
- :ref:`pwchem-openbabel-prepare-small-molecules`: Prepares a ``SetOfSmallMolecules`` using `OpenBabel <https://github.com/openbabel/openbabel>`_.
- :ref:`pwchem-rdkit-prepare-small-molecules`: Prepares a ``SetOfSmallMolecules`` using `RDKit <https://github.com/rdkit/rdkit>`_.
- :ref:`pwchem-prepare-receptor`: Provides a simple ``AtomStruct`` preparation with `BioPython <https://biopython.org/>`_ where the user can choose different cleaning options like removing waters, heteroatoms, keep only specific chains...
- :ref:`pwchem-adme-small-molecules-filter`: uses `RDKit <https://github.com/rdkit/rdkit>`_ to filter a ``SetOfSmallMolecules`` by applying the `ADME (Absortion, Distribution, Metabolism, Excretion) filter <https://en.wikipedia.org/wiki/ADME>`_ to each of the small molecules stored.
- :ref:`pwchem-pains-small-molecules-filter`: Uses `RDKit <https://github.com/rdkit/rdkit>`_ to filter a ``SetOfSmallMolecules`` by applying the `PAINS (Pan-assay interference compounds) filter <https://en.wikipedia.org/wiki/Pan-assay_interference_compounds>`_ to each of the small molecules stored.
- :ref:`pwchem-shape-small-molecules-filter`: Uses `RDKit <https://github.com/rdkit/rdkit>`_ to filter a ``SetOfSmallMolecules`` by applying shape filters to each of the small molecules stored.
- :ref:`pwchem-fingerprint-small-molecules-filter`: Uses `RDKit <https://github.com/rdkit/rdkit>`_ to filter a ``SetOfSmallMolecules`` by applying fingerprint filters to each of the small molecules stored.
- :ref:`pwchem-pharmacophore-generation`: Generate a ``Pharmacophore`` object that can be parse by `RDKit <https://github.com/rdkit/rdkit>`_ from a ``SetOfSmallMolecules``.
- :ref:`pwchem-pharmacophore-modification`: Modifies the properties of the features inside a ``Pharmacophore`` object.
- :ref:`pwchem-pharmacophore-filtering`: Uses `RDKit <https://github.com/rdkit/rdkit>`_ for filtering a ``SetOfSmallMolecules`` by matching them with a ``Pharmacophore``.
- :ref:`pwchem-define-structural-rois`: Allows the user to manually define a ``SetOfStructROIs`` from ``AtomStruct`` objects.
- :ref:`pwchem-consensus-structural-rois`: Performs a consensus operation over several ``SetOfStructROIs``, studying which of them are shared among all or a subset of the input sets.
- :ref:`pwchem-score-docking-positions`: Allows the user to rescore a ``SetOfSmallMolecules`` docked to a receptor using several `ODDT <https://github.com/oddt/oddt>`_ scoring functions.
- :ref:`pwchem-rmsd-docking`: Allows the user to calculate the RMSD between a ``SetOfSmallMolecules`` to a reference molecule docked to the same receptor.
- :ref:`pwchem-consensus-docking`: Performs a consensus operation over several docked ``SetOfSmallMolecules``, studying which positions are shared among all or a subset of the input sets.
- :ref:`pwchem-sasa-calculation`: Uses `BioPython <https://biopython.org/>`_ to calculate the `SASA <https://en.wikipedia.org/wiki/Accessible_surface_area>`_ (Solvent-Accessible Surface Area) for each residue in an ``AtomStruct``.