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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: protein_quest
-Version: 0.3.2
+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,12 +56,14 @@ 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}}
+    fetchpdbe -->|mmcif_files| chainfilter{{Filter on chain of uniprot}}
     chainfilter --> |mmcif_files| residuefilter{{Filter on chain length}}
-    fetchad -->|pdb_files| confidencefilter{{Filter out low confidence}}
+    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;
@@ -69,6 +71,8 @@ graph TB;
     taxonomy:::dashedBorder
     searchemdb:::dashedBorder
     fetchemdb:::dashedBorder
+    searchintactionpartners:::dashedBorder
+    searchcomplexes:::dashedBorder
 ```
 
 (Dotted nodes and edges are side-quests.)
@@ -204,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.2 → protein_quest-0.4.0}/README.md

@@ -26,12 +26,14 @@ 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}}
+    fetchpdbe -->|mmcif_files| chainfilter{{Filter on chain of uniprot}}
     chainfilter --> |mmcif_files| residuefilter{{Filter on chain length}}
-    fetchad -->|pdb_files| confidencefilter{{Filter out low confidence}}
+    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;
@@ -39,6 +41,8 @@ graph TB;
     taxonomy:::dashedBorder
     searchemdb:::dashedBorder
     fetchemdb:::dashedBorder
+    searchintactionpartners:::dashedBorder
+    searchcomplexes:::dashedBorder
 ```
 
 (Dotted nodes and edges are side-quests.)
@@ -174,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.2 → 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.2 → 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.2 → protein_quest-0.4.0}/src/protein_quest/__version__.py

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

{protein_quest-0.3.2 → protein_quest-0.4.0}/src/protein_quest/cli.py

@@ -15,6 +15,7 @@ from textwrap import dedent
 from cattrs import structure
 from rich import print as rprint
 from rich.logging import RichHandler
+from rich.markdown import Markdown
 from rich.panel import Panel
 from rich_argparse import ArgumentDefaultsRichHelpFormatter
 from tqdm.rich import tqdm
@@ -31,7 +32,17 @@ from protein_quest.pdbe import fetch as pdbe_fetch
 from protein_quest.pdbe.io import glob_structure_files, locate_structure_file
 from protein_quest.ss import SecondaryStructureFilterQuery, filter_files_on_secondary_structure
 from protein_quest.taxonomy import SearchField, _write_taxonomy_csv, search_fields, search_taxon
-from protein_quest.uniprot import PdbResult, Query, search4af, search4emdb, search4pdb, search4uniprot
+from protein_quest.uniprot import (
+    ComplexPortalEntry,
+    PdbResult,
+    Query,
+    search4af,
+    search4emdb,
+    search4interaction_partners,
+    search4macromolecular_complexes,
+    search4pdb,
+    search4uniprot,
+)
 from protein_quest.utils import CopyMethod, copy_methods, copyfile
 
 logger = logging.getLogger(__name__)
@@ -211,6 +222,73 @@ def _add_search_taxonomy_parser(subparser: argparse._SubParsersAction):
     parser.add_argument("--limit", type=int, default=100, help="Maximum number of results to return")
 
 
+def _add_search_interaction_partners_parser(subparsers: argparse._SubParsersAction):
+    """Add search interaction partners subcommand parser."""
+    parser = subparsers.add_parser(
+        "interaction-partners",
+        help="Search for interaction partners of given UniProt accession",
+        description=dedent("""\
+            Search for interaction partners of given UniProt accession
+            in the Uniprot SPARQL endpoint and Complex Portal.
+        """),
+        formatter_class=ArgumentDefaultsRichHelpFormatter,
+    )
+    parser.add_argument(
+        "uniprot_acc",
+        type=str,
+        help="UniProt accession (for example P12345).",
+    )
+    parser.add_argument(
+        "--exclude",
+        type=str,
+        action="append",
+        help="UniProt accessions to exclude from the results. For example already known interaction partners.",
+    )
+    parser.add_argument(
+        "output_csv",
+        type=argparse.FileType("w", encoding="UTF-8"),
+        help="Output CSV with interaction partners per UniProt accession. Use `-` for stdout.",
+    )
+    parser.add_argument(
+        "--limit", type=int, default=10_000, help="Maximum number of interaction partner uniprot accessions to return"
+    )
+    parser.add_argument("--timeout", type=int, default=1_800, help="Maximum seconds to wait for query to complete")
+
+
+def _add_search_complexes_parser(subparsers: argparse._SubParsersAction):
+    """Add search complexes subcommand parser."""
+    description = dedent("""\
+        Search for complexes in the Complex Portal.
+        https://www.ebi.ac.uk/complexportal/
+
+        The output CSV file has the following columns:
+
+        - query_protein: UniProt accession used as query
+        - complex_id: Complex Portal identifier
+        - complex_url: URL to the Complex Portal entry
+        - complex_title: Title of the complex
+        - members: Semicolon-separated list of UniProt accessions of complex members
+    """)
+    parser = subparsers.add_parser(
+        "complexes",
+        help="Search for complexes in the Complex Portal",
+        description=Markdown(description, style="argparse.text"),  # type: ignore using rich formatter makes this OK
+        formatter_class=ArgumentDefaultsRichHelpFormatter,
+    )
+    parser.add_argument(
+        "uniprot_accs",
+        type=argparse.FileType("r", encoding="UTF-8"),
+        help="Text file with UniProt accessions (one per line) as query for searching complexes. Use `-` for stdin.",
+    )
+    parser.add_argument(
+        "output_csv",
+        type=argparse.FileType("w", encoding="UTF-8"),
+        help="Output CSV file with complex results. Use `-` for stdout.",
+    )
+    parser.add_argument("--limit", type=int, default=100, help="Maximum number of complex results to return")
+    parser.add_argument("--timeout", type=int, default=1_800, help="Maximum seconds to wait for query to complete")
+
+
 def _add_retrieve_pdbe_parser(subparsers: argparse._SubParsersAction):
     """Add retrieve pdbe subcommand parser."""
     parser = subparsers.add_parser(
@@ -458,6 +536,8 @@ def _add_search_subcommands(subparsers: argparse._SubParsersAction):
     _add_search_emdb_parser(subsubparsers)
     _add_search_go_parser(subsubparsers)
     _add_search_taxonomy_parser(subsubparsers)
+    _add_search_interaction_partners_parser(subsubparsers)
+    _add_search_complexes_parser(subsubparsers)
 
 
 def _add_retrieve_subcommands(subparsers: argparse._SubParsersAction):
@@ -636,6 +716,32 @@ def _handle_search_taxonomy(args):
     _write_taxonomy_csv(results, output_csv)
 
 
+def _handle_search_interaction_partners(args: argparse.Namespace):
+    uniprot_acc: str = args.uniprot_acc
+    excludes: set[str] = set(args.exclude) if args.exclude else set()
+    limit: int = args.limit
+    timeout: int = args.timeout
+    output_csv: TextIOWrapper = args.output_csv
+
+    rprint(f"Searching for interaction partners of '{uniprot_acc}'")
+    results = search4interaction_partners(uniprot_acc, excludes=excludes, limit=limit, timeout=timeout)
+    rprint(f"Found {len(results)} interaction partners, written to {output_csv.name}")
+    _write_lines(output_csv, results.keys())
+
+
+def _handle_search_complexes(args: argparse.Namespace):
+    uniprot_accs = args.uniprot_accs
+    limit = args.limit
+    timeout = args.timeout
+    output_csv = args.output_csv
+
+    accs = _read_lines(uniprot_accs)
+    rprint(f"Finding complexes for {len(accs)} uniprot accessions")
+    results = search4macromolecular_complexes(accs, limit=limit, timeout=timeout)
+    rprint(f"Found {len(results)} complexes, written to {output_csv.name}")
+    _write_complexes_csv(results, output_csv)
+
+
 def _handle_retrieve_pdbe(args):
     pdbe_csv = args.pdbe_csv
     output_dir = args.output_dir
@@ -875,6 +981,8 @@ HANDLERS: dict[tuple[str, str | None], Callable] = {
     ("search", "emdb"): _handle_search_emdb,
     ("search", "go"): _handle_search_go,
     ("search", "taxonomy"): _handle_search_taxonomy,
+    ("search", "interaction-partners"): _handle_search_interaction_partners,
+    ("search", "complexes"): _handle_search_complexes,
     ("retrieve", "pdbe"): _handle_retrieve_pdbe,
     ("retrieve", "alphafold"): _handle_retrieve_alphafold,
     ("retrieve", "emdb"): _handle_retrieve_emdb,
@@ -937,3 +1045,33 @@ def _iter_csv_rows(file: TextIOWrapper) -> Generator[dict[str, str]]:
 
 def _read_column_from_csv(file: TextIOWrapper, column: str) -> set[str]:
     return {row[column] for row in _iter_csv_rows(file)}
+
+
+def _write_complexes_csv(complexes: list[ComplexPortalEntry], output_csv: TextIOWrapper) -> None:
+    """Write ComplexPortal information to a CSV file.
+
+    Args:
+        complexes: List of ComplexPortalEntry objects.
+        output_csv: TextIOWrapper to write the CSV data to.
+    """
+    writer = csv.writer(output_csv)
+    writer.writerow(
+        [
+            "query_protein",
+            "complex_id",
+            "complex_url",
+            "complex_title",
+            "members",
+        ]
+    )
+    for entry in complexes:
+        members_str = ";".join(sorted(entry.members))
+        writer.writerow(
+            [
+                entry.query_protein,
+                entry.complex_id,
+                entry.complex_url,
+                entry.complex_title,
+                members_str,
+            ]
+        )

{protein_quest-0.3.2 → protein_quest-0.4.0}/src/protein_quest/converter.py

@@ -13,6 +13,7 @@ type PositiveInt = int
 converter = make_converter()
 """cattrs converter to read JSON document or dict to Python objects."""
 converter.register_structure_hook(URL, lambda v, _: URL(v))
+converter.register_unstructure_hook(URL, lambda u: str(u))
 
 
 @converter.register_structure_hook

{protein_quest-0.3.2 → protein_quest-0.4.0}/src/protein_quest/mcp_server.py

@@ -48,7 +48,15 @@ from protein_quest.pdbe.fetch import fetch as pdbe_fetch
 from protein_quest.pdbe.io import glob_structure_files, nr_residues_in_chain, write_single_chain_pdb_file
 from protein_quest.ss import filter_file_on_secondary_structure
 from protein_quest.taxonomy import search_taxon
-from protein_quest.uniprot import PdbResult, Query, search4af, search4emdb, search4pdb, search4uniprot
+from protein_quest.uniprot import (
+    PdbResult,
+    Query,
+    search4af,
+    search4emdb,
+    search4macromolecular_complexes,
+    search4pdb,
+    search4uniprot,
+)
 
 mcp = FastMCP("protein-quest")
 
@@ -137,6 +145,7 @@ def search_alphafolds(
 
 
 mcp.tool(search4emdb, name="search_emdb")
+mcp.tool(search4macromolecular_complexes, name="search_macromolecular_complexes")
 
 
 @mcp.tool

{protein_quest-0.3.2 → protein_quest-0.4.0}/src/protein_quest/ss.py

@@ -111,6 +111,26 @@ class SecondaryStructureFilterQuery:
     ratio_min_sheet_residues: Ratio | None = None
     ratio_max_sheet_residues: Ratio | None = None
 
+    def is_actionable(self) -> bool:
+        """Check if the secondary structure query has any actionable filters.
+
+        Returns:
+            True if any of the filters are set, False otherwise.
+        """
+        return any(
+            field is not None
+            for field in [
+                self.abs_min_helix_residues,
+                self.abs_max_helix_residues,
+                self.abs_min_sheet_residues,
+                self.abs_max_sheet_residues,
+                self.ratio_min_helix_residues,
+                self.ratio_max_helix_residues,
+                self.ratio_min_sheet_residues,
+                self.ratio_max_sheet_residues,
+            ]
+        )
+
 
 def _check_range(min_val, max_val, label):
     if min_val is not None and max_val is not None and min_val >= max_val: