RESDY

Extensive featurisation toolkit of protein sidechain structure and properties for classification tasks.

Introduction

This toolkit is subdivided in a set of classes that together operate as a pipeline enabling the rapid featurisation of aminoacids from collections of protein structures. Features and associated protein metadata can be explored with dedicated analysis and visualisation tools. In short, the pipeline will:

• Identify PDB or AlphaFold files from UNIPROT codes (see Uniprot class). UNIPROT codes are either:

  • associated with an organism
  • provided manually
  • contained in an input CSV file

• download and curate each identified PDB file (see PDB class). Results are saved in the CSV file result\proteins.csv. Curation operations offer optional operations including:

  • removal of user-defined HETATM, ions, and water molecules
  • reversion to modified aminoacid to their wild type counterpart
  • saving alternate conformations (e.g., NMR ensemble) in individual files
  • saving alternate side chain rotamers in individual files
  • addition of missing regions, if their size falls within a user-defined length
  • application of biomatrix operations
  • energy minimization

• calculate a set of features for every amino acid of interest in every curated structure. A range of features comes pre-implemented (see Measure class), but the user can also include own-designed features. Results are saved in the CSV file result\measures.csv.

• Aggregate data, and produce informative plots on their distribution via an interactive interface.

Installation

RESDY needs biobox 2.0 or later (older versions, including the 1.x releases, are not compatible). Install it first, then clone the repository and install RESDY from its root:

conda install -c conda-forge "biobox>=2.0"
git clone https://github.com/Degiacomi-Lab/RESDY.git
cd RESDY
pip install -e .

The -e flag means an edit to a file under src/resdy/ takes effect on the next import, with no reinstall. Drop it for a normal install. This pulls in the required dependencies listed below, and makes the package importable from any working directory.

Several of the features rely on external programs rather than on Python packages, and are listed in the Optional table below. To check the installation:

python -c "import resdy; print(resdy.__version__)"

Dependencies

Required

The following required dependencies are installed by pip install -e ., and are needed to run the overall pipeline:

• numpy
• pandas
• biobox (2.0 or later; pip install -e . checks for it but cannot install it, see Installation)
• matplotlib
• seaborn

There are also a couple of other required packages for running this pipeline and must be added by hand:

• Modeller (conda, salilab channel) is needed to patch gaps in a structure, without it all protein curation is unavailable significantly limiting output.
• Openmm (conda, conda-forge channel) is needed if energy minimisation of structures is requested within the pipeline, this is determined by setting the minimise_strucs parameter in RD.PDB

Note Installation of Modeller requires a license key: https://salilab.org/modeller/registration.html. Note: there are issues with Modeller version 10.3, but any more recent version works correctly.

Optional

Features denoted in the table below with specific package requirements or programme installations may not be available unless manually added to the working environment. A feature whose dependency is absent is skipped, with a message on the console, rather than stopping the run.

Feature	Methods	Requirements	Where to find
pKa	PROPKA3	propka	anaconda
	pKaANI	pKaANI	pKaANI GitHub Repository
Depth	Biopython	Biopython	anaconda
		MSMS	from this website anaconda
Solvent Accessible Surface Area	Biobox	no extra requirements
Atomic Environment Vectors	ANI-2x	ase	anaconda
		torch	anaconda
		torchani	anaconda
		cuaev (optional: for gpu accelerated calculation)	GitHub Repository
Dynamically Accessible Surface	Biobox	no extra requirements
Sequence Charge	Biobox	Biopython	anaconda
Curvature, Writhing, Torsion, arc_length, phi, psi	Melodia	Melodia-py	GitHub Repository or pip
Frustration, density	Frustratometer	Frustratometer	GitHub Repository
		openmm	anaconda
		pdbfixer	anaconda
15N NMR shift	Legolas	Legolas	Follow the installation instructions at GitHub repo.
Flexibility	Biobox	no extra requirements
Root Mean Square Fluctuation	Biobox	no extra requirements
Evolution	ESM	Fair-ESM	fair-esm
Secondary Structure	Biobox	Biopython	anaconda
		DSSP	DSSP
Legolas (15N nmr prediction)	Legolas	Legolas	Install through their GitHub

If running the Jupyter notebook resdy.ipynb (pip install -e ".[notebook]"), additional dependencies are:

• plotly
• nglview
• jupyter

Usage

After installation, the package is usable as follows.

import resdy as RD

UP = RD.Uniprot()

Uniprot, PDB, Measure, Analysis, Preprocessing, Aggregation and Viewer are reachable straight from the package.

• A tutorial demonstrating the pipeline main functionalities is provided in the notebook resdy.ipynb.
• The API reference is hosted on Read the Docs: resdy.readthedocs.io. It documents each of the five pipeline steps in turn, together with a page per pre-implemented feature and a FAQ.

Technical Notes

• The Uniprot class (src/resdy/uniprot.py) is used to handle the collection of structural information for required proteins by mining the UNIPROT database. There are multiple ways to use this:

  • from_csv_file() function allow you to pass a list of UNIPROT codes as a csv to mine. Respective headers for the file should be from: 'Uniprot_Entry', PDB_Code', 'Resid'. 'Uniprot_Entry' is the only required column. Add data in 'PDB_Code' if you only require a specific PDB file from this protein. 'Resid' allows you to note a specific residue of interest within this protein, can be used for later analysis.
  • get_protein_data() function allows you to pass a UNIPROT code directly as a function input
  • count_organism_proteins() function allows you to pass a code for a whole proteome and extract information about all the proteins within this.

• The Protein class (src/resdy/protein.py) is used to handle extracting PDB and AlphaFold files for proteins specified within the Uniprot class. Structures are downloaded and patched to ensure good quality structures as used for calculations.

• The Measure class (src/resdy/measure.py) has been implemented to facilitate the addition of new measurable features. This is done by implementing a new measuring class in a new file, saved in the src/resdy/features folder.

• The Analysis class (src/resdy/analysis.py) is responsible for aggregating the data (calculating mean, std, range for the feature of each residue of interest), scrape GO Terms from the Uniprot Database for each protein.

  • Analysis class takes the Measure.df pandas dataframe as the input.
  • method aggregate will aggregate data and calculate descriptive statistics for each residue of interest. The resulting dataframe will be stored in self.df_aggregated.
  • method relative_best will aggregate data in a way that aims to find the row of measurements for each subset of data based on Uniprot_Entry and Resid number key, that has the best relative statistics. Eg balance of smallest depth and propka values, but biggest value for das. Weights can be passed to bias the decision towards specific features. The resulting dataframe will be stored in self.df_sub.
  • method Go_get_data will extract GO Terms associated with each distinct residue of interest from the Uniprot Database. This operation is sped up by applying multi-threading. The data will be stored in a dictionary (GO ID: a list of uniprot codes).

• The Viewer class (src/resdy/viewer.py) can integrate different functionalities all together in an interactive plot.

  • Viewer class takes an instance of the Analysis class as the input.
  • method enrichment_analysis will do identify if there is any GO Term gets enriched within a group of proteins. The process of the enrichment analysis is: (1) for each GO Term, calculate an contingency table (2) compute the p-value for that contigency table and obtain a list of p-values in the end (3) adjust these p values using BH method to correct possible false postives.
  • method advanced_plot can make the interactive plot that integrates the scatter plot, enrichment analysis, and 3D visualisation of protein structures all together.
  • Note: the 3D visualisation requires downloaded PDB files.