Merge pull request #13 from haddocking/powerfit

Powerfit

Author: sverhoeven

.github/workflows/ci.yml

@@ -47,10 +47,19 @@ jobs:
         uses: astral-sh/setup-uv@v6
       - name: Install the project
         run: uv sync --locked --dev        
+      - name: Run type checkers
+        run: uv run pyrefly check src tests
+  typing-docs:
+    name: typing-docs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+      - name: Install the project
+        run: uv sync --locked --group docs-type --group docs
       - name: Convert notebooks to Python scripts
         run: |
-          uv run --group docs jupyter nbconvert --to python docs/*.ipynb
-          sed -i 's/^get_ipython/# get_ipython/' docs/*.py
-          uv run pyrefly check docs/*.py
-      - name: Run type checkers
-        run: uv run pyrefly check
+          find docs/ -name "*.ipynb" -exec uv run --group docs-type marimo convert {} -o {}.py \;
+      - name: Run type checkers on docs
+        run: uv run --group docs-type pyrefly check docs/*.ipynb.py

.gitignore

@@ -68,9 +68,9 @@ venv.bak/
 *.swo
 *.orig
 
-IDEAS.md
 /docs/session1/
 /docs/alphafold_files/
 /docs/pdb_files/
 /docs/density_filtered/
-/docs/cli.md
+/site
+/mysession/

CONTRIBUTING.md

@@ -37,7 +37,7 @@ The sections below outline the steps in each case.
 1. add your own tests (if necessary);
 1. format your code with `uvx ruff format` and sort imports with `uvx ruff check --select I --fix`;
 1. lint your code with `uvx ruff check` (use `uvx ruff check --fix` to fix issues automatically);
-1. type check your code with `uv run pyrefly check`;
+1. type check your code with `uv run pyrefly check src tests`;
 1. update or expand the documentation (see [Contributing with documentation](#contributing-with-documentation) section below);
 1. [push](http://rogerdudler.github.io/git-guide/) your feature branch to (your fork of) the protein-detective repository on GitHub;
 1. create the pull request, e.g. following the instructions [here](https://help.github.com/articles/creating-a-pull-request/).
@@ -88,11 +88,9 @@ python3 -m http.server -d site
 [Pyrefly](https://pyrefly.org/) does not support notebooks yet, so we need to convert them to python scripts and then run pyrefly on them.
 
 ```shell
-uv run --group docs jupyter nbconvert --to python docs/*.ipynb
-# Comment out magic commands
-sed -i 's/^get_ipython/# get_ipython/' docs/*.py
-uv run pyrefly check docs/*.py
-rm docs/*.py
+find docs/ -name "*.ipynb" -exec uv run --group docs-type marimo convert {} -o {}.py \;
+uv run --group docs-type --group docs pyrefly check docs/*.ipynb.py
+rm docs/*.ipynb.py
 ```
 
 </details>

README.md

@@ -21,6 +21,10 @@ pip install git+https://github.com/haddocking/protein-detective.git
 
 ## Usage
 
+The main entry point is the `protein-detective` command line tool which has multiple subcommands to perform actions.
+
+To use programmaticly, see the [notebooks](docs/notebooks) and [API documentation](https://www.bonvinlab.org/protein-detective/autoapi/summary/).
+
 ### Search Uniprot for structures
 
 ```shell
@@ -43,7 +47,7 @@ In `./mysession` directory, you will find session.db file, which is a [DuckDB](h
 protein-detective retrieve ./mysession
 ```
 
-In `./mysession` directory, you will find PDB files from PDBe and AlphaFold DB.
+In `./mysession` directory, you will find mmCIF files from PDBe and PDB files and AlphaFold DB.
 
 ### To filter AlphaFold structures on confidence
 
@@ -67,6 +71,41 @@ Make PDBe files smaller by only keeping first chain of found uniprot entry and r
 protein-detective prune-pdbs ./mysession
 ```
 
+### Powerfit
+
+Generate the powerfit commands for the filtered and pruned structures.
+
+```shell
+protein-detective powerfit commands ../powerfit-tutorial/ribosome-KsgA.map 13 docs/session1
+```
+This will print commands to the terminal, which you can then run in whatever way you prefer.
+Like just sequentially, or with [GNU parallel](https://www.gnu.org/software/parallel/) or as a [Slurm array job](https://slurm.schedmd.com/job_array.html).
+
+Alternatively, you can use the `protein-detective powerfit run ...` command to run powerfit commands sequentially, which is useful for small datasets with rough options.
+
+```shell
+
+To print top 10 solutions to the terminal, you can use:
+
+```shell
+protein-detective powerfit report docs/session1
+```
+
+Outputs something like:
+
+```
+powerfit_run_id,structure,rank,cc,fishz,relz,translation,rotation,density_filter_id,pdb_id,pdb_file,uniprot_acc
+10,A8MT69_pdb4e45.ent_B2A,1,0.432,0.463,10.091,227.18:242.53:211.83,0.0:1.0:1.0:0.0:0.0:1.0:1.0:0.0:0.0,,4E45,docs/session1/single_chain/A8MT69_pdb4e45.ent_B2A.pdb,A8MT69
+10,A8MT69_pdb4ne5.ent_B2A,1,0.423,0.452,10.053,227.18:242.53:214.9,0.0:-0.0:-0.0:-0.604:0.797:0.0:0.797:0.604:0.0,,4NE5,docs/session1/single_chain/A8MT69_pdb4ne5.ent_B2A.pdb,A8MT69
+...
+```
+
+To generate model PDB files rotated/translated to PowerFit solutions, you can use:
+
+```shell
+protein-detective powerfit fit-models docs/session1
+```
+
 ## Contributing
 
 For development information and contribution guidelines, please see [CONTRIBUTING.md](CONTRIBUTING.md).

docs/cli_doc_hook.py

@@ -0,0 +1,89 @@
+"""MkDocs hooks for generating CLI documentation."""
+
+import argparse
+import io
+import logging
+
+from mkdocs.config.defaults import MkDocsConfig
+from mkdocs.structure.files import File, Files
+
+from protein_detective.cli import make_parser
+
+logger = logging.getLogger("mkdocs.plugins.argparse")
+
+
+def capture_help(parser: argparse.ArgumentParser) -> str:
+    """Capture the help text of an argparse parser."""
+    with io.StringIO() as help_output:
+        parser.print_help(help_output)
+        return help_output.getvalue()
+
+
+def argparser_to_markdown(parser: argparse.ArgumentParser, heading="CLI Reference") -> str:
+    prog = parser.prog
+
+    main_help = capture_help(parser)
+
+    lines = [
+        f"# {heading}",
+        f"Documentation for the `{prog}` script.",
+        "```shell",
+        f"$ {prog} --help",
+        main_help,
+        "```",
+    ]
+
+    subparsers_actions = [action for action in parser._actions if isinstance(action, argparse._SubParsersAction)]
+    current_subparsers_action = subparsers_actions[0]
+
+    for sub_cmd_name, sub_cmd_parser in current_subparsers_action.choices.items():
+        sub_cmd_help_text = capture_help(sub_cmd_parser)
+
+        lines.extend(
+            [
+                f"## {sub_cmd_name}",
+                "```shell",
+                f"$ {prog} {sub_cmd_name} --help",
+                sub_cmd_help_text,
+                "```",
+            ]
+        )
+
+        # Check for sub-sub-commands
+        sub_subparsers_actions = [
+            action for action in sub_cmd_parser._actions if isinstance(action, argparse._SubParsersAction)
+        ]
+        if sub_subparsers_actions:
+            sub_current_subparsers_action = sub_subparsers_actions[0]
+            for sub_sub_cmd_name, sub_sub_cmd_parser in sub_current_subparsers_action.choices.items():
+                sub_sub_cmd_help_text = capture_help(sub_sub_cmd_parser)
+
+                lines.extend(
+                    [
+                        f"## {sub_cmd_name} {sub_sub_cmd_name}",
+                        "```shell",
+                        f"$ {prog} {sub_cmd_name} {sub_sub_cmd_name} --help",
+                        sub_sub_cmd_help_text,
+                        "```",
+                    ]
+                )
+
+    return "\n".join(lines)
+
+
+def generate_cli_docs() -> str:
+    """Generate CLI documentation markdown."""
+    parser = make_parser()
+    return argparser_to_markdown(parser)
+
+
+def on_files(files: Files, config: MkDocsConfig) -> Files:
+    logger.info("Generating CLI documentation...")
+    docs_content = generate_cli_docs()
+    cli_md_file = File.generated(
+        config=config,
+        src_uri="cli.md",
+        content=docs_content,
+    )
+    files.append(cli_md_file)
+    return files