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, 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.

Installation

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

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>:

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:

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:

surfaces.protein_protein(pdb, "ABC", "DEF", vcon_executable="./vcon")

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

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