dcatoolkit 0.1.1__tar.gz → 0.1.3__tar.gz

{dcatoolkit-0.1.1/src/dcatoolkit.egg-info → dcatoolkit-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: dcatoolkit
-Version: 0.1.1
+Version: 0.1.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>
@@ -48,6 +48,7 @@ Provides-Extra: tests
 Requires-Dist: pytest; extra == "tests"
 Provides-Extra: docs
 Requires-Dist: sphinx; extra == "docs"
+Requires-Dist: pdoc; extra == "docs"
 Requires-Dist: numpydoc; extra == "docs"
 Provides-Extra: lint
 Requires-Dist: ruffle; extra == "lint"

{dcatoolkit-0.1.1 → dcatoolkit-0.1.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "dcatoolkit"
-version = "0.1.1"
+version = "0.1.3"
 description = "Collection of useful modules and representations for managing DCA output data."
 keywords = ["dca", "toolkit", "DI", "coevolution"]
 
@@ -46,6 +46,7 @@ tests = [
 ]
 docs = [
   "sphinx",
+  "pdoc",
   "numpydoc"
 ]
 lint = [

dcatoolkit-0.1.3/src/dcatoolkit/__init__.py

@@ -0,0 +1,4 @@
+
+__version__ = "0.1.3"
+from .representation import Pairs, DirectInformationData, StructureInformation, ResidueAlignment
+from .analytics import MSATools

dcatoolkit-0.1.3/src/dcatoolkit/analytics.py

@@ -0,0 +1,145 @@
+import re
+from collections import Counter
+from typing import Optional
+import string
+
+class MSATools:
+    """
+    Tools and interface for encapsulating MSA data and providing functionality for filtering and analysis.
+
+    Parameters
+    ----------
+    MSA : list of tuple of str, str
+        Loaded MSA that is a list of tuples where the first element is the header and the second element is its corresponding sequence.
+    """
+    def __init__(self, MSA: list[tuple[str, str]]):
+        self.MSA = MSA
+    
+    @staticmethod
+    def load_from_file(msa_filepath: str) -> 'MSATools':
+        """
+        Generates MSATools object from an MSA file in ".afa" format.
+
+        Parameters
+        ----------
+        msa_filepath : str
+            Filepath of the MSA in ".afa" format that is provided.
+        
+        Returns
+        -------
+        MSATools
+            An MSATools instance with the appropriate list of (header, sequence) tuples where sequences are simplified and converted to single line format.
+        """
+        msa_entries: list[tuple[str, str]] = []
+        with open(msa_filepath, 'r') as fs:
+            data = fs.read()
+        split_data = data.split(">")[1:]
+        for entry in split_data:
+            line_split_entry = entry.split("\n")
+            header = line_split_entry[0]
+            sequence = "".join(line_split_entry[1:])
+            msa_entries.append((">"+header, sequence))
+        return MSATools(msa_entries)
+
+    @staticmethod
+    def get_sequence_max_cont_gaps(sequence: str) -> int:
+        """
+        Find maximum number of continuous gaps in a specific sequence.
+
+        Parameters
+        ----------
+        sequence : str
+            Sequence of characters, potentially containing multiple of '-', a gap character.
+        
+        Returns
+        -------
+        int
+            The maximum number of continuous gaps in a sequence.
+        """
+        dash_match = re.findall(r"-+", sequence)
+        gap_counts = [len(match) for match in dash_match]
+        if len(gap_counts) > 0:
+            return max(gap_counts)
+        else:
+            return 0
+    
+    def gap_frequency(self) -> tuple[dict[int, int], dict[int, float]]:
+        """
+        Calculates the frequency of maximum continuous gaps throughout the MSA where the key corresponds to the number of continous gaps and the value corresponds to the number of sequences or the cumulative percentage of their sequences.
+
+        Returns
+        -------
+        tuple of dict of int, int and dict of int, int
+            Two element tuple where first element is a frequency count dictionary and the second element is a cumulative percentage of sequences with a specific maximum number of continous gaps.
+        """
+        max_gap_counts = []
+        for header, sequence in self.MSA:
+            max_gap_counts.append(MSATools.get_sequence_max_cont_gaps(sequence))
+        frequency_count_dict = dict(Counter(max_gap_counts))
+        cumul_perc_dict = {}
+        cumul_count = 0
+        for key in sorted(frequency_count_dict.keys()):
+            value = frequency_count_dict[key]
+            cumul_count += value
+            cumul_perc_dict[key] = cumul_count / len(self.MSA)
+        return (frequency_count_dict, cumul_perc_dict)
+    
+    def filter_by_continuous_gaps(self, max_gaps: Optional[int]=None) -> list[tuple[str, str]]:
+        """
+        Filter out entries in your MSA by the number of maximum continuous gaps specified unless None is provided. Also, removes .s and lowercase letters from the sequence.
+
+        Parameters
+        ----------
+        max_gaps : int
+            The maximum allowed number of continuous gaps in a sequence
+
+        Returns
+        -------
+        list of tuple of str, str
+            List of entries that are valid in that their sequences' number of maximum continuous gaps is within the threshold supplied as `max_gaps`. 
+        """
+        table = str.maketrans('', '', string.ascii_lowercase+".")
+        if max_gaps == None:
+            kept_entries = []
+            for header, sequence in self.MSA:
+                sequence = sequence.translate(table)
+                kept_entries.append((header, sequence))
+            return kept_entries
+        else:
+            kept_entries = []
+            for header, sequence in self.MSA:
+                sequence = sequence.translate(table)
+                if MSATools.get_sequence_max_cont_gaps(sequence) <= max_gaps:
+                    kept_entries.append((header, sequence))
+        return kept_entries
+
+    def write(self, filepath: str) -> None:
+        """
+        Writes this MSA's headers and sequences to the filepath specified.
+        
+        Parameters
+        ----------
+        filepath : str
+            Filepath to write the MSA supplied to.
+
+        Returns
+        -------
+        None
+        """
+        with open(filepath, 'w') as fs:
+            for header, sequence in self.MSA:
+                fs.write(header)
+                fs.write("\n")
+                fs.write(sequence)
+                fs.write("\n")
+
+    def __len__(self):
+        """
+        Returns the number of sequences, and equivalently, the number of headers in the MSA.
+
+        Returns
+        -------
+        int
+            length of the MSA list of header, sequence tuples.
+        """
+        return len(self.MSA)

{dcatoolkit-0.1.1 → dcatoolkit-0.1.3}/src/dcatoolkit/representation.py

@@ -1,5 +1,6 @@
 import numpy as np
 import pandas as pd
+from collections.abc import Iterable
 from scipy.spatial.distance import cdist
 
 import biotite.structure.io.pdbx as pdbx
@@ -462,6 +463,42 @@ class DirectInformationData:
         """
         return DI_data[abs(DI_data['residue1'] - DI_data['residue2']) > 4]
     
+    @staticmethod
+    def find_DI_with_residues(critical_residues_1 : Iterable[int], critical_residues_2 : Iterable[int], max_rank: Optional[int]=None, *mapped_resi_arrs: Iterable[npt.NDArray]) -> list[tuple[list, int]]:
+        """
+        Function that takes an n number of ranked, mapped DI pairs and checks to see if they're in a list of potential residue indices.
+        
+        Parameters
+        ----------
+        critical_residues_1 : collections.abc.Iterable of int
+            Specific residue indices that a DI pair will be compared to. If the first residue of the DI pair is not one of these indices, it will not be appended to results.
+        crtical_residues_2 : collections.abc.Iterable of int
+            Specific residue indices that a DI pair will be compared to. If the second residue of the DI pair is not one of these indices, it will not be appended to results.
+        threshold : int, optional
+            Maximum "rank" of the DI pair considered.
+        *mapped_resi_arrs : tuple of numpy.ndarray
+            Tuple of ranked, mapped pairs that are compared to critical residue indices and appended to results if in those indices and within threshold.
+        
+        Returns
+        -------
+        results : list of tuple of list of int, int
+            Results which consist of tuples where the first element is a list of residue1, residue2, and DI score, whereas the second element is the rank.
+        """
+        results = []
+        for mapped_resi_arr in mapped_resi_arrs:
+            # count_rank represents the rank of the DI pair being evaluated, iterating over every new row considered.
+            count_rank = 0
+            for row in mapped_resi_arr:
+                row_as_list = list(row)
+                count_rank += 1
+                if max_rank:
+                    if row_as_list[0] in critical_residues_1 and row_as_list[1] in critical_residues_2 and count_rank <= max_rank:
+                        results.append((row_as_list, count_rank))
+                else:
+                    if row_as_list[0] in critical_residues_1 and row_as_list[1] in critical_residues_2:
+                        results.append((row_as_list, count_rank))
+        return results
+
     @staticmethod
     def get_dist_commands(model1: str | int, model2: str | int, chain1: str, chain2: str, pairs: npt.NDArray, ca_only: bool=True, auth_res_ids=False) -> list[str]:
         """
@@ -543,29 +580,78 @@ class StructureInformation:
         Structure obtained from an RCSB entry with a provided pdbx/mmcif file with a specified model number.
     pdbx_file : biotite.io.pdbx.CIFFile
         mmCIF file that contains generic information and atomic information of the protein structure categorized into mmCIF blocks.
+    model_num : int
+        The model number to access from the PDB to ensure an AtomArray is returned containing the atom information of the protein structure.
 
     Attributes
     ----------
-    struct_ref_seq : zip
-        zipped version of parallel arrays that contain chain ids, beginning align indices of the sequence, and beginning align indices of the auth sequence.
+    self.atom_data : numpy.ndarray, optional
+        Entries in the format 'ATOM', residue index, chain ID, auth residue index, auth chain ID, model number
+    self.het_atom_data : numpy.ndarray, optional
+        Array of entries in the format 'HETATM', residue index, chain ID, auth residue index, auth chain ID, model number
+    self.unique_chains : numpy.ndarray, optional
+        Array of unique asym_id entries which corresponds to unique chain IDs.
+    self.chain_auth_dict : dict of str, str, optional
+        Uses chain id as a key and provides auth chain id as a value. 
+    self.res_auth_dict : dict of str, tuple of int, int or optional 
+        Uses chain id as a key and an array of residue index and auth residue index as a value.
     """
-    def __init__(self, structure, pdbx_file: pdbx.CIFFile):
+    def __init__(self, structure, pdbx_file: pdbx.CIFFile, model_num: int):
         self.structure = structure
         self.pdbx_file = pdbx_file
-        strand_ids = []
-        align_beg = []
-        auth_align_beg = []
-        # Obtain struct ref seq information (chain names, beginning residue, and the corresponding protein beginning residue)
-        for col_name, col in self.pdbx_file[list(self.pdbx_file.keys())[0]]['struct_ref_seq'].items():
-            if col_name == "pdbx_strand_id":
-                    strand_ids = col.data.array
-            if col_name == "seq_align_beg":
-                    align_beg = col.data.array
-            if col_name == "pdbx_auth_seq_align_beg": 
-                    auth_align_beg = col.data.array
-        # Put all three lists together
-        self.struct_ref_seq = zip(strand_ids, align_beg, auth_align_beg)
-                
+        self.model_num = model_num
+        self.generate_auth_info()
+
+    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.
+        
+        Note
+        ----
+        See attributes for details.
+        
+        Returns
+        -------
+        None
+        """
+        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')
+            self.chain_auth_dict = {}
+            self.res_auth_dict = {}
+            if self.atom_site_category:
+                group_pdbs = []
+                seq_ids = []
+                asym_ids = []
+                auth_seq_ids = []
+                auth_asym_ids = []
+                model_nums = []
+                for col_name, col in self.atom_site_category.items():
+                    if col_name == 'group_PDB':
+                        group_pdbs = col.as_array()
+                    elif col_name == 'label_seq_id':
+                        seq_ids = col.as_array()
+                    elif col_name == 'label_asym_id':
+                        asym_ids = col.as_array()
+                    elif col_name == 'auth_seq_id':
+                        auth_seq_ids = col.as_array()
+                    elif col_name == 'auth_asym_id':
+                        auth_asym_ids = col.as_array()
+                    elif col_name == 'pdbx_PDB_model_num':
+                        model_nums = col.as_array()
+
+                atom_site_data = np.unique(np.column_stack((group_pdbs, seq_ids, asym_ids, auth_seq_ids, auth_asym_ids, model_nums)), axis=0)
+                atom_site_data = atom_site_data[atom_site_data[:,5] == str(self.model_num)]
+                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])
+                for unique_chain in self.unique_chains:
+                    unique_entry = self.atom_data[self.atom_data[:,2] == unique_chain][0]
+                    self.chain_auth_dict[unique_entry[2]] = unique_entry[4]
+                    self.res_auth_dict[unique_entry[2]] = unique_entry[[1,3]].astype('int')
+        else:
+            self.atom_site_category = None
+
     @staticmethod
     def fetch_pdb(pdb_id: str, model_num: int=1, struc_format: str="mmcif") -> 'StructureInformation':
         """
@@ -594,7 +680,7 @@ class StructureInformation:
         if fetched_data is None:
             raise TypeError("RCSB fetch failed. Try fetch again.")
         pdbx_file = pdbx.CIFFile.read(fetched_data)
-        return StructureInformation(pdbx.get_structure(pdbx_file=pdbx_file, model=model_num, use_author_fields=False), pdbx_file)
+        return StructureInformation(pdbx.get_structure(pdbx_file=pdbx_file, model=model_num, use_author_fields=False), pdbx_file, model_num)
     
     @staticmethod
     def read_pdb_mmCIF(pdb_filepath: str, model_num: int=1) -> 'StructureInformation':
@@ -614,7 +700,7 @@ class StructureInformation:
             StructureInformation generated from pdbx.get_structure() function using the pdbx file fetched from RCSB. The pdbx file is also supplied as an argument.
         """
         pdbx_file = pdbx.CIFFile.read(pdb_filepath)
-        return StructureInformation(pdbx.get_structure(pdbx_file, model=model_num, use_author_fields=False), pdbx_file)
+        return StructureInformation(pdbx.get_structure(pdbx_file, model=model_num, use_author_fields=False), pdbx_file, model_num)
     
     def get_chain_specific_structure(self, ca_only: bool, chain1: str, chain2: str, remove_hetero=True) -> tuple:
         """
@@ -669,6 +755,31 @@ class StructureInformation:
         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.
+        """
+        shift1 = 0
+        shift2 = 0
+        if self.atom_site_category:
+            shift1 = abs(self.res_auth_dict[chain1][0] - self.res_auth_dict[chain1][1])
+            shift2 = abs(self.res_auth_dict[chain2][0] - self.res_auth_dict[chain2][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.
@@ -687,15 +798,7 @@ class 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,str,str]}
         """
-        shift1 = 0
-        shift2 = 0
-        for row in list(self.struct_ref_seq):
-            ref_seq_chain, ref_seq_beg, auth_ref_seq_beg = row
-            if ref_seq_chain == chain1:
-                shift1 = int(auth_ref_seq_beg) - int(ref_seq_beg)
-            if ref_seq_chain == chain2:
-                shift2 = int(auth_ref_seq_beg) - int(ref_seq_beg)
-            
+        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)
         min_dist_pairs_atoms = []
         for row in pairs:
@@ -711,11 +814,11 @@ class StructureInformation:
             # Generate the auth ids of the residues in the pairs ndarray
             auth_res_id1 = row['residue1'] + shift1
             auth_res_id2 = row['residue2'] + shift2
-            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.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) -> set[tuple[int, int]]:
+    def get_contacts(self, ca_only: bool, threshold: float, chain1: str, chain2: str, auth_contacts: bool=False) -> set[tuple[int, int]]:
         """
         Get contacts from the structure attribute where the distance between two residues is less than the threshold.
 
@@ -729,15 +832,47 @@ class 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 supplying alt_ids for residues indices, False if cif residue indexing is needed.
 
         Returns
         -------
         contacts_set : set of tuple of ints
             Set of contacts, tuples with "residue1" and "residue2" from the structure that are within the distance threshold.
         """
+        shift1, shift2 = self.get_shift_values(chain1, chain2)
         chain1_structure, chain2_structure, dist_matrix = self.generate_dist_matrix(ca_only, chain1, chain2)
-        contacts = np.argwhere(dist_matrix <= threshold)
+        thresh_ind = np.argwhere(dist_matrix <= threshold)
         contacts_set = set()
-        for contact in contacts:
-            contacts_set.add((chain1_structure[contact[0]].res_id, chain2_structure[contact[1]].res_id))
-        return contacts_set
+        for indices in thresh_ind:
+            chain1_atom = chain1_structure[indices[0]]
+            chain2_atom = chain2_structure[indices[1]]
+            res1 = chain1_atom.res_id
+            res2 = chain2_atom.res_id
+            if not(chain1==chain2 and res1 >= res2):
+                if auth_contacts:
+                    contacts_set.add((res1 + shift1, res2 + shift2))
+                else:
+                    contacts_set.add((res1, res2))
+        return contacts_set
+    
+    @staticmethod
+    def write_contacts_set(filepath : str, contacts_set : set[tuple[int, int]]) -> None:
+        """
+        Write the contacts generated from get_contacts or general set of tuples of pairs.
+
+        Parameters
+        ----------
+        filepath : str
+            Path of file to output contacts_set to.
+        contacts_set : set of tuple of int, int
+            Set of tuples of pairs that represent contacts.
+        
+        Returns
+        -------
+        None
+        """
+        contacts_list = list(sorted(contacts_set))
+        with open(filepath, 'w') as fs:
+            for pair in contacts_list:
+                fs.write(str(pair[0]) + "\t" + str(pair[1]) + "\n")

{dcatoolkit-0.1.1 → dcatoolkit-0.1.3/src/dcatoolkit.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: dcatoolkit
-Version: 0.1.1
+Version: 0.1.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>
@@ -48,6 +48,7 @@ Provides-Extra: tests
 Requires-Dist: pytest; extra == "tests"
 Provides-Extra: docs
 Requires-Dist: sphinx; extra == "docs"
+Requires-Dist: pdoc; extra == "docs"
 Requires-Dist: numpydoc; extra == "docs"
 Provides-Extra: lint
 Requires-Dist: ruffle; extra == "lint"

{dcatoolkit-0.1.1 → dcatoolkit-0.1.3}/src/dcatoolkit.egg-info/SOURCES.txt

@@ -2,6 +2,7 @@ LICENSE
 README.md
 pyproject.toml
 src/dcatoolkit/__init__.py
+src/dcatoolkit/analytics.py
 src/dcatoolkit/representation.py
 src/dcatoolkit.egg-info/PKG-INFO
 src/dcatoolkit.egg-info/SOURCES.txt

{dcatoolkit-0.1.1 → dcatoolkit-0.1.3}/src/dcatoolkit.egg-info/requires.txt

@@ -7,6 +7,7 @@ scipy>=1.11.0
 
 [docs]
 sphinx
+pdoc
 numpydoc
 
 [lint]

dcatoolkit-0.1.1/src/dcatoolkit/__init__.py

@@ -1,3 +0,0 @@
-
-__version__ = "0.1.1"
-from .representation import Pairs, DirectInformationData, StructureInformation, ResidueAlignment