protein-quest 0.3.1__py3-none-any.whl → 0.3.2__py3-none-any.whl

protein_quest/__version__.py

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

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/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",

protein_quest/cli.py

@@ -23,13 +23,16 @@ from protein_quest.__version__ import __version__
 from protein_quest.alphafold.confidence import ConfidenceFilterQuery, filter_files_on_confidence
 from protein_quest.alphafold.fetch import DownloadableFormat, downloadable_formats
 from protein_quest.alphafold.fetch import fetch_many as af_fetch
+from protein_quest.converter import converter
 from protein_quest.emdb import fetch as emdb_fetch
 from protein_quest.filters import filter_files_on_chain, filter_files_on_residues
 from protein_quest.go import Aspect, allowed_aspects, search_gene_ontology_term, write_go_terms_to_csv
 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.utils import CopyMethod, copy_methods, copyfile
 
 logger = logging.getLogger(__name__)
 
@@ -282,6 +285,22 @@ def _add_retrieve_emdb_parser(subparsers: argparse._SubParsersAction):
     parser.add_argument("output_dir", type=Path, help="Directory to store downloaded EMDB volume files")
 
 
+def _add_copy_method_argument(parser: argparse.ArgumentParser):
+    """Add copy method argument to parser."""
+    default_copy_method = "symlink"
+    if os.name == "nt":
+        # On Windows you need developer mode or admin privileges to create symlinks
+        # so we default to copying files instead of symlinking
+        default_copy_method = "copy"
+    parser.add_argument(
+        "--copy-method",
+        type=str,
+        choices=copy_methods,
+        default=default_copy_method,
+        help="How to copy files when no changes are needed to output file.",
+    )
+
+
 def _add_filter_confidence_parser(subparsers: argparse._SubParsersAction):
     """Add filter confidence subcommand parser."""
     parser = subparsers.add_parser(
@@ -312,6 +331,7 @@ def _add_filter_confidence_parser(subparsers: argparse._SubParsersAction):
             In CSV format with `<input_file>,<residue_count>,<passed>,<output_file>` columns.
             Use `-` for stdout."""),
     )
+    _add_copy_method_argument(parser)
 
 
 def _add_filter_chain_parser(subparsers: argparse._SubParsersAction):
@@ -347,8 +367,11 @@ def _add_filter_chain_parser(subparsers: argparse._SubParsersAction):
     )
     parser.add_argument(
         "--scheduler-address",
-        help="Address of the Dask scheduler to connect to. If not provided, will create a local cluster.",
+        help=dedent("""Address of the Dask scheduler to connect to.
+            If not provided, will create a local cluster.
+            If set to `sequential` will run tasks sequentially."""),
     )
+    _add_copy_method_argument(parser)
 
 
 def _add_filter_residue_parser(subparsers: argparse._SubParsersAction):
@@ -371,6 +394,7 @@ def _add_filter_residue_parser(subparsers: argparse._SubParsersAction):
     )
     parser.add_argument("--min-residues", type=int, default=0, help="Min residues in chain A")
     parser.add_argument("--max-residues", type=int, default=10_000_000, help="Max residues in chain A")
+    _add_copy_method_argument(parser)
     parser.add_argument(
         "--write-stats",
         type=argparse.FileType("w", encoding="UTF-8"),
@@ -381,6 +405,43 @@ def _add_filter_residue_parser(subparsers: argparse._SubParsersAction):
     )
 
 
+def _add_filter_ss_parser(subparsers: argparse._SubParsersAction):
+    """Add filter secondary structure subcommand parser."""
+    parser = subparsers.add_parser(
+        "secondary-structure",
+        help="Filter PDB/mmCIF files by secondary structure",
+        description="Filter PDB/mmCIF files by secondary structure",
+        formatter_class=ArgumentDefaultsRichHelpFormatter,
+    )
+    parser.add_argument("input_dir", type=Path, help="Directory with PDB/mmCIF files (e.g., from 'filter chain')")
+    parser.add_argument(
+        "output_dir",
+        type=Path,
+        help=dedent("""\
+            Directory to write filtered PDB/mmCIF files. Files are copied without modification.
+        """),
+    )
+    parser.add_argument("--abs-min-helix-residues", type=int, help="Min residues in helices")
+    parser.add_argument("--abs-max-helix-residues", type=int, help="Max residues in helices")
+    parser.add_argument("--abs-min-sheet-residues", type=int, help="Min residues in sheets")
+    parser.add_argument("--abs-max-sheet-residues", type=int, help="Max residues in sheets")
+    parser.add_argument("--ratio-min-helix-residues", type=float, help="Min residues in helices (relative)")
+    parser.add_argument("--ratio-max-helix-residues", type=float, help="Max residues in helices (relative)")
+    parser.add_argument("--ratio-min-sheet-residues", type=float, help="Min residues in sheets (relative)")
+    parser.add_argument("--ratio-max-sheet-residues", type=float, help="Max residues in sheets (relative)")
+    _add_copy_method_argument(parser)
+    parser.add_argument(
+        "--write-stats",
+        type=argparse.FileType("w", encoding="UTF-8"),
+        help=dedent("""
+            Write filter statistics to file. In CSV format with columns:
+            `<input_file>,<nr_residues>,<nr_helix_residues>,<nr_sheet_residues>,
+            <helix_ratio>,<sheet_ratio>,<passed>,<output_file>`.
+            Use `-` for stdout.
+        """),
+    )
+
+
 def _add_search_subcommands(subparsers: argparse._SubParsersAction):
     """Add search command and its subcommands."""
     parser = subparsers.add_parser(
@@ -422,6 +483,7 @@ def _add_filter_subcommands(subparsers: argparse._SubParsersAction):
     _add_filter_confidence_parser(subsubparsers)
     _add_filter_chain_parser(subsubparsers)
     _add_filter_residue_parser(subsubparsers)
+    _add_filter_ss_parser(subsubparsers)
 
 
 def _add_mcp_command(subparsers: argparse._SubParsersAction):
@@ -620,21 +682,22 @@ def _handle_filter_confidence(args: argparse.Namespace):
     # to get rid of duplication
     input_dir = structure(args.input_dir, Path)
     output_dir = structure(args.output_dir, Path)
-    confidence_threshold = structure(args.confidence_threshold, float)
-    # TODO add min/max
-    min_residues = structure(args.min_residues, int)
-    max_residues = structure(args.max_residues, int)
+
+    confidence_threshold = args.confidence_threshold
+    min_residues = args.min_residues
+    max_residues = args.max_residues
     stats_file: TextIOWrapper | None = args.write_stats
+    copy_method: CopyMethod = structure(args.copy_method, CopyMethod)  # pyright: ignore[reportArgumentType]
 
     output_dir.mkdir(parents=True, exist_ok=True)
     input_files = sorted(glob_structure_files(input_dir))
     nr_input_files = len(input_files)
     rprint(f"Starting confidence filtering of {nr_input_files} mmcif/PDB files in {input_dir} directory.")
-    query = structure(
+    query = converter.structure(
         {
             "confidence": confidence_threshold,
-            "min_threshold": min_residues,
-            "max_threshold": max_residues,
+            "min_residues": min_residues,
+            "max_residues": max_residues,
         },
         ConfidenceFilterQuery,
     )
@@ -643,7 +706,11 @@ def _handle_filter_confidence(args: argparse.Namespace):
         writer.writerow(["input_file", "residue_count", "passed", "output_file"])
 
     passed_count = 0
-    for r in tqdm(filter_files_on_confidence(input_files, query, output_dir), total=len(input_files), unit="file"):
+    for r in tqdm(
+        filter_files_on_confidence(input_files, query, output_dir, copy_method=copy_method),
+        total=len(input_files),
+        unit="file",
+    ):
         if r.filtered_file:
             passed_count += 1
         if stats_file:
@@ -656,9 +723,10 @@ def _handle_filter_confidence(args: argparse.Namespace):
 
 def _handle_filter_chain(args):
     input_dir = args.input_dir
-    output_dir = args.output_dir
+    output_dir = structure(args.output_dir, Path)
     pdb_id2chain_mapping_file = args.chains
-    scheduler_address = args.scheduler_address
+    scheduler_address = structure(args.scheduler_address, str | None)  # pyright: ignore[reportArgumentType]
+    copy_method: CopyMethod = structure(args.copy_method, CopyMethod)  # pyright: ignore[reportArgumentType]
 
     # make sure files in input dir with entries in mapping file are the same
     # complain when files from mapping file are missing on disk
@@ -683,18 +751,25 @@ def _handle_filter_chain(args):
         rprint("[red]No valid structure files found. Exiting.")
         sys.exit(1)
 
-    results = filter_files_on_chain(file2chain, output_dir, scheduler_address=scheduler_address)
+    results = filter_files_on_chain(
+        file2chain, output_dir, scheduler_address=scheduler_address, copy_method=copy_method
+    )
 
     nr_written = len([r for r in results if r.passed])
 
     rprint(f"Wrote {nr_written} single-chain PDB/mmCIF files to {output_dir}.")
 
+    for result in results:
+        if result.discard_reason:
+            rprint(f"[red]Discarding {result.input_file} ({result.discard_reason})[/red]")
+
 
 def _handle_filter_residue(args):
     input_dir = structure(args.input_dir, Path)
     output_dir = structure(args.output_dir, Path)
     min_residues = structure(args.min_residues, int)
     max_residues = structure(args.max_residues, int)
+    copy_method: CopyMethod = structure(args.copy_method, CopyMethod)  # pyright: ignore[reportArgumentType]
     stats_file: TextIOWrapper | None = args.write_stats
 
     if stats_file:
@@ -705,7 +780,9 @@ def _handle_filter_residue(args):
     input_files = sorted(glob_structure_files(input_dir))
     nr_total = len(input_files)
     rprint(f"Filtering {nr_total} files in {input_dir} directory by number of residues in chain A.")
-    for r in filter_files_on_residues(input_files, output_dir, min_residues=min_residues, max_residues=max_residues):
+    for r in filter_files_on_residues(
+        input_files, output_dir, min_residues=min_residues, max_residues=max_residues, copy_method=copy_method
+    ):
         if stats_file:
             writer.writerow([r.input_file, r.residue_count, r.passed, r.output_file])
         if r.passed:
@@ -716,6 +793,68 @@ def _handle_filter_residue(args):
         rprint(f"Statistics written to {stats_file.name}")
 
 
+def _handle_filter_ss(args):
+    input_dir = structure(args.input_dir, Path)
+    output_dir = structure(args.output_dir, Path)
+    copy_method: CopyMethod = structure(args.copy_method, CopyMethod)  # pyright: ignore[reportArgumentType]
+    stats_file: TextIOWrapper | None = args.write_stats
+
+    raw_query = {
+        "abs_min_helix_residues": args.abs_min_helix_residues,
+        "abs_max_helix_residues": args.abs_max_helix_residues,
+        "abs_min_sheet_residues": args.abs_min_sheet_residues,
+        "abs_max_sheet_residues": args.abs_max_sheet_residues,
+        "ratio_min_helix_residues": args.ratio_min_helix_residues,
+        "ratio_max_helix_residues": args.ratio_max_helix_residues,
+        "ratio_min_sheet_residues": args.ratio_min_sheet_residues,
+        "ratio_max_sheet_residues": args.ratio_max_sheet_residues,
+    }
+    query = converter.structure(raw_query, SecondaryStructureFilterQuery)
+    input_files = sorted(glob_structure_files(input_dir))
+    nr_total = len(input_files)
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    if stats_file:
+        writer = csv.writer(stats_file)
+        writer.writerow(
+            [
+                "input_file",
+                "nr_residues",
+                "nr_helix_residues",
+                "nr_sheet_residues",
+                "helix_ratio",
+                "sheet_ratio",
+                "passed",
+                "output_file",
+            ]
+        )
+
+    rprint(f"Filtering {nr_total} files in {input_dir} directory by secondary structure.")
+    nr_passed = 0
+    for input_file, result in filter_files_on_secondary_structure(input_files, query=query):
+        output_file: Path | None = None
+        if result.passed:
+            output_file = output_dir / input_file.name
+            copyfile(input_file, output_file, copy_method)
+            nr_passed += 1
+        if stats_file:
+            writer.writerow(
+                [
+                    input_file,
+                    result.stats.nr_residues,
+                    result.stats.nr_helix_residues,
+                    result.stats.nr_sheet_residues,
+                    round(result.stats.helix_ratio, 3),
+                    round(result.stats.sheet_ratio, 3),
+                    result.passed,
+                    output_file,
+                ]
+            )
+    rprint(f"Wrote {nr_passed} files to {output_dir} directory.")
+    if stats_file:
+        rprint(f"Statistics written to {stats_file.name}")
+
+
 def _handle_mcp(args):
     if find_spec("fastmcp") is None:
         msg = "Unable to start MCP server, please install `protein-quest[mcp]`."
@@ -742,6 +881,7 @@ HANDLERS: dict[tuple[str, str | None], Callable] = {
     ("filter", "confidence"): _handle_filter_confidence,
     ("filter", "chain"): _handle_filter_chain,
     ("filter", "residue"): _handle_filter_residue,
+    ("filter", "secondary-structure"): _handle_filter_ss,
     ("mcp", None): _handle_mcp,
 }
 

protein_quest/converter.py

@@ -0,0 +1,45 @@
+"""Convert json or dict to Python objects."""
+
+from cattrs.preconf.orjson import make_converter
+from yarl import URL
+
+type Percentage = float
+"""Type alias for percentage values (0.0-100.0)."""
+type Ratio = float
+"""Type alias for ratio values (0.0-1.0)."""
+type PositiveInt = int
+"""Type alias for positive integer values (>= 0)."""
+
+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_structure_hook
+def percentage_hook(val, _) -> Percentage:
+    value = float(val)
+    """Cattrs hook to validate percentage values."""
+    if not 0.0 <= value <= 100.0:
+        msg = f"Value {value} is not a valid percentage (0.0-100.0)"
+        raise ValueError(msg)
+    return value
+
+
+@converter.register_structure_hook
+def ratio_hook(val, _) -> Ratio:
+    """Cattrs hook to validate ratio values."""
+    value = float(val)
+    if not 0.0 <= value <= 1.0:
+        msg = f"Value {value} is not a valid ratio (0.0-1.0)"
+        raise ValueError(msg)
+    return value
+
+
+@converter.register_structure_hook
+def positive_int_hook(val, _) -> PositiveInt:
+    """Cattrs hook to validate positive integer values."""
+    value = int(val)
+    if value < 0:
+        msg = f"Value {value} is not a valid positive integer (>= 0)"
+        raise ValueError(msg)
+    return value

protein_quest/filters.py

@@ -4,7 +4,7 @@ import logging
 from collections.abc import Collection, Generator
 from dataclasses import dataclass
 from pathlib import Path
-from shutil import copyfile
+from typing import Literal
 
 from dask.distributed import Client
 from distributed.deploy.cluster import Cluster
@@ -15,6 +15,7 @@ from protein_quest.pdbe.io import (
     nr_residues_in_chain,
     write_single_chain_pdb_file,
 )
+from protein_quest.utils import CopyMethod, copyfile
 
 logger = logging.getLogger(__name__)
 
@@ -29,11 +30,17 @@ class ChainFilterStatistics:
 
 
 def filter_file_on_chain(
-    file_and_chain: tuple[Path, str], output_dir: Path, out_chain: str = "A"
+    file_and_chain: tuple[Path, str],
+    output_dir: Path,
+    out_chain: str = "A",
+    copy_method: CopyMethod = "copy",
 ) -> ChainFilterStatistics:
     input_file, chain_id = file_and_chain
+    logger.debug("Filtering %s on chain %s", input_file, chain_id)
     try:
-        output_file = write_single_chain_pdb_file(input_file, chain_id, output_dir, out_chain=out_chain)
+        output_file = write_single_chain_pdb_file(
+            input_file, chain_id, output_dir, out_chain=out_chain, copy_method=copy_method
+        )
         return ChainFilterStatistics(
             input_file=input_file,
             chain_id=chain_id,
@@ -48,7 +55,8 @@ def filter_files_on_chain(
     file2chains: Collection[tuple[Path, str]],
     output_dir: Path,
     out_chain: str = "A",
-    scheduler_address: str | Cluster | None = None,
+    scheduler_address: str | Cluster | Literal["sequential"] | None = None,
+    copy_method: CopyMethod = "copy",
 ) -> list[ChainFilterStatistics]:
     """Filter mmcif/PDB files by chain.
 
@@ -58,19 +66,37 @@ def filter_files_on_chain(
         output_dir: The directory where the filtered files will be written.
         out_chain: Under what name to write the kept chain.
         scheduler_address: The address of the Dask scheduler.
+            If not provided, will create a local cluster.
+            If set to `sequential` will run tasks sequentially.
+        copy_method: How to copy when a direct copy is possible.
 
     Returns:
         Result of the filtering process.
     """
     output_dir.mkdir(parents=True, exist_ok=True)
+    if scheduler_address == "sequential":
+
+        def task(file_and_chain: tuple[Path, str]) -> ChainFilterStatistics:
+            return filter_file_on_chain(file_and_chain, output_dir, out_chain=out_chain, copy_method=copy_method)
+
+        return list(map(task, file2chains))
+
+    # TODO make logger.debug in filter_file_on_chain show to user when --log
+    # GPT-5 generated a fairly difficult setup with a WorkerPlugin, need to find a simpler approach
     scheduler_address = configure_dask_scheduler(
         scheduler_address,
         name="filter-chain",
     )
 
     with Client(scheduler_address) as client:
+        client.forward_logging()
         return dask_map_with_progress(
-            client, filter_file_on_chain, file2chains, output_dir=output_dir, out_chain=out_chain
+            client,
+            filter_file_on_chain,
+            file2chains,
+            output_dir=output_dir,
+            out_chain=out_chain,
+            copy_method=copy_method,
         )
 
 
@@ -92,7 +118,12 @@ class ResidueFilterStatistics:
 
 
 def filter_files_on_residues(
-    input_files: list[Path], output_dir: Path, min_residues: int, max_residues: int, chain: str = "A"
+    input_files: list[Path],
+    output_dir: Path,
+    min_residues: int,
+    max_residues: int,
+    chain: str = "A",
+    copy_method: CopyMethod = "copy",
 ) -> Generator[ResidueFilterStatistics]:
     """Filter PDB/mmCIF files by number of residues in given chain.
 
@@ -102,6 +133,7 @@ def filter_files_on_residues(
         min_residues: The minimum number of residues in chain.
         max_residues: The maximum number of residues in chain.
         chain: The chain to count residues of.
+        copy_method: How to copy passed files to output directory:
 
     Yields:
         Objects containing information about the filtering process for each input file.
@@ -112,7 +144,7 @@ def filter_files_on_residues(
         passed = min_residues <= residue_count <= max_residues
         if passed:
             output_file = output_dir / input_file.name
-            copyfile(input_file, output_file)
+            copyfile(input_file, output_file, copy_method)
             yield ResidueFilterStatistics(input_file, residue_count, True, output_file)
         else:
             yield ResidueFilterStatistics(input_file, residue_count, False, None)

protein_quest/go.py

@@ -8,8 +8,8 @@ from io import TextIOWrapper
 from typing import Literal, get_args
 
 from cattrs.gen import make_dict_structure_fn, override
-from cattrs.preconf.orjson import make_converter
 
+from protein_quest.converter import converter
 from protein_quest.utils import friendly_session
 
 logger = logging.getLogger(__name__)
@@ -52,9 +52,6 @@ class SearchResponse:
     page_info: PageInfo
 
 
-converter = make_converter()
-
-
 def flatten_definition(definition, _context) -> str:
     return definition["text"]
 

protein_quest/mcp_server.py

@@ -46,6 +46,7 @@ from protein_quest.emdb import fetch as emdb_fetch
 from protein_quest.go import search_gene_ontology_term
 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
 
@@ -165,6 +166,9 @@ def alphafold_confidence_filter(file: Path, query: ConfidenceFilterQuery, filter
     return filter_file_on_residues(file, query, filtered_dir)
 
 
+mcp.tool(filter_file_on_secondary_structure)
+
+
 @mcp.prompt
 def candidate_structures(
     species: str = "Human",

protein_quest/pdbe/io.py

@@ -2,12 +2,14 @@
 
 import gzip
 import logging
-from collections.abc import Generator
+from collections.abc import Generator, Iterable
+from datetime import UTC, datetime
 from pathlib import Path
 
 import gemmi
 
-from protein_quest import __version__
+from protein_quest.__version__ import __version__
+from protein_quest.utils import CopyMethod, copyfile
 
 logger = logging.getLogger(__name__)
 
@@ -28,14 +30,21 @@ def nr_residues_in_chain(file: Path | str, chain: str = "A") -> int:
         The number of residues in the specified chain.
     """
     structure = gemmi.read_structure(str(file))
-    model = structure[0]
-    gchain = find_chain_in_model(model, chain)
+    gchain = find_chain_in_structure(structure, chain)
     if gchain is None:
         logger.warning("Chain %s not found in %s. Returning 0.", chain, file)
         return 0
     return len(gchain)
 
 
+def find_chain_in_structure(structure: gemmi.Structure, wanted_chain: str) -> gemmi.Chain | None:
+    for model in structure:
+        chain = find_chain_in_model(model, wanted_chain)
+        if chain is not None:
+            return chain
+    return None
+
+
 def find_chain_in_model(model: gemmi.Model, wanted_chain: str) -> gemmi.Chain | None:
     chain = model.find_chain(wanted_chain)
     if chain is None:
@@ -68,10 +77,12 @@ def write_structure(structure: gemmi.Structure, path: Path):
         with gzip.open(path, "wt") as f:
             f.write(body)
     elif path.name.endswith(".cif"):
-        doc = structure.make_mmcif_document()
+        # do not write chem_comp so it is viewable by molstar
+        # see https://github.com/project-gemmi/gemmi/discussions/362
+        doc = structure.make_mmcif_document(gemmi.MmcifOutputGroups(True, chem_comp=False))
         doc.write_file(str(path))
     elif path.name.endswith(".cif.gz"):
-        doc = structure.make_mmcif_document()
+        doc = structure.make_mmcif_document(gemmi.MmcifOutputGroups(True, chem_comp=False))
         cif_str = doc.as_string()
         with gzip.open(path, "wt") as f:
             f.write(cif_str)
@@ -111,14 +122,17 @@ def locate_structure_file(root: Path, pdb_id: str) -> Path:
     Raises:
         FileNotFoundError: If no structure file is found for the given PDB ID.
     """
-    exts = [".cif.gz", ".cif", ".pdb.gz", ".pdb"]
-    # files downloaded from https://www.ebi.ac.uk/pdbe/ website
-    # have file names like pdb6t5y.ent or pdb6t5y.ent.gz for a PDB formatted file.
-    # TODO support pdb6t5y.ent or pdb6t5y.ent.gz file names
+    exts = [".cif.gz", ".cif", ".pdb.gz", ".pdb", ".ent", ".ent.gz"]
     for ext in exts:
-        candidate = root / f"{pdb_id.lower()}{ext}"
-        if candidate.exists():
-            return candidate
+        candidates = (
+            root / f"{pdb_id}{ext}",
+            root / f"{pdb_id.lower()}{ext}",
+            root / f"{pdb_id.upper()}{ext}",
+            root / f"pdb{pdb_id.lower()}{ext}",
+        )
+        for candidate in candidates:
+            if candidate.exists():
+                return candidate
     msg = f"No structure file found for {pdb_id} in {root}"
     raise FileNotFoundError(msg)
 
@@ -139,20 +153,84 @@ def glob_structure_files(input_dir: Path) -> Generator[Path]:
 class ChainNotFoundError(IndexError):
     """Exception raised when a chain is not found in a structure."""
 
-    def __init__(self, chain: str, file: Path | str):
-        super().__init__(f"Chain {chain} not found in {file}")
+    def __init__(self, chain: str, file: Path | str, available_chains: Iterable[str]):
+        super().__init__(f"Chain {chain} not found in {file}. Available chains are: {available_chains}")
         self.chain_id = chain
         self.file = file
 
 
-def write_single_chain_pdb_file(input_file: Path, chain2keep: str, output_dir: Path, out_chain: str = "A") -> Path:
+def _dedup_helices(structure: gemmi.Structure):
+    helix_starts: set[str] = set()
+    duplicate_helix_indexes: list[int] = []
+    for hindex, helix in enumerate(structure.helices):
+        if str(helix.start) in helix_starts:
+            logger.debug(f"Duplicate start helix found: {hindex} {helix.start}, removing")
+            duplicate_helix_indexes.append(hindex)
+        else:
+            helix_starts.add(str(helix.start))
+    for helix_index in reversed(duplicate_helix_indexes):
+        structure.helices.pop(helix_index)
+
+
+def _dedup_sheets(structure: gemmi.Structure, chain2keep: str):
+    duplicate_sheet_indexes: list[int] = []
+    for sindex, sheet in enumerate(structure.sheets):
+        if sheet.name != chain2keep:
+            duplicate_sheet_indexes.append(sindex)
+    for sheet_index in reversed(duplicate_sheet_indexes):
+        structure.sheets.pop(sheet_index)
+
+
+def _add_provenance_info(structure: gemmi.Structure, chain2keep: str, out_chain: str):
+    old_id = structure.name
+    new_id = structure.name + f"{chain2keep}2{out_chain}"
+    structure.name = new_id
+    structure.info["_entry.id"] = new_id
+    new_title = f"From {old_id} chain {chain2keep} to {out_chain}"
+    structure.info["_struct.title"] = new_title
+    structure.info["_struct_keywords.pdbx_keywords"] = new_title.upper()
+    new_si = gemmi.SoftwareItem()
+    new_si.classification = gemmi.SoftwareItem.Classification.DataExtraction
+    new_si.name = "protein-quest.pdbe.io.write_single_chain_pdb_file"
+    new_si.version = str(__version__)
+    new_si.date = str(datetime.now(tz=UTC).date())
+    structure.meta.software = [*structure.meta.software, new_si]
+
+
+def chains_in_structure(structure: gemmi.Structure) -> set[gemmi.Chain]:
+    """Get a list of chains in a structure."""
+    return {c for model in structure for c in model}
+
+
+def write_single_chain_pdb_file(
+    input_file: Path,
+    chain2keep: str,
+    output_dir: Path,
+    out_chain: str = "A",
+    copy_method: CopyMethod = "copy",
+) -> Path:
     """Write a single chain from a mmCIF/pdb file to a new mmCIF/pdb file.
 
+    Also
+
+    - removes ligands and waters
+    - renumbers atoms ids
+    - removes chem_comp section from cif files
+    - adds provenance information to the header like software and input file+chain
+
+    This function is equivalent to the following gemmi commands:
+
+    ```shell
+    gemmi convert --remove-lig-wat --select=B --to=cif chain-in/3JRS.cif - | \\
+    gemmi convert --from=cif --rename-chain=B:A - chain-out/3JRS_B2A.gemmi.cif
+    ```
+
     Args:
         input_file: Path to the input mmCIF/pdb file.
         chain2keep: The chain to keep.
         output_dir: Directory to save the output file.
         out_chain: The chain identifier for the output file.
+        copy_method: How to copy when no changes are needed to output file.
 
     Returns:
         Path to the output mmCIF/pdb file
@@ -162,39 +240,42 @@ def write_single_chain_pdb_file(input_file: Path, chain2keep: str, output_dir: P
         ChainNotFoundError: If the specified chain is not found in the input file.
     """
 
+    logger.debug(f"chain2keep: {chain2keep}, out_chain: {out_chain}")
     structure = gemmi.read_structure(str(input_file))
-    model = structure[0]
-
-    # Only count residues of polymer
-    model.remove_ligands_and_waters()
+    structure.setup_entities()
 
-    chain = find_chain_in_model(model, chain2keep)
+    chain = find_chain_in_structure(structure, chain2keep)
+    chainnames_in_structure = {c.name for c in chains_in_structure(structure)}
     if chain is None:
-        raise ChainNotFoundError(chain2keep, input_file)
+        raise ChainNotFoundError(chain2keep, input_file, chainnames_in_structure)
+    chain_name = chain.name
     name, extension = _split_name_and_extension(input_file.name)
-    output_file = output_dir / f"{name}_{chain.name}2{out_chain}{extension}"
+    output_file = output_dir / f"{name}_{chain_name}2{out_chain}{extension}"
 
     if output_file.exists():
         logger.info("Output file %s already exists for input file %s. Skipping.", output_file, input_file)
         return output_file
 
-    new_structure = gemmi.Structure()
-    new_structure.resolution = structure.resolution
-    new_id = structure.name + f"{chain2keep}2{out_chain}"
-    new_structure.name = new_id
-    new_structure.info["_entry.id"] = new_id
-    new_title = f"From {structure.info['_entry.id']} chain {chain2keep} to {out_chain}"
-    new_structure.info["_struct.title"] = new_title
-    new_structure.info["_struct_keywords.pdbx_keywords"] = new_title.upper()
-    new_si = gemmi.SoftwareItem()
-    new_si.classification = gemmi.SoftwareItem.Classification.DataExtraction
-    new_si.name = "protein-quest"
-    new_si.version = str(__version__)
-    new_structure.meta.software.append(new_si)
-    new_model = gemmi.Model(1)
-    chain.name = out_chain
-    new_model.add_chain(chain)
-    new_structure.add_model(new_model)
-    write_structure(new_structure, output_file)
+    if chain_name == out_chain and len(chainnames_in_structure) == 1:
+        logger.info(
+            "%s only has chain %s and out_chain is also %s. Copying file to %s.",
+            input_file,
+            chain_name,
+            out_chain,
+            output_file,
+        )
+        copyfile(input_file, output_file, copy_method)
+        return output_file
+
+    gemmi.Selection(chain_name).remove_not_selected(structure)
+    for m in structure:
+        m.remove_ligands_and_waters()
+    structure.setup_entities()
+    structure.rename_chain(chain_name, out_chain)
+    _dedup_helices(structure)
+    _dedup_sheets(structure, out_chain)
+    _add_provenance_info(structure, chain_name, out_chain)
+
+    write_structure(structure, output_file)
 
     return output_file

protein_quest/ss.py

@@ -0,0 +1,264 @@
+"""Module for dealing with secondary structure."""
+
+import logging
+from collections.abc import Generator, Iterable
+from dataclasses import dataclass
+from pathlib import Path
+
+from gemmi import Structure, read_structure, set_leak_warnings
+
+from protein_quest.converter import PositiveInt, Ratio, converter
+
+logger = logging.getLogger(__name__)
+
+# TODO remove once v0.7.4 of gemmi is released,
+# as uv pip install git+https://github.com/project-gemmi/gemmi.git installs 0.7.4.dev0 which does not print leaks
+# Swallow gemmi leaked function warnings
+set_leak_warnings(False)
+
+# TODO if a structure has no secondary structure information, calculate it with `gemmi ss`.
+# https://github.com/MonomerLibrary/monomers/wiki/Installation as --monomers dir
+# gemmi executable is in https://pypi.org/project/gemmi-program/
+# `gemmi ss` only prints secondary structure to stdout with `-v` flag.
+
+
+def nr_of_residues_in_total(structure: Structure) -> int:
+    """Count the total number of residues in the structure.
+
+    Args:
+        structure: The gemmi Structure object to analyze.
+
+    Returns:
+        The total number of residues in the structure.
+    """
+    count = 0
+    for model in structure:
+        for chain in model:
+            count += len(chain)
+    return count
+
+
+def nr_of_residues_in_helix(structure: Structure) -> int:
+    """Count the number of residues in alpha helices.
+
+    Requires structure to have secondary structure information.
+
+    Args:
+        structure: The gemmi Structure object to analyze.
+
+    Returns:
+        The number of residues in alpha helices.
+    """
+    # For cif files from AlphaFold the helix.length is set to -1
+    # so use resid instead
+    count = 0
+    for helix in structure.helices:
+        end = helix.end.res_id.seqid.num
+        start = helix.start.res_id.seqid.num
+        if end is None or start is None:
+            logger.warning(f"Invalid helix coordinates: {helix.end} or {helix.start}")
+            continue
+        length = end - start + 1
+        count += length
+    return count
+
+
+def nr_of_residues_in_sheet(structure: Structure) -> int:
+    """Count the number of residues in beta sheets.
+
+    Requires structure to have secondary structure information.
+
+    Args:
+        structure: The gemmi Structure object to analyze.
+
+    Returns:
+        The number of residues in beta sheets.
+    """
+    count = 0
+    for sheet in structure.sheets:
+        for strand in sheet.strands:
+            end = strand.end.res_id.seqid.num
+            start = strand.start.res_id.seqid.num
+            if end is None or start is None:
+                logger.warning(f"Invalid strand coordinates: {strand.end} or {strand.start}")
+                continue
+            length = end - start + 1
+            count += length
+    return count
+
+
+@dataclass
+class SecondaryStructureFilterQuery:
+    """Query object to filter on secondary structure.
+
+    Parameters:
+        abs_min_helix_residues: Minimum number of residues in helices (absolute).
+        abs_max_helix_residues: Maximum number of residues in helices (absolute).
+        abs_min_sheet_residues: Minimum number of residues in sheets (absolute).
+        abs_max_sheet_residues: Maximum number of residues in sheets (absolute).
+        ratio_min_helix_residues: Minimum number of residues in helices (relative).
+        ratio_max_helix_residues: Maximum number of residues in helices (relative).
+        ratio_min_sheet_residues: Minimum number of residues in sheets (relative).
+        ratio_max_sheet_residues: Maximum number of residues in sheets (relative).
+    """
+
+    abs_min_helix_residues: PositiveInt | None = None
+    abs_max_helix_residues: PositiveInt | None = None
+    abs_min_sheet_residues: PositiveInt | None = None
+    abs_max_sheet_residues: PositiveInt | None = None
+    ratio_min_helix_residues: Ratio | None = None
+    ratio_max_helix_residues: Ratio | None = None
+    ratio_min_sheet_residues: Ratio | None = None
+    ratio_max_sheet_residues: Ratio | None = None
+
+
+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:
+        msg = f"Invalid {label} range: min {min_val} must be smaller than max {max_val}"
+        raise ValueError(msg)
+
+
+base_query_hook = converter.get_structure_hook(SecondaryStructureFilterQuery)
+
+
+@converter.register_structure_hook
+def secondary_structure_filter_query_hook(value, _type) -> SecondaryStructureFilterQuery:
+    result: SecondaryStructureFilterQuery = base_query_hook(value, _type)
+    _check_range(result.abs_min_helix_residues, result.abs_max_helix_residues, "absolute helix residue")
+    _check_range(result.abs_min_sheet_residues, result.abs_max_sheet_residues, "absolute sheet residue")
+    _check_range(result.ratio_min_helix_residues, result.ratio_max_helix_residues, "ratio helix residue")
+    _check_range(result.ratio_min_sheet_residues, result.ratio_max_sheet_residues, "ratio sheet residue")
+    return result
+
+
+@dataclass
+class SecondaryStructureStats:
+    """Statistics about the secondary structure of a protein.
+
+    Parameters:
+        nr_residues: Total number of residues in the structure.
+        nr_helix_residues: Number of residues in helices.
+        nr_sheet_residues: Number of residues in sheets.
+        helix_ratio: Ratio of residues in helices.
+        sheet_ratio: Ratio of residues in sheets.
+    """
+
+    nr_residues: PositiveInt
+    nr_helix_residues: PositiveInt
+    nr_sheet_residues: PositiveInt
+    helix_ratio: Ratio
+    sheet_ratio: Ratio
+
+
+@dataclass
+class SecondaryStructureFilterResult:
+    """Result of filtering on secondary structure.
+
+    Parameters:
+        stats: The secondary structure statistics.
+        passed: Whether the structure passed the filtering criteria.
+    """
+
+    stats: SecondaryStructureStats
+    passed: bool = False
+
+
+def _gather_stats(structure: Structure) -> SecondaryStructureStats:
+    nr_total_residues = nr_of_residues_in_total(structure)
+    nr_helix_residues = nr_of_residues_in_helix(structure)
+    nr_sheet_residues = nr_of_residues_in_sheet(structure)
+    if nr_total_residues == 0:
+        msg = "Structure has zero residues; cannot compute secondary structure ratios."
+        raise ValueError(msg)
+    helix_ratio = nr_helix_residues / nr_total_residues
+    sheet_ratio = nr_sheet_residues / nr_total_residues
+    return SecondaryStructureStats(
+        nr_residues=nr_total_residues,
+        nr_helix_residues=nr_helix_residues,
+        nr_sheet_residues=nr_sheet_residues,
+        helix_ratio=helix_ratio,
+        sheet_ratio=sheet_ratio,
+    )
+
+
+def filter_on_secondary_structure(
+    structure: Structure,
+    query: SecondaryStructureFilterQuery,
+) -> SecondaryStructureFilterResult:
+    """Filter a structure based on secondary structure criteria.
+
+    Args:
+        structure: The gemmi Structure object to analyze.
+        query: The filtering criteria to apply.
+
+    Returns:
+        Filtering statistics and whether structure passed.
+    """
+    stats = _gather_stats(structure)
+    conditions: list[bool] = []
+
+    # Helix absolute thresholds
+    if query.abs_min_helix_residues is not None:
+        conditions.append(stats.nr_helix_residues >= query.abs_min_helix_residues)
+    if query.abs_max_helix_residues is not None:
+        conditions.append(stats.nr_helix_residues <= query.abs_max_helix_residues)
+
+    # Helix ratio thresholds
+    if query.ratio_min_helix_residues is not None:
+        conditions.append(stats.helix_ratio >= query.ratio_min_helix_residues)
+    if query.ratio_max_helix_residues is not None:
+        conditions.append(stats.helix_ratio <= query.ratio_max_helix_residues)
+
+    # Sheet absolute thresholds
+    if query.abs_min_sheet_residues is not None:
+        conditions.append(stats.nr_sheet_residues >= query.abs_min_sheet_residues)
+    if query.abs_max_sheet_residues is not None:
+        conditions.append(stats.nr_sheet_residues <= query.abs_max_sheet_residues)
+
+    # Sheet ratio thresholds
+    if query.ratio_min_sheet_residues is not None:
+        conditions.append(stats.sheet_ratio >= query.ratio_min_sheet_residues)
+    if query.ratio_max_sheet_residues is not None:
+        conditions.append(stats.sheet_ratio <= query.ratio_max_sheet_residues)
+
+    if not conditions:
+        msg = "No filtering conditions provided. Please specify at least one condition."
+        raise ValueError(msg)
+    passed = all(conditions)
+    return SecondaryStructureFilterResult(stats=stats, passed=passed)
+
+
+def filter_file_on_secondary_structure(
+    file_path: Path,
+    query: SecondaryStructureFilterQuery,
+) -> SecondaryStructureFilterResult:
+    """Filter a structure file based on secondary structure criteria.
+
+    Args:
+        file_path: The path to the structure file to analyze.
+        query: The filtering criteria to apply.
+
+    Returns:
+        Filtering statistics and whether file passed.
+    """
+    structure = read_structure(str(file_path))
+    return filter_on_secondary_structure(structure, query)
+
+
+def filter_files_on_secondary_structure(
+    file_paths: Iterable[Path],
+    query: SecondaryStructureFilterQuery,
+) -> Generator[tuple[Path, SecondaryStructureFilterResult]]:
+    """Filter multiple structure files based on secondary structure criteria.
+
+    Args:
+        file_paths: A list of paths to the structure files to analyze.
+        query: The filtering criteria to apply.
+
+    Yields:
+        For each file returns the filtering statistics and whether structure passed.
+    """
+    # TODO check if quick enough in serial mode, if not switch to dask map
+    for file_path in file_paths:
+        result = filter_file_on_secondary_structure(file_path, query)
+        yield file_path, result

protein_quest/taxonomy.py

@@ -9,9 +9,9 @@ from typing import Literal, get_args
 from aiohttp.client import ClientResponse
 from aiohttp_retry import RetryClient
 from cattrs.gen import make_dict_structure_fn, override
-from cattrs.preconf.orjson import make_converter
 from yarl import URL
 
+from protein_quest.converter import converter
 from protein_quest.go import TextIOWrapper
 from protein_quest.utils import friendly_session
 
@@ -42,8 +42,6 @@ class SearchTaxonResponse:
     results: list[Taxon]
 
 
-converter = make_converter()
-
 converter.register_structure_hook(
     Taxon,
     make_dict_structure_fn(

protein_quest/utils.py

@@ -2,11 +2,12 @@
 
 import asyncio
 import logging
+import shutil
 from collections.abc import Coroutine, Iterable
 from contextlib import asynccontextmanager
 from pathlib import Path
 from textwrap import dedent
-from typing import Any
+from typing import Any, Literal, get_args
 
 import aiofiles
 import aiohttp
@@ -138,3 +139,29 @@ def run_async[R](coroutine: Coroutine[Any, Any, R]) -> R:
         return asyncio.run(coroutine)
     except RuntimeError as e:
         raise NestedAsyncIOLoopError from e
+
+
+CopyMethod = Literal["copy", "symlink"]
+copy_methods = set(get_args(CopyMethod))
+
+
+def copyfile(source: Path, target: Path, copy_method: CopyMethod = "copy"):
+    """Make target path be same file as source by either copying or symlinking.
+
+    Args:
+        source: The source file to copy or symlink.
+        target: The target file to create.
+        copy_method: The method to use for copying.
+
+    Raises:
+        FileNotFoundError: If the source file or parent of target does not exist.
+        ValueError: If the method is not "copy" or "symlink".
+    """
+    if copy_method == "copy":
+        shutil.copyfile(source, target)
+    elif copy_method == "symlink":
+        rel_source = source.relative_to(target.parent, walk_up=True)
+        target.symlink_to(rel_source)
+    else:
+        msg = f"Unknown method: {copy_method}"
+        raise ValueError(msg)

{protein_quest-0.3.1.dist-info → protein_quest-0.3.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: protein_quest
-Version: 0.3.1
+Version: 0.3.2
 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
@@ -59,9 +59,11 @@ graph TB;
     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_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}}
+    confidencefilter --> |mmcif_files| ssfilter{{Filter on secondary structure}}
+    residuefilter --> |mmcif_files| ssfilter
     classDef dashedBorder stroke-dasharray: 5 5;
     goterm:::dashedBorder
     taxonomy:::dashedBorder
@@ -175,6 +177,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

protein_quest-0.3.2.dist-info/RECORD

@@ -0,0 +1,26 @@
+protein_quest/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+protein_quest/__version__.py,sha256=tDIN8WjNdFKRoXsf6tArV0_n6nbcPEBWNv1zuhaRbKo,56
+protein_quest/cli.py,sha256=k4HC282QkbAAIk614vIJgaKfkS3XD9hYj7E5hEuiDxA,37893
+protein_quest/converter.py,sha256=tSDw7HOlC7UoWryr_G-sHGzGq8nwflzSq8o7Gv1hWuQ,1382
+protein_quest/emdb.py,sha256=QEeU0VJQ4lLM-o5yAU3QZlrtzDZNgnC5fCjlqPtTyAY,1370
+protein_quest/filters.py,sha256=-gasSXR4g5SzYSYbkfcDwR-tm2KCAhCMdpIVJrUPR1w,5224
+protein_quest/go.py,sha256=lZNEcw8nTc9wpV3cl4y2FG9Lsj8wsXQ6zemmAQs_DWE,5650
+protein_quest/mcp_server.py,sha256=auftrx4aBZp1P-pBcunkPiSmXLtOIZ6MTuhUuW7yrGY,7241
+protein_quest/parallel.py,sha256=ZJrLO1t2HXs4EeNctytvBTyROPBq-4-gLf35PiolHf0,3468
+protein_quest/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+protein_quest/ss.py,sha256=MMHgqKPxjYpjyExiqslWjmyG7aeForeAeJorCYdh75g,9663
+protein_quest/taxonomy.py,sha256=4mKv8zll4mX02Ow8CTvyqMJE2KJZvcq3QlTjjjLOJJk,5072
+protein_quest/uniprot.py,sha256=8qWV4GWqHTRfed0bE_TdgsLYcnDT_vzKu-6JxIgapJQ,18680
+protein_quest/utils.py,sha256=z4PPPcog6nvPhA93DWVf7stv5uJ4h_2BP5owdhoO5mo,5626
+protein_quest/alphafold/__init__.py,sha256=Ktasi5BRp71wO7-PpOGDpIRRtBEefs8knIdlKQeLQpk,51
+protein_quest/alphafold/confidence.py,sha256=pYIuwYdkuPuHLagcX1dSvSyZ_84xboRLfHUxkEoc4MY,6766
+protein_quest/alphafold/entry_summary.py,sha256=GtE3rT7wH3vIOOeiXY2s80Fo6EzdoqlcvakW8K591Yk,1257
+protein_quest/alphafold/fetch.py,sha256=iFHORaO-2NvPwmpm33tfOFUcSJx8mBGwMXxwc4bRuk8,11336
+protein_quest/pdbe/__init__.py,sha256=eNNHtN60NAGea7gvRkIzkoTXsYPK99s-ldIcKWYO6So,61
+protein_quest/pdbe/fetch.py,sha256=tlCrWoaOrwxnQFrf-PnimUUa6lmtHwwysS51efYsBcA,2379
+protein_quest/pdbe/io.py,sha256=iGLvmsD-eEYnrgZDYfkGWIDCzwDRRD5dwqB480talCs,10037
+protein_quest-0.3.2.dist-info/METADATA,sha256=wcURSjBlmkCt-ddhZX7xRYrL-7tT1VuBpJ36_mP0Iuk,7760
+protein_quest-0.3.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+protein_quest-0.3.2.dist-info/entry_points.txt,sha256=f1RtOxv9TFBO3w01EMEuFXBTMsqKsQcKlkxmj9zE-0g,57
+protein_quest-0.3.2.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+protein_quest-0.3.2.dist-info/RECORD,,

protein_quest-0.3.1.dist-info/RECORD

@@ -1,24 +0,0 @@
-protein_quest/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-protein_quest/__version__.py,sha256=Bu2gp24I4eIxc1qgY2e0PnF8N-szjUpFQwVAe10IRAo,56
-protein_quest/cli.py,sha256=xjiWtRDqv-Ruv1fpvXq4dmDSuuyewxw81akDs1ktVbI,31772
-protein_quest/emdb.py,sha256=QEeU0VJQ4lLM-o5yAU3QZlrtzDZNgnC5fCjlqPtTyAY,1370
-protein_quest/filters.py,sha256=3vqfFH87Lz7r9uYiSvwMxzShMfRNv1Zv_freJtDljrU,4051
-protein_quest/go.py,sha256=ycV3-grxuIKFt28bFgH6iRKmt5AEGi7txoTbaAnBxQE,5684
-protein_quest/mcp_server.py,sha256=1_CGC0peqoNUFBvgFWupKwIWjmHsKxN5Vxy1K7dt5Dw,7130
-protein_quest/parallel.py,sha256=ZJrLO1t2HXs4EeNctytvBTyROPBq-4-gLf35PiolHf0,3468
-protein_quest/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-protein_quest/taxonomy.py,sha256=wPzLjum5n_SEkL2rHUKvyRnjL1pG7bhEnE2vMmXixEc,5105
-protein_quest/uniprot.py,sha256=8qWV4GWqHTRfed0bE_TdgsLYcnDT_vzKu-6JxIgapJQ,18680
-protein_quest/utils.py,sha256=YhlTJreIr1bExbh1M514l6sz4GmLVa3RN57mI1kjjuw,4730
-protein_quest/alphafold/__init__.py,sha256=Ktasi5BRp71wO7-PpOGDpIRRtBEefs8knIdlKQeLQpk,51
-protein_quest/alphafold/confidence.py,sha256=GGd_vYsqVvs9InvFKtqHdGKB_61GHllPmDyIztvzG7E,5625
-protein_quest/alphafold/entry_summary.py,sha256=GtE3rT7wH3vIOOeiXY2s80Fo6EzdoqlcvakW8K591Yk,1257
-protein_quest/alphafold/fetch.py,sha256=1mDbQNm01cxlwFNDsKHBWD7MEwzB3PaheskdaLN7XJs,11491
-protein_quest/pdbe/__init__.py,sha256=eNNHtN60NAGea7gvRkIzkoTXsYPK99s-ldIcKWYO6So,61
-protein_quest/pdbe/fetch.py,sha256=tlCrWoaOrwxnQFrf-PnimUUa6lmtHwwysS51efYsBcA,2379
-protein_quest/pdbe/io.py,sha256=J6fHlRLHLALnpxDgSUUnFCNFV9Hr3u6eJDO6j81ftT4,6936
-protein_quest-0.3.1.dist-info/METADATA,sha256=fWvmMbm5aEMb3WbWgPAqwEOWeYJSY47iuZLaRIgBuuk,7305
-protein_quest-0.3.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-protein_quest-0.3.1.dist-info/entry_points.txt,sha256=f1RtOxv9TFBO3w01EMEuFXBTMsqKsQcKlkxmj9zE-0g,57
-protein_quest-0.3.1.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-protein_quest-0.3.1.dist-info/RECORD,,