dcatoolkit 0.2.2__tar.gz → 0.2.3__tar.gz

{dcatoolkit-0.2.2/src/dcatoolkit.egg-info → dcatoolkit-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: dcatoolkit
-Version: 0.2.2
+Version: 0.2.3
 Summary: Collection of useful modules and representations for managing DCA output data.
 Author-email: Raheel Syed Ahmed <raheelsyedahmed@gmail.com>
 Maintainer-email: Raheel Syed Ahmed <raheelsyedahmed@gmail.com>
@@ -52,6 +52,7 @@ Requires-Dist: pdoc; extra == "docs"
 Requires-Dist: numpydoc; extra == "docs"
 Provides-Extra: lint
 Requires-Dist: ruffle; extra == "lint"
+Dynamic: license-file
 
 # dcatoolkit
  Collection of useful modules and representations for managing DCA output data.

{dcatoolkit-0.2.2 → dcatoolkit-0.2.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "dcatoolkit"
-version = "0.2.2"
+version = "0.2.3"
 description = "Collection of useful modules and representations for managing DCA output data."
 keywords = ["dca", "toolkit", "DI", "coevolution"]
 

{dcatoolkit-0.2.2 → dcatoolkit-0.2.3}/src/dcatoolkit/__init__.py

@@ -1,5 +1,5 @@
 
-__version__ = "0.2.2"
+__version__ = "0.2.3"
 from .representation import Pairs, DirectInformationData, StructureInformation, ResidueAlignment, MMCIFInformation, PDBInformation
 from .analytics import MSATools
 

{dcatoolkit-0.2.2 → dcatoolkit-0.2.3}/src/dcatoolkit/analytics.py

@@ -1,8 +1,11 @@
 import re
 from collections import Counter
-from typing import Optional, Union
+from collections.abc import Callable
+from typing import Optional, Union, Literal
 import string
 import io
+import numpy as np
+import numpy.typing as npt
 
 class MSATools:
     """
@@ -122,6 +125,27 @@ class MSATools:
                     kept_entries.append((header, sequence))
         return kept_entries
 
+    def gap_proportion(self, agg_func: Callable[..., float | int]=np.mean, axis: Literal[0, 1] = 0) -> float | int:
+        """
+        Evaluates gap frequency per alignment position, or column, in the MSA.
+
+        Parameters
+        ----------
+        agg_func: function = np.mean
+            The aggregation function applied to get the expected result, usually a mean, max, or min value, of the gap frequencies present per alignment position in the MSA.
+        axis: int or str
+            When axis is 0, the aggregation function is applied per column for entries from every row in that column. When axis is 1, the aggregation function is applied per row for entries from every column in that row.
+        
+        Return
+        ------
+        float
+            A numerical value determined by the aggregation function supplied over the gap frequencies of the alignment positions in the MSA.
+        """
+        sequence_matrix = self.as_matrix()
+        non_alpha_counts = np.sum(~np.char.isalpha(sequence_matrix), axis)
+        non_alpha_counts = non_alpha_counts / sequence_matrix.shape[axis]
+        return agg_func(non_alpha_counts)
+
     def write(self, destination: Union[str, io.IOBase]) -> None:
         """
         Writes this MSA's headers and sequences to the destination specified.
@@ -149,6 +173,28 @@ class MSATools:
                 destination.write(sequence)
                 destination.write("\n")
 
+    def as_matrix(self) -> npt.NDArray:
+        """
+        Represents the MSA as a numpy matrix of sequences.
+
+        Returns
+        -------
+        npt.NDArray
+            A matrix of "number of sequences" rows and "number of alignment positions" columns. Each cell is the sequence character for that sequence at that position.
+        """
+        return np.array([list(seq) for _, seq in self.MSA])
+
+    def __str__(self) -> str:
+        """
+        Returns the sequences present in the loaded MSA in string format.
+
+        Returns
+        -------
+        str
+            Each sequence in the instance separated with newline characters.
+        """
+        return "\n".join([seq for _, seq in self.MSA])
+    
     def __len__(self):
         """
         Returns the number of sequences, and equivalently, the number of headers in the MSA.

{dcatoolkit-0.2.2 → dcatoolkit-0.2.3}/src/dcatoolkit/representation.py

@@ -6,6 +6,7 @@ import biotite.structure as struc
 import biotite.structure.io.pdbx as pdbx
 import biotite.structure.io.pdb as pdb
 import biotite.database.rcsb as rcsb
+from biotite.sequence import ProteinSequence
 
 from collections.abc import Iterable
 from typing import Optional, Union, Literal, overload
@@ -195,6 +196,8 @@ class ResidueAlignment:
         The sequence of the domain in the query HMM corresponding to this alignment.
     protein_text : str
         The sequence of the protein target sequence corresponding to this alignment.
+    valid_residues : list of tuple of int, str
+        A list of tuples that contain first residue index then residue name (e.g. [(1, 'A'), (2, 'W'), (3, 'C')]  )
 
     Attributes
     ----------
@@ -205,12 +208,73 @@ class ResidueAlignment:
     protein_to_domain : dict[int, int]
         A dictionary allowing for mapping from indices corresponding to the protein target sequence to the query HMM and Multiple Sequence Alignment.
     """
-    def __init__(self, domain_name: str, protein_name: str, domain_start: int, protein_start: int, domain_text: str, protein_text: str) -> None:
+    def __init__(self, domain_name: str, protein_name: str, domain_start: int, protein_start: int, domain_text: str, protein_text: str, valid_residues: Optional[list[tuple[int, str]]]=None) -> None:
         self.domain_name = domain_name
         self.protein_name = protein_name
-        self.set_reference_mapping(domain_start, protein_start, domain_text, protein_text)
+        self.valid_residues = valid_residues
+        if valid_residues:
+            self._set_restricted_reference_mapping(domain_start, protein_start, domain_text, protein_text, valid_residues)
+        else:
+            self._set_reference_mapping(domain_start, protein_start, domain_text, protein_text)
     
-    def set_reference_mapping(self, domain_start: int, protein_start: int, domain_text: str, protein_text: str) -> None:
+    def _set_restricted_reference_mapping(self, domain_start: int, protein_start: int, domain_text: str, protein_text: str, valid_residues: list[tuple[int, str]]) -> None:
+        """
+        Set values for reference_mapping and mapping dictionaries, domain_to_protein and protein_to_domain.
+
+        Parameters
+        ----------
+        valid_residues : list of tuple of int, str
+            List of valid residues, non-missing residues in a structure, in the format of (seq_id, residue_name). These are iteratively selected in the order of the sequence to map to.
+
+        Notes
+        -----
+        For details on `domain_start`, `protein_start`, `domain_text`, `protein_text`, please refer to the `ResidueAlignment` docstring.
+
+        Returns
+        -------
+        None
+        """
+        invalid_chars = [".", "_", "-"]
+        # Convert text to list variant for iteration
+        domain_sequence = list(domain_text)
+        protein_sequence = list(protein_text)
+        # Store mapping values per iteration here.
+        mapping_entries = []
+        
+        # Go through aligned sequences and append data concerning domain index, domain residue, protein residue, and protein index per valid aligned residues.
+        for domain_aa, protein_aa in zip(domain_sequence, protein_sequence):
+            mapping_entry = []
+            if domain_aa not in invalid_chars:
+                mapping_entry.append(domain_start)
+                domain_start += 1
+            else:
+                mapping_entry.append(pd.NA)
+            mapping_entry.append(domain_aa)
+
+            if protein_aa not in invalid_chars:
+                while len(valid_residues) >= protein_start:
+                    prot_index, valid_residue = valid_residues.pop(protein_start-1)
+                    if protein_aa.lower() == valid_residue.lower():
+                        mapping_entry.append(protein_aa)
+                        mapping_entry.append(prot_index)
+                        break
+                else:
+                    # Default case for if valid residues are missing towards the end.
+                    mapping_entry.append(protein_aa)
+                    mapping_entry.append(pd.NA)
+            else:
+                mapping_entry.append(protein_aa)
+                mapping_entry.append(pd.NA)
+            mapping_entries.append(mapping_entry)
+
+        self.reference_mapping = pd.DataFrame(mapping_entries, columns=['domain_index', 'domain_residue', 'protein_residue', 'protein_index'])
+        self.reference_mapping = self.reference_mapping.astype({'domain_index': pd.Int32Dtype(), 'protein_index': pd.Int32Dtype(), 'domain_residue': pd.StringDtype(), 'protein_residue': pd.StringDtype()})
+        reference_mapping_notna = self.reference_mapping.dropna()
+        
+        self.domain_to_protein = dict(zip(reference_mapping_notna.domain_index, reference_mapping_notna.protein_index))
+        self.protein_to_domain = dict(zip(reference_mapping_notna.protein_index, reference_mapping_notna.domain_index))
+
+    def _set_reference_mapping(self, domain_start: int, protein_start: int, domain_text: str, protein_text: str) -> None:
         """
         Set values for reference_mapping and mapping dictionaries, domain_to_protein and protein_to_domain.
 
@@ -222,25 +286,26 @@ class ResidueAlignment:
         -------
         None
         """
+        invalid_chars = [".", "_", "-"]
         # Convert text to list variant for iteration
         domain_sequence = list(domain_text)
         protein_sequence = list(protein_text)
-        
+        # Store mapping values per iteration here.
         mapping_entries = []
 
-        for i in range(len(domain_sequence)):
+        for domain_aa, protein_aa in zip(domain_sequence, protein_sequence):
             mapping_entry = []
             # Check to see if domain residue is valid, if so, we can assign the proper index.
-            if domain_sequence[i] != '.':
+            if domain_aa not in invalid_chars:
                 mapping_entry.append(domain_start)
                 domain_start += 1
             else:
                 mapping_entry.append(pd.NA)
             # Assign the values of the residues mapped together.
-            mapping_entry.append(domain_sequence[i])
-            mapping_entry.append(protein_sequence[i])
+            mapping_entry.append(domain_aa)
+            mapping_entry.append(protein_aa)
             # Check to see if protein residue is valid, if so, we can assign the proper index.
-            if protein_sequence[i] != '-':
+            if protein_aa not in invalid_chars:
                 mapping_entry.append(protein_start)
                 protein_start += 1
             else:
@@ -282,7 +347,7 @@ class ResidueAlignment:
         89
         """
         # Read the alignment file and parse the important information from each alignment entry.
-        alignment_entries = ResidueAlignment.read_align_file(align_filepath)
+        alignment_entries = ResidueAlignment._read_align_file(align_filepath)
         hmm_entry, protein_entry = alignment_entries
         domain_name, domain_start, domain_text, _ = hmm_entry
         protein_name, protein_start, protein_text, _ = protein_entry
@@ -294,7 +359,7 @@ class ResidueAlignment:
         return ResidueAlignment(domain_name, protein_name, domain_start, protein_start, domain_text, protein_text)
 
     @staticmethod
-    def read_align_file(align_filepath: str) -> list[list[str]]:
+    def _read_align_file(align_filepath: str) -> list[list[str]]:
         """
         Reads standard align file, where a scan file is selected for a particular domain and processed into an align file format. Details are present in produce_align_from_scan().
         
@@ -770,9 +835,9 @@ class MMCIFInformation(StructureInformation):
         self.full_sequences = pdbx.get_sequence(pdbx_file)
         non_hetero_structure = self.structure[self.structure.hetero == False]
         self.non_missing_sequences = {str(chain): str(sequence) for (chain, sequence) in list(zip(struc.get_chains(non_hetero_structure), struc.to_sequence(non_hetero_structure)[0]))}
-        self.generate_auth_info()
+        self._generate_auth_info()
 
-    def generate_auth_info(self) -> None:
+    def _generate_auth_info(self) -> None:
         """
         Ran as part of constructor function. Generates information needed to access auth information including auth_seq_id and auth_asym_id, which correspond to alternative chain ids and alternative residue indices.
         
@@ -786,28 +851,25 @@ class MMCIFInformation(StructureInformation):
         """
         if len(self.pdbx_file.keys()) > 0:
             self.first_block = list(self.pdbx_file)[0]
-            self.atom_site_category = self.pdbx_file[self.first_block].get('atom_site')
+            atom_site_category = self.pdbx_file[self.first_block].get('atom_site')
             self.chain_auth_dict: dict[str, str] = {}
             self.auth_chain_dict: dict[str, str] = {}
-            self.res_auth_dict: dict[str, tuple[int, int]] = {}
-            
-            if self.atom_site_category:
+            if atom_site_category:
                 categories = ['group_PDB', 'label_seq_id', 'label_asym_id', 'auth_seq_id', 'auth_asym_id', 'pdbx_PDB_model_num']
-                atom_site_data = np.column_stack([self.atom_site_category[category].as_array() for category in categories])
+                atom_site_data = np.column_stack([atom_site_category[category].as_array() for category in categories])
                 _, idx = np.unique(atom_site_data, axis=0, return_index=True)
                 atom_site_data = atom_site_data[np.sort(idx)]
-                self.atom_data = atom_site_data[atom_site_data[:,0] == "ATOM"]
-                self.het_atom_data = atom_site_data[atom_site_data[:,0] == "HETATM"]
-                self.unique_chains = np.unique(self.atom_data[:,2])
+                atom_data = atom_site_data[atom_site_data[:,0] == "ATOM"]
+                self.unique_chains = np.unique(atom_data[:,2])
                 for unique_chain in self.unique_chains:
-                    unique_entry = self.atom_data[self.atom_data[:,2] == unique_chain][0]
+                    unique_entry = atom_data[atom_data[:,2] == unique_chain][0]
                     self.chain_auth_dict[unique_entry[2]] = unique_entry[4]
                     self.auth_chain_dict[unique_entry[4]] = unique_entry[2]
-                    self.res_auth_dict[unique_entry[2]] = unique_entry[[1,3]].astype('int')
-        else:
-            self.atom_site_category = None
-    
-    def get_start_res_id(self, chain_id: str, auth_res_ids: bool=False, auth_chain_id_supplied: bool=False) -> int:
+                self.atom_site_df = pd.DataFrame(np.column_stack([atom_site_category[category].as_array() for category in atom_site_category.keys()]), columns=atom_site_category.keys())
+                type_conversion_dict = {'label_seq_id': 'int64', 'auth_seq_id': 'int64', 'id': 'int64', 'Cartn_x': 'float', 'Cartn_y': 'float','Cartn_z': 'float', 'B_iso_or_equiv': 'float'}
+                self.atom_df = self.atom_site_df[self.atom_site_df['group_PDB'] == 'ATOM'].astype(type_conversion_dict)
+
+    def get_start_res_id(self, chain_id: str, get_auth_res_ids: bool=False, auth_chain_id_supplied: bool=False) -> int:
         """
         Gets starting residue id of the specified chain excluding heteroatom group entries.
 
@@ -815,7 +877,7 @@ class MMCIFInformation(StructureInformation):
         ----------
         chain_id : str
             The chain id supplied and selected for from the structure.
-        auth_res_ids : bool
+        get_auth_res_ids : bool
             True if you want alt_ids for residues indices, False if cif residue indexing is needed.
         auth_chain_id_supplied : bool
             If True, the chain_id supplied is the auth chain id found on the RCSB website.            
@@ -826,11 +888,13 @@ class MMCIFInformation(StructureInformation):
             The residue id of the first atom in the chain provided.
         """
         if auth_chain_id_supplied:
-            chain_id = self.auth_chain_dict[chain_id]
-        if auth_res_ids:
-            return self.res_auth_dict[chain_id][1]
+            chain_df = self.atom_df[self.atom_df['auth_asym_id'] == chain_id]
+        else:
+            chain_df = self.atom_df[self.atom_df['label_asym_id'] == chain_id]
+        if get_auth_res_ids:
+            return chain_df['auth_seq_id'][0]
         else:
-            return self.res_auth_dict[chain_id][0]
+            return chain_df['label_seq_id'][0]
 
     def get_full_sequence(self, chain_id: str, auth_chain_id_supplied: bool=False) -> str:
         """
@@ -875,7 +939,7 @@ class MMCIFInformation(StructureInformation):
         else:
             return self.non_missing_sequences[chain_id]
         
-    def get_chain_specific_structure(self, ca_only: bool, chain1: str, chain2: str, remove_hetero=True, auth_chain_id_supplied: bool=False) -> tuple:
+    def get_chain_specific_structure(self, ca_only: bool, chain_id: str, remove_hetero=True, auth_chain_id_supplied: bool=False):
         """
         Subsets structure attribute to select for chain specific portions of the structure.
 
@@ -883,10 +947,8 @@ class MMCIFInformation(StructureInformation):
         ----------
         ca_only : bool
             If true, the structure will also be subsetted for atom entries where the atom_name annotation is "CA" (referring to alpha-carbons)
-        chain1 : str
-            Chain id corresponding to the first column of residues in the structure.
-        chain2 : str
-            Chain id corresponding to the second column of residues in the structure.
+        chain_id : str
+            The name of the chain to be selected for within the structure.
         remove_hetero : bool, default=True
             If true, the structure will also be subsetted for atom entries where the hetero annotation is False, thus removing heteroatoms.
         auth_chain_id_supplied : bool
@@ -898,9 +960,7 @@ class MMCIFInformation(StructureInformation):
             Two AtomArrays that refer to atoms in the first chain and second chain, respectively without accounting for the presence of heteroatoms if `remove_hetero` is True.
         """
         if auth_chain_id_supplied:
-            chain1 = self.auth_chain_dict[chain1]
-            chain2 = self.auth_chain_dict[chain2]
-
+            chain_id = self.auth_chain_dict[chain_id]
         selected_structure = self.structure
         if remove_hetero:
             # Remove hetero atoms via hetero column of structure ndarray
@@ -908,64 +968,110 @@ class MMCIFInformation(StructureInformation):
         if ca_only:
             # Consider selection of alpha-carbon atoms only
             selected_structure = selected_structure[selected_structure.atom_name == "CA"]
-        chain1_structure = selected_structure[selected_structure.chain_id == chain1]
-        chain2_structure = selected_structure[selected_structure.chain_id == chain2]
-        return (chain1_structure, chain2_structure)
-
-    def generate_dist_matrix(self, ca_only: bool, chain1: str, chain2: str, auth_chain_id_supplied: bool=False):
+        chain_structure = selected_structure[selected_structure.chain_id == chain_id]
+        return chain_structure
+    
+    def get_chain_site_data(self, ca_only: bool, chain_id: str, remove_hetero=True, auth_chain_id_supplied: bool=False):
         """
-        Generates distance matrix between two chains in the structure attribute.
+        Subsets the atom_site dataframe to get atom information where the conditions are met.
 
         Parameters
         ----------
         ca_only : bool
-            If True, only atoms that have the name "CA" are selected in the chains the distance matrix is calculated between.
-        chain1 : str
-            Chain id corresponding to the first column of residues in the structure.
-        chain2 : str
-            Chain id corresponding to the first column of residues in the structure.
+            If true, the dataframe will also be subsetted for atom entries where the label_atom_id annotation is "CA" (referring to alpha-carbons)
+        chain_id : str
+            The name of the chain to be selected for within the dataframe.
+        remove_hetero : bool, default=True
+            If true, the dataframe will also be subsetted for atom entries where the group_PDB annotation is ATOM rather than HETATM, thus removing heteroatoms.
+        auth_chain_id_supplied : bool
+            If True, the chain_id supplied is the auth chain id found on the RCSB website.
+        """
+        atom_df = self.atom_df.copy()
+        if ca_only:
+            atom_df = atom_df[atom_df['label_atom_id'] == 'CA']
+        if remove_hetero:
+            atom_df = atom_df[atom_df['group_PDB'] == 'ATOM']
+        if auth_chain_id_supplied:
+            return atom_df[atom_df['auth_asym_id'] == chain_id]
+        else:
+            return atom_df[atom_df['label_asym_id'] == chain_id]
+        
+    def get_seq_id_mapping(self, chain_id: str, seq_to_auth: bool, auth_chain_id_supplied: bool=False) -> dict[int, int]:
+        """
+        Gets mapping from auth seq ids to label seq ids or vice-versa.
+
+        Parameters
+        ----------
+        chain_id : str
+            Chain id of the chain addressed for determining residue index mappings.
+        seq_to_auth : bool
+            If True, this indicates the mapping uses the label_seq_id as a key and the auth_seq_id as a value. Otherwise, keys and values are switched.
         auth_chain_id_supplied : bool
             If True, the chain_id supplied is the auth chain id found on the RCSB website.
 
         Returns
         -------
-        tuple of biotite.structure.AtomArray, biotite.structure.AtomArray, numpy.ndarray
-            Tuple containing the chain 1 structure, the chain 2 structure, and the distance matrix of chain 1 and chain 2's pairwise distances.
+        dict of int, int
+            Dictionary with either label seq id or auth seq id as a key and the other as a value. The directionality is dependent on seq_to_auth.
         """
-        chain1_structure, chain2_structure = self.get_chain_specific_structure(ca_only, chain1, chain2, remove_hetero=True, auth_chain_id_supplied=auth_chain_id_supplied)
-        dist_matrix = cdist(chain1_structure.coord, chain2_structure.coord)
-        return (chain1_structure, chain2_structure, dist_matrix)
+        chain_df = self.get_chain_site_data(ca_only=True, chain_id=chain_id, remove_hetero=True, auth_chain_id_supplied=auth_chain_id_supplied)
+        if seq_to_auth: 
+            return dict(zip(chain_df['label_seq_id'], chain_df['auth_seq_id']))
+        else:
+            return dict(zip(chain_df['auth_seq_id'], chain_df['label_seq_id']))
     
-    def get_shift_values(self, chain1: str, chain2: str, auth_chain_id_supplied: bool=False) -> tuple[int, int]:
+    def get_valid_chain_residues(self, chain_id: str, auth_seq_id: bool=False, auth_chain_id_supplied: bool=False) -> list[tuple[int, str]]:
         """
-        Get shift values needed for production of auth residue ids.
+        Gets valid indexing for residues of a specified chain. This is directly analogous to get_non_missing_sequence, does not contain missing residues, and provides the corresponding indices as well.
+
+        Parameters
+        ----------
+        chain_id : str
+            Chain id of the chain to be selected from the structure. This chain's sequence and corresponding residue indices are what are exclusively selected for.
+        auth_seq_id: bool
+            If True, the seq_ids that are the first element of the tuples in the returned list are auth_seq_ids. 
+        auth_chain_id_supplied : bool
+            If True, the chain_id supplied is the auth chain id found on the RCSB website.
         
+        Returns
+        -------
+        list of tuple of int, str
+            A list of residue information in sequential order reflecting the structure. The list consists of tuple elements where each tuple is the residue index and its corresponding one-letter amino acid.
+        """
+        chain_structure = self.get_chain_specific_structure(ca_only=True, chain_id=chain_id, remove_hetero=True, auth_chain_id_supplied=auth_chain_id_supplied)
+        res_ids = chain_structure.res_id.tolist()
+        res_names = chain_structure.res_name
+        if auth_seq_id:
+            seq_id_mapping = self.get_seq_id_mapping(chain_id=chain_id, seq_to_auth=True, auth_chain_id_supplied=auth_chain_id_supplied)
+            auth_res_ids = [seq_id_mapping[res_id] for res_id in res_ids]
+            return list(zip(auth_res_ids, map(lambda symbol: ProteinSequence.convert_letter_3to1(symbol), res_names)))
+        else:
+            return list(zip(res_ids, map(lambda symbol: ProteinSequence.convert_letter_3to1(symbol), res_names)))
+
+    def generate_dist_matrix(self, ca_only: bool, chain1: str, chain2: str, auth_chain_id_supplied: bool=False):
+        """
+        Generates distance matrix between two chains in the structure attribute.
+
         Parameters
         ----------
+        ca_only : bool
+            If True, only atoms that have the name "CA" are selected in the chains the distance matrix is calculated between.
         chain1 : str
-            Name of the chain id present referring to the second column of residues.
+            Chain id corresponding to the first column of residues in the structure.
         chain2 : str
-            Name of the chain id present referring to the second column of residues.
+            Chain id corresponding to the first column of residues in the structure.
         auth_chain_id_supplied : bool
             If True, the chain_id supplied is the auth chain id found on the RCSB website.
 
         Returns
         -------
-        (shift1, shift2) : tuple of int, int
-            Tuple containing both shift values, the difference between the auth_res_id and res_id.
+        tuple of biotite.structure.AtomArray, biotite.structure.AtomArray, numpy.ndarray
+            Tuple containing the chain 1 structure, the chain 2 structure, and the distance matrix of chain 1 and chain 2's pairwise distances.
         """
-        if auth_chain_id_supplied:
-            chain1 = self.auth_chain_dict[chain1]
-            chain2 = self.auth_chain_dict[chain2]
-
-        shift1 = 0
-        shift2 = 0
-        if self.atom_site_category:
-            shift1 = self.res_auth_dict[chain1][1] - self.res_auth_dict[chain1][0]
-            shift2 = self.res_auth_dict[chain2][1] - self.res_auth_dict[chain2][0]
-            return shift1, shift2
-        else:
-            return shift1, shift2
+        chain1_structure = self.get_chain_specific_structure(ca_only=ca_only, chain_id=chain1, remove_hetero=True, auth_chain_id_supplied=auth_chain_id_supplied)
+        chain2_structure = self.get_chain_specific_structure(ca_only=ca_only, chain_id=chain2, remove_hetero=True, auth_chain_id_supplied=auth_chain_id_supplied)
+        dist_matrix = cdist(chain1_structure.coord, chain2_structure.coord)
+        return (chain1_structure, chain2_structure, dist_matrix)
 
     def get_min_dist_atom_info(self, pairs: npt.NDArray, chain1: str, chain2: str, auth_chain_id_supplied: bool=False) -> npt.NDArray:
         """
@@ -987,8 +1093,8 @@ class MMCIFInformation(StructureInformation):
         min_dist_pairs_atoms_arr : numpy.ndarray
             Structured ndarray that has residue indices, auth residue indices (corresponding to the protein numbering), and atomic names in the format {'names': ['residue1','residue2','auth_residue1','auth_residue2','atom_name1','atom_name2'], 'formats': [int,int,int,int,'<U10','<U10']}
         """
-        shift1, shift2 = self.get_shift_values(chain1, chain2, auth_chain_id_supplied=auth_chain_id_supplied)
-        chain1_structure, chain2_structure = self.get_chain_specific_structure(ca_only=False, chain1=chain1, chain2=chain2, remove_hetero=True, auth_chain_id_supplied=auth_chain_id_supplied)
+        chain1_structure = self.get_chain_specific_structure(ca_only=False, chain_id=chain1, remove_hetero=True, auth_chain_id_supplied=auth_chain_id_supplied)
+        chain2_structure = self.get_chain_specific_structure(ca_only=False, chain_id=chain2, remove_hetero=True, auth_chain_id_supplied=auth_chain_id_supplied)
         min_dist_pairs_atoms = []
         for row in pairs:
             # Obtain structure information for chains 1 and 2
@@ -1001,13 +1107,15 @@ class MMCIFInformation(StructureInformation):
             ind = np.unravel_index(np.argmin(dist_matrix), dist_matrix.shape)
             # Use the indices to access the atom in the atom array and get the correct atom name.
             # Generate the auth ids of the residues in the pairs ndarray
-            auth_res_id1 = row['residue1'] + shift1
-            auth_res_id2 = row['residue2'] + shift2
+            seq_mapping_chain1 = self.get_seq_id_mapping(chain_id=chain1, seq_to_auth=True, auth_chain_id_supplied=auth_chain_id_supplied)
+            seq_mapping_chain2 = self.get_seq_id_mapping(chain_id=chain2, seq_to_auth=True, auth_chain_id_supplied=auth_chain_id_supplied)
+            auth_res_id1 = seq_mapping_chain1[row['residue1']]
+            auth_res_id2 = seq_mapping_chain2[row['residue2']]
             min_dist_pairs_atoms.append((row['residue1'], row['residue2'], auth_res_id1, auth_res_id2, chain1_res1_structure[ind[0]].atom_name, chain2_res2_structure[ind[1]].atom_name))
         min_dist_pairs_atoms_arr = np.array(min_dist_pairs_atoms, dtype={'names': ['residue1','residue2','auth_residue1','auth_residue2','atom_name1','atom_name2'], 'formats': [int,int,int,int,'<U10','<U10']})
         return min_dist_pairs_atoms_arr
 
-    def get_contacts(self, ca_only: bool, threshold: float, chain1: str, chain2: str, auth_contacts: bool=False, auth_chain_id_supplied: bool=False) -> set[tuple[int, int]]:
+    def get_contacts(self, ca_only: bool, threshold: float, chain1: str, chain2: str, auth_seq_id: bool=False, auth_chain_id_supplied: bool=False) -> set[tuple[int, int]]:
         """
         Get contacts from the structure attribute where the distance between two residues is less than the threshold.
 
@@ -1021,8 +1129,8 @@ class MMCIFInformation(StructureInformation):
             Chain id corresponding to the first column of residues in the structure.
         chain2 : str
             Chain id corresponding to the second column of residues in the structure.
-        auth_contacts : bool
-            True if you want alt_ids for residues indices, False if cif residue indexing is needed.
+        auth_seq_id : bool
+            True if you want auth_seq_ids for residues indices, False if cif residue indexing is needed.
         auth_chain_id_supplied : bool
             If True, the chain_id supplied is the auth chain id found on the RCSB website.
 
@@ -1031,8 +1139,9 @@ class MMCIFInformation(StructureInformation):
         contacts_set : set of tuple of ints
             Set of contacts, tuples with "residue1" and "residue2" from the structure that are within the distance threshold.
         """
-        
         chain1_structure, chain2_structure, dist_matrix = self.generate_dist_matrix(ca_only, chain1, chain2, auth_chain_id_supplied=auth_chain_id_supplied)
+        seq_mapping_chain1 = self.get_seq_id_mapping(chain_id=chain1, seq_to_auth=True, auth_chain_id_supplied=auth_chain_id_supplied)
+        seq_mapping_chain2 = self.get_seq_id_mapping(chain_id=chain2, seq_to_auth=True, auth_chain_id_supplied=auth_chain_id_supplied)
         thresh_ind = np.argwhere(dist_matrix <= threshold)
         contacts_set = set()
         for indices in thresh_ind:
@@ -1041,9 +1150,8 @@ class MMCIFInformation(StructureInformation):
             res1 = chain1_atom.res_id
             res2 = chain2_atom.res_id
             if not(chain1==chain2 and res1 >= res2):
-                if auth_contacts:
-                    shift1, shift2 = self.get_shift_values(chain1, chain2, auth_chain_id_supplied=auth_chain_id_supplied)
-                    contacts_set.add((res1 + shift1, res2 + shift2))
+                if auth_seq_id:
+                    contacts_set.add((seq_mapping_chain1[res1], seq_mapping_chain2[res2]))
                 else:
                     contacts_set.add((res1, res2))
         return contacts_set
@@ -1111,7 +1219,7 @@ class PDBInformation(StructureInformation):
         """
         return self.non_missing_sequences[chain_id]
     
-    def get_chain_specific_structure(self, ca_only: bool, chain1: str, chain2: str, remove_hetero=True) -> tuple:
+    def get_chain_specific_structure(self, ca_only: bool, chain_id: str, remove_hetero=True):
         """
         Subsets structure attribute to select for chain specific portions of the structure.
 
@@ -1131,7 +1239,6 @@ class PDBInformation(StructureInformation):
         tuple of biotite.structure.AtomArray, biotite.structure.AtomArray
             Two AtomArrays that refer to atoms in the first chain and second chain, respectively without accounting for the presence of heteroatoms if `remove_hetero` is True.
         """
-
         selected_structure = self.structure
         if remove_hetero:
             # Remove hetero atoms via hetero column of structure ndarray
@@ -1139,10 +1246,26 @@ class PDBInformation(StructureInformation):
         if ca_only:
             # Consider selection of alpha-carbon atoms only
             selected_structure = selected_structure[selected_structure.atom_name == "CA"]
-        chain1_structure = selected_structure[selected_structure.chain_id == chain1]
-        chain2_structure = selected_structure[selected_structure.chain_id == chain2]
-        return (chain1_structure, chain2_structure)
+        chain_structure = selected_structure[selected_structure.chain_id == chain_id]
+        return chain_structure
     
+    def get_valid_chain_residues(self, chain_id: str) -> list[tuple[int, str]]:
+        """
+        Gets valid indexing for residues of a specified chain. This is directly analogous to get_non_missing_sequence, does not contain missing residues, and provides the corresponding indices as well.
+
+        Parameters
+        ----------
+        chain_id : str
+            Chain id of the chain to be selected from the structure. This chain's sequence and corresponding residue indices are what are exclusively selected for.
+        
+        Returns
+        -------
+        list of tuple of int, str
+            A list of residue information in sequential order reflecting the structure. The list consists of tuple elements where each tuple is the residue index and its corresponding one-letter amino acid.
+        """
+        chain_structure = self.get_chain_specific_structure(ca_only=True, chain_id=chain_id, remove_hetero=True)
+        return list(zip(chain_structure.res_id.tolist(), map(lambda symbol: ProteinSequence.convert_letter_3to1(symbol), chain_structure.res_name)))
+
     def generate_dist_matrix(self, ca_only: bool, chain1: str, chain2: str):
         """
         Generates distance matrix between two chains in the structure attribute.
@@ -1161,38 +1284,11 @@ class PDBInformation(StructureInformation):
         tuple of biotite.structure.AtomArray, biotite.structure.AtomArray, numpy.ndarray
             Tuple containing the chain 1 structure, the chain 2 structure, and the distance matrix of chain 1 and chain 2's pairwise distances.
         """
-        chain1_structure, chain2_structure = self.get_chain_specific_structure(ca_only, chain1, chain2, remove_hetero=True)
+        chain1_structure = self.get_chain_specific_structure(ca_only=ca_only, chain_id=chain1, remove_hetero=True)
+        chain2_structure = self.get_chain_specific_structure(ca_only=ca_only, chain_id=chain2, remove_hetero=True)
         dist_matrix = cdist(chain1_structure.coord, chain2_structure.coord)
         return (chain1_structure, chain2_structure, dist_matrix)
 
-    def get_shift_values(self, chain1: str, chain2: str) -> tuple[int, int]:
-        """
-        Get shift values needed for production of auth residue ids.
-        
-        Parameters
-        ----------
-        chain1 : str
-            Name of the chain id present in the struct_ref_seq block of cif files referring to the second column of residues.
-        chain2 : str
-            Name of the chain id present in the struct_ref_seq block of cif files referring to the second column of residues.
-
-        Returns
-        -------
-        (shift1, shift2) : tuple of int, int
-            Tuple containing both shift values, the difference between the auth_res_id and res_id.
-        """
-        non_hetero_structure = self.structure[self.structure.hetero == False]
-        shift1 = 0
-        shift2 = 0
-        if chain1 in self.unique_chains and chain2 in self.unique_chains:
-            shift1 = non_hetero_structure[non_hetero_structure.chain_id == chain1][0].res_id - 1
-            shift2 = non_hetero_structure[non_hetero_structure.chain_id == chain2][0].res_id - 1
-            shift1 *= -1
-            shift2 *= -1
-            return shift1, shift2
-        else:
-            return shift1, shift2
-
     def get_min_dist_atom_info(self, pairs: npt.NDArray, chain1: str, chain2: str) -> npt.NDArray:
         """
         Generate a ndarray of residue ids and their corresponding atom names such that the distance is the minimum between the initial residues provided.
@@ -1211,8 +1307,8 @@ class PDBInformation(StructureInformation):
         min_dist_pairs_atoms_arr : numpy.ndarray
             Structured ndarray that has residue indices, auth residue indices (corresponding to the protein numbering), and atomic names in the format {'names': ['residue1','residue2','auth_residue1','auth_residue2','atom_name1','atom_name2'], 'formats': [int,int,int,int,'<U10','<U10']}
         """
-        shift1, shift2 = self.get_shift_values(chain1, chain2)
-        chain1_structure, chain2_structure = self.get_chain_specific_structure(ca_only=False, chain1=chain1, chain2=chain2, remove_hetero=True)
+        chain1_structure = self.get_chain_specific_structure(ca_only=False, chain_id=chain1, remove_hetero=True)
+        chain2_structure = self.get_chain_specific_structure(ca_only=False, chain_id=chain2, remove_hetero=True)
         min_dist_pairs_atoms = []
         for row in pairs:
             # Obtain structure information for chains 1 and 2
@@ -1223,15 +1319,11 @@ class PDBInformation(StructureInformation):
             dist_matrix = cdist(chain1_res1_structure.coord, chain2_res2_structure.coord)
             
             ind = np.unravel_index(np.argmin(dist_matrix), dist_matrix.shape)
-            # Use the indices to access the atom in the atom array and get the correct atom name.
-            # Generate the auth ids of the residues in the pairs ndarray
-            orig_res_id1 = row['residue1'] + shift1
-            orig_res_id2 = row['residue2'] + shift2
-            min_dist_pairs_atoms.append((orig_res_id1, orig_res_id2, row['residue1'], row['residue2'], chain1_res1_structure[ind[0]].atom_name, chain2_res2_structure[ind[1]].atom_name))
+            min_dist_pairs_atoms.append((row['residue1'], row['residue2'], row['residue1'], row['residue2'], chain1_res1_structure[ind[0]].atom_name, chain2_res2_structure[ind[1]].atom_name))
         min_dist_pairs_atoms_arr = np.array(min_dist_pairs_atoms, dtype={'names': ['residue1','residue2','auth_residue1','auth_residue2','atom_name1','atom_name2'], 'formats': [int,int,int,int,'<U10','<U10']})
         return min_dist_pairs_atoms_arr    
 
-    def get_contacts(self, ca_only: bool, threshold: float, chain1: str, chain2: str, auth_contacts: bool=False) -> set[tuple[int, int]]:
+    def get_contacts(self, ca_only: bool, threshold: float, chain1: str, chain2: str) -> set[tuple[int, int]]:
         """
         Get contacts from the structure attribute where the distance between two residues is less than the threshold.
 
@@ -1245,8 +1337,6 @@ class PDBInformation(StructureInformation):
             Chain id corresponding to the first column of residues in the structure.
         chain2 : str
             Chain id corresponding to the second column of residues in the structure.
-        auth_contacts : bool
-            True if you want alt_ids for residues indices, False if cif residue indexing is needed.
 
         Returns
         -------
@@ -1263,9 +1353,5 @@ class PDBInformation(StructureInformation):
             res1 = chain1_atom.res_id
             res2 = chain2_atom.res_id
             if not(chain1==chain2 and res1 >= res2):
-                if not auth_contacts:
-                    shift1, shift2 = self.get_shift_values(chain1, chain2)
-                    contacts_set.add((res1 + shift1, res2 + shift2))
-                else:
-                    contacts_set.add((res1, res2))
+                contacts_set.add((res1, res2))
         return contacts_set

{dcatoolkit-0.2.2 → dcatoolkit-0.2.3/src/dcatoolkit.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: dcatoolkit
-Version: 0.2.2
+Version: 0.2.3
 Summary: Collection of useful modules and representations for managing DCA output data.
 Author-email: Raheel Syed Ahmed <raheelsyedahmed@gmail.com>
 Maintainer-email: Raheel Syed Ahmed <raheelsyedahmed@gmail.com>
@@ -52,6 +52,7 @@ Requires-Dist: pdoc; extra == "docs"
 Requires-Dist: numpydoc; extra == "docs"
 Provides-Extra: lint
 Requires-Dist: ruffle; extra == "lint"
+Dynamic: license-file
 
 # dcatoolkit
  Collection of useful modules and representations for managing DCA output data.

{dcatoolkit-0.2.2 → dcatoolkit-0.2.3}/src/dcatoolkit.egg-info/SOURCES.txt

@@ -9,4 +9,6 @@ src/dcatoolkit.egg-info/SOURCES.txt
 src/dcatoolkit.egg-info/dependency_links.txt
 src/dcatoolkit.egg-info/requires.txt
 src/dcatoolkit.egg-info/top_level.txt
-tests/test_contacts.py
+tests/test_alignments.py
+tests/test_contacts.py
+tests/test_sequence_numbering.py

dcatoolkit-0.2.3/tests/test_alignments.py

@@ -0,0 +1,88 @@
+from context import ResidueAlignment
+import pandas as pd
+
+test_cases = """
+Test Case 1
+First:  MA.KLT
+Second: MAAKLT
+
+Test Case 2
+First:  Q..EWLP
+Second: QATEWLP
+
+Test Case 3
+First:  D.G.H.V
+Second: DAGAHAV
+
+Test Case 4
+First:  TAKAPF
+Second: TAMAPF
+
+Test Case 5
+First:  FACARAA
+Second: FACAR--
+
+Test Case 6
+First:  ALMAY
+Second: ALMAY
+
+Test Case 7
+First:  VAIDTSK
+Second: VAID--K
+
+Test Case 8
+First:  NG.TA
+Second: NG-TA
+
+Test Case 9
+First:  STWLPL
+Second: SAWLPL
+
+Test Case 10
+First:  HCSTCRAAC
+Second: H--TAR--C
+"""
+
+
+test_cases = [
+    (47, 15, 'MA.KLT', 'MAAKLT'),
+    (39, 3, 'Q..EWLP', 'QATEWLP'),
+    (8, 45, 'D.G.H.V', 'DAGAHAV'),
+    (26, 19, 'TAKAPF', 'TAMAPF'),
+    (33, 9, 'FACARAA', 'FACAR--')
+]
+test_cases_validation = [
+    (42, 28, 'ALMAY', 'ALMAY'),
+    (14, 11, 'VAIDTSK', 'VAID--K'),
+    (10, 5, 'NG.TA', 'NG-TA'),
+    (2, 44, 'STWLPL', 'SAWLPL'),
+    (17, 34, 'HCSTCRAAC', 'H--TAR--C')
+]
+
+test_answers = [
+    [(47, 48, pd.NA, 49, 50, 51), tuple('MA.KLT'), tuple('MAAKLT'), (15,16,17,18,19,20)],
+    [(39, pd.NA, pd.NA, 40, 41, 42, 43), tuple('Q..EWLP'), tuple('QATEWLP'), (3,4,5,6,7,8,9)],
+    [(8, pd.NA, 9, pd.NA, 10, pd.NA, 11), tuple('D.G.H.V'), tuple('DAGAHAV'), (45,46,47,48,49,50,51)],
+    [(26, 27, 28, 29, 30, 31), tuple('TAKAPF'), tuple('TAMAPF'), (19,20,21,22,23,24)],
+    [(33, 34, 35, 36, 37, 38, 39), tuple('FACARAA'), tuple('FACAR--'), (9,10,11,12,13,pd.NA,pd.NA)],
+    [(42, 43, 44, 45, 46), tuple('ALMAY'), tuple('ALMAY'), (28,29,30,31,32)],
+    [(14, 15, 16, 17, 18, 19, 20), tuple('VAIDTSK'), tuple('VAID--K'), (11, 12, 13, 14, pd.NA, pd.NA, 15)],
+    [(10,11,pd.NA,12,13), tuple('NG.TA'), tuple('NG-TA'), (5,6,pd.NA,7,8)],
+    [(2,3,4,5,6,7), tuple('STWLPL'), tuple('SAWLPL'), (44,45,46,47,48,49)],
+    [(17,18,19,20,21,22,23,24,25), tuple('HCSTCRAAC'), tuple('H--TAR--C'), (34, pd.NA, pd.NA, 35,36,37, pd.NA, pd.NA, 38)]
+]
+
+def test_residue_alignments():
+    for test_num, test_case in enumerate(test_cases):
+        domain_start, protein_start, first_seq, second_seq = test_case
+        module_result = list(ResidueAlignment(f"Test_{test_num}", f"Test {test_num}", domain_start, protein_start, first_seq, second_seq).reference_mapping.itertuples(index=False, name=None))
+        answer = list(zip(*test_answers[test_num]))
+        assert module_result == answer
+    for test_num, test_case in enumerate(test_cases_validation, start=test_num+1):
+        domain_start, protein_start, first_seq, second_seq = test_case
+        module_result = list(ResidueAlignment(f"Test_{test_num}", f"Test {test_num}", domain_start, protein_start, first_seq, second_seq).reference_mapping.itertuples(index=False, name=None))
+        answer = list(zip(*test_answers[test_num]))
+        assert module_result == answer
+
+# Can handle excess residues, but not missing any ones that are supposed to be there.
+print(ResidueAlignment('name1', 'name2', 1, 1, 'MAAFT', 'MAAFT', valid_residues=[(5, 'M'), (6, 'A'), (7, 'A'), (8, 'R'), (12, 'F')]))

{dcatoolkit-0.2.2 → dcatoolkit-0.2.3}/tests/test_contacts.py

@@ -59,12 +59,12 @@ def check_contacts(test_CA: bool, threshold: float):
         
         cif_file_contacts = read_contacts(corresponding_file)
         chain1, auth_chain1, chain2, auth_chain2 = pdb_id_chain_map[pdb_id]
-        fetch_cif_contacts = {(int(x[0]), int(x[1])) for x in MMCIFInformation.fetch_pdb(pdb_id, 'mmcif').get_contacts(test_CA, threshold, chain1, chain2, auth_contacts=True)}
-        read_cif_contacts = {(int(x[0]), int(x[1])) for x in MMCIFInformation.read_mmCIF_file(str(cif_file)).get_contacts(test_CA, threshold, chain1, chain2, auth_contacts=True)}
-        fetch_authchain_cif_contacts = {(int(x[0]), int(x[1])) for x in MMCIFInformation.fetch_pdb(pdb_id, 'mmcif').get_contacts(test_CA, threshold, auth_chain1, auth_chain2, auth_contacts=True, auth_chain_id_supplied=True)}
-        read_authchain_cif_contacts = {(int(x[0]), int(x[1])) for x in MMCIFInformation.read_mmCIF_file(str(cif_file)).get_contacts(test_CA, threshold, auth_chain1, auth_chain2, auth_contacts=True, auth_chain_id_supplied=True)}
-        fetch_pdb_contacts = {(int(x[0]), int(x[1])) for x in PDBInformation.fetch_pdb(pdb_id, struc_format="pdb").get_contacts(test_CA, threshold, auth_chain1, auth_chain2, auth_contacts=True)}
-        read_pdb_contacts = {(int(x[0]), int(x[1])) for x in PDBInformation.read_pdb_file(f"tests/pdb_info/{pdb_id.lower()}.pdb").get_contacts(test_CA, threshold, auth_chain1, auth_chain2, auth_contacts=True)}
+        fetch_cif_contacts = {(int(x[0]), int(x[1])) for x in MMCIFInformation.fetch_pdb(pdb_id, 'mmcif').get_contacts(test_CA, threshold, chain1, chain2, auth_seq_id=True)}
+        read_cif_contacts = {(int(x[0]), int(x[1])) for x in MMCIFInformation.read_mmCIF_file(str(cif_file)).get_contacts(test_CA, threshold, chain1, chain2, auth_seq_id=True)}
+        fetch_authchain_cif_contacts = {(int(x[0]), int(x[1])) for x in MMCIFInformation.fetch_pdb(pdb_id, 'mmcif').get_contacts(test_CA, threshold, auth_chain1, auth_chain2, auth_seq_id=True, auth_chain_id_supplied=True)}
+        read_authchain_cif_contacts = {(int(x[0]), int(x[1])) for x in MMCIFInformation.read_mmCIF_file(str(cif_file)).get_contacts(test_CA, threshold, auth_chain1, auth_chain2, auth_seq_id=True, auth_chain_id_supplied=True)}
+        fetch_pdb_contacts = {(int(x[0]), int(x[1])) for x in PDBInformation.fetch_pdb(pdb_id, struc_format="pdb").get_contacts(test_CA, threshold, auth_chain1, auth_chain2)}
+        read_pdb_contacts = {(int(x[0]), int(x[1])) for x in PDBInformation.read_pdb_file(f"tests/pdb_info/{pdb_id.lower()}.pdb").get_contacts(test_CA, threshold, auth_chain1, auth_chain2)}
         
         
         fetch_cif_contacts = drop_inord_res(fetch_cif_contacts)
@@ -86,7 +86,7 @@ def check_contacts(test_CA: bool, threshold: float):
         else:
             compare(fetch_cif_contacts, fetch_pdb_contacts, read_cif_contacts, read_pdb_contacts)
             print(f"{pdb_id} has no difference between cif and pdb reading.")
-
+            
             compare(fetch_cif_contacts, fetch_authchain_cif_contacts, read_cif_contacts, read_authchain_cif_contacts)
             print(f"{pdb_id} has no issue reading with auth chains and asym chains.")
         

dcatoolkit-0.2.3/tests/test_sequence_numbering.py

@@ -0,0 +1,14 @@
+from context import MMCIFInformation, PDBInformation
+from pathlib import Path
+import biotite.structure.io.pdbx as pdbx
+import biotite.database.rcsb as rcsb
+
+
+pdb_ids = ['1pzs', '3ddv', '6avj', '3d7i', '4OO8']
+
+for index, AA in MMCIFInformation.fetch_pdb("4OO8", "mmcif").get_valid_chain_residues("A"):
+   if index > 30:
+       break
+   else:
+       pass
+       print(index, AA)