Home

Awesome

codecov CI Documentation Status PyPI version DOI

pyscreener

A pythonic interface to high-throughput virtual screening software

Overview

This repository contains the source of pyscreener, both a library and software for conducting HTVS via python calls

Table of Contents

Installation

Docker

If docker is not installed already for your system then it can be installed from the official docker website.

The provided Dockerfile can be used to create pyscreener instances containing the required docking software and python dependencies / code. Any of the four vina docking softwares - vina, qvina2, smina, and psovina - can be specified for installation to the docker image. All python dependencies and the pyscreener library are installed to a conda environment named pyscreener which must be activated once the docker image starts.

The below commands can be run in the directory containing the Dockerfile and environment.yml files to build the desired image:

As DOCK6 software requires a license, it is not possible to include its installation within the associated docker image. A compiled form of sphgen_cpp and the binary required for installation of chimera are both available within the dock6_utils directory of the associated dock6 image:

Notes :

  1. Within the docker container, the environment base will be activated by default. This contains all the required python dependencies so there is no need to manually activate an environment once inside the container
  2. If installing using docker, then the below installation stages are not required for the corresponding vina-type software. However, the DOCK6 directions must still be followed.

General requirements

Setup

  1. (if necessary) install conda
  2. conda env create -f environment.yml
  3. conda activate pyscreener
  4. pip install pyscreener (or if installing from source, pip install .)
  5. follow the corresponding directions below for the intended software

Before running pyscreener, be sure to first activate the environment: conda activate pyscreener (or whatever you've named your environment)

external software

adding an executable to your PATH

To add an executable to your PATH, you have three options:

  1. create a symbolic link to the executable inside a directory that is already on your path: ln -s FILE -t DIR. Typically, ~/bin or ~/.local/bin are good target directories (i.e., DIR). To see what directories are currently on your path, type echo $PATH. There will typically be a lot of directories on your path, and it is best to avoid creating files in any directory above your home directory ($HOME on most *nix-based systems)
  2. copy the software to a directory that is already on your path. Similar, though less preferred than the above: cp FILE DIR
  3. append the directory containing the file to your PATH: export PATH=$PATH:DIR, where DIR is the directory containing the file in question. As your PATH must be configured each time run pyscreener, this command should also be placed inside your ~/.bashrc or ~/.bash_profile (if using a bash shell) to avoid needing to run the command every time you log in. Note: if using a non-bash shell, the specific file will be different.

specifying an environment variable

To set the DOCK6 environment variable, run the following command: export DOCK6=path/to/dock6, where path/to/dock6 is the full path of the DOCK6 parent directory mentioned above. As this this environment variable must always be set before running pyscreener, the command should be placed inside your ~/.bashrc or ~/.bash_profile (if using a bash shell) to avoid needing to run the command every time you log in. Note: if using a non-bash shell, the specific file will be different.

Ray Setup

pyscreener uses ray as its parallel backend. If you plan to parallelize the software only across your local machine, don't need to do anything . However, if you wish to either (a.) limit the number of cores pyscreener will be run over or (b.) run it over a distributed setup (e.g., an HPC with many distinct nodes), you must manually start a ray cluster before running pyscreener.

Limiting the number of cores

To do this, simply type ray start --head --num-cpus N before starting pyscreener (where N is the total number of cores you wish to allow pyscreener to utilize). Not performing this step will give pyscreener access to all of the cores on your local machine, potentially slowing down other applications.

Distributing across many nodes

While the precise instructions for this will vary with HPC cluster architecture, the general idea is to establish a ray cluster between the nodes allocated to your job. We have provided a sample SLURM submission script (run_pyscreener_distributed_example.batch) to achieve this, but you may have to alter some commands depending on your system. For more information on this see here. To allow pyscreener to connect to your ray cluster, you must set the ip_head and redis_password environment variables appropriately, where ip_head is the address of the head of your ray cluster, i.e., IP:PORT where IP is the IP address of the head node and PORT is the port that is running ray.

pyscreener writes a lot of intermediate input and output files (due to the inherent specifications of the underlying docking software.) Given that the primary endpoint of pyscreener is a list of ligands and associated scores (rather than the specific binding poses,) these files are written to each node's temporary directory (determined by tempfile.gettempdir()) and discarded at the end. If you wish to collect these files, pass the --collect-all flag in the program arguments or run the collect_files() method of your VirtualScreen object when your screen is complete.

Note: the VirtualScreen.collect_files() method is slow due to the need to send possibly a bunch of files over the network. This method should only be run once over the lifetime of a VirtualScreen object, as several intermediate calls will yield the same result as a single, final call.

Note: tempfile.gettempdir() returns a path that depends the values of specific environment variables (see here). It is possible that the value returned on your system is not actually a valid path for you! In this case you will likely get file permissions errors and must ask your system administrator where this value should point to and set your environment variables accordingly before running pyscreener!

Running pyscreener as a software

!!please read the entire section before running pyscreener!!

pyscreener was designed to have a minimal interface under the principal that a high-throughput virtual screen is intended to be a broad strokes technique to gauge ligand favorability. With that in mind, all one really needs to get going are the following:

There are a variety of other options you can specify as well (including how to score a ligand given that multiple scored conformations are output, how to score against an ensemble of structures, etc.) To see all of these options and what they do, use the following command: pyscreener --help. All of these options may be specified on the command line or in a configuration file that accepts YAML, INI, and argparse syntaxes. Example configuration files are located in integration-tests/configs.

To check if everything is working and installed properly, first run pyscreener like so: pyscreener --config path/to/your/config --smoke-test

Metadata Templates

Vina-type and DOCK6 docking simulations have a number of options unique to their preparation and simulation pipeline, and these options are termed simulation "metadata" in pyscreener. At present, only a few of these options are supported for both families of docking software, but future updates will add support for more of these options. These options may be specified via a JSON struct to the --metadata-template argument. Below is a list of the supported options for both types of docking screen (default options provided in parentheses next to the parameter)

Testing your environment setup

To test whether your environment is setup correctly with respect to pathing and environment variables, run pyscreener like so:

pyscreener --smoke-test --screen-type SCREEN_TYPE --metadata-template TEMPLATE

where SCREEN_TYPE and METADATA_TEMPLATE and values as described above

If the checks pass, then your environment is set up correctly.

Using pyscreener as a library

To check if pyscreener is set up properly, you can run the following:

>>> import pyscreener as ps

>>> software = "..."
>>> metadata = {...}

>>> ps.check_env(software, metadata)
...

where software is the name of the software you intend to use and metadata is a dictionary containing the metadata template. Please see the metadata templates section for details on possible key-value pairs.

The object model of pyscreener relies on four classes:

To perform docking calls inside your python code using pyscreener, you must first initialize a DockingVirtualScreen object either through the factory pyscreener.virtual_screen function or manually initializing one. The following section will show an example of how to perform computational from inside a python interpreter.

Examples

the following code snippet will dock benzene (SMILES string "c1ccccc1") against the D4 dopamine receptor (PDB ID 5WIU) using a predefined docking box and Autodock Vina

>>> import ray
>>> ray.init()
[...]
>>> import pyscreener as ps
>>> metadata = ps.build_metadata("vina")
>>> virtual_screen = ps.virtual_screen("vina", ["integration-tests/inputs/5WIU.pdb"], (-18.2, 14.4, -16.1), (15.4, 13.9, 14.5), metadata, ncpu=8)
{...}
>>> scores = virtual_screen("c1ccccc1")
>>> scores
array([-4.4])

A few notes from the above example:

for more examples, check out the examples folder!

Testing

  1. pip install pytest-cov
  2. pytest

Copyright

Copyright (c) 2021, david graff