MSA documentation

Added the CLI information to the documentation in its own page. Cleaned up the CLI docstrings and added information about required docstrings. Added the preprocessing/msa functions to the API documentation.

Thanks to Hope for helping test and take notes!

Author: rclune

docs/conf.py

@@ -11,6 +11,7 @@
 
 sys.path.insert(0, os.path.abspath("../src"))
 
+
 import atomworks
 
 project = "atomworks"
@@ -44,11 +45,17 @@
     "sphinx.ext.viewcode",  # Add source code links
     "sphinx.ext.napoleon",  # Google/NumPy style docstrings
     "sphinx_gallery.gen_gallery",  # Generates auto_examples/ from examples/
+    #"sphinx_click",
+    "sphinxcontrib.typer"
 ]
 
 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"]#, "ml/preprocessing.rst"]
 
+#autodoc_mock_imports = [
+#    "zstandard",
+#    "torch",
+#]
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 

docs/docs_requirements.txt

@@ -5,4 +5,5 @@ sphinx-autodoc-typehints>=1.20.0,<2
 nbsphinx>=0.8.9,<1
 sphinx-gallery>=0.8.1,<1
 ghp-import>=2.0.0,<3
-pandoc>=2.0.0,<3
+pandoc>=2.0.0,<3
+sphinxcontrib-typer>=0.7.2

docs/index.rst

@@ -23,4 +23,5 @@ Welcome to **atomworks** — a toolkit for converting, parsing, and manipulating
    api_reference
    auto_examples/index
    contributor_guide
-   mirrors
+   mirrors
+   msa

docs/ml.rst

@@ -11,7 +11,7 @@ Core Modules
    ml/samplers
 
 Data Processing Modules
-----------------------
+-----------------------
 
 .. toctree::
    :maxdepth: 2
@@ -23,4 +23,5 @@ Data Processing Modules
    ml/transforms/dna
    ml/transforms/feature_aggregation
    ml/transforms/msa
-   ml/utils
+   ml/utils
+   ml/preprocessing

docs/ml/preprocessing.rst

@@ -23,6 +23,45 @@ Utilities
 ---------
 
 .. automodule:: atomworks.ml.preprocessing.utils
+   :members:
+   :undoc-members:
+   :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: 

docs/msa.rst

@@ -0,0 +1,31 @@
+Multiple Sequence Alignment in AtomWorks
+========================================
+
+AtomWorks provides several command-line tools for Multiple Sequence Alignment (MSA) operations.
+
+--------------
+
+Find
+----
+
+.. 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:

src/atomworks_cli/filter.py

@@ -21,7 +21,7 @@
 def filter(
     input_dir: str = typer.Argument(
         ...,
-        help="Source directory containing MSA files to filter (supports glob patterns like '0*')",
+        help="Source directory containing MSA files to filter (supports glob patterns like '0*'),",
     ),
     output_dir: Path = typer.Argument(
         None,
@@ -30,49 +30,49 @@ def filter(
         dir_okay=True,
         writable=True,
         resolve_path=True,
-        help="Destination directory for filtered files. If not provided uses the input paths with the specified output extension.",
+        help="Destination directory for filtered files. If not provided, this uses the input paths with the specified output extension.",
     ),
     input_extension: str = typer.Option(
         MSAFileExtension.A3M_GZ.value,
         "--input-extension",
         "-i",
-        help="File extension for input MSA files (e.g., .a3m, .a3m.gz, .a3m.zst, .afa, .afa.gz, .afa.zst)",
+        help="File extension for input MSA files (e.g., .a3m, .a3m.gz, .a3m.zst, .afa, .afa.gz, .afa.zst).",
     ),
     output_extension: str = typer.Option(
         MSAFileExtension.A3M_GZ.value,
         "--output-extension",
         "-o",
-        help="File extension for output MSA files (e.g., .a3m, .a3m.gz, .a3m.zst, .afa, .afa.gz, .afa.zst)",
+        help="File extension for output MSA files (e.g., .a3m, .a3m.gz, .a3m.zst, .afa, .afa.gz, .afa.zst).",
     ),
     max_sequences: int = typer.Option(
         10_000,
         "--max-sequences",
         "--maxseq",
-        help="Maximum number of sequences to keep in each MSA",
+        help="Maximum number of sequences to keep in each MSA.",
     ),
     max_identity: float = typer.Option(
         90.0,
         "--max-identity",
         "--id",
-        help="Maximum pairwise sequence identity (%)",
+        help="Maximum pairwise sequence identity (%).",
     ),
     min_coverage: float = typer.Option(
         50.0,
         "--min-coverage",
         "--cov",
-        help="Minimum coverage with query (%)",
+        help="Minimum coverage with query (%).",
     ),
     num_workers: int | None = typer.Option(
         None,
         "--num-workers",
         "-j",
-        help="Number of parallel workers (defaults to min(CPU_COUNT, 16))",
+        help="Number of parallel workers (defaults to min(CPU_COUNT, 16)).",
     ),
     verbose: bool = typer.Option(
         False,
         "--verbose",
         "-v",
-        help="Enable verbose logging",
+        help="Enable verbose logging.",
     ),
 ) -> None:
     """Filter MSA files using HHfilter to reduce sequence count and redundancy.
@@ -85,6 +85,8 @@ def filter(
     Can be applied to organized MSA files or any directory of MSA files.
     Automatic compression/decompression is applied based on the input and output file extensions.
 
+    Before using this command users must have HH-Filter installed and the path set. HH-Filter is part of the HH-suite package.
+
     Examples:
         # Filter files in a separate output directory
         atomworks msa filter ./msas ./filtered_msas --max-sequences 1000

src/atomworks_cli/find.py

@@ -25,41 +25,44 @@ def find(
         dir_okay=False,
         readable=True,
         resolve_path=True,
-        help="CSV file containing protein sequences",
+        help="Path and file name for a CSV file containing protein sequences.",
     ),
     sequence_column: str | None = typer.Option(
         None,
         "--sequence-column",
         "-c",
-        help="Name of column containing sequences (required if CSV has multiple columns)",
+        help="Name of column containing sequences (required if CSV has multiple columns).",
     ),
     existing_msa_dirs: str | None = typer.Option(
         None,
         "--existing-msa-dirs",
-        help="Comma-separated MSA directories to find (uses LOCAL_MSA_DIRS env var if not specified)",
+        help="Comma-separated list of directories containing MSA information. (Uses LOCAL_MSA_DIRS env var if not specified.)",
     ),
     missing_output: Path | None = typer.Option(
         None,
         "--missing-output",
-        help="Optional path to save CSV with missing sequences",
+        help="Optional path and file name to save CSV with missing sequences.",
     ),
     found_output: Path | None = typer.Option(
         None,
         "--found-output",
-        help="Optional path to save CSV with found sequences and their MSA paths",
+        help="Optional path and file name to save CSV with found sequences and their MSA paths.",
     ),
     verbose: bool = typer.Option(
         False,
         "--verbose",
         "-v",
-        help="Enable verbose logging",
+        help="Enable verbose logging.",
     ),
 ) -> None:
     """Find MSA files for sequences in a CSV file.
 
     Analyzes a CSV file to find existing MSA files for sequences and
     optionally saves missing and found sequences to separate CSV files.
 
+    You will need to set the LOCAL_MSA_DIRS environment variable to the directory
+    where your MSA information is stored.
+
     Examples:
         # Find MSAs for single-column CSV
         atomworks msa find sequences.csv

src/atomworks_cli/generate.py

@@ -30,7 +30,7 @@ def generate(
         dir_okay=False,
         readable=True,
         resolve_path=True,
-        help="CSV file containing protein sequences",
+        help="Path to and file name of the CSV file containing protein sequences.",
     ),
     output_dir: Path = typer.Argument(
         ...,
@@ -39,78 +39,80 @@ def generate(
         dir_okay=True,
         writable=True,
         resolve_path=True,
-        help="Output directory for generated MSA files",
+        help="Output directory for generated MSA files.",
     ),
     sequence_column: str | None = typer.Option(
         None,
         "--sequence-column",
         "-c",
-        help="Name of column containing sequences (required if CSV has multiple columns)",
+        help="Name of column containing sequences (required if CSV has multiple columns).",
     ),
     # MSAGenerationConfig parameters
     sharding_pattern: str = typer.Option(
         "/0:2/",
         "--sharding-pattern",
         "-s",
-        help="Directory sharding pattern (e.g., '/0:2/')",
+        help="Directory sharding pattern (e.g., '/0:2/').",
     ),
     output_extension: str = typer.Option(
         MSAFileExtension.A3M_GZ.value,
         "--output-extension",
         "-o",
-        help="Output file extension (.a3m, .a3m.gz, .a3m.zst, .afa, .afa.gz, .afa.zst)",
+        help="Output file extension (.a3m, .a3m.gz, .a3m.zst, .afa, .afa.gz, .afa.zst).",
     ),
     gpu: bool | None = typer.Option(
         None,
         "--gpu/--no-gpu",
-        help="Use GPU acceleration (auto-detects if not specified)",
+        help="Use GPU acceleration (auto-detects if not specified).",
     ),
     num_iterations: int = typer.Option(
         3,
         "--num-iterations",
         "-n",
-        help="Number of MMseqs2 search iterations",
+        help="Number of MMseqs2 search iterations.",
     ),
     max_final_sequences: int = typer.Option(
         10_000,
         "--max-final-sequences",
-        help="Maximum number of sequences in final MSAs",
+        help="Maximum number of sequences in final MSAs.",
     ),
     use_env: bool = typer.Option(
         True,
         "--use-env/--no-env",
-        help="Include environmental (metagenomic) database",
+        help="Include environmental (metagenomic) database.",
     ),
     num_workers: int = typer.Option(
         32,
         "--num-workers",
         "-j",
-        help="Number of CPU threads",
+        help="Number of CPU threads.",
     ),
     sensitivity: float | None = typer.Option(
         8.0,
         "--sensitivity",
-        help="MMseqs2 sensitivity (lower = faster, sparser MSAs)",
+        help="MMseqs2 sensitivity (lower = faster, sparser MSAs).",
     ),
     verbose: bool = typer.Option(
         False,
         "--verbose",
         "-v",
-        help="Enable verbose logging",
+        help="Enable verbose logging.",
     ),
     check_existing: bool = typer.Option(
         False,
         "--check-existing/--no-check-existing",
-        help="Check for existing MSAs before generation",
+        help="Check for existing MSAs before generation.",
     ),
     existing_msa_dirs: str | None = typer.Option(
         None,
         "--existing-msa-dirs",
-        help="Comma-separated MSA directories to check (uses LOCAL_MSA_DIRS env var if not specified)",
+        help="Comma-separated list of MSA directories to check (uses LOCAL_MSA_DIRS env var if not specified).",
     ),
 ) -> None:
     """Generate MSAs from sequences in a CSV file using MMseqs2.
 
+    Before using this command users must first install MMseqs2.
+
     Examples:
         # Single-column CSV
         atomworks msa generate sequences.csv output_msas/