From bffeb79262535134c35bf45d9173db0749439af1 Mon Sep 17 00:00:00 2001 From: Nathaniel Corley Date: Mon, 5 Oct 2026 02:58:38 +0000 Subject: [PATCH] docs: document MSA CLI and preprocessing APIs --- docs/conf.py | 3 +- docs/docs_requirements.txt | 1 + docs/index.rst | 1 + docs/ml.rst | 1 + docs/ml/preprocessing.rst | 43 ++++++++++++++++++- docs/msa.rst | 38 ++++++++++++++++ pyproject.toml | 1 + src/atomworks/ml/preprocessing/msa/finding.py | 1 + 8 files changed, 86 insertions(+), 3 deletions(-) create mode 100644 docs/msa.rst diff --git a/docs/conf.py b/docs/conf.py index d4b57813..73de1615 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -27,6 +27,7 @@ "sphinx.ext.viewcode", # Add source code links "sphinx.ext.napoleon", # Google/NumPy style docstrings "sphinx_gallery.gen_gallery", # Generates auto_examples/ from examples/ + "sphinxcontrib.typer", "myst_parser", # Support Markdown tutorial pages "sphinx_design", # Render collapsible tutorial code examples ] @@ -35,7 +36,7 @@ html_favicon = "_static/favicon-32x32.png" templates_path = ["_templates"] -exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "examples/GALLERY_HEADER.rst", "ml/preprocessing.rst"] +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "examples/GALLERY_HEADER.rst"] napoleon_use_ivar = True # -- Options for HTML output ------------------------------------------------- diff --git a/docs/docs_requirements.txt b/docs/docs_requirements.txt index e9b5c236..fee6b7b8 100644 --- a/docs/docs_requirements.txt +++ b/docs/docs_requirements.txt @@ -8,3 +8,4 @@ ghp-import>=2.0.0,<3 pandoc>=2.0.0,<3 myst-parser>=5.0.0 sphinx-design>=0.6.0,<1 +sphinxcontrib-typer>=0.7.2,<1 diff --git a/docs/index.rst b/docs/index.rst index ffeebd78..81aa51c0 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -27,3 +27,4 @@ Welcome to **atomworks** — a toolkit for converting, parsing, and manipulating auto_examples/index contributor_guide mirrors + msa diff --git a/docs/ml.rst b/docs/ml.rst index ca59f38c..010b7835 100644 --- a/docs/ml.rst +++ b/docs/ml.rst @@ -25,3 +25,4 @@ Data Processing Modules ml/msa_server ml/transforms/msa ml/utils + ml/preprocessing diff --git a/docs/ml/preprocessing.rst b/docs/ml/preprocessing.rst index 1fe05690..e2ff1cbe 100644 --- a/docs/ml/preprocessing.rst +++ b/docs/ml/preprocessing.rst @@ -6,7 +6,7 @@ This module contains utilities for preprocessing molecular structures and data. Core Preprocessing Functions ---------------------------- -.. automodule:: atomworks.ml.preprocessing.get_pn_unit_data_from_structure +.. automodule:: atomworks.ml.preprocessing.preprocess :members: :undoc-members: :show-inheritance: @@ -25,4 +25,43 @@ Utilities .. automodule:: atomworks.ml.preprocessing.utils :members: :undoc-members: - :show-inheritance: \ No newline at end of file + :show-inheritance: + + +MSA +--- + +Note that the following functions can be called via the command line. See :doc:`../msa` +for more details. + +Finding +^^^^^^^ + +.. automodule:: atomworks.ml.preprocessing.msa.finding + :members: + :undoc-members: + :show-inheritance: + +Filtering +^^^^^^^^^ + +.. automodule:: atomworks.ml.preprocessing.msa.filtering + :members: + :undoc-members: + :show-inheritance: + +Generating +^^^^^^^^^^ + +.. automodule:: atomworks.ml.preprocessing.msa.generating + :members: + :undoc-members: + :show-inheritance: + +Organizing +^^^^^^^^^^ + +.. automodule:: atomworks.ml.preprocessing.msa.organizing + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/msa.rst b/docs/msa.rst new file mode 100644 index 00000000..153f7cf2 --- /dev/null +++ b/docs/msa.rst @@ -0,0 +1,38 @@ +Multiple Sequence Alignment in AtomWorks +======================================== + +AtomWorks provides several command-line tools for Multiple Sequence Alignment (MSA) operations. + +Install AtomWorks with the ML extra. Filtering requires hhfilter from HH-suite +on PATH. Local generation requires the selected MMseqs2 or HHblits backend and +configured sequence databases, plus hhfilter for filtering the results. The +ColabFold Python API supports remote generation; see :doc:`ml/msa_server`. +Finding and organizing existing files do not run a sequence search. + +Find +---- + +Provide ``--existing-msa-dirs`` or set ``PROTEIN_MSA_DIRS`` to the directories +containing your MSA files. + +.. typer:: atomworks_cli.find:app + :prog: atomworks msa find + :show-nested: + +Filter +------ +.. typer:: atomworks_cli.filter:app + :prog: atomworks msa filter + :show-nested: + +Generate +-------- +.. typer:: atomworks_cli.generate:app + :prog: atomworks msa generate + :show-nested: + +Organize +-------- +.. typer:: atomworks_cli.organize:app + :prog: atomworks msa organize + :show-nested: diff --git a/pyproject.toml b/pyproject.toml index 47902a51..2c91e933 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -111,6 +111,7 @@ dev = [ ] docs = [ + "sphinxcontrib-typer>=0.7.2,<1", "sphinx>=8.0.0", "sphinx-gallery>=0.19.0", "pydata-sphinx-theme>=0.16.1", diff --git a/src/atomworks/ml/preprocessing/msa/finding.py b/src/atomworks/ml/preprocessing/msa/finding.py index 2141d850..ba37d210 100644 --- a/src/atomworks/ml/preprocessing/msa/finding.py +++ b/src/atomworks/ml/preprocessing/msa/finding.py @@ -350,6 +350,7 @@ def find_template_alignments( Args: sequences: Protein sequences to find template alignments for. template_dirs: Directories to search. Accepts: + - None: No directories (all sequences reported missing). - list[PathLike]: Auto-assumes ``.m8`` / directory_depth=2 (matching `organize_template_alignments`'s defaults).