Metadata-Version: 2.4
Name: SSDraw
Version: 0.2.0
Summary: Tool for creating publication-quality protein secondary structure diagrams
Author: Ethan Chen
Author-email: Lauren Porter <lauren.porter@nih.gov>, Pramesh Sharma <pramesh.sharma@nih.gov>
License: This software is a "United States Government Work" under the terms of the United States Copyright Act. It was written as part of the authors' official duties as United States Government employees and thus cannot be copyrighted. This software is freely available to the public for use. The National Library of Medicine and the U.S. Government have not placed any restriction on its use or reproduction.
        
        Although all reasonable efforts have been taken to ensure the accuracy and reliability of the software and data, the NLM and the U.S. Government do not and cannot warrant the performance or results that may be obtained by using this software or data. The NLM and the U.S. Government disclaim all warranties, express or implied, including warranties of performance, merchantability or fitness for any particular purpose.
        
        Please cite NCBI in any work or product based on this material.
        
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: biopython>=1.81
Requires-Dist: numpy>=1.24
Requires-Dist: matplotlib>=3.7
Requires-Dist: torch>=2.0.1
Requires-Dist: pydssp
Dynamic: license-file

![header](imgs/1ndd_conservation.png)
# SSDraw
SSDraw is a program that generates publication-quality protein secondary structure diagrams from three-dimensional protein structures. To depict relationships between secondary structure and other protein features, diagrams can be colored by conservation score, B-factor, or custom scoring.

SSDraw also has a colab notebook available at https://colab.research.google.com/github/ethanchen1301/SSDraw/blob/main/SSDraw.ipynb (only usable for Chrome)

## Installation

The easiest way to install SSDraw is via pip:

```bash
pip install SSDraw
```

You can find the package on PyPi [here](https://pypi.org/project/SSDraw/)

## Instructions
SSDraw provides two subcommands:
1. single: Run SSDraw on a single FASTA/PDB pair
2. multi: Run SSDraw for multiple PDBs from one MSA

SSDraw single requires 4 arguments:
1. --fasta: the file name sequence or alignment file in fasta format.
2. --name: the id of the sequence in the fasta file corresponding to your protein of interest.
3. --pdb: the file name of the pdb file of your protein
4. --output: the output file name to use


#### Example 1:
```
ssdraw single --fasta 1ndd.fasta --name 1ndd --pdb 1ndd.pdb --output 1ndd_out
```
![Example 1](imgs/1ndd_out.png)

### Coloring options:
SSDraw uses a gradient to color each position in the alignment by a certain score. The user can choose which scoring system to use, and they can also choose which colormap.

### Scoring: 
-conservation_score: score each position in the alignment by conservation score.

-bfactor: score each residue in the pdb by B-factor.

-scoring_file: score each residue by a custom scoring file prepared by the user.

-mview: color each residue by the mview coloring system.

#### Example 2: score by conservation
```
ssdraw single --fasta aligned.fasta --name 1ndd --pdb 1ndd.pdb --output 1ndd_conservation -conservation_score --start 80 --end 132
```
![Example 2](imgs/1ndd_conservation.png)
Note: for more on how the --start and --end options work, see [choosing a subregion](#choosing-a-subregion).

#### Example 3: Score by B-factor
```
ssdraw single --fasta 1ndd.fasta --name 1ndd --pdb 1ndd.pdb --output 1ndd_bfactor -bfactor
```
![Example 3](imgs/1ndd_bfactor.png)
### Choosing a colormap:
The default colormap for SSDraw is inferno. The user can select one of the matplotlib library color maps or simply list a space delimited set of colors they'd like to use with the --color_map option. Alternatively, the user can select a single color with the --color option and SSDraw will use that color on the whole image.

#### Example 4: Custom scoring file with custom color map
```
ssdraw single --fasta 2kdl.fasta --name 2kdl --pdb 2kdl.pdb --output 2kdl_out --scoring_file 2kdl_scoring.txt --color_map black cyan  
```
![Example 4](imgs/2kdl_out.png)
### DSSP files:
Normally, SSDraw will generate a DSSP annotation from the PDB file, but if you have a DSSP file you would like to use, you can upload it and input the file name in Options.

### Choosing a subregion:
If you want SSDraw to draw only a portion of your alignment, you can specify the start and/or end points using the --start and --end options respectively. The argument for these options correspond to the index of the alignment position, not to the residue position numbers. See [example 2](#example-2-score-by-conservation).

### ConSurf
We now provide the option to color by ConSurf grade using --consurf option:
```
ssdraw single --fasta 2n1v.fasta --name 2n1v --pdb 2n1v.pdb --output 2n1v_consurf --consurf 2n1v_nscores.txt --ticks 5
```
![ConSurf](imgs/2n1v_consurf.png)
The code can read in either the ConSurf grades file or a Rate4Site file with raw scores. The raw scores will be converted into grades according to the algorithm used by ConSurf: https://github.com/Rostlab/ConSurf

### Stacking diagrams
We now provide a `multi` option to assist the user in stacking multiple diagrams.
```
ssdraw multi --input [input script] --output [output directory]
```

This will run SSDraw for multiple pdbs from a single multiple sequence alignment, saving the diagrams to a specified output directory. Finally, this will create a composite stacked image of the diagrams. An example input script is shown in SSDraw/examples/example_run.txt.

## Running with Docker

You can use Docker to run SSDraw without installing dependencies on your system. However, you must have Docker Desktop for your OS installed. You can find that [here](https://www.docker.com/get-started/).

Pull the image from the Docker Registry [here](https://hub.docker.com/r/prameshsharma25/ssdraw):
```
docker pull prameshsharma25/ssdraw
```

### 1. Run SSDraw with your input files

Make sure your input files (FASTA, PDB, etc.) are in your current directory.  
Then run:

```sh
docker run --rm -v "$PWD":/app prameshsharma25/ssdraw single --fasta your.fasta --name your_id --pdb your.pdb --output output_name
```

- Replace `your.fasta`, `your_id`, `your.pdb`, and `output_name` with your actual file names and sequence ID.
- The output image will be saved in your current directory.

#### Example

```sh
docker run --rm -v "$PWD":/app prameshsharma25/ssdraw single --fasta examples/1ndd.fasta --name 1ndd --pdb examples/1ndd.pdb --output 1ndd_out --dpi 1000
```

**Note:**  
The `-v "$PWD":/app` option mounts your current directory into the container, so SSDraw can access your files and save outputs locally.  
You can pass any SSDraw command-line options as usual after the image

### 3. Run SSDraw with multiple PDBs
Following the format in examples/example_run.txt, you're able to utilize SSDraw across several PDBs which builds a composite image of secondary structures.

```sh
docker run --rm -v "$PWD":/app prameshsharma25/ssdraw multi -i run.txt -o output_name
```

#### Example

```sh
docker run --rm -v "$PWD":/app prameshsharma25/ssdraw multi -i examples/example_run.txt -o ubiquitin_stacked
```


