Merge pull request #9 from labstructbioinf/develop

DeepCoil2

Author: jludwiczak

.github/workflows/main.yml

@@ -0,0 +1,25 @@
+name: deepcoil
+on: [push]
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python-version: [3.6, 3.7, 3.8]
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Python
+      uses: actions/setup-python@v2
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip setuptools wheel twine pytest pytest-cov
+        pip install -r requirements.txt
+    - name: Set environment
+      run: |
+        echo "::set-env name=PYTHONPATH::/home/runner/work/DeepCoil/DeepCoil"
+    - name: Test with pytest
+      run: |
+        pytest -v

.travis.yml

@@ -0,0 +1,2 @@
+include deepcoil/weights/*.h5
+include deepcoil/models/seq.json

MANIFEST.in

@@ -1,61 +1,64 @@
-![Build Status](https://travis-ci.org/labstructbioinf/DeepCoil.svg?branch=master)
 # **DeepCoil** #
-Accurate prediction of coiled coil domains in protein sequences.
-​
-## **Installation** ##
-First clone this repository:
-```bash
-$ git clone https://github.com/labstructbioinf/DeepCoil.git
-```
-Required packages to run DeepCoil are listed in the **`requirements.txt`** file.
-We suggest running DeepCoil in the virtual environment:
-If you don't have virtualenv installed do so:
-```bash
-$ pip3 install virtualenv
-```
-Create virtual environment and install required packages:
-```bash
-$ cd virtual_envs_location
-$ virtualenv deepcoil_env
-$ source deepcoil_env/bin/activate
-$ cd DEEPCOIL_LOCATION
-$ pip3 install -r requirements.txt
-```
-Test the installation:
+[![DOI:10.1093/bioinformatics/bty1062](https://zenodo.org/badge/DOI/10.1093/bioinformatics/bty1062.svg)](https://doi.org/10.1093/bioinformatics/bty1062 )
+![build](https://github.com/labstructbioinf/DeepCoil/workflows/deepcoil/badge.svg) 
+
+## **Fast and accurate prediction of coiled coil domains in protein sequences**
+### **New in version 2.0** ###
+- Faster inference time by applying *[SeqVec](https://github.com/rostlab/SeqVec)* embeddings instead of *psiblast* profiles.
+- Additional heptad predictions (*a* and *d* core positions).
+- No maximum sequence length limit.
+- Convenient interface for using *DeepCoil* within python scripts.
+- Automated peak detection for improved output readability.
+- Simplified installation with *pip*.
+
+Older DeepCoil versions are available [here](https://github.com/labstructbioinf/DeepCoil/releases). 
+
+### **Requirements and installation** ###
+DeepCoil requires `python>=3.6.1` and `pip>=19.0`. Other requirements are specified in the `requirements.txt` file.
+
+The most convenient way to install **DeepCoil** is to use pip:
 ```bash
-$ ./run_example.sh
+$ pip3 install deepcoil
 ```
-This should produce output **`example/out_pssm/GCN4_YEAST.out`** identical to **`example/out_pssm/GCN4_YEAST.out.bk`** and accordingly for the **`example/out_seq/`** directory.
-​
-## **Usage** ##
+
+### **Usage** ###
+
+#### Running DeepCoil standalone version:
+
 ```bash
-python3.5 deepcoil.py [-h] -i FILE [-out_path DIR] [-pssm] [-pssm_path DIR]
+deepcoil [-h] -i FILE [-out_path DIR] [-n_cpu NCPU] [--gpu] [--plot]
+                [--dpi DPI]
 ```
-| Option        | Description |
+| Argument        | Description |
 |:-------------:|-------------|
 | **`-i`** | Input file in FASTA format. Can contain multiple entries. |
-| **`-pssm`** | Flag for the PSSM-mode. If enabled DeepCoil will require psiblast PSSM files in the pssm_path. Otherwise only sequence information will be used.|
-| **`-pssm_path`** | Directory with psiblast PSSM files. For each entry in the input fasta file there must be a PSSM file. |
-| **`-out_path`** | Directory where the predictions are saved. For each entry one file will be saved. |
-| **`-out_type`** | Output type. Either **'ascii'** (default), which will write single file for each entry in input or **'h5'** which will generate single hdf5 file storing all predictions. |
-| **`-out_filename`** | Works with **"-out_type h5"** option and specifies the hdf5 output filename Overrides the **-out_path** if specified. |
-| **`-min_residue_score`** | Number in the range <0,1>. DeepCoil will return sequences that have at least one residue with  score greater than min_residue_score |
-| **`-min_segment_length`** | Number greater than 0. DeepCoil will return sequences that contain a segment of length **-min_segment_length** or more. To be used with **-min_residue_score** |
+| **`-out_path`** | Directory where the predictions are saved. For each entry in the input file one file will be saved. Defaults to the current directory if not specified.|
+| **`-n_cpu`** | Number of CPUs to use in the prediction. By the default all cores will be used.|
+| **`--gpu`** | Flag for turning on the GPU usage. Allows faster inference on large datasets. Overrides **`-n_cpu`** option.|
+| **`--plot`** | Turns on the additional visual output of the predictions for each entry in the input. Plot files are saved in the **`-out_path`** directory.|
+| **`--dpi`** | DPI of the saved plots, active only with **`--plot`** option.|
 
-Results of **`-min_residue_score`** and **`-min_segment_length`** filters are stored in directories located in **`-out_path`**.
+In a rare case of `deepcoil` being not available in your `PATH` after installation please look in the `$HOME/.local/bin/` or other system specific `pip` directory.
 
-PSSM filenames should be based on the identifiers in the fasta file (only alphanumeric characters and '_'). For example if a fasta sequence is as follows:
-```
->GCN4_YEAST RecName: Full=General control protein GCN4; AltName: Full=Amino acid biosynthesis regulatory protein
-MSEYQPSLFALNPMGFSPLD....
-```
-PSSM file should be named **`GCN4_YEAST.pssm`**.
-​
-You can generate PSSM files with the following command (requires NR90 database):
-```bash
-psiblast -query GCN4_YEAST.fasta -db NR90_LOCATION -evalue 0.001 -num_iterations 3 -out_ascii_pssm GCN4_YEAST.pssm
-```
-In order to generate PSSM file from multiple sequence alignment (MSA) you can use this command:
-```bash
-psiblast -subject sequence.fasta -in_msa alignment.fasta -out_ascii_pssm output.pssm
+#### Running DeepCoil within script:
+
+```python
+from deepcoil import DeepCoil
+from deepcoil.utils import plot_preds
+from Bio import SeqIO
+
+dc = DeepCoil(use_gpu=True)
+
+inp = {str(entry.id): str(entry.seq) for entry in SeqIO.parse('example/example.fas', 'fasta')}
+
+results = dc.predict(inp)
+
+plot_preds(results['3WPA_1'], out_file='example/example.png')
 ```
+`results[entry]`  for an entry of sequence length `N` contains two keys:
+- `['cc']` - per residue coiled coil propensity (`[N, 1]` shape)
+- `['hept']` - per residue core positions (`[N, 3]` shape, order in the second axis is: no/other position, *a* position, *d* position)
+
+Peak detection can be performed with the `deepcoil.utils.sharpen_preds` helper function.
+#### Example graphical output:
+![Example](example/example.png)

README.md

@@ -0,0 +1,83 @@
+#!/usr/bin/env python
+
+import os
+import argparse
+from Bio import SeqIO
+from deepcoil import DeepCoil
+from deepcoil.utils import is_fasta, sharpen_preds, plot_preds
+
+parser = argparse.ArgumentParser(description='DeepCoil')
+parser.add_argument('-i',
+                    help='Input file with sequence in fasta format.',
+                    required=True,
+                    metavar='FILE')
+parser.add_argument('-out_path',
+                    help='Output directory',
+                    default='.',
+                    metavar='DIR')
+parser.add_argument('-n_cpu',
+                    help='Number of CPUs to use in the prediction',
+                    default=-1,
+                    type=int,
+                    metavar='NCPU')
+parser.add_argument('--gpu',
+                    help='Use GPU. This option overrides -n_cpu option',
+                    action='store_true')
+parser.add_argument('--plot',
+                    help='Plot predictions. Images will be stored in the path defined by the -out_path',
+                    action='store_true')
+parser.add_argument('--dpi',
+                    help='DPI of the produced images',
+                    default=300,
+                    type=int,
+                    metavar='DPI')
+args = parser.parse_args()
+
+# Check if input file exists
+if not os.path.isfile(args.i):
+    print('ERROR: Input file does not exist!')
+    exit()
+# Check if input is valid fasta file
+if not is_fasta(args.i):
+    print("ERROR: Malformed fasta file. Please check input!")
+    exit()
+# Check if output dir exists
+if not os.path.isdir(args.out_path):
+    print("ERROR: Output directory does not exist!")
+    exit()
+
+# Verify fasta file
+raw_data = list(SeqIO.parse(args.i, "fasta"))
+data = {''.join(e for e in str(entry.id) if (e.isalnum() or e == '_')): str(entry.seq) for entry in raw_data}
+if not len(data) == len(raw_data):
+    print("ERROR: Sequence identifiers in the fasta file are not unique!")
+    exit()
+
+print("Loading DeepCoil model...")
+dc = DeepCoil(use_gpu=args.gpu, n_cpu=args.n_cpu)
+
+print('Predicting...')
+preds = dc.predict(data)
+
+print('Writing output...')
+
+inp_keys = set(data.keys())
+out_keys = set(preds.keys())
+
+if len(out_keys) < len(inp_keys):
+    print('WARNING: Predictions for some sequences were not calculated due to length limitations and/or other errors.' \
+    ' Inspect the warnings and results carefully!')
+
+for entry in out_keys:
+    f = open(f'{args.out_path}/{entry}.out', 'w')
+    cc_pred_raw = preds[entry]['cc']
+    cc_pred = sharpen_preds(cc_pred_raw)
+    hept_pred = preds[entry]['hept']
+    f.write('aa\tcc\traw_cc\tprob_a\tprob_d\n')
+    for aa, cc_prob, cc_prob_raw, a_prob, d_prob in zip(data[entry], cc_pred, cc_pred_raw, hept_pred[:, 1], hept_pred[:, 2]):
+        f.write('{0}\t{1:.3f}\t{2:.3f}\t{3:.3f}\t{4:.3f}\n'.format(aa, float(cc_prob), float(cc_prob_raw), float(a_prob), float(d_prob)))
+    f.close()
+if args.plot:
+    for entry in out_keys:
+        plot_preds(preds[entry], out_file=f'{args.out_path}/{entry}.png', dpi=args.dpi)
+print("Done!")