diff --git a/README.md b/README.md index 79de161..fe2136a 100644 --- a/README.md +++ b/README.md @@ -10,127 +10,133 @@ neural network (GNN) that predicts an association to a target molecule, e.g., a DeepFPlearn+ is an extension of deepFPlearn[[2]](#2), which uses binary fingerprints to represent the molecule's structure computationally. -## Setting up Python environment +## Installation The DFPL package requires a particular Python environment to work properly. It consists of a recent Python interpreter and packages for data-science and neural networks. -The exact dependencies can be found in the -[`requirements.txt`](requirements.txt) (which is used when installing the package with pip) -and [`environment.yml`](environment.yml) (for installation with conda). You have several ways to provide the correct environment to run code from the DFPL package. -1. Use the automatically built docker/Singularity containers -2. Build your own container [following the steps here](container/README.md) -3. Setup a python virtual environment -4. Set up a conda environment install the requirements via conda and the DFPL package via pip +1. Use conda (bioconda) to install the package +2. Set up a Python virtual environment +3. Use the automatically built Docker +4. Use the automatically built Singularity containers -In the following, you find details for option 1., 3., and 4. +### Conda (bioconda) + +The package is also available on Bioconda. You can find the Bioconda recipe here and +[![install with bioconda](http://bioconda.github.io/recipes/deepfplearn/README.html)] + +First create an environment with the following command: + +```shell +conda create --override-channels --channel conda-forge --channel bioconda -n dfpl deepfplearn +``` + +If you have a GPU available you can install the package with additional tensorflow-gpu package: + +```shell +conda create --override-channels --channel conda-forge --channel bioconda -n dfpl deepfplearn tensorflow-gpu +``` + +Then activate the environment: + +```shell +conda activate dfpl +``` + +Now, you can start using deepFPlearn as described in section **Running deepFPlearn** + +### Set up DFPL in a python virtual environment + +Clone the `deepFPlearn` repository` on your machine + +```shell +git clone git@github.com:yigbt/deepFPlearn.git +``` + +From within the `deepFPlearn` directory call + +```shell +virtualenv -p python3 ENV_PATH +. ENV_PATH/bin/activate +pip install ./ +``` + +replace `ENV_PATH` by the directory where the python virtual environment should be created. +If your system has only python3 installed `-p python3` may be removed. + +In order to use the environment, it needs to be activated with `. ENV_PATH/bin/activate`. ### Docker container -You need docker installed on you machine. +You need docker installed on your machine. If you don't have it installed yet, you can find the installation +instructions [here](https://docs.docker.com/engine/install/). + +In order to run DFPL pull the image using the following command line: -In order to run DFPL use the following command line +```shell +docker pull quay.io/biocontainers/deepfplearn:TAG +``` +Then mount the directory containing the data you want to process and run the container with the following command: + +```shell +docker run -v /path/to/local/repo quay.io/biocontainers/deepfplearn:TAG dfpl DFPL_ARGS +``` +And then you can run the container with the following command: ```shell -docker run --gpus GPU_REQUEST registry.hzdr.de/department-computational-biology/deepfplearn/deepfplearn:TAG dfpl DFPL_ARGS +docker run quay.io/biocontainers/deepfplearn:TAG dfpl DFPL_ARGS ``` where you replace -- `TAG` by the version you want to use or `latest` if you want to use latest available version) -- You can see available tags - here https://gitlab.hzdr.de/department-computational-biology/deepfplearn/container_registry/5827. +- `TAG` by the version you want to use +- You can see available tags in [biocontainers](https://biocontainers.pro/tools/deepfplearn). In general a container should be available for each released version of DFPL. -- `GPU_REQUEST` by the GPUs you want to use or `all` if all GPUs should be used (remove `--gpus GPU_REQUEST` if only the - CPU should) - `DFPL_ARGS` by arguments that should be passed to DFPL (use `--help` to see available options) In order to get an interactive bash shell in the container use: ```shell -docker run -it --gpus GPU_REQUEST registry.hzdr.de/department-computational-biology/deepfplearn/deepfplearn:TAG bash +docker run -it quay.io/biocontainers/deepfplearn:TAG /bin/bash ``` + ### Singularity container -You need Singularity installed on your machine. You can download a container with +You need Singularity installed on your machine. You can find the installation instructions +[here](https://apptainer.org/user-docs/master/quick_start.html). ```shell -singularity pull dfpl.TAG.sif docker://registry.hzdr.de/department-computational-biology/deepfplearn/deepfplearn:TAG +singularity pull dfpl.TAG.sif docker://quay.io/biocontainers/deepfplearn:TAG ``` -- replace `TAG` by the version you want to use or `latest` if you want to use latest available version) +- replace `TAG` by the version you want to use - You can see available tags - here https://gitlab.hzdr.de/department-computational-biology/deepfplearn/container_registry/5827. - In general a container should be available for each released version of DFPL. + [here](https://biocontainers.pro/tools/deepfplearn). This stores the container as a file `dfpl.TAG.sif` which can be run as follows: ```shell script -singularity run --nv dfpl.TAG.sif dfpl DFPL_ARGS +singularity run dfpl.TAG.sif dfpl DFPL_ARGS ``` - replace `DFPL_ARGS` by arguments that should be passed to DFPL (use `--help` to see available options) -- omit the `--nv` tag if you don't want to use GPUs or you can start a shell script (look at [run-all-cases.sh](scripts/run-all-cases.sh) for an example) -```shell script -singularity run --nv dfpl.sif ". ./example/run-multiple-cases.sh" -``` - It's also possible to get an interactive shell into the container ```shell script -singularity shell --nv dfpl.TAG.sif +singularity shell dfpl.TAG.sif ``` **Note:** The Singularity container is intended to be used on HPC cluster where your ability to install software might be limited. -For local testing or development, setting up the conda environment is preferable. - -### Set up DFPL in a python virtual environment - -From within the `deepFPlearn` directory call - -``` -virtualenv -p python3 ENV_PATH -. ENV_PATH/bin/activate -pip install ./ -``` - -replace `ENV_PATH` by the directory where the python virtual environment should be created. -If your system has only python3 installed `-p python3` may be removed. - -In order to use the environment it needs to be activated with `. ENV_PATH/bin/activate`. - -### Set up DFPL in a conda environment - -To use this tool in a conda environment: - -1. Create the conda env from scratch - - From within the `deepFPlearn` directory, you can create the conda environment with the provided yaml file that - contains all information and necessary packages - - ```shell - conda env create -f environment.yml - ``` - -2. Activate the `dfpl_env` environment with - - ```shell - conda activate dfpl_env - ``` - -3. Install the local `dfpl` package by calling +For local testing or development, setting up the bioconda environment is preferable. - ```shell - pip install --no-deps ./ - ``` ## Prepare data @@ -325,7 +331,7 @@ memory on disk. [1] Kyriakos Soulios, Patrick Scheibe, Matthias Bernt, Jörg Hackermüller, and Jana Schor. deepFPlearn+: Enhancing Toxicity Prediction Across the Chemical Universe Using Graph Neural Networks. -Bioinformatics, Volume 39, Issue 12, December 2023, btad713, https://doi.org/10.1093/bioinformatics/btad713 +Submitted to a scientific journal, currently under review. [2] Jana Schor, Patrick Scheibe, Matthias Bernt, Wibke Busch, Chih Lai, and Jörg Hackermüller. diff --git a/setup.py b/setup.py index 42c22c0..14e6fdd 100644 --- a/setup.py +++ b/setup.py @@ -26,8 +26,8 @@ "pandas==1.4.2", "rdkit-pypi==2022.03.1", "scikit-learn==1.0.2", - "keras==2.9.0", - "tensorflow-gpu==2.9.3", + "keras==2.10.0", + "tensorflow-gpu==2.10.0", "wandb~=0.12.0", "umap-learn~=0.1.1", "seaborn~=0.12.2",