Metadata-Version: 2.4
Name: protein-design-tools
Version: 0.3.0
Summary: A toolkit for protein structure analysis and design.
Author-email: Andrew Schaub <andrew.schaub@protonmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/drewschaub/protein-design-tools
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Provides-Extra: torch
Requires-Dist: torch; extra == "torch"
Provides-Extra: jax
Requires-Dist: jax; extra == "jax"
Provides-Extra: jax-cuda12
Requires-Dist: jax[cuda12]; extra == "jax-cuda12"
Provides-Extra: jax-tpu
Requires-Dist: jax[tpu]; extra == "jax-tpu"
Provides-Extra: fetch
Requires-Dist: requests; extra == "fetch"
Provides-Extra: fast
Requires-Dist: numba; extra == "fast"
Provides-Extra: all
Requires-Dist: torch; extra == "all"
Requires-Dist: jax; extra == "all"
Requires-Dist: requests; extra == "all"
Requires-Dist: numba; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-mock; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# Protein-Design Tools

![Banner](assets/banner.png)

[![PyPI version](https://badge.fury.io/py/protein-design-tools.svg)](https://badge.fury.io/py/protein-design-tools)
![License](https://img.shields.io/badge/license-MIT-blue.svg) 
![Python Version](https://img.shields.io/pypi/pyversions/protein-design-tools)

## Table of Contents

- [Overview](#overview)
- [Features](#features)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Detailed Usage](#detailed-usage)
  - [Reading Protein Structures](#reading-protein-structures)
  - [Analyzing Sequences](#analyzing-sequences)
  - [Computing Structural Metrics](#computing-structural-metrics)
  - [Generating Idealized Structures](#generating-idealized-structures)
- [Examples](#examples)
- [Contributing](#contributing)
- [License](#license)
- [Contact](#contact)

## Overview

**Protein-Design Tools** is a Python library tailored for structural bioinformatics, with a specific focus on protein design and engineering. It provides a suite of tools for analyzing and manipulating protein structures, enabling researchers and practitioners to perform complex structural comparisons, design new proteins, and engineer existing ones with ease.

Whether you're conducting research in protein folding, designing novel enzymes, or engineering therapeutic proteins, Protein-Design Tools offers the functionalities you need to advance your projects.

## Features

### **Protein Structure Representation**
- **Core Classes**:
  - `ProteinStructure`: Represents the entire protein structure.
  - `Chain`: Represents individual chains within the protein.
  - `Residue`: Represents residues within chains.
  - `Atom`: Represents individual atoms within residues.
- **File Parsing**:
  - **PDB Support**: Parse and read PDB files seamlessly.
  - **CIF Support**: Future support planned for CIF files.
- **Programmatic Construction**:
  - Build idealized protein structures (e.g., alpha helices) programmatically.

### **Structural Metrics**
Calculate structural metrics across multiple computational frameworks for flexibility and performance optimization:
- **RMSD (Root Mean Square Deviation)**: Measure the average distance between atoms of superimposed proteins.
- **TM-score**: Assess structural similarity normalized by protein length.
- **GDT-TS (Global Distance Test - Total Score)**: Evaluate global structural similarity using multiple distance thresholds.
- **LDDT (Local Distance Difference Test)**: Measure local structural accuracy.

### **Utilities**
- **Radius of Gyration**: Compute the radius of gyration for protein structures to assess compactness.
- **Sequence Analysis**: Extract and manipulate amino acid sequences from structures.

### **Input/Output Support**
- **File Operations**:
  - Read and write protein structures in PDB format.
  - Write FASTA sequences derived from 3D structure files.
- **Data Export**:
  - Export coordinates and other structural data in various formats, including HDF5.

### **Extensible Architecture**
- **Modular Design**: Easily add new metrics, file formats, and functionalities without disrupting existing components.
- **Multiple Frameworks**: Leverage the strengths of NumPy, PyTorch, and JAX for computational tasks.

## Installation

The core package needs only NumPy. PyTorch, JAX and `requests` are optional
extras, so install just what you use:

| Extra | What it enables | Install |
|-------|-----------------|---------|
| *(none)* | NumPy metrics (`compute_*_numpy`), PDB/mmCIF reading and writing, superposition | `pip install protein-design-tools` |
| `fetch` | `fetch_pdb` / `fetch_cif` (download from RCSB) | `pip install "protein-design-tools[fetch]"` |
| `torch` | `compute_*_pytorch` | `pip install "protein-design-tools[torch]"` |
| `jax` | `compute_*_jax` on CPU | `pip install "protein-design-tools[jax]"` |
| `jax_cuda12`, `jax_tpu` | JAX on an NVIDIA GPU / Cloud TPU | `pip install "protein-design-tools[jax_cuda12]"` |
| `fast` | numba-compiled dynamic programming in TM-align (identical results, much faster) | `pip install "protein-design-tools[fast]"` |
| `all` | every optional backend above | `pip install "protein-design-tools[all]"` |

Calling a backend-specific function without its backend installed raises an
`ImportError` that names the extra to install.

For a development checkout:

```bash
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"        # core + pytest, pytest-mock, black, flake8
pip install -e ".[dev,all]"    # ...plus every optional backend
pytest
```

## Superpose on one selection, measure on another

```python
from protein_design_tools.io.pdb import read_pdb
from protein_design_tools.alignment import superpose, correspond
from protein_design_tools.metrics import rmsd, tmscore

ref = read_pdb("ref.pdb")
model = read_pdb("model.pdb")

# Fit on the target chain A, then judge the binder chain B in that frame.
fit = superpose(model, ref, on="A").apply(model)
print(rmsd(fit, ref, over="B"), tmscore(fit, ref, over="B"))

# Different numbering or indels?  Pair residues by sequence first
# (BLOSUM62, affine gaps; pure NumPy, no Biopython).
pairs = correspond(model, ref, chain_a="B", chain_b="B")
print(rmsd(fit, ref, pairs=pairs))

# Sequences too different to align?  Pair residues by structure instead
# (TM-align, reimplemented in NumPy; Zhang & Skolnick, NAR 2005).
pairs = correspond(model, ref, chain_a="B", chain_b="B", method="structure")
print(pairs.score)                      # TM-score normalised by the reference chain
```

Selections are `None` (everything), a chain ID, a list of chain IDs,
`{"A": range(10, 50)}`, or explicit `(chain, number, insertion_code)` keys;
`on` and `over` are resolved on the reference.  The `compute_*` functions
score pre-paired coordinate arrays and do no alignment themselves.

## Quick Start

Here's a quick example to get you started with Protein-Design Tools:

```python
from protein_design_tools.core.protein_structure import ProteinStructure
from protein_design_tools.io.pdb_io import read_pdb
from protein_design_tools.metrics import compute_rmsd_numpy, compute_gdt_pytorch
from protein_design_tools.utils.coordinate_utils import get_coordinates, get_masses

# Reading a PDB file
protein = read_pdb("path/to/file.pdb", chains=['A', 'B'], name="Sample_Protein")

# Getting sequences
sequences = protein.get_sequence_dict()
print(sequences)

# Getting coordinates of all backbone atoms in chain A
coords = get_coordinates(protein, atom_type="backbone", chains={'A': range(1, 21)})

# Getting masses of all non-hydrogen atoms
masses = get_masses(protein, atom_type="non-hydrogen")
```

Several structural metrics are available, which are accessible across multiple computational frameworks
```python
from protein_design_tools.metrics import compute_rmsd_numpy, compute_gdt_pytorch
# Computing RMSD using NumPy
import numpy as np
import torch

P = np.random.rand(1000, 3)
Q = np.random.rand(1000, 3)
rmsd = compute_rmsd_numpy(P, Q)
print(f"RMSD (NumPy): {rmsd:.4f}")

# Computing GDT-TS using PyTorch
P_pt = torch.tensor(P)
Q_pt = torch.tensor(Q)
gdt = compute_gdt_pytorch(P_pt, Q_pt)
print(f"GDT-TS (PyTorch): {gdt:.2f}")
```

## Detailed Usage

### Reading Protein Structures

Protein-Design Tools supports reading and parsing protein structures from PDB files. Future updates will include CIF file support.

```python
from protein_design_tools.io.pdb_io import read_pdb

# Read all chains
protein = read_pdb("path/to/file.pdb")

# Read specific chains
protein = read_pdb("path/to/file.pdb", chains=['A', 'B'], name="My_Protein")
```

### Analyzing Sequences

Extract amino acid sequences from the protein structure.

```python
# Get the sequence of each chain in the protein
sequence_dict = protein.get_sequence_dict()
for chain_id, sequence in sequence_dict.items():
    print(f"Chain {chain_id}: {sequence}")
```

### Computing Structural Metrics

Leverage multiple frameworks to compute various structural metrics.

```python
from protein_design_tools.metrics import compute_rmsd_numpy, compute_gdt_pytorch

# Example data
import numpy as np
import torch

P = np.random.rand(1000, 3)
Q = np.random.rand(1000, 3)

# Compute RMSD using NumPy
rmsd = compute_rmsd_numpy(P, Q)
print(f"RMSD (NumPy): {rmsd:.4f}")

# Compute GDT-TS using PyTorch
P_pt = torch.tensor(P)
Q_pt = torch.tensor(Q)
gdt = compute_gdt_pytorch(P_pt, Q_pt)
print(f"GDT-TS (PyTorch): {gdt:.2f}")
```

### Generating Idealized Structures

Create idealized protein structures programmatically, such as an alpha helix.

```python
from protein_design_tools.io.builder import build_ideal_alpha_helix

# Build an idealized alpha helix with 10 residues
ideal_helix = build_ideal_alpha_helix(sequence_length=10, chain_id='A', start_res_seq=1)

# Display sequence
sequence_dict = ideal_helix.get_sequence_dict()
print(sequence_dict)
```

## Examples

### Calculating the Radius of Gyration

Calculate the radius of gyration for a protein and compare it to an idealized alpha helix.

```python
from protein_design_tools.core.protein_structure import ProteinStructure
from protein_design_tools.io.pdb_io import read_pdb
from protein_design_tools.metrics import compute_radgyr, compute_radgyr_ratio

# Read the protein structure
protein = read_pdb("example.pdb")

# Display the amino acid sequence of the protein
sequence_dict = protein.get_sequence_dict()
for chain_id, sequence in sequence_dict.items():
    print(f"Chain {chain_id}: {sequence}")

# Calculate the radius of gyration of the backbone of chain A
rgA = compute_radgyr(protein, chains={'A'}, atom_type="backbone")
print(f"Protein Structure Chain A Radius of Gyration: {rgA:.4f}")

# Calculate the radius of gyration of an ideal alanine helix
ideal_helix_seq_length = len(sequence_dict['A'])
rg_ideal_helix = compute_radgyr_alanine_helix(ideal_helix_seq_length, atom_type="backbone")
print(f"Ideal Alanine Helix Radius of Gyration: {rg_ideal_helix:.4f}")

# Calculate the radius of gyration ratio
rg_ratio = compute_radgyr_ratio(protein, chains={'A'}, atom_type="backbone")
print(f"Radius of Gyration Ratio: {rg_ratio:.4f}")
```

### Comparing Protein Structures Using TM-score

Assess the structural similarity between two protein structures.

```python
from protein_design_tools.metrics import compute_tmscore_numpy

# Assume P and Q are numpy arrays of shape (N, D) representing atom coordinates
P = np.random.rand(1000, 3)
Q = np.random.rand(1000, 3)

# Compute TM-score using NumPy
tm_score = compute_tmscore_numpy(P, Q)
print(f"TM-score (NumPy): {tm_score:.4f}")
```

### Contributing

Contributions are welcome! Whether you're fixing bugs, improving documentation, or adding new features, your help is greatly appreciated.

1. **Fork the Repository**: Click the "Fork" button at the top right of the repository page.
2. **Clone Your Fork**:
    ```bash
    git clone https://github.com/your-username/protein-design-tools.git
    ```
3. **Create a New Branch**:
    ```bash
    git checkout -b feature/YourFeatureName
    ```
4. **Make Your Changes**: Implement your feature or fix.
5. **Commit Your Changes**:
    ```bash
    git commit -m "Add feature: YourFeatureName"
    ```
6. **Push to Your Fork**:
    ```bash
    git push origin feature/YourFeatureName
    ```
7. **Create a Pull Request**: Go to the original repository and create a pull request from your fork.

For major changes, please open an issue first to discuss what you would like to change.

### Development Guidelines

- Follow PEP8 style guidelines.
- Write clear and concise docstrings for all functions and classes.
- Include unit tests for new features or bug fixes.
- Ensure that existing tests pass before submitting a pull request. 

## License

This project is licensed under the MIT License.

## Contact

For any questions, suggestions, or contributions, please reach out:
- **Author**: Andrew Schaub
- **Linkedin**: https://www.linkedin.com/in/andrewjschaub
- **GitHub**: https://github.com/drewschaub/protein-design-tools

---

Thank you for using Protein-Design Tools! We hope it serves as a valuable resource in your structural bioinformatics and protein engineering endeavors.
