Skip to main content

ARCTIC-3D

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

ci Codacy Badge Codacy Badge

DOI SQAaaS badge shields.io fair-software.eu

SQAaaS badge

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)

Metadata

Release files for arctic3d 0.7.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for arctic3d 0.7.1
File Size Uploaded Provenance Actions
arctic3d-0.7.1.tar.gz 6.1 MB Without provenance Details for arctic3d-0.7.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for arctic3d 0.7.1
File Interpreter ABI Platform Actions
arctic3d-0.7.1-py3-none-any.whl Python 3 none any Details for arctic3d-0.7.1-py3-none-any.whl

Total release size: 6.2 MB

Release files / arctic3d-0.7.1.tar.gz

Download URL arctic3d-0.7.1.tar.gz
Size 6.1 MB
Tags Source
SHA-256 checksum
How to use checksums
739739a4707e1294fb013efa490e46b7937878d10bf77b6a42a24f5ba737ff3d
BLAKE2b-256 checksum
How to use checksums
36cca7e754bc4d208eb4b37a96eaa4de8f9fbf712729fed78f6b1928f3a3f5b0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / arctic3d-0.7.1-py3-none-any.whl

Download URL arctic3d-0.7.1-py3-none-any.whl
Size 54.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
c77fcb5eb695df68f310b3985be24e3f2a0f0a2ed773fa4a9c880640333c2d78
BLAKE2b-256 checksum
How to use checksums
62716c0c57c25ceecd6284794a90f5f66d629abe989e6d8e2a6a4cdbc9681226
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for arctic3d 0.7.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page