update docs

README.md

@@ -41,27 +41,30 @@ Main features:
 
 📣 [Discussions](https://github.com/DeepRank/deeprank2/discussions)
 
-## Table of contents
+## Table of Contents
 
 - [DeepRank2](#deeprank2)
   - [Overview](#overview)
-  - [Table of contents](#table-of-contents)
+  - [Table of Contents](#table-of-contents)
   - [Installation](#installation)
     - [Containerized Installation](#containerized-installation)
-    - [Local/remote installation](#localremote-installation)
-      - [YML file installation (recommended)](#yml-file-installation-recommended)
-      - [Manual installation (customizable)](#manual-installation-customizable)
-      - [Testing DeepRank2 installation](#testing-deeprank2-installation)
+      - [Pull and Run the Pre-build Docker Image (Recommended)](#pull-and-run-the-pre-build-docker-image-recommended)
+      - [Build the Docker Image Manually](#build-the-docker-image-manually)
+      - [Removing the Docker Image](#removing-the-docker-image)
+    - [Local/remote Installation](#localremote-installation)
+      - [YML File Installation (Recommended)](#yml-file-installation-recommended)
+      - [Manual Installation (Customizable)](#manual-installation-customizable)
+      - [Testing DeepRank2 Installation](#testing-deeprank2-installation)
   - [Contributing](#contributing)
   - [Using DeepRank2](#using-deeprank2)
-    - [Data generation](#data-generation)
+    - [Data Generation](#data-generation)
     - [Datasets](#datasets)
       - [GraphDataset](#graphdataset)
       - [GridDataset](#griddataset)
     - [Training](#training)
-      - [Run a pre-trained model on new data](#run-a-pre-trained-model-on-new-data)
-  - [Computational performances](#computational-performances)
-  - [Package development](#package-development)
+      - [Run a Pre-trained Model on New Data](#run-a-pre-trained-model-on-new-data)
+  - [Computational Performances](#computational-performances)
+  - [Package Development](#package-development)
 
 ## Installation
 
@@ -74,33 +77,59 @@ There are two ways to install DeepRank2:
 
 ### Containerized Installation
 
-In order to try out the package without worrying about your OS and without the need of installing all the required dependencies, we created a `Dockerfile` that can be used for taking care of everything in a suitable container.
+We provide a pre-built Docker image hosted on GitHub Packages, allowing you to use DeepRank2 without worrying about installing dependencies or configuring your system. This is the recommended method for trying out the package quickly.
 
-For this, you first need to install [Docker](https://docs.docker.com/engine/install/) on your system. Then run the following commands. You may need to have sudo permission for some steps, in which case the commands below can be preceded by `sudo`:
+#### Pull and Run the Pre-build Docker Image (Recommended)
+
+- Install [Docker](https://docs.docker.com/engine/install/) on your system, if not already installed.
+- Pull the latest Docker image from GitHub Packages by running the following command:
+
+```bash
+docker pull ghcr.io/deeprank/deeprank2:latest
+```
+
+- Run the container from the pulled image:
+
+```bash
+docker run -p 8888:8888 ghcr.io/deeprank/deeprank2:latest
+```
+
+- Once the container is running, open your browser and navigate to `http://localhost:8888` to access the DeepRank2 application.
+
+From here, you can use DeepRank2, including running the tutorial notebooks. More details about the tutorials can be found [here](https://github.com/DeepRank/deeprank2/blob/main/tutorials/TUTORIAL.md). Note that the Docker container downloads only the raw PDB files required for the tutorials. To generate processed HDF5 files, you will need to run the `data_generation_xxx.ipynb` notebooks. Since Docker containers may have limited memory resources, we reduce the number of data points processed in the tutorials. To fully utilize the package, consider [installing it locally](#localremote-installation).
+
+#### Build the Docker Image Manually
+
+If you prefer to build the Docker image yourself or run into issues with the pre-built image, you can manually build and run the container as follows:
+
+- Install [Docker](https://docs.docker.com/engine/install/) on your system, if not already installed.
+- Clone the DeepRank2 repository and navigate to its root directory:
 
 ```bash
-# Clone the DeepRank2 repository and enter its root directory
 git clone https://github.com/DeepRank/deeprank2
 cd deeprank2
+```
 
-# Build and run the Docker image
+- Build and run the Docker image:
+
+```bash
 docker build -t deeprank2 .
 docker run -p 8888:8888 deeprank2
 ```
 
-Next, open a browser and go to `http://localhost:8888` to access the application running inside the Docker container. From there you can use DeepRank2, e.g. to run the tutorial notebooks.
+- Once the container is running, open your browser and navigate to `http://localhost:8888` to access the DeepRank2 application.
 
-More details about the tutorials' contents can be found [here](https://github.com/DeepRank/deeprank2/blob/main/tutorials/TUTORIAL.md). Note that in the docker container only the raw PDB files are downloaded, which needed as a starting point for the tutorials. You can obtain the processed HDF5 files by running the `data_generation_xxx.ipynb` notebooks. Because Docker containers are limited in memory resources, we limit the number of data points processed in the tutorials. Please [install the package locally](#localremote-installation) to fully leverage its capabilities.
+#### Removing the Docker Image
 
-If after running the tutorials you want to remove the (quite large) Docker image from your machine, you must first [stop the container](https://docs.docker.com/engine/reference/commandline/stop/) and can then [remove the image](https://docs.docker.com/engine/reference/commandline/image_rm/). More general information about Docker can be found on the [official website docs](https://docs.docker.com/get-started/).
+If you no longer need the Docker image (which can be quite large), you can remove it after stopping the container. Follow the [container stop instructions](https://docs.docker.com/engine/reference/commandline/stop/) and [remove the image](https://docs.docker.com/engine/reference/commandline/image_rm/). For more general information on Docker, refer to the [official Docker documentation](https://docs.docker.com/get-started/).
 
-### Local/remote installation
+### Local/remote Installation
 
 Local installation is formally only supported on the latest stable release of ubuntu, for which widespread automated testing through continuous integration workflows has been set up. However, it is likely that the package runs smoothly on other operating systems as well.
 
 Before installing DeepRank2 please ensure you have [GCC](https://gcc.gnu.org/install/) installed: if running `gcc --version` gives an error, run `sudo apt-get install gcc`.
 
-#### YML file installation (recommended)
+#### YML File Installation (Recommended)
 
 You can use the provided YML file for creating a [conda environment](https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html) via [mamba](https://mamba.readthedocs.io/en/latest/installation/mamba-installation.html), containing the latest stable release of DeepRank2 and all its dependencies.
 This will install the CPU-only version of DeepRank2 on Python 3.10.
@@ -117,7 +146,7 @@ pip install deeprank2
 
 We also provide a frozen environment YML file located at `env/deeprank2_frozen.yml` with all dependencies set to fixed versions. The `env/deeprank2_frozen.yml` file provides a frozen environment with all dependencies set to fixed versions. This ensures reproducibility of experiments and results by preventing changes in package versions that could occur due to updates or modifications in the default `env/deeprank2.yml`. Use this frozen environment file for a stable and consistent setup, particularly if you encounter issues with the default environment file.
 
-#### Manual installation (customizable)
+#### Manual Installation (Customizable)
 
 If you want to use the GPUs, choose a specific python version (note that at the moment we support python 3.10 only), are a MacOS user, or if the YML installation was not successful, you can install the package manually. We advise to do this inside a [conda virtual environment](https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html).
 
@@ -143,7 +172,7 @@ pip install -e .'[test]'
 
 The `test` extra is optional, and can be used to install test-related dependencies, useful during development.
 
-#### Testing DeepRank2 installation
+#### Testing DeepRank2 Installation
 
 If you have cloned the repository, you can check that all components were installed correctly using `pytest`. We especially recommend doing this in case you installed DeepRank2 and its dependencies manually (the latter option above).
 
@@ -160,7 +189,7 @@ If you would like to contribute to the package in any way, please see [our guide
 The following section serves as a first guide to start using the package, using protein-protein Interface (PPI) queries as example. For an enhanced learning experience, we provide in-depth [tutorial notebooks](https://github.com/DeepRank/deeprank2/tree/main/tutorials) for generating PPI data, generating SVR data, and for the training pipeline.
 For more details, see the [extended documentation](https://deeprank2.rtfd.io/).
 
-### Data generation
+### Data Generation
 
 For each protein-protein complex (or protein structure containing a missense variant), a `Query` can be created and added to the `QueryCollection` object, to be processed later on. Two subtypes of `Query` exist: `ProteinProteinInterfaceQuery` and `SingleResidueVariantQuery`.
 
@@ -370,7 +399,7 @@ trainer.test()
 
 ```
 
-#### Run a pre-trained model on new data
+#### Run a Pre-trained Model on New Data
 
 If you want to analyze new PDB files using a pre-trained model, the first step is to process and save them into HDF5 files [as we have done above](#data-generation).
 
@@ -404,7 +433,7 @@ trainer.test()
 
 For more details about how to run a pre-trained model on new data, see the [docs](https://deeprank2.readthedocs.io/en/latest/getstarted.html#run-a-pre-trained-model-on-new-data).
 
-## Computational performances
+## Computational Performances
 
 We measured the efficiency of data generation in DeepRank2 using the tutorials' [PDB files](https://zenodo.org/record/8187806) (~100 data points per data set), averaging the results run on Apple M1 Pro, using a single CPU.
 Parameter settings were: atomic resolution, `distance_cutoff` of 5.5 Å, radius (for SRV only) of 10 Å. The [features modules](https://deeprank2.readthedocs.io/en/latest/features.html) used were `components`, `contact`, `exposure`, `irc`, `secondary_structure`, `surfacearea`, for a total of 33 features for PPIs and 26 for SRVs (the latter do not use `irc` features).
@@ -414,6 +443,6 @@ Parameter settings were: atomic resolution, `distance_cutoff` of 5.5 Å, radius
 | PPIs | graph only: **2.99** (std 0.23) <br />graph+grid: **11.35** (std 1.30) | graph only: **0.54** (std 0.07) <br />graph+grid: **16.09** (std 0.44) |
 | SRVs | graph only: **2.20** (std 0.08) <br />graph+grid: **2.85** (std 0.10)  | graph only: **0.05** (std 0.01) <br />graph+grid: **17.52** (std 0.59) |
 
-## Package development
+## Package Development
 
 If you're looking for developer documentation, go [here](https://github.com/DeepRank/deeprank2/blob/dev/README.dev.md).

docs/source/docking.md

@@ -1,4 +1,4 @@
-# Docking scores
+# Docking Scores
 
 The following scores have been developed for evaluating the quality of the protein-protein models produced by computational methods (docking models), and all of them compare the structural similarity between the decoys (computationally generated structures) and the experimentally solved native structures. To calculate these measures, the interface between the two interacting protein molecules is defined as any pair of heavy atoms from the two molecules within 5Å of each other.
 
@@ -11,7 +11,7 @@ The following scores have been developed for evaluating the quality of the prote
 
 See https://onlinelibrary.wiley.com/doi/abs/10.1002/prot.10393 for more details about `capri_class`, `lrmsd`, `irmsd`, and `fnat`. See https://journals.plos.org/plosone/article?id=10.1371/journal.pone.0161879 for more details about `dockq`.
 
-## Compute and add docking scores
+## Compute and Add Docking Scores
 
 The following code snippet shows an example of how to use deeprank2 to compute the docking scores for a given docking model, and how to add one of the scores (e.g., `dockq`) as a target to the already processed data.