build: switch to conda dssp installation

.github/actions/install-python-and-package/action.yml

@@ -1,6 +1,6 @@
-name: "Install Python and deeprank2"
+name: "Install Python and DeepRank2"
 
-description: "Installs Python, updates pip and installs deeprank2 together with its dependencies."
+description: "Installs Python, updates pip and installs DeepRank2 together with its dependencies."
 
 inputs:
   python-version:
@@ -27,8 +27,10 @@ runs:
       with:
         update-conda: true
         python-version: ${{ inputs.python-version }}
-        conda-channels: anaconda
-    - run: conda --version
+        conda-channels: pytorch, pyg, bioconda, defaults, sbl, conda-forge
+    - run: |
+        conda --version
+        conda env list
       shell: bash {0}
     - name: Python info
       shell: bash -e {0}
@@ -41,16 +43,16 @@ runs:
         CMAKE_INSTALL_PREFIX: .local
       if: runner.os == 'Linux'
       run: |
-        # Install dependencies not handled by setuptools
+        # Install deeprank2 conda dependencies
         ## DSSP
-        sudo apt-get install -y dssp
+        conda install -c sbl dssp>=4.2.2.1
         ## MSMS
-        conda install -c bioconda msms
+        conda install -c bioconda msms>=2.6.1
         ## PyTorch, PyG, PyG adds
         ### Installing for CPU only on the CI
-        conda install pytorch==2.0.1 torchvision==0.15.2 torchaudio==2.0.2 -c pytorch
-        pip install torch_geometric==2.3.1
-        pip install torch_scatter torch_sparse torch_cluster torch_spline_conv -f https://data.pyg.org/whl/torch-$(python3 -c "import torch; print(torch.__version__)")+cpu.html
+        conda install pytorch=2.1.1 torchvision=0.16.1 torchaudio=2.1.1 cpuonly=2.0.* -c pytorch
+        conda install pyg=2.4.0 -c pyg
+        pip install torch_scatter==2.1.2 torch_sparse==0.6.18 torch_cluster==1.6.3 torch_spline_conv==1.2.2 -f https://data.pyg.org/whl/torch-2.1.0+cpu.html
     - name: Install dependencies on MacOS
       shell: bash {0}
       env:
@@ -59,26 +61,7 @@ runs:
       run: |
         # Install dependencies not handled by setuptools
         ## DSSP
-        git clone https://github.com/PDB-REDO/libcifpp.git --recurse-submodules
-        cd libcifpp
-        cmake -S . -B build -DCMAKE_INSTALL_PREFIX=$HOME/.local -DCMAKE_BUILD_TYPE=Release
-        cmake --build build
-        cmake --install build
-        #######
-        git clone https://github.com/mhekkel/libmcfp.git
-        cd libmcfp
-        mkdir build
-        cd build
-        cmake ..
-        cmake --build .
-        cmake --install .
-        #######
-        git clone https://github.com/PDB-REDO/dssp.git
-        cd dssp
-        mkdir build
-        cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
-        cmake --build build
-        cmake --install build
+        conda install -c sbl dssp>=4.2.2.1
         ## MSMS
         cd /tmp/
         wget http://mgltools.scripps.edu/downloads/tars/releases/MSMSRELEASE/REL2.6.1/msms_i86Linux2_2.6.1.tar.gz

.github/workflows/coveralls.yml

@@ -46,7 +46,7 @@ jobs:
           python-version: ${{ matrix.python-version }}
           extras-require: test
       - name: Run unit tests with coverage
-        run: pytest --cov --cov-append --cov-report xml --cov-report term --cov-report html
+        run: pytest --cov --cov-append --cov-report xml --cov-fail-under=80 --cov-report term --cov-report html
       - name: Coveralls
         env:
           GITHUB_TOKEN: ${{ secrets.github_token }}

Dockerfile

@@ -0,0 +1,32 @@
+# Pull base image
+FROM --platform=linux/x86_64 condaforge/miniforge3:23.3.1-1
+
+# Add files
+ADD ./tutorials /home/deeprank2/tutorials 
+ADD ./env/environment.yml /home/deeprank2
+ADD ./env/requirements.txt /home/deeprank2
+
+# Install
+RUN \
+  apt update -y && \
+  apt install unzip -y && \
+  ## GCC
+  apt install -y gcc && \
+  ## Conda and pip deps
+  mamba env create -f /home/deeprank2/environment.yml && \
+  ## Get the data for running the tutorials
+  if [ -d "/home/deeprank2/tutorials/data_raw" ]; then rm -Rf /home/deeprank2/tutorials/data_raw; fi && \
+  if [ -d "/home/deeprank2/tutorials/data_processed" ]; then rm -Rf /home/deeprank2/tutorials/data_processed; fi && \
+  wget https://zenodo.org/records/8349335/files/data_raw.zip && \
+  unzip data_raw.zip -d data_raw && \
+  mv data_raw /home/deeprank2/tutorials
+
+# Activate the environment
+RUN echo "source activate deeprank2" > ~/.bashrc
+ENV PATH /opt/conda/envs/deeprank2/bin:$PATH
+
+# Define working directory
+WORKDIR /home/deeprank2
+
+# Define default command
+CMD ["jupyter", "notebook", "--ip=0.0.0.0", "--NotebookApp.token=''","--NotebookApp.password=''", "--allow-root"]

README.md

@@ -1,4 +1,4 @@
-# Deeprank2
+# DeepRank2
 
 |     Badges     |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 | :------------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -34,54 +34,100 @@ DeepRank2 extensive documentation can be found [here](https://deeprank2.rtfd.io/
 
 ## Table of contents
 
-- [Deeprank2](#deeprank2)
+- [DeepRank2](#deeprank2)
   - [Overview](#overview)
   - [Table of contents](#table-of-contents)
-  - [Installation](#installation)
-    - [Dependencies](#dependencies)
-  - [Deeprank2 Package](#deeprank2-package)
-    - [Test installation](#test-installation)
-    - [Contributing](#contributing)
-    - [Data generation](#data-generation)
-    - [Datasets](#datasets)
-      - [GraphDataset](#graphdataset)
-      - [GridDataset](#griddataset)
-    - [Training](#training)
+  - [Installations](#installations)
+    - [Containerized Installation](#containerized-installation)
+    - [Local/remote installation](#localremote-installation)
+      - [Non-pythonic dependencies](#non-pythonic-dependencies)
+      - [Pythonic dependencies](#pythonic-dependencies)
+      - [Deeprank2 Package](#deeprank2-package)
+      - [Test installation](#test-installation)
+  - [Contributing](#contributing)
+  - [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)
 
-## Installation
+## Installations
 
 The package officially supports ubuntu-latest OS only, whose functioning is widely tested through the continuous integration workflows.
 
-### Dependencies
+You can either install DeepRank2 in a [dockerized container](#containerized-installation), which will allow you to run our [tutorial notebooks](https://github.com/DeepRank/deeprank2/tree/main/tutorials), or you can [install the package locally](#localremote-installation).
 
-Before installing deeprank2 you need to install some dependencies. We advise to use a [conda environment](https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html) with Python >= 3.10 installed. The following dependency installation instructions are updated as of 14/09/2023, but in case of issues during installation always refer to the official documentation which is linked below:
+### Containerized Installation 
 
-- [MSMS](https://anaconda.org/bioconda/msms): `conda install -c bioconda msms`.
-  - [Here](https://ssbio.readthedocs.io/en/latest/instructions/msms.html) for MacOS with M1 chip users.
-- [PyTorch](https://pytorch.org/get-started/locally/)
-  - We support torch's CPU library as well as CUDA.
-  - Currently, the package is tested using [PyTorch 2.0.1](https://pytorch.org/get-started/previous-versions/#v201).
-- [PyG](https://pytorch-geometric.readthedocs.io/en/latest/install/installation.html) and its optional dependencies: `torch_scatter`, `torch_sparse`, `torch_cluster`, `torch_spline_conv`.
-- [DSSP 4](https://swift.cmbi.umcn.nl/gv/dssp/)
-  - Check if `dssp` is installed: `dssp --version`. If this gives an error or shows a version lower than 4:
-    - on ubuntu 22.04 or newer: `sudo apt-get install dssp`. If the package cannot be located, first run `sudo apt-get update`.
-    - on older versions of ubuntu or on mac or lacking sudo priviliges: install from [here](https://github.com/pdb-redo/dssp), following the instructions listed. Alternatively, follow [this](https://github.com/PDB-REDO/libcifpp/issues/49) thread.
-- [GCC](https://gcc.gnu.org/install/)
-  - Check if gcc is installed: `gcc --version`. If this gives an error, run `sudo apt-get install gcc`.
-- For MacOS with M1 chip users only install [the conda version of PyTables](https://www.pytables.org/usersguide/installation.html).
+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. After having cloned the repository and installed [Docker](https://docs.docker.com/engine/install/), run the following commands (you may need to have sudo permission) from the root of the repository.
 
-## Deeprank2 Package
+Build the Docker image:
 
-Once the dependencies are installed, you can install the latest stable release of deeprank2 using the PyPi package manager:
+```bash
+docker build -t deeprank2 .
+```
+
+Run the Docker container:
+
+```bash
+docker run -p 8888:8888 deeprank2
+```
+
+This assumes that your application inside the container is listening on port 8888, and you want to map it to port 8888 on your host machine. Open a browser and go to `http://localhost:8888` to access the application running inside the Docker container and run the tutorials' notebooks.
+
+More details about the tutorials' content 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, 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 to fully leverage its capabilities.
+
+After running the tutorials, you may want to remove the (quite large) Docker image from your machine. In this case, remember to [stop the container](https://docs.docker.com/engine/reference/commandline/stop/) and 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/). 
+
+### Local/remote installation
+
+#### Non-pythonic dependencies
+
+Instructions are up to date as of 19 Jan 2024.
+
+Before installing DeepRank2 you need to install some dependencies:
+
+*  [GCC](https://gcc.gnu.org/install/)
+    * Check if gcc is installed: `gcc --version`. If this gives an error, run `sudo apt-get install gcc`. 
+
+#### Pythonic dependencies
+
+Instructions are up to date as of 19 Jan 2024.
+
+Then, you can use the YML file we provide for creating a [conda environment](https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html) containing the latest stable release of the package and all the other necessary conda and pip dependencies (CPU only, Python 3.10):
+
+```bash
+# Ensure you are in your base environment
+conda activate
+# Create the environment
+conda env create -f env/environment.yml
+# Activate the environment
+conda activate deeprank2
+```
+
+Alternatively, if you are a MacOS user, if the YML file installation is not successfull, or if you want to use CUDA or Python 3.11, you can install each dependency separately, and then the latest stable release of the package using the PyPi package manager. Also in this case, we advise to use a [conda environment](https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html). In case of issues during installation, please refer to the official documentation for each package (linked below), as our instructions may be out of date:
+
+*  [DSSP 4](https://anaconda.org/sbl/dssp): `conda install -c sbl dssp`.
+*  [MSMS](https://anaconda.org/bioconda/msms): `conda install -c bioconda msms`.
+    * [Here](https://ssbio.readthedocs.io/en/latest/instructions/msms.html) for MacOS with M1 chip users.
+*  [PyTorch](https://pytorch.org/get-started/locally/)
+    * We support torch's CPU library as well as CUDA.
+    * Currently, the package is tested using [PyTorch 2.0.1](https://pytorch.org/get-started/previous-versions/#v201).   
+*  [PyG](https://pytorch-geometric.readthedocs.io/en/latest/install/installation.html) and its optional dependencies: `torch_scatter`, `torch_sparse`, `torch_cluster`, `torch_spline_conv`.
+*  For MacOS with M1 chip users only install [the conda version of PyTables](https://www.pytables.org/usersguide/installation.html).
+
+#### Deeprank2 Package
+
+Finally do:
 
 ```bash
 pip install deeprank2
 ```
 
-Alternatively, get all the new developments by cloning the repo and installing the editable version of the package with:
+Alternatively, get the latest updates by cloning the repo and installing the editable version of the package with:
 
 ```bash
 git clone https://github.com/DeepRank/deeprank2
@@ -91,22 +137,21 @@ pip install -e .'[test]'
 
 The `test` extra is optional, and can be used to install test-related dependencies useful during the development.
 
-### Test installation
+#### Test installation
 
-If you have installed the package from a cloned repository (second option above), you can check that all components were installed correctly, using pytest.
+If you have installed the package from a cloned repository (the latter option above), you can check that all components were installed correctly, using pytest (run `pip install pytest` if you did not install it above).
 The quick test should be sufficient to ensure that the software works, while the full test (a few minutes) will cover a much broader range of settings to ensure everything is correct.
 
 Run `pytest tests/test_integration.py` for the quick test or just `pytest` for the full test (expect a few minutes to run).
 
-### Contributing
+## Contributing
 
 If you would like to contribute to the package in any way, please see [our guidelines](CONTRIBUTING.rst).
 
-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.
+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`.
 
@@ -189,11 +234,11 @@ hdf5_paths = queries.process(
     grid_map_method = MapMethod.GAUSSIAN)
 ```
 
-### Datasets
+## Datasets
 
 Data can be split in sets implementing custom splits according to the specific application. Assuming that the training, validation and testing ids have been chosen (keys of the HDF5 file/s), then the `DeeprankDataset` objects can be defined.
 
-#### GraphDataset
+### GraphDataset
 
 For training GNNs the user can create a `GraphDataset` instance:
 
@@ -227,7 +272,7 @@ dataset_test = GraphDataset(
 )
 ```
 
-#### GridDataset
+### GridDataset
 
 For training CNNs the user can create a `GridDataset` instance:
 
@@ -259,7 +304,7 @@ dataset_test = GridDataset(
 )
 ```
 
-### Training
+## Training
 
 Let's define a `Trainer` instance, using for example of the already existing `GINet`. Because `GINet` is a GNN, it requires a dataset instance of type `GraphDataset`.
 

docs/features.md

@@ -4,7 +4,9 @@ Features implemented in the code-base are defined in `deeprank2.feature` subpack
 
 ## Custom features
 
-Users can add custom features by creating a new module and placing it in `deeprank2.feature` subpackage. One requirement for any feature module is to implement an `add_features` function, as shown below. This will be used in `deeprank2.models.query` to add the features to the nodes or edges of the graph.
+Users can add custom features by cloning the repository, creating a new module and placing it in `deeprank2.feature` subpackage. The custom features can then be used by installing the package in editable mode (see [here](https://deeprank2.readthedocs.io/en/latest/installation.html#install-deeprank2) for more details). We strongly recommend submitting a pull request (PR) to merge the new feature into the official repository.
+
+One requirement for any feature module is to implement an `add_features` function, as shown below. This will be used in `deeprank2.models.query` to add the features to the nodes or edges of the graph.
 
 ```python
 
@@ -20,7 +22,60 @@ def add_features(
     pass
 ```
 
-The following is a brief description of the features already implemented in the code-base, for each features' module.
+Additionally, the nomenclature of the custom feature should be added in `deeprank2.domain.edgestorage` or `deeprank2.domain.nodestorage`, depending on which type of feature it is. 
+
+As an example, this is the implementation of the node feature `res_type`, which represents the one-hot encoding of the amino acid residue and is defined in `deeprank2.features.components` module:
+
+```python
+from deeprank2.domain import nodestorage as Nfeat
+from deeprank2.molstruct.atom import Atom
+from deeprank2.molstruct.residue import Residue, SingleResidueVariant
+from deeprank2.utils.graph import Graph
+
+def add_features(
+    pdb_path: str, graph: Graph,
+    single_amino_acid_variant: Optional[SingleResidueVariant] = None
+    ):
+
+    for node in graph.nodes:
+        if isinstance(node.id, Residue):
+            residue = node.id
+        elif isinstance(node.id, Atom):
+            atom = node.id
+            residue = atom.residue
+        else:
+            raise TypeError(f"Unexpected node type: {type(node.id)}")
+
+        node.features[Nfeat.RESTYPE] = residue.amino_acid.onehot
+```
+
+`RESTYPE` is the name of the variable assigned to the feature `res_type` in `deeprank2.domain.nodestorage`. In order to use the feature from DeepRank2 API, its module needs to be imported and specified during the queries processing:
+
+```python
+from deeprank2.features import components
+
+feature_modules = [components]
+
+# Save data into 3D-graphs only
+hdf5_paths = queries.process(
+    "<output_folder>/<prefix_for_outputs>",
+    feature_modules = feature_modules)
+```
+
+Then, the feature `res_type` can be used from the DeepRank2 datasets API:
+
+```python
+from deeprank2.dataset import GraphDataset
+
+node_features = ["res_type"]
+
+dataset = GraphDataset(
+    hdf5_path = hdf5_paths,
+    node_features = node_features
+)
+```
+
+The following is a brief description of the features already implemented in the code-base, for each features' module. 
 
 ## Default node features