Structural Bioinformatics Library
Template C++ / Python API for developping structural bioinformatics applications.
User Manual

Table of Contents

Multiple_interface_string_alignment

Authors: S. Bereux and F. Cazals

Goals: combining MSA and interface models

Multiple Sequence Alignments are pivotal to understand commonalities and differences between protein sequences. Likewise, interface models are pivotal to mine to stability and the specificity of protein interactions. Combining MSA and interface models yields Multiple Interface String Alignment (MISA), namely alignments of strings coding properties of a.a. found at protein-protein interfaces.

Assume the interface of a complex has been found – we do so using the package Space_filling_model_interface . MISA are a visualization tool to display coherently various sequence and structure based statistics for the residues found at this interface, on a chain instance basis. That is, a MISA primarily consists of annotations for chain instances. Currently supported annotations for are:

  • $\text{\misasse}$ : secondary structure elements (SSE)
  • $\text{\misabsa}$ : buried surface area (BSA),
  • $\text{\misadasa}$ : variation of the solvent accessible area,
  • $\text{\misabfactor}$ : B factor values.

The benefit of MISA are:

  • to collate annotated sequences of (homologous) chains
  • to allow for a comparison of properties of chains found in different biological contexts i.e. bound with different partners, but also unbound. In particular, the aggregated views $\text{\misasse}$, $\text{\misabsa}$, $\text{\misadasa}$ etc make it trivial to identify commonalities and differences between chains, to infer key interface residues, and to understand where conformational changes occur upon binding.
The logo of the package illustrates the two central objects used thereafter: (Top) the Voronoi interface (green polygons) shared by two proteins, and (Bottom) the multiple sequence alignment of selected amino-acids – those found at the interface, colored with biological / biophysical properties.


Pre-requisites

Terminology


MISA id. A complex $C_i$ is specified by two sorted lists of chains ids i.e. $C_i = ( \{ A_j\}, \{ B_j\})$ for the two partners $A$ and $B$ defining the complex. For the sake of exposure, we also assume each partner is given a structure name (e.g. antibody or antigen or ...).

Likewise, an unbound structure is specified by a sorted list of chain ids $U_i = \{ A_j \}$. We consider a collection of complexes $\calC = \{ C_i\}$, and optionally a collection of unbound structures $\calU = \{ U_i \}$. The minimal setup is naturally that of a single complex without any unbound structure.

Our goal is two build one MISA for each so-called MISA id, which we formally define as:

The MISA id of a chain involved in the specification of a complex is the string defined by the structure name followed by the index of the chain in its sorted list ${A_j}$ or ${B_j}$.


Note that because of th sortedness, a given chain gets the same MISA id in a complex or unbound structure.

Consider two antibody-antigen complexes. $C_1 = ( {H, L}, {A} ), C_2 = ( {M, N}, {B} )$, each involving the heavy chains (chains H and M), the light chains (chains L and N), and the antigen (chains A and B). The two structure names are thus antibody (IG for short) and antigen (Ag for short). The MISA id of the heavy chain is IG_0, that of the light chain IG_1, and that of the antigen Ag_0.


MISA


Interface strings (i-strings). In the sequel, we present MISA informally. We represent each instance with a so-called interface string encoding properties of amino acids found interfaces involving that chain. The interface string of a chain instance is a character string with one character per residue, and is actually defined from all instances with the same MISA id. To build this character string, we first define:

The consensus is the set of aa defined from all Voronoi interfaces of all complexes in the set $\calC$. At each position of the consensus interface, the most frequent residue observed in all the bound structures is chosen as the consensus residue, with ties broken using the alphabetical order (of the 1-letter code of a.a.)


Using this consensus interface, the residues of a given chain instance (bound or unbound) are displayed as follows:

The interface string (i-string) of a chain instance is the string with one character per amino acid, defined as follows:
  1. Residue not part of the consensus interface :
    1. Displayed with a dash "-" if it is part of the crystal structure, underscore "\_" otherwise.
  2. Residue part of the consensus interface:
    1. Residue not found in the crystal structure: displayed with the star '*'.
    2. Residue found at the interface for this particular chain: displayed with the uppercase one letter code if the a.a. matches the consensus a.a., or with the lowercase letter otherwise.
    3. Residue not found at the interface for this particular chain, even though the corresponding position contributes to the consensus interface: displayed in an italicized font. (Note that this is the case for all residues of unbound structures, as no partner implies no interface.)


Finally, assembling i-strings yields MISA:

The MISA of all chain instances with the same MISA id is the multiple alignment of their interface strings.


Colored MISA

A colored MISA is a plain MISA whose 1-letter code of a.a. are colored using specific biological / biophysical properties:

$\text{\misasse:}$ coloring based on Secondary Structure Elements The type of SSE a given a.a. belongs to is especially useful when comparing bound and unbound structures, to assess perturbations in the hydrogen bonding network. Practically, we use the dictionary of SSE from ~[102] .

$\text{\misabsa}$: coloring based on Buried Surface Area. Consider a chain instance in a complex. The BSA of this chain is defined as the accessible surface area (ASA) [149] of this chain in the partner alone minus the ASA of the chain in the complex. We report the BSA on a per residue basis, computed using the algorithm from [43].

$\text{\misadasa}$: coloring based on the variation of accessible surface area.

A limitation of the BSA is that its calculation uses the geometry of the bound structure only. The calculation is thus oblivious to conformational changes which may be at play in case of induced fit or conformer selection. To mitigate the previous plot, we also provide a the so-called $\text{\Dasa}$ coloring scheme.

Consider an interface partner $P (=A \text{ or } B)$, in the complex, and consider the i-th residue of one of its chains. Let $ASA^{b}_i$ be the ASA of the i-th residue in the structure involving only those chains of partner $P$. Also denote $\overline{ASA}^u_i$ the average ASA of the i-th residue in unbound structures containing chains identical to those of partner $P$. We compute for the i-th residue of a bound structure the quantity $ASA^b_i-\overline{ASA}^u_i$ and display it with a color map.

$\text{\misabfactor}$: coloring based on B-factors.

The B-factors reflects the atomic thermal motions. Selected recent crystal structures report this information as a 3x3 ANISOU matrix (the anisotropic B-factor). In order to have a single quantity for all the crystals, the ANISOU matrix $B_{anisou}$ is converted into B-factor thanks to the formula $B_{factor} = \text{trace}(B_{anisou})/3$ [177] .

Optionally, one can choose to normalize the B-factor with respect to (i) all the residues in the chain, or (ii) all the displayed residues.

Using Multiple_interface_string_alignment

The package actually provides four complementary scripts:

  • $\text{\sblmisapy}$: building MISA from a description of structures.
  • $\text{\sblmisamixpy}$: mixing selected colored MISA into a single (html) file.
  • $\text{\sblmisabsapy}$: post-processing the output of interface model and perform statistics on the BSA of selected specified residues.
  • $\text{\sblmisadiffpy}$: comparing i-strings and associated properties (in particular BSA) of two interfaces. Has two modes: comparing two i-strings; comparing one i-string and a list of interface residues typically coming from a publication.

The reader is referred to section Dependencies and Installation for installation related issues.

In the following, we briefly specify the entry of the scripts provided by this package, and refer the reader to the jupyter notebook of use cases.

Main script: sbl-misa.py

$\text{\sblmisapy}$

This is the main script computing (colored) MISA.


Specification file. The link between Voronoi interfaces and interface strings is done by providing a list of so-called Interface string specifications:

Given a PDB file, the interface string specification of a chain is the four-tuple:
  • intervor-partner-id: letters in tandem (A or B, or C or D, etc)
  • chain-name: the character specifying the chain instance in the PDB file.
  • structure-name: a string used to identify homologous structures.
  • tag: a string providing extra information - annotations.


We note that the tag ie string providing extra information is a placeholder to accommodate any relevant information. It should contain only alphanumerical characters, without blank spaces or special characters. For example, the tag may specify a feature (eg open or close) qualifying the crystallized conformation of the chain X.

Such interface string specifications are possibly enriched by specifying windows, ie a list of ranges of amino acids of interest – to be use to restrict the display.

Here is an illustration for the first example provided in the jupyter notebook:

# Windows for ACE2-bound-to-SARS-CoV-1
[ACE2-bound-to-SARS-CoV-1_0 (19, 83) (321,393)]
./pdb/2ajf.pdb (A, E, SARS-CoV-1-RBD, bound) (B, A, ACE2-bound-to-SARS-CoV-1, bound)
./pdb/2ajf.pdb (A, F, SARS-CoV-1-RBD, bound) (B, B, ACE2-bound-to-SARS-CoV-1, bound)
./pdb/5x58.pdb (A, A, SARS-CoV-1-RBD, unbound-closed)
./pdb/6crz.pdb (A, C, SARS-CoV-1-RBD, unbound-closed)
# Specification for SARS-CoV-2
./pdb/6m0j.pdb (C, E, SARS-CoV-2-RBD, bound) (D, A, ACE2-bound-to-SARS-CoV-2, bound)
./pdb/6lzg.pdb (C, B, SARS-CoV-2-RBD, bound) (D, A, ACE2-bound-to-SARS-CoV-2, bound)
./pdb/6vxx.pdb (C, A, SARS-CoV-2-RBD, unbound-closed)
./pdb/6vyb.pdb (C, A, SARS-CoV-2-RBD, unbound-closed)


Main options. The main arguments of the script $\text{\sblmisapy}$ are:

  • spec file, denoted ifile as just described.
  • a directory $\text{\texttt{pdir}}$ to store the output of the parsing of the files generated by $\text{\sblintervorabw}$.
  • a directory, $\text{\texttt{odir}}$ to store the created MISA.
  • a string $\text{\texttt{prefix}}$ which is added at the beginning from the output filenames.
  • a directory $\text{\texttt{rdir}}$ to store the output of the i-RMSD computations.

The script $\text{\sblmisapy}$ also requires some additional input data, which can either be re-computed, or directly provided by the user:

  • a directory $\text{\texttt{idir}}$ : If the option $\text{\texttt{--no\_intervor}}$ is provided, directory expected to contain the output files produced by $\text{\sblintervorabw}$. (Nb: $\text{\sblintervorabw}$ run with $\text{\texttt{--output-prefix}}$.) Otherwise, directory to be created to host the files generated by $\text{\sblintervorabw}$.
  • a directory $\text{\texttt{vdir}}$ : If the option $\text{\texttt{--no\_vorlume}}$ is provided, directory expected to contain the output files produced by $\text{\sblvorlumepdb}$. (Nb: $\text{\sblvorlumepdb}$ run with the option $\text{\texttt{--output-prefix}}$) should be located. Otherwise, where to create the files generated by $\text{\sblvorlumepdb}$.

Mixing colored MISA: sbl-misa-mix.py

$\text{\sblmisamixpy}$


Specification file. The MISA id and coloring as well as the location of the individual files must be provided. These three pieces of information are provided thanks to a specification file, organized in three lines. Each line begins by a tag which indicates the information type provided on the line :

  • The first line indicates the path to the directory(ies) containing the figures to be gathered : $\text{\texttt{location (path\_to\_MISA\_directory\_1, path\_to\_MISA\_dir\_2,...)}}$
  • The second line indicates the MISA ids to gather : $\text{\texttt{misa\_id (MISA\_id\_1, MISA\_id\_2, ...)}}$
  • The third line indicates the coloring(s) to display : $\text{\texttt{coloring (coloring\_1, coloring\_2, ..)}}$

Here is an illustration for the first example provided in the jupyter notebook:

# List of input directories
localisation (./misa-RBD-ACE2-cmp/MISA)
# List of MISA_chain_ids
misa_chain_id (SARS-CoV-1-RBD_0, SARS-CoV-2-RBD_0)
# List of colorings of interest
coloring (SSE, BSA, Delta_ASA)


Main options. Summarizing, here are the main input arguments of the script $\text{\sblmisamixpy}$:

  • a spec file $\text{\texttt{mix\_ifile}}$ as just described.
  • a directory $\text{\texttt{odir}}$ to store the created mixed figure.
  • a string $\text{\texttt{prefix}}$, which is added at the beginning from the output filenames.

BSA: sbl-misa-bsa.py

The script $\text{\sblmisabsapy}$ displays the BSA of all (or selected user defined) residues.


Specification file. By default, all residues are processed. A specification file can also be provided to $\text{\sblmisabsapy}$ to specify selected residues.

(residue identifier) Given an $\text{\texttt{.xml}}$ file containing the buried surface area from intervor, we call residue identifier the 3-tuple containing :
  • intervor-partner-id: A or B
  • chain-name: the character specifying the chain instance in the original PDB file
  • index of the residue in the chain


The specification file then consists of a list of residue identifiers: $\text{\texttt{[ residue identifier 1, residue identifier 2...]}}$

By default, in the absence of such a specification file, the BSA of every residue (with a BSA greater than or equal to 0.01) is displayed.

Here is an illustration for the first example provided in the jupyter notebook:

[(A, E, 303), (A, E, 403), (A, E, 449), (A, E, 455), (A, E, 486), (A, E, 502), (B, A, 79), (B, A, 35)]


Main options. The main options are:

  • a spec file $\text{\texttt{specfile}}$ as just described.
  • an .xml file $\text{\texttt{xmlfile}}$ produced by $\text{\sblintervorabw}$ containing the BSA data.
  • a directory $\text{\texttt{odir}}$ to store the output : if not provided, the result will be dispayed in the command line.

MISA diff: sbl-misa-diff.py

The script $\text{\sblmisadiffpy}$ compares the i-strings and associated properties (in particular BSA) of two interfaces.

$\text{\sblmisadiffpy}$ needs a specification file $\text{\texttt{specfile}}$ with two lines. Each of them contains the specification of one interface. There are two possible ways to specify an interface in this $\text{\texttt{specfile}}$.


Automatic interface specification file. The first consists of extracting it from the $\text{\sblmisapy}$ output. One must then specify the following 3-tuple: which gives : $\text{\texttt{(MISA directory, PDBID, chain-name)}}$

  • MISA directory containing the chain in question
  • PDBID of the original PDB file
  • chain-name : character specifying the chain instance in the original PDB file

Here is an illustration for the first example provided in the jupyter notebook, which uses both specifications:

(./misa-RBD-ACE2-cmp/MISA/raw-data, 2ajf, E)
(./misa-RBD-ACE2-cmp/SARS-CoV-1-RBD-Harisson-2005.txt)


Manual interface specification. The second consists of enumerating the interface in a $\text{\texttt{interface-file}}$ (def def-interface-file ) whose format is detailed in the following paragraph). One must then indicate in the $\text{\texttt{specfile}}$ : $\text{\texttt{(interface-file)}}$.

(short-residue-spec) We call short-residue-spec the compact specification of a residue, composed of the nature of the residue (written in the one-letter code), denoted by N, joined to its index in the protein sequence, denoted by XXX, which gives NXXX.


Using this compact residue specification, one can manually specify an interface in an $\text{\texttt{interface-file}}$:

(interface-file) An interface-file is a $\text{\texttt{.txt}}$ file, organized as follows:
  • First line: Name of the chain
  • Each of the following lines: one short-residue-spec (def def-short-res-spec ) per line


Here is an illustration for the $\text{\texttt{interface-file}}$ corresponding to the first example in the jupyter-notebook:

harisson-interface
T402
R426
Y436
Y440
Y442
L472
N473
Y475
N479
Y484
T486
T487
G488
Y491


Main options. Summarizing, here are the main input arguments of the script $\text{\sblmisadiffpy}$:

  • a spec file $\text{\texttt{specfile}}$ as just described.
  • a directory $\text{\texttt{odir}}$ to store the output.

Algorithms and Methods

The analysis provided by the previous scripts involve the following seven steps:

  • Step 1 : Parsing the input : Parse the specification file and gather the structural data processed

    • Main classe(s): SBL::Multiple_interface_string_alignment::MISA_preprocessor

  • Step 2 : Constructing the MISA: Initializing the MISA by gathering the chains with the same MISA id and aligning them

  • Step 3 : Coloring the MISA: Collecting the coloring values and attributing the coloring to each chain of the MISA

  • Step 4 : Recording the cMISA: recording the colored MISA into an HTML file presenting simultaneously the four colorings

  • Step 5 : Construction of the PDB interface files: storing the interface residues shared by each pair of chain into PDB files

    • Main classe(s): SBL::Multiple_interface_string_alignment::Extract_PDB_interface

  • Step 6 : Computation of the i-RMSD for each pair of chain: computing the iRMSD for each pair of PDB interface files

    • Main classe(s): SBL::Multiple_interface_string_alignment::Compute_interface_iRMSD_for_pairs

  • Step 7 : Analysis of the interface RMSD (i-RMSD): clustering the chains according to the iRMSD and recording statistics on the iRMSD

    • Main classe(s): SBL::Multiple_interface_string_alignment::Plot_tools

Overview of sbl-misa.py

Dependencies and Installation

Dependencies and installation of packages outside the SBL

Dictionary of Secondary Structures (DSSP). DSSP [102] : DSSP . The package DSSP is used to infer the type of secondary structure element a given aa belong to. The program mkdssp used is described here; one may also consult directly the source code. executable: $\text{\codecx{mkdssp}}$

DSSP is provided by package managers. For example, it is easily installed as follows under Fedora 

dnf install dssp.x86_64


Multi Sequence Alignment. We compute Multi Sequence Alignment with ClustalOmega [161] To install ClustalOmega, proceed as indicated on the web site ClustalOmega .


Python packages. The following python packages are used:

All of them are easily installed as follows: 

pip3 install biopython numpy scipy pandas matplotlib weasyprint seaborn

Dependencies and installation of packages from the SBL

We first list the required packages from the SBL, and then detail the two options supported to install these packages.


List of SBL packages. The computation of MISAs uses the following packages from the SBL:

  • Parsing XML files to collect interface atoms: package PALSE


Installation using package managers. One can install the executables and python scripts available within packages using package managers , (dnf or rpm under Linux Fedora). In short:

> dnf install sbl-VERSIONNUMBER-Linux-apps.rpm
> dnf install sbl-VERSIONNUMBER-Linux-scripts.rpm


Installation upon git cloning the SBL. As explained in the installation guide, one can git clone the SBL, and compile the whole library, or more specifically the packages required, namely Space_filling_model_interface, Buried_surface_area and Space_filling_model_surface_volume.

To clone the SBL, proceed as indicated here. To compile the SBL or the required packages, follow the Compilation and installation .


Remark. Whatever the installation method used, make sure all executables and python scripts are visible from one's PATH environment variable.

Jupyter demo

See the following jupyter notebook:

  • Jupyter notebook file
  • Multiple_interface_string_alignment