protein-quest 0.3.1__tar.gz → 0.4.0__tar.gz

{protein_quest-0.3.1 → protein_quest-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: protein_quest
-Version: 0.3.1
+Version: 0.4.0
 Summary: Search/retrieve/filter proteins and protein structures
 Project-URL: Homepage, https://github.com/haddocking/protein-quest
 Project-URL: Issues, https://github.com/haddocking/protein-quest/issues
@@ -56,17 +56,23 @@ graph TB;
     searchuniprot --> |uniprot_accessions|searchpdbe[/Search PDBe/]
     searchuniprot --> |uniprot_accessions|searchaf[/Search Alphafold/]
     searchuniprot -. uniprot_accessions .-> searchemdb[/Search EMDB/]
+    searchintactionpartners[/Search interaction partners/] -.-x |uniprot_accessions|searchuniprot
+    searchcomplexes[/Search complexes/]
     searchpdbe -->|pdb_ids|fetchpdbe[Retrieve PDBe]
     searchaf --> |uniprot_accessions|fetchad(Retrieve AlphaFold)
     searchemdb -. emdb_ids .->fetchemdb[Retrieve EMDB]
-    fetchpdbe -->|mmcif_files_with_uniprot_acc| chainfilter{Filter on chain of uniprot}
-    chainfilter --> |mmcif_files| residuefilter{Filter on chain length}
-    fetchad -->|pdb_files| confidencefilter{Filter out low confidence}
+    fetchpdbe -->|mmcif_files| chainfilter{{Filter on chain of uniprot}}
+    chainfilter --> |mmcif_files| residuefilter{{Filter on chain length}}
+    fetchad -->|mmcif_files| confidencefilter{{Filter out low confidence}}
+    confidencefilter --> |mmcif_files| ssfilter{{Filter on secondary structure}}
+    residuefilter --> |mmcif_files| ssfilter
     classDef dashedBorder stroke-dasharray: 5 5;
     goterm:::dashedBorder
     taxonomy:::dashedBorder
     searchemdb:::dashedBorder
     fetchemdb:::dashedBorder
+    searchintactionpartners:::dashedBorder
+    searchcomplexes:::dashedBorder
 ```
 
 (Dotted nodes and edges are side-quests.)
@@ -175,6 +181,18 @@ protein-quest filter residue  \
     ./filtered-chains ./filtered
 ```
 
+### To filter on secondary structure
+
+To filter on structure being mostly alpha helices and have no beta sheets.
+
+```shell
+protein-quest filter secondary-structure \
+    --ratio-min-helix-residues 0.5 \
+    --ratio-max-sheet-residues 0.0 \
+    --write-stats filtered-ss/stats.csv \
+    ./filtered-chains ./filtered-ss
+```
+
 ### Search Taxonomy
 
 ```shell
@@ -190,6 +208,32 @@ You can use following command to search for a Gene Ontology (GO) term.
 protein-quest search go --limit 5 --aspect cellular_component apoptosome -
 ```
 
+### Search for interaction partners
+
+Use https://www.ebi.ac.uk/complexportal to find interaction partners of given UniProt accession.
+
+```shell
+protein-quest search interaction-partners Q05471 interaction-partners-of-Q05471.txt
+```
+
+The `interaction-partners-of-Q05471.txt` file contains uniprot accessions (one per line).
+
+### Search for complexes
+
+Given Uniprot accessions search for macromolecular complexes at https://www.ebi.ac.uk/complexportal
+and return the complex entries and their members.
+
+```shell
+echo Q05471 | protein-quest search complexes - complexes.csv
+```
+
+The `complexes.csv` looks like
+
+```csv
+query_protein,complex_id,complex_url,complex_title,members
+Q05471,CPX-2122,https://www.ebi.ac.uk/complexportal/complex/CPX-2122,Swr1 chromatin remodelling complex,P31376;P35817;P38326;P53201;P53930;P60010;P80428;Q03388;Q03433;Q03940;Q05471;Q06707;Q12464;Q12509
+```
+
 ##  Model Context Protocol (MCP) server
 
 Protein quest can also help LLMs like Claude Sonnet 4 by providing a [set of tools](https://modelcontextprotocol.io/docs/learn/server-concepts#tools-ai-actions) for protein structures.

{protein_quest-0.3.1 → protein_quest-0.4.0}/README.md

@@ -26,17 +26,23 @@ graph TB;
     searchuniprot --> |uniprot_accessions|searchpdbe[/Search PDBe/]
     searchuniprot --> |uniprot_accessions|searchaf[/Search Alphafold/]
     searchuniprot -. uniprot_accessions .-> searchemdb[/Search EMDB/]
+    searchintactionpartners[/Search interaction partners/] -.-x |uniprot_accessions|searchuniprot
+    searchcomplexes[/Search complexes/]
     searchpdbe -->|pdb_ids|fetchpdbe[Retrieve PDBe]
     searchaf --> |uniprot_accessions|fetchad(Retrieve AlphaFold)
     searchemdb -. emdb_ids .->fetchemdb[Retrieve EMDB]
-    fetchpdbe -->|mmcif_files_with_uniprot_acc| chainfilter{Filter on chain of uniprot}
-    chainfilter --> |mmcif_files| residuefilter{Filter on chain length}
-    fetchad -->|pdb_files| confidencefilter{Filter out low confidence}
+    fetchpdbe -->|mmcif_files| chainfilter{{Filter on chain of uniprot}}
+    chainfilter --> |mmcif_files| residuefilter{{Filter on chain length}}
+    fetchad -->|mmcif_files| confidencefilter{{Filter out low confidence}}
+    confidencefilter --> |mmcif_files| ssfilter{{Filter on secondary structure}}
+    residuefilter --> |mmcif_files| ssfilter
     classDef dashedBorder stroke-dasharray: 5 5;
     goterm:::dashedBorder
     taxonomy:::dashedBorder
     searchemdb:::dashedBorder
     fetchemdb:::dashedBorder
+    searchintactionpartners:::dashedBorder
+    searchcomplexes:::dashedBorder
 ```
 
 (Dotted nodes and edges are side-quests.)
@@ -145,6 +151,18 @@ protein-quest filter residue  \
     ./filtered-chains ./filtered
 ```
 
+### To filter on secondary structure
+
+To filter on structure being mostly alpha helices and have no beta sheets.
+
+```shell
+protein-quest filter secondary-structure \
+    --ratio-min-helix-residues 0.5 \
+    --ratio-max-sheet-residues 0.0 \
+    --write-stats filtered-ss/stats.csv \
+    ./filtered-chains ./filtered-ss
+```
+
 ### Search Taxonomy
 
 ```shell
@@ -160,6 +178,32 @@ You can use following command to search for a Gene Ontology (GO) term.
 protein-quest search go --limit 5 --aspect cellular_component apoptosome -
 ```
 
+### Search for interaction partners
+
+Use https://www.ebi.ac.uk/complexportal to find interaction partners of given UniProt accession.
+
+```shell
+protein-quest search interaction-partners Q05471 interaction-partners-of-Q05471.txt
+```
+
+The `interaction-partners-of-Q05471.txt` file contains uniprot accessions (one per line).
+
+### Search for complexes
+
+Given Uniprot accessions search for macromolecular complexes at https://www.ebi.ac.uk/complexportal
+and return the complex entries and their members.
+
+```shell
+echo Q05471 | protein-quest search complexes - complexes.csv
+```
+
+The `complexes.csv` looks like
+
+```csv
+query_protein,complex_id,complex_url,complex_title,members
+Q05471,CPX-2122,https://www.ebi.ac.uk/complexportal/complex/CPX-2122,Swr1 chromatin remodelling complex,P31376;P35817;P38326;P53201;P53930;P60010;P80428;Q03388;Q03433;Q03940;Q05471;Q06707;Q12464;Q12509
+```
+
 ##  Model Context Protocol (MCP) server
 
 Protein quest can also help LLMs like Claude Sonnet 4 by providing a [set of tools](https://modelcontextprotocol.io/docs/learn/server-concepts#tools-ai-actions) for protein structures.

{protein_quest-0.3.1 → protein_quest-0.4.0}/docs/notebooks/alphafold.ipynb

@@ -301,7 +301,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "query = ConfidenceFilterQuery(confidence=80, min_threshold=100, max_threshold=1000)"
+    "query = ConfidenceFilterQuery(confidence=80, min_residues=100, max_residues=1000)"
    ]
   },
   {
@@ -318,7 +318,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 17,
+   "execution_count": null,
    "id": "6a6f8e3f",
    "metadata": {},
    "outputs": [
@@ -338,7 +338,7 @@
    "source": [
     "list(\n",
     "    filter_files_on_confidence(\n",
-    "        input_files, ConfidenceFilterQuery(confidence=80, min_threshold=100, max_threshold=1000), output_dir\n",
+    "        input_files, ConfidenceFilterQuery(confidence=80, min_residues=100, max_residues=1000), output_dir\n",
     "    )\n",
     ")"
    ]

{protein_quest-0.3.1 → protein_quest-0.4.0}/docs/notebooks/uniprot.ipynb

@@ -12,7 +12,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 23,
+   "execution_count": 1,
    "id": "85674583",
    "metadata": {},
    "outputs": [],
@@ -282,6 +282,99 @@
     "first_uniprot = next(iter(uniprot_accessions.items()))\n",
     "pprint(first_uniprot)"
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "e32a95f8",
+   "metadata": {},
+   "source": [
+    "## Find interaction partners for uniprot entries"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "id": "d035c702",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from protein_quest.uniprot import search4interaction_partners, search4macromolecular_complexes"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "id": "601c690a",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Helicase SWR1 in yeast\n",
+    "uniprot_accession = \"Q05471\""
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "id": "173c764d",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "{'Q12464': {'CPX-2122'},\n",
+       " 'P35817': {'CPX-2122'},\n",
+       " 'P80428': {'CPX-2122'},\n",
+       " 'Q12509': {'CPX-2122'},\n",
+       " 'Q03388': {'CPX-2122'},\n",
+       " 'P53201': {'CPX-2122'},\n",
+       " 'P53930': {'CPX-2122'},\n",
+       " 'P60010': {'CPX-2122'},\n",
+       " 'Q03433': {'CPX-2122'},\n",
+       " 'Q06707': {'CPX-2122'},\n",
+       " 'P38326': {'CPX-2122'},\n",
+       " 'P31376': {'CPX-2122'},\n",
+       " 'Q03940': {'CPX-2122'}}"
+      ]
+     },
+     "execution_count": 3,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "partners = search4interaction_partners(uniprot_accession, limit=100)\n",
+    "partners"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "a763b6f8",
+   "metadata": {},
+   "source": [
+    "To get more information about the complex you can search for the complexes themselves with:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "id": "236050ea",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "[ComplexPortalEntry(query_protein='Q05471', complex_id='CPX-2122', complex_url='https://www.ebi.ac.uk/complexportal/complex/CPX-2122', complex_title='Swr1 chromatin remodelling complex', members={'P35817', 'Q05471', 'Q12464', 'Q12509', 'Q06707', 'Q03433', 'P38326', 'P53201', 'Q03388', 'P53930', 'P80428', 'Q03940', 'P60010', 'P31376'})]"
+      ]
+     },
+     "execution_count": 4,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "complexes = search4macromolecular_complexes([uniprot_accession])\n",
+    "complexes"
+   ]
   }
  ],
  "metadata": {
@@ -300,7 +393,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.13.2"
+   "version": "3.13.5"
   }
  },
  "nbformat": 4,

{protein_quest-0.3.1 → protein_quest-0.4.0}/pyproject.toml

@@ -52,6 +52,7 @@ dev = [
 ]
 docs = [
     "ipykernel>=6.29.5", # For notebook support in VS Code
+    "ipywidgets", # For tqdm support in notebooks
     "mkdocs>=1.6.1",
     "mkdocs-autoapi>=0.4.1",
     "mkdocs-jupyter>=0.25.1",

{protein_quest-0.3.1 → protein_quest-0.4.0}/src/protein_quest/__version__.py

@@ -1,2 +1,2 @@
-__version__ = "0.3.1"
+__version__ = "0.4.0"
 """The version of the package."""

{protein_quest-0.3.1 → protein_quest-0.4.0}/src/protein_quest/alphafold/confidence.py

@@ -7,7 +7,10 @@ from pathlib import Path
 
 import gemmi
 
+from protein_quest.converter import Percentage, PositiveInt, converter
 from protein_quest.pdbe.io import write_structure
+from protein_quest.ss import nr_of_residues_in_total
+from protein_quest.utils import CopyMethod, copyfile
 
 """
 Methods to filter AlphaFoldDB structures on confidence scores.
@@ -73,13 +76,25 @@ class ConfidenceFilterQuery:
     Parameters:
         confidence: The confidence threshold for filtering residues.
             Residues with a pLDDT (b-factor) above this value are considered high confidence.
-        min_threshold: The minimum number of high-confidence residues required to keep the structure.
-        max_threshold: The maximum number of high-confidence residues required to keep the structure.
+        min_residues: The minimum number of high-confidence residues required to keep the structure.
+        max_residues: The maximum number of high-confidence residues required to keep the structure.
     """
 
-    confidence: float
-    min_threshold: int
-    max_threshold: int
+    confidence: Percentage
+    min_residues: PositiveInt
+    max_residues: PositiveInt
+
+
+base_query_hook = converter.get_structure_hook(ConfidenceFilterQuery)
+
+
+@converter.register_structure_hook
+def confidence_filter_query_hook(val, _type) -> ConfidenceFilterQuery:
+    result: ConfidenceFilterQuery = base_query_hook(val, _type)
+    if result.min_residues > result.max_residues:
+        msg = f"min_residues {result.min_residues} cannot be larger than max_residues {result.max_residues}"
+        raise ValueError(msg)
+    return result
 
 
 @dataclass
@@ -93,17 +108,20 @@ class ConfidenceFilterResult:
     """
 
     input_file: str
-    count: int
+    count: PositiveInt
     filtered_file: Path | None = None
 
 
-def filter_file_on_residues(file: Path, query: ConfidenceFilterQuery, filtered_dir: Path) -> ConfidenceFilterResult:
+def filter_file_on_residues(
+    file: Path, query: ConfidenceFilterQuery, filtered_dir: Path, copy_method: CopyMethod = "copy"
+) -> ConfidenceFilterResult:
     """Filter a single AlphaFoldDB structure file (*.pdb[.gz], *.cif[.gz]) based on confidence.
 
     Args:
         file: The path to the PDB file to filter.
         query: The confidence filter query.
         filtered_dir: The directory to save the filtered PDB file.
+        copy_method: How to copy when no residues have to be removed.
 
     Returns:
         result with filtered_file property set to Path where filtered PDB file is saved.
@@ -112,19 +130,24 @@ def filter_file_on_residues(file: Path, query: ConfidenceFilterQuery, filtered_d
     structure = gemmi.read_structure(str(file))
     residues = set(find_high_confidence_residues(structure, query.confidence))
     count = len(residues)
-    if count < query.min_threshold or count > query.max_threshold:
+    if count < query.min_residues or count > query.max_residues:
         # Skip structure that is outside the min and max threshold
         # just return number of high confidence residues
         return ConfidenceFilterResult(
             input_file=file.name,
             count=count,
         )
+    total_residues = nr_of_residues_in_total(structure)
     filtered_file = filtered_dir / file.name
-    new_structure = filter_out_low_confidence_residues(
-        structure,
-        residues,
-    )
-    write_structure(new_structure, filtered_file)
+    if count == total_residues:
+        # if no residues have to be removed then copy instead of slower gemmi writing
+        copyfile(file, filtered_file, copy_method)
+    else:
+        new_structure = filter_out_low_confidence_residues(
+            structure,
+            residues,
+        )
+        write_structure(new_structure, filtered_file)
     return ConfidenceFilterResult(
         input_file=file.name,
         count=count,
@@ -133,7 +156,10 @@ def filter_file_on_residues(file: Path, query: ConfidenceFilterQuery, filtered_d
 
 
 def filter_files_on_confidence(
-    alphafold_pdb_files: list[Path], query: ConfidenceFilterQuery, filtered_dir: Path
+    alphafold_pdb_files: list[Path],
+    query: ConfidenceFilterQuery,
+    filtered_dir: Path,
+    copy_method: CopyMethod = "copy",
 ) -> Generator[ConfidenceFilterResult]:
     """Filter AlphaFoldDB structures based on confidence.
 
@@ -141,6 +167,7 @@ def filter_files_on_confidence(
         alphafold_pdb_files: List of mmcif/PDB files from AlphaFoldDB to filter.
         query: The confidence filter query containing the confidence thresholds.
         filtered_dir: Directory where the filtered mmcif/PDB files will be saved.
+        copy_method: How to copy when a direct copy is possible.
 
     Yields:
         For each mmcif/PDB files yields whether it was filtered or not,
@@ -150,4 +177,4 @@ def filter_files_on_confidence(
     # In ../filter.py:filter_files_on_residues() we filter on number of residues on a file level
     # here we filter on file level and inside file remove low confidence residues
     for pdb_file in alphafold_pdb_files:
-        yield filter_file_on_residues(pdb_file, query, filtered_dir)
+        yield filter_file_on_residues(pdb_file, query, filtered_dir, copy_method)

{protein_quest-0.3.1 → protein_quest-0.4.0}/src/protein_quest/alphafold/fetch.py

@@ -9,17 +9,15 @@ from typing import Literal, cast, get_args
 
 from aiohttp_retry import RetryClient
 from aiopath import AsyncPath
-from cattrs.preconf.orjson import make_converter
 from tqdm.asyncio import tqdm
 from yarl import URL
 
 from protein_quest.alphafold.entry_summary import EntrySummary
+from protein_quest.converter import converter
 from protein_quest.utils import friendly_session, retrieve_files, run_async
 
 logger = logging.getLogger(__name__)
-converter = make_converter()
-"""cattrs converter to read AlphaFold summary JSON document."""
-converter.register_structure_hook(URL, lambda v, _: URL(v))
+
 
 DownloadableFormat = Literal[
     "summary",