ProtACon package¶

Subpackages¶

ProtACon.modules package

ProtACon.align_with_contact module¶

Author: S. Chiarella

Compute the attention alignment with the contact map of one peptide chain. The pairwise attention similarity is computed, too. The user can also choose if to plot and save those quantities for every single protein in the set.

ProtACon.align_with_contact.main(attention, CA_atoms, chain_amino_acids, att_to_aa, seq_ID, save_opt)¶

Compute the attention alignment with the contact map for one chain.

Compute the alignment of the attention matrices with the contact map for the peptide chain identified with seq_ID. Pairwise attention similarity is computed, too. Both those quantities can be plotted and saved.

Parameters:

attention (tuple[torch.Tensor, ...]) – The attention matrices returned by the model, cleared of the attention related to the tokens [CLS] and [SEP].
CA_atoms (tuple[CA_Atom, ...]) – The alpha carbon atoms of the residues in the peptide chain.
chain_amino_acids (list[str]) – The single letter codes of the amino acid in the peptide chain.
att_to_aa (torch.Tensor) – Tensor with shape (len(all_amino_acids), n_layers, n_heads), storing the absolute attention given to each amino acid by each attention head.
seq_ID (str) – The alphanumerical code representing uniquely the protein.
save_opt (str) – One between (‘none’, ‘plot’, ‘csv’, ‘both’). If ‘plot’ or ‘both’, save the plots of every single chain.

Return type:

tuple[ndarray, ndarray]

Returns:

head_att_align (np.ndarray) – Array with shape (n_layers, n_heads), storing how much attention aligns with indicator_function for each attention matrices.
layer_att_align (np.ndarray) – Array with shape (n_layers), storing how much attention aligns with indicator_function for each average attention matrix computed independently over each layer.

ProtACon.compute_on_set module¶

Author: S. Chiarella Date: 2024-08-14

Given a set of peptide chains, compute and save:

the percentage of total attention given to each amino acid;
the percentage of total attention given to each amino acid, weighted by the occurrences of that amino acid in all the proteins of the set;
the percentage of attention of each head given to each amino acid;
the global attention similarity between each couple of amino acids;
the attention-contact alignment in the attention heads, averaged over the whole set of proteins;
the attention-contact alignment across the layers, averaged over the whole set of proteins.

ProtACon.compute_on_set.main(tot_amino_acid_df, tot_att_head_sum, tot_att_to_aa, tot_head_att_align, tot_layer_att_align, sample_size)¶

Compute and save several quantities on a set of proteins.

Compute the attention to the amino acids, the global attention similarity and the average attention alignment over the whole set of proteins.

Parameters:

tot_amino_acid_df (pd.DataFrame) – The data frame - with len(chain_amino_acids) - to store the amino acids in each peptide chain and the occurrences of each of them.
tot_att_head_sum (torch.Tensor) – The tensor - with shape (n_layers, n_heads) - storing the total values of the sums of all the values of attention in each head.
tot_att_to_aa (torch.Tensor) – The tensor - with shape (len(chain_amino_acids), n_layers, n_heads) - to store the total values of the attention given to each amino acid.
tot_head_att_align (np.ndarray) – The array - with shape (n_layers, n_heads) - storing the total values of the attention alignment for each head.
tot_layer_att_align (np.ndarray) – The array - with shape (n_layers) - storing the total values of the attention alignment for each layer.
sample_size (int) – The number of proteins in the set.

Return type:

tuple[tuple[Tensor, Tensor, Tensor], DataFrame, tuple[ndarray, ndarray]]

Returns:

tuple[torch.Tensor, torch.Tensor, torch.Tensor] –

PT_att_to_aa
The percentage of total attention given to each amino acid in the whole set of proteins.

PWT_att_to_aa
The percentage of total attention given to each amino acid in the whole set of proteins, weighted by the occurrences of that amino acid along all the proteins.

PH_att_to_aa
The percentage of attention of each head given to each amino acid, in the whole set of proteins.
glob_att_sim (pd.DataFrame) – The attention similarity between each couple of amino acids in the whole set of proteins.
tuple[np.ndarray, np.ndarray] –

avg_head_att_align
The head attention alignment averaged over the whole protein set.

avg_layer_att_align
The layer attention alignment averaged over the whole protein set.

ProtACon.config_parser module¶

Author: S. Chiarella

Configuration parser.

class ProtACon.config_parser.Config(file_path)¶

Bases: object

A class of objects that can read data from a configuration file.

__init__(file_path)¶

Contructor of the class.

Parameters:: file_path (pathlib.Path) – The path to the configuration file.
Return type:: None

get_cutoffs()¶

Get the configuration parameters for the cutoffs.

Return a dictionary with the cutoffs for thresholding the attention matrices and for binarizing the contact map.

Returns:: The identifier and the cutoffs for the corresponding thresholdings.
Return type:: dict[str, float | int]

get_paths()¶

Get the configuration parameters for the paths.

Return a dictionary with the paths to folders to store the files.

Returns:: The identifier and the paths to the corresponding folder.
Return type:: dict[str, str]

get_proteins()¶

Get the configuration parameters for the set of proteins.

Return a dictionary with either the codes representing the proteins to run the experiment, or the parameters to fetch the codes from PDB.

Returns:: The identifier and the list of protein codes, the min and the max length that a protein can have, the minimum number of actual residues and the protein sample size.
Return type:: dict[str, str | int]

ProtACon.manage_tot_ds module¶

Author: S. Chiarella Date: 2024-09-25

Create and operate with the data structures that store the sums of the quantities computed for each peptide chain:

the data frame with the amino acids in each peptide chain, storing the occurrences of each amino acid;
the tensor to store the total values of the sums of all the values of attention in each head;
the tensor to store the total values of the attention given to each amino acid;
the array to store the total values of the attention alignment for each head;
the array to store the total values of the attention alignment for each layer.

ProtACon.manage_tot_ds.append_frequency_and_total(tot_amino_acid_df)¶

Add the amino acid relative frequencies and the total occurrences.

Compute and add to the data frame the percentage frequency of each amino acid over the whole set of proteins, and the total number of residues in the set.

Parameters:: tot_amino_acid_df (pd.DataFrame) – The data frame with len(all_amino_acids) storing the amino acids in each peptide chain and the occurrences of each of them.
Returns:: tot_amino_acid_df – The data frame with length len(all_amino_acids) storing the amino acids in each peptide chain and the occurrences of each of them, the percentage frequency of each amino acid over the whole set of proteins, and the total number of residues in the set.
Return type:: pd.DataFrame

ProtACon.manage_tot_ds.create(n_layers, n_heads)¶

Create the data structures for the total values of several quantities.

Create one pd.DataFrame, two torch.Tensor and two np.ndarray, with proper lengths and shapes, to store the sums of some quantities computed for each peptide chain.

Parameters:

n_layers (int) – The number of layers in the model.
n_heads (int) – The number of attention heads in the model.

Return type:

tuple[DataFrame, Tensor, Tensor, ndarray, ndarray]

Returns:

tot_amino_acid_df (pd.DataFrame) – The data frame with length len(all_amino_acids) to store the amino acids in each peptide chain and the occurrences of each of them.
tot_att_head_sum (torch.Tensor) – The tensor with shape (n_layers, n_heads) to store the total values of the sums of all the values of attention in each head.
tot_att_to_aa (torch.Tensor) – The tensor with shape (len(all_amino_acids), n_layers, n_heads) to store the total values of the attention given to each amino acid.
tot_head_att_align (np.ndarray) – The array with shape (n_layers, n_heads) to store the total values of the attention alignment for each head.
tot_layer_att_align (np.ndarray) – The array with shape (n_layers) to store the total values of the attention alignment for each layer.

ProtACon.manage_tot_ds.keep_nonzero(tot_amino_acid_df, tot_att_to_aa)¶

Drop the rows and the tensors of the amino acids with zero occurrences.

The data frame and the tensor have shapes made for a fixed number of amino acids, which is 20 as the maximum number of amino acids. However, one chain may not contain all the amino acids, so we need to drop the rows and the tensors of the amino acids with zero occurrences.

Parameters:

tot_amino_acid_df (pd.DataFrame) – The data frame with length len(all_amino_acids) storing the amino acids in each peptide chain and the occurrences of each of them.
tot_att_to_aa (torch.Tensor) – The tensor with shape (len(all_amino_acids), n_layers, n_heads) storing the total values of the attention given to each amino acid.

Return type:

tuple[DataFrame, Tensor]

Returns:

tot_amino_acid_df (pd.DataFrame) – The data frame with length len(chain_amino_acids) storing the amino acids in each peptide chain and the occurrences of each of them.
tot_att_to_aa (torch.Tensor) – The tensor with shape (len(chain_amino_acids), n_layers, n_heads) storing the total values of the attention given to each amino acid.

ProtACon.manage_tot_ds.update(tot_amino_acid_df, tot_att_head_sum, tot_att_to_aa, tot_head_att_align, tot_layer_att_align, chain_ds)¶

Update the total data structures with the values computed for one chain.

Update the data structures storing the total values of the quantities, by summing the values computed for each peptide chain.

Parameters:

tot_amino_acid_df (pd.DataFrame) – The data frame with length len(all_amino_acids) storing the amino acids in each peptide chain and the occurrences of each of them.
tot_att_head_sum (torch.Tensor) – The tensor with shape (n_layers, n_heads) storing the total values of the sums of all the values of attention in each head.
tot_att_to_aa (torch.Tensor) – The tensor with shape (len(all_amino_acids), n_layers, n_heads) storing the total values of the attention given to each amino acid.
tot_head_att_align (np.ndarray) – The array with shape (n_layers, n_heads) storing the total values of the attention alignment for each head.
tot_layer_att_align (np.ndarray) – The array with shape (n_layers) storing the total values of the attention alignment for each layer.
chain_ds (tuple[pd.DataFrame, torch.Tensor, torch.Tensor, np.ndarray, np.ndarray]) –

amino_acid_df
The data frame with the amino acids and the occurrences of each of them, for one peptide chain.

att_head_sum
The tensor with shape (n_layers, n_heads) resulting from the sum of all the values in each attention matrix, for one peptide chain.

att_to_aa
The tensor with shape (len(all_amino_acids), n_layers, n_heads) storing the attention given to each amino acid by each attention head, for one peptide chain.

head_att_align
The array with shape (n_layers, n_heads) storing how much attention aligns with indicator_function for each attention matrix, for one peptide chain.

layer_att_align
The array with shape (n_layers) storing how much attention aligns with indicator_function for each average attention matrix computed independently over each layer, for one peptide chain.

Return type:

tuple[DataFrame, Tensor, Tensor, ndarray, ndarray]

Returns:

tot_amino_acid_df (pd.DataFrame) – The data frame with length len(all_amino_acids) to store the amino acids in each peptide chain and the occurrences of each of them.
tot_att_head_sum (torch.Tensor) – The tensor with shape (n_layers, n_heads) to store the total values of the sums of all the values of attention in each head.
tot_att_to_aa (torch.Tensor) – The tensor with shape (len(all_amino_acids), n_layers, n_heads) to store the total values of the attention given to each amino acid.
tot_head_att_align (np.ndarray) – The array with shape (n_layers, n_heads) to store the total values of the attention alignment for each head.
tot_layer_att_align (np.ndarray) – The array with shape (n_layers) to store the total values of the attention alignment for each layer.

ProtACon.plotting module¶

Author: S. Chiarella

Given one peptide chain, plot:: 1.1. the distance map between each couple of amino acids; 1.2. the normalized contact map between each couple of amino acids; 1.3. the binary thresholded contact map between each couple of amino acids; 1.4. the attention matrices from each head of the last layer; 1.5. the averages of the attention matrices independently computed for each layer; 1.6. the average of the layer attention averages, relative to the whole model; 1.7. the heatmaps of the total attention given to each amino acid; 1.8. the heatmap of the attention similarity between each couple of amino acids; 1.9. the heatmap of the attention alignment of each head; 1.10. the bar plot of the attention alignment of each layer.
Given a set of peptide chains, plot:: 2.1. the heatmaps of the percentage of attention given to each amino acid; 2.2. the heatmaps of the percentage of attention given to each amino acid, weighted by the occurrences of that amino acid in all the proteins of the set; 2.3. the heatmaps of the percentage of attention of each head given to each amino acid; 2.4. the heatmap of the global attention similarity between each couple of amino acids; 2.5. the heatmap of the average head attention alignment; 2.6. the bar plot of the average layer attention alignment.

ProtACon.plotting.plot_on_chain(distance_map, norm_contact_map, binary_contact_map, attention, att_avgs, att_to_aa, att_sim_df, head_att_align, layer_att_align, seq_dir, chain_amino_acids)¶

Plot and save to seq_dir the arguments received.

Parameters:

distance_map (np.ndarray) – The distance in Angstroms between each couple of amino acids in the peptide chain.
norm_contact_map (np.ndarray) – The contact map in a scale between 0 and 1.
binary_contact_map (np.ndarray) – The contact map binarized using two thresholding criteria.
attention (tuple[torch.Tensor, ...]) – The attention from the model, cleared of the attention relative to tokens [CLS] and [SEP].
att_avgs (tuple[torch.Tensor, ...]) – The averages of the attention masks independently computed for each layer and, as last element, the average of those averages.
att_to_aa (torch.Tensor) – The attention given to each amino acid by each attention head.
att_sim_df (pd.DataFrame) – The attention similarity between each couple of amino acids.
head_att_align (np.ndarray) – Array with shape (n_layers, n_heads), storing how much attention aligns with indicator_function for each attention masks.
layer_att_align (np.ndarray) – Array with shape (n_layers), storing how much attention aligns with indicator_function for each average attention mask computed independently over each layer.
seq_dir (pathlib.Path) – The path to the folder containing where to store the plots related to the peptide chain.
chain_amino_acids (list[str]) – The single letter codes of the amino acid types in the peptide chain.

Return type:

None

ProtACon.plotting.plot_on_set(tot_amino_acid_df, glob_att_to_aa, glob_att_sim_arr, avg_att_align)¶

Plot and save the arguments received.

Parameters:

tot_amino_acid_df (pd.DataFrame) – The data frame containing the information about all the amino acids in the set of proteins.
glob_att_to_aa (tuple[torch.Tensor, torch.Tensor, torch.Tensor]) –

PT_att_to_aa
The percentage of total attention given to each amino acid.

PWT_att_to_aa
The percentage of total attention given to each amino acid, weighted by the occurrences of that amino acid across the set of proteins.

PH_att_to_aa
The percentage of attention of each head given to each amino acid.
glob_att_sim_arr (np.ndarray) – The global attention similarity between each couple of amino acids.
avg_att_align (tuple[np.ndarray, np.ndarray]) –

avg_head_att_align
The head attention alignment averaged over the whole protein set.

avg_layer_att_align
The layer attention alignment averaged over the whole protein set.

Return type:

None

ProtACon.preprocess module¶

Author: S. Chiarella

Extract and preprocess the attention returned by ProtBert, by removing the attention relative to the tokens [CLS] and [SEP]. Then, return the attention given by the model to each amino acid.

ProtACon.preprocess.main(seq_ID, model, tokenizer, save_opt)¶

Extract the attention matrices from the model and preprocess the data.

Run ProtBert on one peptide chain and extract the attention. The peptide chain is identified with its seq_ID. Then, preprocess the attention. raw_attention and raw_tokens are cleared of the tokens [CLS] and [SEP]. Optionally, thresholding on attention is applied. Finally, the attention given to each amino acid is computed. It also contructs a data frame with the information about the amino acids in the input peptide chain.

Parameters:

seq_ID (str) – The alphanumerical code representing uniquely the peptide chain.
model (BertModel) – The object storing the Bert model.
tokenizer (BertTokenizer) – The object storing the tokenizer for the Bert model.
save_opt (str) – One between (‘none’, ‘plot’, ‘csv’, ‘both’). If ‘csv’ or ‘both’, save the amino acid data frame of every single chain.

Return type:

tuple[tuple[Tensor, ...], Tensor, tuple[CA_Atom, ...], DataFrame, Tensor]

Returns:

attention (tuple[torch.Tensor, …]) – The attention returned by the model, cleared of the attention related to the tokens [CLS] and [SEP].
att_head_sum (torch.Tensor) – Tensor with shape (n_layers, n_heads), resulting from the sum of all the values in each attention matrix.
CA_atoms (tuple[CA_Atom, …]) – The alpha carbon atoms of the residues in the peptide chain.
amino_acid_df (pd.DataFrame) – The data frame containing the information about the amino acids that constitute the peptide chain.
T_att_to_aa (torch.Tensor) – Tensor with shape (len(all_amino_acids), n_layers, n_heads), storing the attention given to each amino acid by each attention head.

ProtACon.process_contact module¶

Author: S. Chiarella

Process the data relative to the distances between the residues in the peptide chain. Those data are used to create protein contact maps.

ProtACon.process_contact.main(CA_Atoms)¶

Generate a distance map, a contact map, and a binary contact map.

Parameters:

CA_Atoms (tuple[CA_Atom, ...]) – The alpha carbon atoms of the residues in the peptide chain.

Return type:

tuple[ndarray, ndarray, ndarray]

Returns:

distance_map (np.ndarray) – The distance in Angstroms between each couple of residues in the peptide chain.
norm_contact_map (np.ndarray) – The contact map in a scale between 0 and 1.
binary_contact_map (np.ndarray) – The contact map binarized using two thresholding criteria.