Metadata-Version: 2.4
Name: surfaces-py
Version: 0.1.0
Summary: Surfaces: quantify and visualize interactions within and between proteins and ligands.
Author: Natália Teruel
License-Expression: MIT
Project-URL: Homepage, https://github.com/NRGlab/Surfaces
Project-URL: Documentation, https://surfaces-tutorial.readthedocs.io
Project-URL: Repository, https://github.com/NRGlab/Surfaces
Project-URL: Issues, https://github.com/NRGlab/Surfaces/issues
Classifier: Intended Audience :: Science/Research
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas
Requires-Dist: numpy
Requires-Dist: vcon-py>=1.0.2
Provides-Extra: viz
Requires-Dist: colour; extra == "viz"
Provides-Extra: cif
Requires-Dist: biopython; extra == "cif"
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Provides-Extra: all
Requires-Dist: colour; extra == "all"
Requires-Dist: biopython; extra == "all"
Dynamic: license-file

# surfaces-py

Surfaces as an installable Python package. It quantifies and visualizes
interactions within and between proteins and ligands, from atom-atom contact
surface areas (Vcontacts) and pairwise atom-type interaction energies.

> Teruel, N. F. B., Borges, V. M., & Najmanovich, R. (2023). *Surfaces: a
> software to quantify and visualize interactions within and between proteins
> and ligands.* Bioinformatics, 39(10), btad608.

What's different from the script version:

* **No compiling.** Vcontacts is run through [`vcon-py`](https://github.com/NRGlab/vcon-py),
  which ships pre-built binaries.
* **Bundled parameters.** `AMINO_FlexAID.def` and `FlexAID.dat` are included,
  so `-def`/`-dat` are only needed for custom files.
* **Same results.** Given the same Vcontacts output, the matrices are
  byte-identical to the original scripts (see `validation/`).
* **Faster.** Atom types are read once and cached. 7VQ0 (ABC vs DEF) drops from
  37 s to 1.4 s.
* **Python API and CLI.** Both work like [NRGTEN](https://nrgten.readthedocs.io).

## Installation

```bash
pip install surfaces-py               # core (pandas, numpy, vcon-py)
pip install "surfaces-py[viz]"        # + colour, for PyMOL sessions
pip install "surfaces-py[cif]"        # + biopython, for mmCIF conversion
conda install -c conda-forge pymol-open-source   # PyMOL (visual outputs only)
```

From source: `pip install .` in this folder.

Works on Linux, macOS (Intel and Apple Silicon) and Windows with Python 3.9 or
newer. Surfaces itself is pure Python, and `vcon-py` provides a pre-built
Vcontacts for each of these systems.

## Python API

```python
import surfaces

# Protein-protein (surface_cont.py)
clean = surfaces.clean_structure("7VQ0.pdb")            # -> 7VQ0_clean.pdb
res = surfaces.protein_protein(clean, "ABC", "DEF")
res.matrix                    # pandas DataFrame, residues x residues
res.ranked().head()           # strongest interactions first
res.to_csv("7VQ0_output.csv") # CSV + List_7VQ0_output.txt

# Protein-ligand (surface_cont_lig.py)
surfaces.create_ligand_file("7NT4.pdb", "PRL")                     # -> PRL.pdb
def_file = surfaces.ligand_atomtypes("PRL.mol2")                   # -> custom_AMINO_FlexAID.def
clean = surfaces.clean_structure("7NT4.pdb", def_file=def_file)
lig = surfaces.protein_ligand(clean, "AB", "PRL", def_file=def_file)

# Particular residues (surface_cont_res.py)
gly = surfaces.particular_residues("7EAZ_clean.pdb", ["GLY614A", "GLY614B", "GLY614C"])

# Utilities
surfaces.steric_clashes("model.pdb")     # list of clashing residue pairs
surfaces.cif_to_pdb("structure.cif")

# PyMOL sessions (image_surfaces*.py); output=None keeps an open PyMOL session unsaved
from surfaces import visualization
visualization.generate_session("7VQ0_clean.pdb", res, "7VQ0.pse")
visualization.generate_ligand_session("7NT4_clean.pdb", lig, "7NT4.pse", color_scale_range=[-0.35, 0.35])
```

Options on every calculation: `def_file`, `dat_file`, `scale_factor`
(default 0.00024329), `atomtypes` (a pre-loaded `surfaces.AtomTypes`),
`vcon_file` (reuse a Vcontacts output) and `vcon_executable` (see below).

## Command line

Each original script is a sub-command with the same flags. Replace
`python <script>.py` with `surfaces <script>`:

```bash
surfaces clean_structure -f 7VQ0.pdb
surfaces surface_cont     -f 7VQ0_clean.pdb -c1 ABC -c2 DEF -o 7VQ0_output.csv
surfaces image_surfaces   -f 7VQ0_clean.pdb -c 7VQ0_output.csv -o 7VQ0_visual_output.pse

surfaces create_lig_file  -f 7NT4.pdb -lig PRL
surfaces ligand_atomtypes -mol2 PRL.mol2            # or -pdb PRL.pdb (needs PyMOL)
surfaces clean_structure  -f 7NT4.pdb -def custom_AMINO_FlexAID.def
surfaces surface_cont_lig -f 7NT4_clean.pdb -c AB -lig PRL -o 7NT4_output.csv -def custom_AMINO_FlexAID.def
surfaces image_surfaces_lig -f 7NT4_clean.pdb -c 7NT4_output.csv -o 7NT4.pse -cs_range -0.35,0.35

surfaces surface_cont_res -f 7EAZ_clean.pdb -res GLY614A,GLY614B,GLY614C -o 7EAZ_output.csv
surfaces steric_clashes   -f model.pdb
surfaces cif2pdb structure.cif
```

`python -m surfaces ...` works too.

### Colour scale options

`-cs` (three colours: bottom, middle, top) and `-cs_range` (minimum and
maximum) take their values without brackets:

```bash
surfaces image_surfaces -f 7VQ0_clean.pdb -c 7VQ0_output.csv -o 7VQ0.pse -cs green,white,orange -cs_range -0.5,0.5
```

Space-separated values (`-cs_range -0.5 0.5`) also work. The bracketed form of
the original scripts (`[-0.5,0.5]`) is still accepted, but it must be quoted
(`"[-0.5,0.5]"`): zsh, the default shell on macOS, otherwise stops with
`no matches found`. In Python, pass lists: `color_scale=["green", "white",
"orange"], color_scale_range=[-0.5, 0.5]`.

## Vcontacts engine and reproducibility

By default Vcontacts runs through `vcon-py`. Its C code gives the same geometry
as the `Vcontacts-v1-2.c` in the Surfaces repository, but it prints areas and
distances with **5 decimals instead of 2**. Results therefore differ slightly
from the published scripts. On the tutorial systems, the largest per-pair
difference is about 0.1 % of the largest interaction, and a few pairs near
zero appear or disappear. To reproduce the published numbers exactly, point
Surfaces at a binary compiled from the original source:

```python
surfaces.protein_protein(pdb, "ABC", "DEF", vcon_executable="./vcon")
```
```bash
surfaces surface_cont ... --vcon ./vcon       # or: export SURFACES_VCON=./vcon
```

See `validation/VALIDATION.md` for the full comparison.

## Citation and license

Released under the MIT License (see `LICENSE`). If you use Surfaces in
published work, please cite the article above (also in `CITATION.cff`).
The bundled FlexAID parameter files are under the Apache License 2.0
(see `src/surfaces/data/`).

## Tests

```bash
pip install "surfaces-py[test]" && pytest     # or: python tests/test_surfaces.py
```
