CPVSAPI

This is Rest API for conformal prediction based virtual screening. Play framework is being used for developing this API. The service is available at https://ptpaas.service.pharmb.io/

Step by step process for running CPVSAPI on a local system

Note:

For this material, we assume that Docker and Git are already installed on your local system. If you want to prepare the Docker images yourself, then first perform section 2 and then start from section 1.2. Section 3 contains some extra docker commands which can be useful if you want to test both ready made and custom build docker images.

0. Test your Docker installation

docker run hello-world

You would need to use sudo in front of all the docker commands if post docker installation was not followed. Details are available here https://docs.docker.com/install/linux/linux-postinstall/

1. Executing the Docker images

      1.1 Pulling readymade Docker images

            1.1.1 To pull MariaDB database

            docker pull laeeq/ligandprofiledb:0.0.3

            1.1.2 To pull CPVSAPI for 1QCF

            docker pull laeeq/cpvsapi:1QCF-0.0.1

      1.2 Starting MariaDB Container from Image in background (using detach)

      docker run --detach --name test-mariadb -d laeeq/ligandprofiledb:0.0.3

      1.3 Checking container status

      docker ps

      1.4 Want to check what happened

      docker logs test-mariadb

      1.5 Finding IP address of container

      docker inspect test-mariadb | grep IPAddress

Now we know the IP Address where the database is running, so we would be able to connect it. In our case, it was 172.17.0.2.

Note: Make sure to write the IP Address down, you will need it in step 1.11.

      1.6 Logging into MariaDB container and start a bash environment

      docker exec -it test-mariadb bash

      1.7 Logging into MariaDB in the Docker container by using the following command

      mysql -uroot -pmariadb_root

      1.8 Allowing other Docker containers to access MariaDB

      GRANT ALL PRIVILEGES ON *.* TO 'root'@'172.17.0.%' IDENTIFIED BY 'mariadb_root' WITH GRANT OPTION;

      1.9 Exit from MariaDB

      exit

      1.10 Exit from MariaDB container

      exit

      1.11 Running the CPVSAPI Docker container for 1QCF receptor and linking to MariaDB container

Note: You must use the correct MARIADB_IP you found in the section 1.5, otherwise the cpvsapi docker container won’t be able to connect the MariaDB database.

      docker run --detach --name test-cpvs -e MARIADB_IP='172.17.0.2' -e MARIADB_PASSWORD='mariadb_root' -e RECEPTOR_NAME='HCK Tyrosine kinase' -e RECEPTOR_PDBCODE='1QCF' --link test-mariadb:mariadb -p 9000:9000 laeeq/cpvsapi:1QCF-0.0.1

So what have we done here? We executed a new container test-cpvs and using --link we linked it to the test-mariadb docker container which was already running. -p 9000:9000 is used to publish test-cpvs port to localhost.

      1.12 Trying out the cpvs rest api for one receptor i.e. 1QCF

Open any web browser and access the 9000 port of the running test-cpvs Docker container we published to the local machine. Try the following in any web browser.

      http://localhost:9000

If everything works, you should see a swagger rest ui for cpvs. There are three end points of the CPVS API that can be tested i.e. predictions, pvalues and docking. Click anyone by try it out by giving compound in SMILES format. A sample SMILE is given below:

      CC(C)c1ccc(Nc2nccc(n2)c3cnn4ncccc34)cc1

2. Preparing Docker images

Note: Java 8, Maven and sbt 1.1.6 must be installed on local for section 2 and JAVA_HOME must be set

      2.1 Installing Project Dependencies

Clone spark-cheminformatics utilities for tools like signature generation

      git clone https://github.com/mcapuccini/spark-cheminformatics.git

Enter the newly cloned directory. There are two projects parsers and sg. Enter both of them and run the following maven command to install each one of them as local dependencies.

      mvn clean install -DskipTests

Clone spark-cpvs-vina project

      git clone https://github.com/laeeq80/spark-cpvs-vina.git

Enter the project vs inside spark-cpvs-vina and run the command

      mvn clean install -DskipTests

      2.2 Building MariaDB image and copying the database that contains model

We need a Docker container for MariaDB that stores the models created using cpvs project.

            2.2.1 Clone the ligandprofiledb repo

Use git clone to clone the repo https://github.com/laeeq80/ligandProfiledb to create MariaDB Docker image including the database with 1QCF model.

      git clone https://github.com/laeeq80/ligandProfiledb.git

            2.2.2 Build the ligandprofiledb image

Use the following command to create the Docker image at CLI from inside the cloned directory. The Dockerfile also includes the database copying step.

Enter the ligandprofiledb directory and run the following command

      docker build . -t laeeq/ligandprofiledb:0.0.3

!! Step 6/8 in the Dockerfile can take upto 5 minutes. Grab a coffee.

      2.3 Building cpvsapi Docker image for one of the receptor i.e. with PDB ID “1QCF”. The pdbqt for the 1QCF is already available in the cpvsapi repo.

            2.3.1 Clone the cpvsapi repo

Get out of the ligandprofiledb directory and run the following command.

      git clone https://github.com/laeeq80/cpvsAPI.git

The pdbqt for the 1QCF and other resources are already available in the this repo resources folder.

            2.3.2 Creating package

Enter the cpvsAPI and run the following command

      sbt dist

The above command will create cpvsapi-1.0.zip file in the cpvsAPI/target/universal/ directory that is needed while building cpvsapi Docker image in step 2.3.4. In addition, openbabel-2.4.1.tar.gz will also be required that the application uses to convert files into different formats. Openbabel can be downloaded online using

      wget  https://sourceforge.net/projects/openbabel/files/openbabel/2.4.1/openbabel-2.4.1.tar.gz

If wget is not available on your system, you can use a web browser to get it.

            2.3.3 Clone cpvsDocker Dockerfile

      git clone https://github.com/laeeq80/cpvsDocker.git

            2.3.4 Build Docker image for cpvsapi

Copy cpvsapi-1.0.zip and openbabel-2.4.1.tar.gz inside the cpvsDocker directory and run the following command from cpvsDocker directory.

      docker build . -t laeeq/cpvsapi:1QCF-0.0.1

This will take around 15 to 20 minutes. Grab another coffee. [:D]

Goto Step 1.2 to test the newly created Docker images.

3. Some helpful commands

      3.1 List all images

      docker image ls

      3.2 Deleting a docker image

      docker rmi imageID

3.3 List running docker containers

      docker ps

3.4 List already stopped but unremoved containers

      docker ps -a

3.5 Stopping and removing a running docker container

      docker stop containerName

      docker rm containerName

E.g.

      docker stop test-cpvs

The step-by-step guide ends here.

Extending the Service by adding the new receptor Docker containers to the service

If you want to create a docker container for a new receptor, please consider the following steps.

We deployed the service using the deployment script available at https://github.com/pharmbio/dpaas. The script can be utilized to deploy image for a new receptor. Pick any receptor yaml file as template from the link provided and make a new yaml file for the new receptor Docker image accordingly.

Then if you want to view and use the newly deployed Docker container in the Web service UI, add the PDB ID of the new receptor to the cpvs ui https://github.com/laeeq80/cpvs-ui/blob/master/index.html#L173

Create new Docker image for the cpvs ui https://github.com/laeeq80/dpaasDockerfiles/tree/master/cpvsUIDocker

Deploy the new Docker image for UI as done in https://github.com/pharmbio/dpaas

Environment Variables

If you want to further improve CPVSAPI and make any changes, you need to know the CPVSAPI environment variables.

MARIADB_IP     		    //IP of machine where MariaDB is running. We are using MariaDB default port i.e. 3306

MARIADB_PASSWORD	    //MariaDB root password

OBABEL_HOME		    //OBabel Location on local computer	

RESOURCES_HOME              //Direct to resources file in cpvsapi

VINA_CONF                   //Configuration file used for AutoDock Vina

RECEPTOR_NAME               //Name of the Receptor

RECEPTOR_PDBCODE            //Pdb Code of the Receptor

One can also use resources.sh to set up the last four environment variables, which is convenient, using the following command.

source resources.sh receptor_name receptor_pdbCode