ProtACon.modules package¶

ProtACon.modules.attention module¶

Author: S. Chiarella

Define the functions for the extraction and processing of attention from the ProtBert model.

ProtACon.modules.attention.average_matrices_together(attention)¶

Average together the attention matrices independently for each layer.

First, average together the attention matrices independently for each layer, which are stored in attention_per_layer. Then, average together the attention matrices in attention_per_layer, and store them in model_attention_average.

Parameters:: attention (tuple[torch.Tensor, ...]) – The attention retuned by the model, cleared of the attention related to the tokens [CLS] and [SEP].
Returns:: attention_avgs – The averages of the attention masks independently computed for each layer and, as last element, the average of those averages.
Return type:: tuple[torch.Tensor, …]
Raises:: ValueError – If the input tensors have a number of dimensions different from 3 or 4.

ProtACon.modules.attention.clean_attention(attention)¶

Remove the part of attention relative to non-amino acid tokens.

If a tensor has a batch dimension, get rid of it – (n_heads, seq_len, seq_len) instead of (1, n_heads, seq_len+2, seq_len+2) –, otherwise just remove the first and last rows and columns.

Parameters:: attention (tuple[torch.Tensor, ...]) – The attention matrices returned by the model, including the attention related to the tokens [CLS] and [SEP].
Returns:: attention – The attention returned by the model, cleared of the attention related to the tokens [CLS] and [SEP].
Return type:: tuple[torch.Tensor, …]
Raises:: ValueError – If the input tensors have a number of dimensions different from 3 or 4.

ProtACon.modules.attention.compute_att_align_on_heads(attention, indicator_function)¶

Compute the attention alignment on the attention heads of the model.

The alignment is computed according to a property, represented with the binary map indicator_function. The tensors in the input tuple are the attention matrices in each layer – with or without the batch dimension.

Parameters:

attention (tuple[torch.Tensor, ...]) – The attention matrices returned by the model.
indicator_function (np.ndarray) – Binary map with shape (len(tokens), len(tokens)), representing one property of the peptide chain – returns 1 if the property is present, 0 otherwise.

Returns:

attention_alignment – Array with shape (n_layers, n_heads), storing the portion of attention that aligns with the indicator_function.

Return type:

np.ndarray

Raises:

ValueError – If the input tensors have a number of dimensions different from 3 or 4.

ProtACon.modules.attention.compute_att_align_on_layers(attention, indicator_function)¶

Compute the attention alignment of the model layers with a property.

The alignment is computed according to a property, represented with the binary map indicator_function. The tensors in the input tuple are the averages of the attention matrices in each layer.

Parameters:

attention (tuple[torch.Tensor, ...]) – The averages of the attention matrices in each layer.
indicator_function (np.ndarray) – Binary map with shape (len(tokens), len(tokens)), representing one property of the peptide chain – returns 1 if the property is present, 0 otherwise.

Returns:

attention_alignment – Array with shape (n_layers), storing the portion of attention that aligns with the indicator_function.

Return type:

np.ndarray

Raises:

ValueError – If the input tensors have a number of dimensions different from 2.

ProtACon.modules.attention.compute_attention_similarity(att_to_am_ac, am_ac)¶

Assess the similarity of the attention between couples of amino acids.

This is achieved by computing the Pearson correlation between the portion of attention that each amino acid receives across the heads. The diagonal obviously returns a perfect correlation (because the attention similarity between one amino acid and itself is total). Therefore, it is set to None.

Parameters:

att_to_am_ac (torch.Tensor) – Tensor with shape (len(am_ac), n_layers, n_heads), storing the attention given to each amino acid by each attention head.
am_ac (list[str]) – The single letter codes of the amino acids.

Returns:

att_sim_df – The attention similarity between each couple of amino acids.

Return type:

pd.DataFrame

ProtACon.modules.attention.get_amino_acid_pos(amino_acid, tokens)¶

Return the positions of a given amino acid along the list of tokens.

Parameters:

amino_acid (str) – The single letter amino acid code.
tokens (list[str]) – The complete list of amino acid tokens.

Returns:

amino_acid_pos – The positions of the tokens corresponding to amino_acid along the list tokens.

Return type:

list[int]

ProtACon.modules.attention.get_attention_to_amino_acid(att_column_sum, amino_acid_pos, n_heads, n_layers)¶

Compute the attention given from each attention head to one amino acid.

Parameters:

att_column_sum (list[torch.Tensor]) – (n_layers*n_heads) tensors, each with a length equal to the number of tokens, resulting from the column-wise sum over the attention values of each attention matrix.
amino_acid_pos (list[int]) – The positions of the tokens corresponding to one amino acid along the list of tokens.
n_heads (int) – The number of attention heads of the model.
n_layers (int) – The number of layers of the model.

Returns:

att_to_am_ac – Tensor with shape (n_layers, n_heads), storing the attention given to each amino acid by each attention head.

Return type:

torch.Tensor

ProtACon.modules.attention.include_att_to_missing_aa(amino_acid_df, L_att_to_am_ac)¶

Insert zero matrices to represent the missing amino acids.

Since the attention given to each amino acid is later used also for the attention analysis on more than one protein, it is necessary to fill the attention matrices relative to the missing amino acids with zeros. The items in L_att_to_am_ac are sorted by amino_acid_df[“Amino Acid”] – i.e., alphabetically by amino acid – but the data frame only includes the amino acids in the current chain. Therefore, I get the correspondence between the index of each amino acid in the data frame and the index of each amino acid in an alphabetically sorted list of all the possible amino acids. Finally, I fill a new list with the attention tensors in the right order – that will be important later on for computing the attention similarity.

Parameters:

amino_acid_df (pd.DataFrame) – Data frame with the amino acids, the occurrences and the positions in the list of tokens of the residues in a chain.
L_att_to_am_ac (list[torch.Tensor]) – Tensors with shape (n_layers, n_heads), each storing the attention given to one amino acid by each attention head.

Returns:

Tensor with shape (len(all_amino_acids), n_layers, n_heads), storing the attention given to each amino acid by each attention head.

Return type:

torch.Tensor

ProtACon.modules.attention.sum_attention_on_columns(attention)¶

Sum the values on the columns of each attention matrix.

It returns a tensor for each attention matrix, each with length equal to the number of columns, that is, the number of tokens.

Parameters:: attention (tuple[torch.Tensor, ...]) – The attention matrices returned by the model.
Returns:: att_column_sum – (n_layers*n_heads) tensors, each with a length equal to the number of tokens, resulting from the column-wise sum over the values of each attention matrix.
Return type:: list[torch.Tensor]
Raises:: ValueError – If the input tensors have a number of dimensions different from 3 or 4.

ProtACon.modules.attention.sum_attention_on_heads(attention)¶

Sum all the values of each attention matrix.

It returns a float number (the sum) for each attention matrix.

Parameters:: attention (tuple[torch.Tensor, ...]) – The attention matrices returned by the model.
Returns:: att_head_sum – Tensor with shape (n_layers, n_heads), resulting from the sum of all the values in each attention matrix.
Return type:: torch.Tensor
Raises:: ValueError – If the input tensors have a number of dimensions different from 3 or 4.

ProtACon.modules.attention.threshold_attention(attention, threshold)¶

Set to zero all the attention values below a given threshold.

Parameters:

attention (tuple[torch.Tensor, ...]) – The attention matrices returned by the model.
threshold (float) – The threshold below which the attention values are set to zero.

Returns:

thresholded – The attention matrices, but all the values below the threshold are set to zero.

Return type:

tuple[torch.Tensor, …]

ProtACon.modules.basics module¶

Author: S. Chiarella

This module defines:

the dictionaries for translating from multiple letter to single letter amino acid codes, and vice versa;
a list with the twenty canonical amino acids;
the definition of the CA_Atom class;
functions for extracting information from ProtBert and from PDB objects;
a function to fetch PDB entries according to some queries;
a function to download .ent – i.e., pdb – files;
a function for normalizing numpy arrays.

class ProtACon.modules.basics.CA_Atom(name, idx, coords)¶

Bases: object

A class to represent the alpha carbon (CA) atoms of the residues.

__init__(name, idx, coords)¶

Contructor of the class.

Parameters:

name (str) – The amino acid of the residue.
idx (int) – The position occupied by the residue within the primary structure of the peptide chain.
coords (np.ndarray) – The x-, y- and z- coordinates of the CA atom of the residue.

ProtACon.modules.basics.download_pdb(pdb_code, pdb_dir, download_url='https://files.rcsb.org/download/')¶

Download a PDB file from the Internet and save it to a directory.

I am defining my own function for the download because the function Bio.PDB.PDBList.retrieve_pdb_file() relies on the PDB FTP service, that may have issues with firewalls.

Parameters:

pdb_code (str) – The PDB code of the chain.
pdb_dir (pathlib.Path) – The directory where to save the PDB file.
download_url (str, default=”https://files.rcsb.org/download/”) – The URL to download the PDB file from.

Return type:

None

ProtACon.modules.basics.extract_CA_atoms(structure)¶

Get the alpha carbon (CA) atoms from a peptide chain.

Given a Structure, take the first chain. Then, look for the CA atoms (main carbon atom of each residue) and for each of them get:

the amino acids of the residue;
the position index in the chain;
the coordinates of the CA atom.

Finally, initialize a CA_Atom object with this information and append it to a list. Repeat for all the CA atoms in the chain and return the list as a tuple.

Parameters:: structure (Bio.PDB.Structure.Structure) – The object containing information about each atom of the peptide chain.
Returns:: The alpha carbon atoms of the residues in the peptide chain.
Return type:: tuple[CA_Atom, …]

ProtACon.modules.basics.fetch_pdb_entries(min_length, max_length, n_results, stricter_search=False)¶

Fetch PDB entries.

The query consists in returning proteins with a minimum and a maximum number of peptides in the structure. Keep only the number of results specified by n_results.

Parameters:

min_length (int) – The minimum number of peptides in the structure.
max_length (int) – The maximum number of peptides in the structure.
n_results (int) – The number of results to keep.
strict_proteins (bool, default=False) – If True, the search will exlude enzymes, transporters, inhibitors, etc.

Returns:

results – The list of PDB IDs.

Return type:

list[str]

ProtACon.modules.basics.get_model_structure(attention)¶

Return the numbers of heads and layers of ProtBert.

Parameters:

attention (tuple[torch.Tensor, ...]) – The attention matrices returned by the model, either “raw” or cleared of the attention related to the tokens [CLS] and [SEP].

Return type:

tuple[int, int]

Returns:

n_heads (int) – The number of attention heads of ProtBert.
n_layers (int) – The number of layers of ProtBert.

ProtACon.modules.basics.get_sequence_to_tokenize(CA_atoms)¶

Get the residue amino acids in a format suitable for tokenization.

Take the name attributes of the CA_Atom objects in the tuple and put them, separated with spaces, in a single string ready to be tokenized.

Parameters:: CA_atoms (tuple[CA_Atom, ...]) – The alpha carbon atoms of the residues in the peptide chain.
Returns:: sequence – The sequence of amino acids of the residues that make up the peptide chain.
Return type:: str

ProtACon.modules.basics.load_Bert(model_name)¶

Load the model and the tokenizer specified by model_name.

Parameters:

model_name (str) – The string with the name of the model to load.

Return type:

tuple[BertModel, BertTokenizer]

Returns:

model (BertModel) – The object storing the Bert model.
tokenizer (BertTokenizer) – The object storing the tokenizer for the Bert model.

ProtACon.modules.basics.normalize_array(array)¶

Normalize a numpy array.

Parameters:: array (np.ndarray)
Returns:: norm_array
Return type:: np.ndarray
Raises:: ValueError – If the input array is empty, has all NaN values, or has constant values.

ProtACon.modules.contact module¶

Author: S. Chiarella

Define the functions for the computation and processing of the contact map of a peptide chain.

ProtACon.modules.contact.binarize_contact_map(distance_map, distance_cutoff, position_cutoff)¶

Generate a binary contact map.

Two criteria, in form of thresholds, are applied to the distance map in order to get the binarized contact map:

Distance thresholding: 1 is set (i.e., a contact) if two residues are at a distance in the tertiary structure smaller than distance_cutoff; otherwise 0 is set.
Position thresholding: we want to keep only the contacts that rise from couples of residues which are close in terms of distance in the tertiary structure, but which are not so close in terms of their position along the peptide chain – that is, in the primary structure. Therefore, 1 is set (i.e., a contact) if two residues are separated by a number of residues larger than position_cutoff in the peptide chain; otherwise 0 is set.

Parameters:

distance_map (np.ndarray) – The distance in Angstroms between each couple of residues in the tertiary structure of the peptide chain.
distance_cutoff (float) – The threshold distance between two residues in the tertiary structure of the peptide chain, expressed in Angstroms.
position_cutoff (int) – The threshold distance between two residues in the primary structure of the peptide chain, represented with the number of other residues separating them.

Returns:

binary_contact_map – The contact map binarized using the two thresholding criteria.

Return type:

np.ndarray

ProtACon.modules.contact.distance_between_atoms(atom1_coords, atom2_coords)¶

Compute the distance in Angstroms between two atoms in the 3D space.

Parameters:

atom1_coords (np.ndarray) – The triplet of coordinates (x, y, z) of the first atom.
atom2_coords (np.ndarray) – The triplet of coordinates (x, y, z) of the second atom.

Returns:

norm – The distance in Angstroms between two atoms in the tertiary structure of the peptide chain.

Return type:

float

ProtACon.modules.contact.generate_distance_map(CA_Atoms)¶

Generate the distance map of a peptide chain.

It stores the distance in Angstroms between each couple of residues in the tertiary structure of the peptide chain.

Parameters:: CA_Atoms (tuple[CA_Atom, ...]) – The tuple of CA atoms of the residues in the peptide chain.
Returns:: distance_map – The distance in Angstroms between each couple of residues in the tertiary structure of the peptide chain.
Return type:: np.ndarray

ProtACon.modules.plot_functions module¶

Author: S. Chiarella

Define the plot functions of ProtACon (attention matrices, attention heatmaps, contact maps, etc.).

ProtACon.modules.plot_functions.find_best_nrows(n_am_ac)¶

Find the adequate number of rows to use in plt.subplots.

Parameters:: n_am_ac (int) – The number of amino acids in the peptide chain.
Raises:: ValueError – If the amino acids in the chain are more than twenty.
Returns:: nrows – The number of rows to use in plt.subplots.
Return type:: int

ProtACon.modules.plot_functions.plot_attention_matrices(attention, plot_title)¶

Plot the attention matrices.

Parameters:

attention (torch.Tensor or tuple[torch.Tensor, ...]) – The attention matrices to plot.
plot_title (str)

Return type:

None

ProtACon.modules.plot_functions.plot_attention_to_amino_acids_alone(attention_to_amino_acids, amino_acids, plot_dir, plot_title)¶

Plot the attention heatmaps for several amino acids in separate plots.

The heatmaps are filled with the values of attention given to each amino acid by each attention head. This function is used to plot the heatmaps representing the percentage of attention of each head given to each amino acid. Each heatmap is plotted separately and saved in a dedicated file, because the percentage represented makes sense only within one heatmap.

Parameters:

attention_to_amino_acids (torch.Tensor) – Tensor with shape (n_am_ac, n_layers, n_heads), storing the attention given to each amino acid by each attention head.
amino_acids (list[str]) – The single letter codes of the amino acids in the peptide chain or in the set of peptide chains.
plot_dir (pathlib.Path) – The path to the folder where to store the plots.
plot_title (str)

Raises:

ValueError – If plt.subplots has too many rows with respect to the number of amino acids in the chain.

Return type:

None

ProtACon.modules.plot_functions.plot_attention_to_amino_acids_together(attention_to_amino_acids, amino_acids, plot_path, plot_title)¶

Plot the attention heatmaps for several amino acids together.

The heatmaps are filled with the values of attention given to each amino acid by each attention head. This function is used to plot the heatmaps representing the percentage of total attention. They must be shown all together in one file, because the percentage represented makes sense only when all the heatmaps relative to the different amino acids are shown. This function is also used to plot the heatmaps representing the absolute attention given to each amino acid in the single peptide chains.

Parameters:

attention_to_amino_acids (torch.Tensor) – Tensor with shape (n_am_ac, n_layers, n_heads), storing the attention given to each amino acid by each attention head.
amino_acids (list[str]) – The single letter codes of the amino acids in the peptide chain or in the set of peptide chains.
plot_path (pathlib.Path) – The path where to store the plot.
plot_title (str)

Raises:

ValueError – If plt.subplots has too many rows with respect to the number of amino acids in the chain.

Return type:

None

ProtACon.modules.plot_functions.plot_bars(attention, plot_path, plot_title)¶

Plot a barplot.

Parameters:

attention (np.ndarray) – Data structure to plot, with shape (n_layers).
plot_path (pathlib.Path) – The path where to store the plot.
plot_title (str)

Return type:

None

ProtACon.modules.plot_functions.plot_distance_and_contact(distance_map, norm_contact_map, plot_path)¶

Plot the distance map and the normalized contact map side by side.

Parameters:

distance_map (np.ndarray) – The distance in Angstroms between each couple of residues in the tertiary structure of the peptide chain.
norm_contact_map (np.ndarray) – distance_map but in a scale between 0 and 1.
plot_path (pathlib.Path) – The path where to store the plot.

Return type:

None

ProtACon.modules.plot_functions.plot_heatmap(data, plot_path, plot_title)¶

Plot an sns.heatmap.

Parameters:

attention (pd.DataFrame or np.ndarray) – The data structure to plot, with shape (n_layers, n_heads) or (n_am_ac, n_am_ac).
plot_path (pathlib.Path) – The path where to store the plot.
plot_title (str)

Return type:

None

ProtACon.modules.utils module¶

Author: S. Chiarella

This module contains:

the definition of the class Logger;
the definition of a timer;
the definition of a loading animation.

class ProtACon.modules.utils.Logger(name, verbosity=0)¶

Bases: object

A class of objects that can log information to stdout.

__init__(name, verbosity=0)¶

Contructor of the class.

Parameters:

name (str) – The name to call the logger with.
verbosity (int, default=0) – The level of verbosity. 0 sets the logging level to WARNING, 1 to INFO and 2 to DEBUG.

get_logger()¶

Get a previously set logger.

Get from the Logger object with a given name, the attributes previously used to set the corresponding logger, in order to get the same logger.

ProtACon.modules.utils.Loading(message)¶

Run a loading animation.

Parameters:: message (str) – The text to print during the animation.
Return type:: Iterator[None]

ProtACon.modules.utils.Timer(description)¶

Run a timer.

Parameters:: description (str) – The text to print.
Return type:: Iterator[None]