ARCTIC-3D

PyPI - License PyPI - Status PyPI - Version PyPI - Python Version

Automatic Retrieval and ClusTering of Interfaces in Complexes from 3D structural information

WEB SERVER

ARCTIC-3D is available at this webserver https://wenmr.science.uu.nl/arctic3d/ (see the web server manual).

ARCTIC-3D: all you want to know about protein-specific interfaces

ARCTIC-3D is a software for data-mining and clustering of protein interface information. It allows you to retrieve all the existing interface information for your desired protein from the PDBE graph database (https://www.ebi.ac.uk/pdbe/pdbe-kb/), grouping similar interfaces in interacting surfaces.

The software first checks your input (a uniprot ID, a FASTA file, or a PDB file), and then retrieves the existing interaction data from the graph API. Such interfaces are projected on a selected PDB structure and their dissimilarity is calculated, thus allowing for the application of a hierarchical clustering algorithm.

In output you will see how your favourite protein can display different binding surfaces, each one characterised by few residues that are always present (hotspots) and other amino acids which are at the interface only from time to time.

Developing

Check CONTRIBUTING.md for more information.

Installation

ARCTIC-3D (Python 3.10 or later) is best installed in a virtual environment. Open a terminal and type

python3 -m venv .venv
source .venv/bin/activate
pip install arctic3d
arctic3d -h

To install from the source instead, clone the repository and run pip install . in it:

git clone https://github.com/haddocking/arctic3d.git
cd arctic3d
pip install .

To run BLAST locally

bash install_blast_deps.sh

And put blastp in your $PATH by adding the following line to your .bashrc or .bash_profile file:

export PATH="PATH_TO_YOUR_ARCTIC3D_INSTALLATION/src/ncbi-blast-2.15.0+/bin:$PATH"

Example usage

Please refer to the examples documentation page.

Documentation

The documentation is at https://www.bonvinlab.org/arctic3d. To build it locally:

pip install mkdocs-material
mkdocs serve

Result interpretation

After running ARCTIC-3D, results are stored in the output directory (default: arctic3d-{uniprot_id}/). Below is an explanation of each output file and how to interpret them.

Output files

File	Description
`arctic3d.log`	Log file with execution details and warnings
`input_data/`	Directory containing copies of input files
`{pdb_id}_updated.cif`	Structure file downloaded from PDBe (mmCIF format)
`{pdb_id}-{chain}.pdb`	Cleaned PDB structure used for analysis (renumbered to UniProt numbering)
`retrieved_interfaces.out`	All interfaces retrieved from PDBe, listing partner IDs and their residue lists
`interface_matrix.txt`	Pairwise dissimilarity values between all interfaces (used for clustering)
`dendrogram_{linkage}.png`	Hierarchical clustering dendrogram (e.g., `dendrogram_average.png`)
`clustered_interfaces.out`	Interfaces grouped into clusters (binding surfaces)
`clustered_residues.out`	Residues belonging to each cluster
`clustered_residues_probs.out`	Residues ranked by probability within each cluster
`{pdb_id}-{chain}_cl{N}.pdb`	PDB structure for cluster N with probabilities encoded in B-factor column
`sequence_probability.html`	Interactive bar plot of per-residue probabilities
`sequence_probability.json`	JSON data for the interactive plot
`report.html`	Report of the results with a Mol* view of the binding surfaces (turn off with `--no_report`)
`state.mvsj`	Mol* views shown in `report.html`
`arctic3d-localise-{type}/`	With `--biological_clustering`: annotations of the partners and a bar plot per cluster (`cluster_{N}.png`, `cluster_{N}.html`) for each type

Understanding the clustering

ARCTIC-3D groups similar interfaces into binding surfaces (clusters). Two interfaces are considered similar when they overlap spatially on the protein surface. The dissimilarity is measured using the squared sine of the angle between interface vectors in a Hilbert space representation - values close to 0 indicate overlapping interfaces, while values close to 1 indicate completely distinct regions.

The interface_matrix.txt file contains the pairwise dissimilarity values in the format:

interface1 interface2 dissimilarity_value

Interpreting residue probabilities

The probability (or "contact probability score") represents the fraction of interfaces within a cluster where a residue is observed. It is calculated independently for each cluster:

probability = (number of interfaces containing the residue) / (total interfaces in cluster)

For each cluster, residues are assigned a probability value between 0 and 1:

Probability = 1.0: The residue appears in every interface within the cluster (a "hotspot" residue)
Probability = 0.5: The residue appears in half of the cluster's interfaces
Probability close to 0: The residue rarely appears at this binding surface

Important: Probabilities do NOT sum to 1.0 across clusters for a given residue. A residue can have high probability in multiple clusters if it participates in different binding surfaces. For example, a residue with probability 0.8 in cluster 1 and 0.6 in cluster 2 means it appears in 80% of cluster 1's interfaces and 60% of cluster 2's interfaces.

The clustered_residues_probs.out file lists residues ranked by probability:

Cluster 1 : 15 residues
rank    resid   resname probability
1       42      ALA     1.000
2       45      GLU     0.875
...

Visualizing probabilities in PDB files

The output PDB files ({pdb_id}-{chain}_cl{N}.pdb) encode probabilities in the B-factor column:

Cluster residues: B = 50 × (1 + probability), ranging from 50 (probability=0) to 100 (probability=1)
Non-cluster residues: B = 0

This allows visualization in molecular viewers (PyMOL, ChimeraX, etc.) using a color spectrum where high B-factors (red) indicate hotspot residues and low values (blue) indicate residues not involved in that binding surface.

Interpreting the dendrogram

The dendrogram (dendrogram_average.png) shows the hierarchical relationship between all retrieved interfaces. The x-axis represents the dissimilarity between interfaces or groups. Interfaces that merge below the threshold (default: 0.866, corresponding to a 60° angle) form a single binding surface. The threshold can be adjusted with --threshold to obtain finer or coarser clustering.

Using the interactive plot

Open sequence_probability.html in a web browser to explore per-residue binding probabilities. Each cluster is shown as a separate colored bar series, allowing you to identify which residues are involved in which binding surface and compare hotspots across different clusters.

Viewing the report

report.html shows the binding surfaces on the structure (Mol*), with the cluster and residue tables, the dendrogram, the sequence plot and, with --biological_clustering, the bar plots of each clustering type. Browsers do not let a page opened from disk load the structure, so serve the output directory and open the report from there:

python -m http.server -d example/arctic3d-P00760

then open http://localhost:8000/report.html. Two example outputs are included: example/arctic3d-P00760, from arctic3d P00760 --biological_clustering location function process (trypsin; the interactive cluster_N.html bar plots are left out to keep the repository small), and example/arctic3d-1ppe_E, from arctic3d example/1ppe_E.pdb --interface_file example/1ppe_E_example_interfaces.txt (input PDB and interfaces).

Citing us

If you used ARCTIC-3D in your work please cite the following publication:

Marco Giulini, Rodrigo V. Honorato, Jesús L. Rivera, and Alexandre MJJ Bonvin: "ARCTIC-3D: automatic retrieval and clustering of interfaces in complexes from 3D structural information." Communications Biology 7, no. 1 (2024): 49. (www.nature.com/articles/s42003-023-05718-w)