dcatoolkit 0.2.3__tar.gz → 0.4.0__tar.gz

{dcatoolkit-0.2.3 → dcatoolkit-0.4.0}/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2024 Raheel Syed Ahmed
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2024 Raheel Syed Ahmed
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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

@@ -1,73 +1,120 @@
-Metadata-Version: 2.4
-Name: dcatoolkit
-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>
-License: MIT License
-        
-        Copyright (c) 2024 Raheel Syed Ahmed
-        
-        Permission is hereby granted, free of charge, to any person obtaining a copy
-        of this software and associated documentation files (the "Software"), to deal
-        in the Software without restriction, including without limitation the rights
-        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-        copies of the Software, and to permit persons to whom the Software is
-        furnished to do so, subject to the following conditions:
-        
-        The above copyright notice and this permission notice shall be included in all
-        copies or substantial portions of the Software.
-        
-        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-        SOFTWARE.
-        
-Keywords: dca,toolkit,DI,coevolution
-Classifier: Development Status :: 4 - Beta
-Classifier: Intended Audience :: Science/Research
-Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: biotite>=1.0.1
-Requires-Dist: matplotlib>=3.8.0
-Requires-Dist: numpy>=1.26.0
-Requires-Dist: pandas>=2.1.0
-Requires-Dist: scikit-learn>=1.3
-Requires-Dist: scipy>=1.11.0
-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"
-Dynamic: license-file
-
-# dcatoolkit
- Collection of useful modules and representations for managing DCA output data.
-
-## Major Sections
-### Representations
-  * Use Pairs to load lists, tuples, sets, and ndarrays with the correct orientation of elements. This will allow you to yield integer pairs that can be mirrored (where y becomes x and vice versa) and to subset various pairs.
-  * Use DirectInformationData to create 3-column structured ndarrays that can be sorted by "DI", mapped to a protein with a ResidueAlignment, and used to generate output for other programs (including UCSF Chimera)
-  * Use ResidueAlignment to generate a reference map. Indices of one sequence of characters can be linked to their corresponding indices of the other sequence of characters. The dictionaries produced, domain-to-protein and protein-to-domain, allow for forward mapping and backmapping.
-  * Use StructureInformation to find contacts in a protein structure and find atomic information related to specific pairs of interest.
-### Analytics
-  * Use MSATools to load in Multiple Sequence Alignment (MSA) data and provide functionality including generating frequency statistics on "gappiness" in the MSA and filtering and cleaning MSAs.
-
-
-## Diagram of Hidden Markov Machine & Direct Coupling Analysis Pipeline
-<p align="center">
-  <img src="https://github.com/user-attachments/assets/4768e08f-d513-4dbf-abc5-c80c1b3d42aa"/>
-</p>
+Metadata-Version: 2.4
+Name: dcatoolkit
+Version: 0.4.0
+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>
+License: MIT License
+        
+        Copyright (c) 2024 Raheel Syed Ahmed
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/RaheelSyedAhmed/dcatoolkit
+Project-URL: Changelog, https://github.com/RaheelSyedAhmed/dcatoolkit/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/RaheelSyedAhmed/dcatoolkit/issues
+Keywords: dca,toolkit,DI,coevolution
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: biotite>=1.7
+Requires-Dist: numpy>=1.26.0
+Requires-Dist: pandas>=2.1.0
+Requires-Dist: scipy>=1.11.0
+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: ruff; extra == "lint"
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.10.9; extra == "plot"
+Dynamic: license-file
+
+# dcatoolkit
+ Collection of useful modules and representations for managing DCA output data.
+
+## Installation
+
+```bash
+pip install dcatoolkit
+
+# optional: adds matplotlib for the plotting example"
+pip install "dcatoolkit[plot]"  
+```
+
+Requires Python 3.12+.
+Upgrading from 0.2.x? See the [changelog](https://github.com/RaheelSyedAhmed/dcatoolkit/blob/main/CHANGELOG.md).
+
+## Major Sections
+### Representations
+  * Use Pairs to load lists, tuples, sets, and ndarrays with the correct orientation of elements. This will allow you to store integer pairs, in the form of structured arrays with fields `residue1` and `residue2` that can be mirrored (where y becomes x and vice versa) and subset.
+  * Use DirectInformationData to create structured ndarrays with `residue1`, `residue2`, and `DI` fields that can be sorted by `DI`, mapped to a protein with a ResidueAlignment, and used to generate output for other programs (including UCSF Chimera)
+  * Use ResidueAlignment to generate a reference map. Indices of one sequence of characters can be linked to their corresponding indices of the other sequence of characters. The dictionaries produced, domain-to-protein and protein-to-domain, allow for forward mapping and backmapping.
+  * Use StructureInformation to find contacts in a protein structure and find atomic information related to specific pairs of interest. It can read in PDBx/mmCIF and PDB files or fetch them from RCSB and find contacts between residues.
+### Analytics
+  * Use MSATools to load in Multiple Sequence Alignment (MSA) data and provide functionality including generating frequency statistics on "gappiness" in the MSA and filtering and cleaning MSAs.
+
+
+## Quick Start
+```python
+from dcatoolkit import DirectInformationData, ResidueAlignment, StructureInformation
+
+# Rank DI pairs and map them from MSA (domain) numbering onto the protein sequence.
+di = DirectInformationData.load_from_DI_file("my_dca_output.DI")
+alignment = ResidueAlignment.load_from_align_file("my_domain.align")
+top_pairs = di.get_ranked_mapped_pairs(alignment, alignment, number=50)
+
+# Compare the top pairs with residue contacts in a structure.
+structure = StructureInformation.fetch_pdb("2KLL")
+contacts = structure.get_contacts(ca_only=False, threshold=8, chain1="A", chain2="A")
+hits = [pair for pair in top_pairs.tolist() if pair in contacts]
+```
+
+## Diagram of Hidden Markov Model & Direct Coupling Analysis Pipeline
+<p align="center">
+  <img src="https://github.com/user-attachments/assets/4768e08f-d513-4dbf-abc5-c80c1b3d42aa"/>
+</p>
+
+## Development
+
+This project uses [uv](https://docs.astral.sh/uv/) for dependency management.
+
+```bash
+git clone https://github.com/RaheelSyedAhmed/dcatoolkit.git
+cd dcatoolkit
+uv sync --all-extras
+```
+
+Run the test suite (requires internet to fetch from RCSB):
+
+```bash
+uv run pytest
+
+uv sync --all-extras # Installs packages from tests, docs, lint, and plot.
+uv run ruff check # linting
+```

dcatoolkit-0.4.0/README.md

@@ -0,0 +1,63 @@
+# dcatoolkit
+ Collection of useful modules and representations for managing DCA output data.
+
+## Installation
+
+```bash
+pip install dcatoolkit
+
+# optional: adds matplotlib for the plotting example"
+pip install "dcatoolkit[plot]"  
+```
+
+Requires Python 3.12+.
+Upgrading from 0.2.x? See the [changelog](https://github.com/RaheelSyedAhmed/dcatoolkit/blob/main/CHANGELOG.md).
+
+## Major Sections
+### Representations
+  * Use Pairs to load lists, tuples, sets, and ndarrays with the correct orientation of elements. This will allow you to store integer pairs, in the form of structured arrays with fields `residue1` and `residue2` that can be mirrored (where y becomes x and vice versa) and subset.
+  * Use DirectInformationData to create structured ndarrays with `residue1`, `residue2`, and `DI` fields that can be sorted by `DI`, mapped to a protein with a ResidueAlignment, and used to generate output for other programs (including UCSF Chimera)
+  * Use ResidueAlignment to generate a reference map. Indices of one sequence of characters can be linked to their corresponding indices of the other sequence of characters. The dictionaries produced, domain-to-protein and protein-to-domain, allow for forward mapping and backmapping.
+  * Use StructureInformation to find contacts in a protein structure and find atomic information related to specific pairs of interest. It can read in PDBx/mmCIF and PDB files or fetch them from RCSB and find contacts between residues.
+### Analytics
+  * Use MSATools to load in Multiple Sequence Alignment (MSA) data and provide functionality including generating frequency statistics on "gappiness" in the MSA and filtering and cleaning MSAs.
+
+
+## Quick Start
+```python
+from dcatoolkit import DirectInformationData, ResidueAlignment, StructureInformation
+
+# Rank DI pairs and map them from MSA (domain) numbering onto the protein sequence.
+di = DirectInformationData.load_from_DI_file("my_dca_output.DI")
+alignment = ResidueAlignment.load_from_align_file("my_domain.align")
+top_pairs = di.get_ranked_mapped_pairs(alignment, alignment, number=50)
+
+# Compare the top pairs with residue contacts in a structure.
+structure = StructureInformation.fetch_pdb("2KLL")
+contacts = structure.get_contacts(ca_only=False, threshold=8, chain1="A", chain2="A")
+hits = [pair for pair in top_pairs.tolist() if pair in contacts]
+```
+
+## Diagram of Hidden Markov Model & Direct Coupling Analysis Pipeline
+<p align="center">
+  <img src="https://github.com/user-attachments/assets/4768e08f-d513-4dbf-abc5-c80c1b3d42aa"/>
+</p>
+
+## Development
+
+This project uses [uv](https://docs.astral.sh/uv/) for dependency management.
+
+```bash
+git clone https://github.com/RaheelSyedAhmed/dcatoolkit.git
+cd dcatoolkit
+uv sync --all-extras
+```
+
+Run the test suite (requires internet to fetch from RCSB):
+
+```bash
+uv run pytest
+
+uv sync --all-extras # Installs packages from tests, docs, lint, and plot.
+uv run ruff check # linting
+```

dcatoolkit-0.4.0/pyproject.toml

@@ -0,0 +1,84 @@
+[build-system]
+requires = ["setuptools >= 61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "dcatoolkit"
+version = "0.4.0"
+description = "Collection of useful modules and representations for managing DCA output data."
+keywords = ["dca", "toolkit", "DI", "coevolution"]
+
+readme = "README.md"
+license = {file = "LICENSE"}
+
+requires-python = ">=3.12"
+
+authors = [
+  {name = "Raheel Syed Ahmed", email = "raheelsyedahmed@gmail.com"}
+]
+maintainers = [
+  {name = "Raheel Syed Ahmed", email = "raheelsyedahmed@gmail.com"}
+]
+
+dependencies = [
+  "biotite>=1.7",
+  "numpy>=1.26.0",
+  "pandas>=2.1.0",
+  "scipy>=1.11.0",
+]
+
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Science/Research",
+  "Topic :: Scientific/Engineering :: Bio-Informatics",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.12",
+]
+
+[project.urls]
+Homepage = "https://github.com/RaheelSyedAhmed/dcatoolkit"
+Changelog = "https://github.com/RaheelSyedAhmed/dcatoolkit/blob/main/CHANGELOG.md"
+Issues = "https://github.com/RaheelSyedAhmed/dcatoolkit/issues"
+
+[project.optional-dependencies]
+tests = [
+  "pytest",
+]
+docs = [
+  "sphinx",
+  "pdoc",
+  "numpydoc"
+]
+lint = [
+  "ruff",
+]
+plot = [
+    "matplotlib>=3.10.9",
+]
+[tool.ruff]
+# The target Python version is inferred from requires-python above.
+# Lint the package and its tests; examples are standalone scripts.
+extend-exclude = [
+  "examples",
+  # Python 2 scripts that generated the reference contact files in tests/pdb_info; not valid Python 3.
+  "tests/pdb_info/interface_contacts_allatom_args.py",
+  "tests/pdb_info/interface_contacts_calpha_args.py",
+]
+
+[tool.ruff.lint]
+# Explicit rule selection, so results don't change with ruff's defaults between versions.
+select = [
+  "E4", "E7", "E9",  # pycodestyle errors: imports, statements, syntax
+  "F",               # Pyflakes: unused imports/variables, undefined names
+  "B",               # flake8-bugbear: likely bugs
+  "I",               # isort: import ordering
+  "UP",              # pyupgrade: modern syntax for the target Python version
+  "C4",              # flake8-comprehensions
+  "SIM",             # flake8-simplify
+  "PIE",             # flake8-pie: unnecessary code
+  "RUF",             # Ruff-specific rules
+]
+ignore = [
+  "B905",  # zip() without strict=: most zips are equal-length by construction, and ResidueAlignment deliberately truncates mismatched align texts.
+]

{dcatoolkit-0.2.3 → dcatoolkit-0.4.0}/setup.cfg

@@ -1,4 +1,4 @@
-[egg_info]
-tag_build = 
-tag_date = 0
-
+[egg_info]
+tag_build = 
+tag_date = 0
+

dcatoolkit-0.4.0/src/dcatoolkit/__init__.py

@@ -0,0 +1,15 @@
+
+from importlib.metadata import version as _version
+
+__version__ = _version("dcatoolkit")
+from .analytics import MSATools
+from .representation import (
+    DirectInformationData,
+    MMCIFInformation,
+    Pairs,
+    PDBInformation,
+    ResidueAlignment,
+    StructureInformation,
+)
+
+__all__ = ['DirectInformationData', 'MMCIFInformation', 'MSATools', 'PDBInformation', 'Pairs', 'ResidueAlignment', 'StructureInformation']

dcatoolkit-0.4.0/src/dcatoolkit/analytics.py

@@ -0,0 +1,230 @@
+import io
+import re
+import string
+from collections import Counter
+from collections.abc import Callable
+from pathlib import Path
+from typing import Literal
+
+import numpy as np
+import numpy.typing as npt
+
+
+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 (including its leading ``">"``) and the second element is its corresponding sequence.
+
+    Attributes
+    ----------
+    MSA : list of tuple of (str, str)
+        The `MSA` supplied.
+    """
+    _GAP_CLEANUP_TABLE = str.maketrans('', '', string.ascii_lowercase + ".")
+
+    def __init__(self, MSA: list[tuple[str, str]]):
+        self.MSA = MSA
+    
+    @staticmethod
+    def load_from_file(msa_source: str | io.IOBase | Path) -> 'MSATools':
+        """
+        Generates MSATools object from an MSA file in aligned FASTA (``.afa``) format.
+
+        Parameters
+        ----------
+        msa_source : str or pathlib.Path or io.BytesIO or io.TextIOBase
+            Filepath, or in-memory bytes or text stream, of the MSA in ``.afa`` format. Streams are read from the beginning.
+
+        Returns
+        -------
+        MSATools
+            An MSATools instance with the appropriate list of ``(header, sequence)`` tuples where sequences are simplified and converted to single line format.
+
+        Raises
+        ------
+        TypeError
+            If `msa_source` is not a filepath, ``io.BytesIO``, or ``io.TextIOBase``.
+
+        Notes
+        -----
+        Windows (``\\r\\n``) and old Mac (``\\r``) line endings are normalized to ``\\n`` before parsing. Headers keep their leading ``">"``.
+        """
+        data = ""
+        msa_entries: list[tuple[str, str]] = []
+        if isinstance(msa_source, (str, Path)):
+            with open(msa_source) as fs:
+                data = fs.read()
+        elif isinstance(msa_source, io.BytesIO):
+            data = msa_source.getvalue().decode()
+        elif isinstance(msa_source, io.TextIOBase):
+            msa_source.seek(0)
+            data = msa_source.read()
+        else:
+            raise TypeError("msa_file is not bytesIO, a TextIO, or a filepath.")
+
+        data = data.replace("\r\n", "\n").replace("\r", "\n")
+        split_data = data.split(">")[1:]
+        for entry in split_data:
+            header, _, rest = entry.partition("\n")
+            sequence = rest.replace("\n", "")
+            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, or 0 if there are none. Other characters, such as ``"."``, break a run of gaps.
+        """
+        return max((m.end() - m.start() for m in re.finditer(r"-+", sequence)), default=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 continuous gaps and the value corresponds to the number of sequences or the cumulative fraction of sequences.
+
+        Returns
+        -------
+        tuple of (dict of {int : int}, dict of {int : float})
+            Two element tuple where the first element maps each maximum continuous gap length to the number of sequences with it, and the second element maps it to the cumulative fraction (0 to 1) of sequences with that maximum or fewer.
+
+        See Also
+        --------
+        get_sequence_max_cont_gaps : Computes each sequence's maximum continuous gap length.
+        filter_by_continuous_gaps : Filters sequences by that length.
+
+        Notes
+        -----
+        Gaps are counted on the sequences as stored. To match the counts `filter_by_continuous_gaps()` uses, run this on an already filtered MSA, e.g. ``MSATools(msa.filter_by_continuous_gaps()).gap_frequency()``.
+        """
+        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: int | None=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 ``"."`` characters and lowercase letters (insert positions) from the sequence.
+
+        Parameters
+        ----------
+        max_gaps : int, optional
+            The maximum allowed number of continuous gaps in a sequence. If None, no entries are removed, but sequences are still cleaned.
+
+        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`. Wrap it in ``MSATools(...)`` to keep working with it as an MSA.
+
+        Notes
+        -----
+        Insert characters are removed before gaps are counted, so gap runs that were separated only by ``"."`` or lowercase letters count as one run.
+        """
+        kept_entries = []
+        for header, sequence in self.MSA:
+            sequence = sequence.translate(MSATools._GAP_CLEANUP_TABLE)
+            if max_gaps is None or MSATools.get_sequence_max_cont_gaps(sequence) <= max_gaps:
+                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 the gap proportion per alignment position (column) or per sequence (row) in the MSA, then aggregates it into one value.
+
+        Parameters
+        ----------
+        agg_func : callable, default numpy.mean
+            The aggregation function applied to get the expected result, usually a mean, max, or min value, of the gap proportions.
+        axis : {0, 1}, default 0
+            When `axis` is 0, gap proportions are computed per column, over every sequence in that column. When `axis` is 1, they are computed per row, over every column in that sequence.
+
+        Returns
+        -------
+        float or int
+            A numerical value determined by `agg_func` over the gap proportions.
+
+        Notes
+        -----
+        Any character that is not an ASCII letter (e.g. ``"-"`` or ``"."``) counts as a gap. All sequences must have the same length, as in an unfiltered or a filtered MSA.
+        """
+        num_rows = len(self.MSA)
+        num_cols = len(self.MSA[0][1])
+        flat = np.frombuffer("".join(seq for _, seq in self.MSA).encode("ascii"), dtype=np.uint8).reshape(num_rows, num_cols)
+        is_alpha = ((flat >= 65) & (flat <= 90)) | ((flat >= 97) & (flat <= 122))
+        non_alpha_counts = np.sum(~is_alpha, axis) / flat.shape[axis]
+        return agg_func(non_alpha_counts)
+
+    def write(self, destination: str | Path | io.TextIOBase) -> None:
+        """
+        Writes this MSA's headers and sequences to the destination specified, each header followed by its sequence on a single line.
+
+        Parameters
+        ----------
+        destination : str or pathlib.Path or io.TextIOBase
+            Filepath or writable text stream to write the MSA to.
+
+        Raises
+        ------
+        TypeError
+            If `destination` is not a filepath or a writable ``io.TextIOBase``.
+        """
+        lines = (f"{header}\n{sequence}\n" for header, sequence in self.MSA)
+        if isinstance(destination, (str, Path)):
+            with open(destination, 'w') as fs:
+                fs.writelines(lines)
+        elif isinstance(destination, io.TextIOBase) and destination.writable():
+            destination.writelines(lines)
+        else:
+            raise TypeError(f"Destination supplied is either not a filepath or is not a writeable TextIO object (got {type(destination).__name__}).")
+
+    def as_matrix(self) -> npt.NDArray:
+        """
+        Represents the MSA as a numpy matrix of sequences.
+
+        Returns
+        -------
+        numpy.ndarray
+            A ``<U1`` (one-character string) matrix with one row per sequence and one column per alignment position. 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.
+
+        Returns
+        -------
+        int
+            Length of the MSA list of ``(header, sequence)`` tuples.
+        """
+        return len(self.MSA)

dcatoolkit-0.4.0/src/dcatoolkit/representation/__init__.py

@@ -0,0 +1,6 @@
+from .alignment import ResidueAlignment
+from .di import DirectInformationData
+from .pairs import Pairs
+from .structure import MMCIFInformation, PDBInformation, StructureInformation
+
+__all__ = ['DirectInformationData', 'MMCIFInformation', 'PDBInformation', 'Pairs', 'ResidueAlignment', 'StructureInformation']