improve documentation and explain how to load GNINA models

.gitignore

@@ -128,3 +128,6 @@ nohup.out
 
 # ML Tracking
 mlruns/
+
+# macOS
+.DS_Store

docs/source/GNINA.rst

@@ -0,0 +1,102 @@
+GNINA_ Models
+=============
+
+Thanks to `Andrew McNutt`_, who converted the original Caffe_ models to PyTorch_, all GNINA_ models are available in gninatorch_.
+
+You can find more information about the Caffe_ implementation at `gnina/models`_.
+
+Loading GNINA_ Models
+---------------------
+
+The pre-trained models can be easily loaded as follows:
+
+.. code-block:: python
+
+ from gninatorch import gnina
+
+ model, ensemble: bool = setup_gnina_model(model_name)
+
+where :code:`model_name` corresponds accepts the same values as the :code:`--cnn` argument in GNINA_.
+
+:code:`ensemble` is a boolean flag that indicates whether the model is an ensemble of models or not.
+
+.. warning::
+ In contrast to GNINA_, which returns :code:`CNNscore`, the PyTorch models return :code:`log_CNNscore`.
+
+The following models are provided:
+
+* :code:`default2017` :cite:`ragoza2017protein`
+* :code:`redock_default2018` or :code:`redock_default2018_[1-4]` :cite:`francoeur2020three`
+* :code:`general_default2018` or :code:`general_default2018_[1-4]` :cite:`francoeur2020three`
+* :code:`crossdock_default2018` or :code:`crossdock_default2018_[1-4]` :cite:`francoeur2020three`
+* :code:`dense` or :code:`dense_[1-4]` :cite:`francoeur2020three`
+
+The following ensembles of models are also provided:
+
+* :code:`default` (GNINA_ default model) :cite:`mcnutt2021gnina` :cite:`francoeur2020three`
+* :code:`redock_default2018_ensemble` :cite:`francoeur2020three`
+* :code:`general_default2018_ensemble` :cite:`francoeur2020three`
+* :code:`crossdock_default2018_ensemble` :cite:`francoeur2020three`
+* :code:`dense_ensemble` :cite:`francoeur2020three`
+
+:code:`default` is the default model used by GNINA_. See :cite:`mcnutt2021gnina` for more information.
+
+.. note::
+ If you are using the pre-trained models, please cite accordingly.
+
+Building your own ensemble
+--------------------------
+
+You can build your own ensemble of models as follows:
+
+.. code-block:: python
+
+ from gninatorch import gnina
+
+ model = gnina.setup_gnina_models([model_name1, model_name2, ...])
+
+The :code:`default` model used by GNINA_ corresponds to the following ensemble:
+
+.. code-block:: python
+
+ from gninatorch import gnina
+
+ names = [
+ "dense",
+ "general_default2018_3",
+ "dense_3",
+ "crossdock_default2018",
+ "redock_default2018_2",
+ ]
+
+ model = gnina.load_gnina_models(names)
+
+The :code:`default` optimises accuracy and inference speed. See :cite:`mcnutt2021gnina` for more information.
+
+Inference with GNINA_ Models
+----------------------------
+
+Inference with the pre-trained GNINA_ models is provided by :code:`gninatorch.gnina`:
+
+.. code-block:: bash
+
+ python -m gninatorch.gnina -h
+
+.. raw:: html
+
+ <hr>
+
+.. bibliography::
+ :cited:
+
+.. _GNINA: https://github.com/gnina/gnina
+.. _conda: https://docs.conda.io/en/latest/
+.. _mamba: https://mamba.readthedocs.io/en/latest/user_guide/mamba.html
+.. _gninatorch: https://gnina-torch.readthedocs.io/en/latest/index.html
+.. _libmolgrid: https://gnina.github.io/libmolgrid/
+.. _NVIDIA: https://www.nvidia.com/
+.. _PyTorch: https://pytorch.org/
+.. _pytest: https://docs.pytest.org/en/7.1.x/contents.html
+.. _`Andrew McNutt`: https://github.com/drewnutt/
+.. _Caffe: http:https://caffe.berkeleyvision.org/
+.. _`gnina/models`: https://github.com/gnina/models

docs/source/getting_started.rst

@@ -6,6 +6,8 @@ gninatorch_ is a PyTorch_ implementation of GNINA_ scoring function, a CNN-based
 .. note::
  gninatorch_ depends on libmolgrid_, and therefore it is only available on Linux and requires a NVIDIA_ GPU.
 
+If you use gninatorch_, please consider citing the following papers: :cite:`ragoza2017protein`, :cite:`sunseri2020libmolgrid`, :cite:`francoeur2020three`, and :cite:`mcnutt2021gnina`.
+
 Installation
 ------------
 
@@ -33,54 +35,32 @@ Install gninatorch_ from source:
  python -m pip install .
 
 
-Testing the Installation
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-Run tests with pytest_ and report code coverage:
+Installation from PyPI
+~~~~~~~~~~~~~~~~~~~~~
 
 .. code-block:: bash
 
- pytest --cov=gninatorch
-
-Loading GNINA Models
---------------------
-
-Thanks to `Andrew McNutt`_, who converted the original GNINA_ Caffe_ models to PyTorch_, all GNINA_ models are available in gninatorch_.
-The pre-trained models can be easily loaded as follows:
-
-.. code-block:: python
+ python -m pip install gninatorch
 
- from gninatorch import gnina
+.. warning::
 
- model, ensemble: bool = setup_gnina_model(model_name)
+ Packages on PyPI are still WIP and should be considered experimental.
 
-where :code:`model_name` corresponds accepts the same values as the :code:`--cnn` argument in GNINA_.
+Testing
+-------
 
-For single models we have the following possibilities:
-
-* :code:`default2017` :cite:`ragoza2017protein`
-* :code:`redock_default2018` or :code:`redock_default2018_[1-4]` :cite:`francoeur2020three`
-* :code:`general_default2018` or :code:`general_default2018_[1-4]` :cite:`francoeur2020three`
-* :code:`crossdock_default2018` or :code:`crossdock_default2018_[1-4]` :cite:`francoeur2020three`
-* :code:`dense` or :code:`dense_[1-4]` :cite:`francoeur2020three`
-
-For ensembles of 5 models we have the following possibilities:
-
-* :code:`default` (GNINA_ default model) :cite:`mcnutt2021gnina` :cite:`francoeur2020three`
-* :code:`redock_default2018_ensemble` :cite:`francoeur2020three`
-* :code:`general_default2018_ensemble` :cite:`francoeur2020three`
-* :code:`crossdock_default2018_ensemble` :cite:`francoeur2020three`
-* :code:`dense_ensemble` :cite:`francoeur2020three`
+Run tests with pytest_ and report code coverage:
 
-Inference with GNINA Models
----------------------------
+.. code-block:: bash
 
-Inference with the pre-trained GNINA_ models is provided by :code:`gninatorch.gnina`:
+ pytest --cov=gninatorch
 
-.. code-block:: bash
+.. raw:: html
 
-  python -m gninatorch.gnina -h
+ <hr>
 
+.. bibliography::
+ :cited:
 
 .. _GNINA: https://github.com/gnina/gnina
 .. _conda: https://docs.conda.io/en/latest/
@@ -89,8 +69,4 @@ Inference with the pre-trained GNINA_ models is provided by :code:`gninatorch.gn
 .. _libmolgrid: https://gnina.github.io/libmolgrid/
 .. _NVIDIA: https://www.nvidia.com/
 .. _PyTorch: https://pytorch.org/
-.. _pytest: https://docs.pytest.org/en/7.1.x/contents.html
-.. _`Andrew McNutt`: https://github.com/drewnutt/
-.. _Caffe: http:https://caffe.berkeleyvision.org/
-
-.. bibliography:: references.bib
+.. _pytest: https://docs.pytest.org/en/7.1.x/contents.html

docs/source/index.rst

@@ -11,6 +11,7 @@ Welcome to gninatorch's documentation!
  :caption: Contents:
 
  getting_started
+ GNINA
  api
 
 

docs/source/references.bib

@@ -27,3 +27,13 @@ @article{ragoza2017protein
  pages = {942--957},
  year = {2017},
 }
+
+@article{sunseri2020libmolgrid,
+ title = {Libmolgrid: graphics processing unit accelerated molecular gridding for deep learning applications},
+ author = {Sunseri, Jocelyn and Koes, David R},
+ journal = {J. Chem. Inf. Model.},
+ volume = {60},
+ number = {3},
+ pages = {1079--1084},
+ year = {2020},
+}