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 Remote MSA generation. 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.

find Usage: atomworks msa find [OPTIONS] {csv_file} 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. Examples:     # Find MSAs for single-column CSV     atomworks msa find sequences.csv     # Find MSAs for multi-column CSV with specific sequence  column     atomworks msa find data.csv --sequence-column seq     # Find MSAs and save missing sequences     atomworks msa find sequences.csv --missing-output missing.csv     # Find MSAs and save both missing and found sequences     atomworks msa find sequences.csv --missing-output missing.csv --found-output found.csv     # Find MSAs with custom MSA directories     atomworks msa find sequences.csv --existing-msa-dirs /path/msa1,/path/msa2 ╭─ Arguments ───────────────────────────────────────────────────╮ │*csv_file<file>CSV file containing protein       │ │sequences                         │ │[required]                        │ ╰───────────────────────────────────────────────────────────────╯ ╭─ Options ─────────────────────────────────────────────────────╮ │--sequence-column-c<str>Name of column         │ │containing sequences   │ │(required if CSV has   │ │multiple columns)      │ │--existing-msa-dirs<str>Comma-separated MSA    │ │directories to find    │ │(uses PROTEIN_MSA_DIRS │ │env var if not         │ │specified)             │ │--missing-output<path>Optional path to save  │ │CSV with missing       │ │sequences              │ │--found-output<path>Optional path to save  │ │CSV with found         │ │sequences and their MSA│ │paths                  │ │--verbose-vEnable verbose logging│ │--install-completionInstall completion for │ │the current shell.     │ │--show-completionShow completion for the│ │current shell, to copy │ │it or customize the    │ │installation.          │ │--helpShow this message and  │ │exit.                  │ ╰───────────────────────────────────────────────────────────────╯
find Usage: atomworks msa find [OPTIONS] {csv_file} 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. Examples:     # Find MSAs for single-column CSV     atomworks msa find sequences.csv     # Find MSAs for multi-column CSV with specific sequence  column     atomworks msa find data.csv --sequence-column seq     # Find MSAs and save missing sequences     atomworks msa find sequences.csv --missing-output missing.csv     # Find MSAs and save both missing and found sequences     atomworks msa find sequences.csv --missing-output missing.csv --found-output found.csv     # Find MSAs with custom MSA directories     atomworks msa find sequences.csv --existing-msa-dirs /path/msa1,/path/msa2 ╭─ Arguments ───────────────────────────────────────────────────╮ │*csv_file<file>CSV file containing protein       │ │sequences                         │ │[required]                        │ ╰───────────────────────────────────────────────────────────────╯ ╭─ Options ─────────────────────────────────────────────────────╮ │--sequence-column-c<str>Name of column         │ │containing sequences   │ │(required if CSV has   │ │multiple columns)      │ │--existing-msa-dirs<str>Comma-separated MSA    │ │directories to find    │ │(uses PROTEIN_MSA_DIRS │ │env var if not         │ │specified)             │ │--missing-output<path>Optional path to save  │ │CSV with missing       │ │sequences              │ │--found-output<path>Optional path to save  │ │CSV with found         │ │sequences and their MSA│ │paths                  │ │--verbose-vEnable verbose logging│ │--install-completionInstall completion for │ │the current shell.     │ │--show-completionShow completion for the│ │current shell, to copy │ │it or customize the    │ │installation.          │ │--helpShow this message and  │ │exit.                  │ ╰───────────────────────────────────────────────────────────────╯

Filter#

filter Usage: atomworks msa filter [OPTIONS] {input_dir} [output_dir] Filter MSA files using HHfilter to reduce sequence count and  redundancy. This command applies HHfilter to MSA files to reduce their size by: 1. Limiting the maximum number of sequences 2. Filtering by maximum pairwise sequence identity 3. Filtering by minimum coverage with the query sequence 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. Examples:     # Filter files in a separate output directory     atomworks msa filter ./msas ./filtered_msas --max-sequences 1000     # Convert uncompressed MSA files to compressed ones while  filtering     atomworks msa filter ./msas ./filtered_msas  --input-extension .a3m --output-extension .a3m.gz  --max-sequences 1000     # Filter multiple directories using glob patterns     atomworks msa filter "0*" ./filtered_msas --max-sequences 1000     atomworks msa filter "*/msas" ./filtered_msas  --max-sequences 1000 ╭─ Arguments ───────────────────────────────────────────────────╮ │*input_dir <str>Source directory containing│ │MSA files to filter        │ │(supports glob patterns    │ │like '0*')                 │ │[required]                 │ │output_dir<directory>Destination directory for  │ │filtered files. If not     │ │provided uses the input    │ │paths with the specified   │ │output extension.          │ ╰───────────────────────────────────────────────────────────────╯ ╭─ Options ─────────────────────────────────────────────────────╮ │--input-extension-i<str>File extension for   │ │input MSA files      │ │(e.g., .a3m, .a3m.gz,│ │.a3m.zst, .afa,      │ │.afa.gz, .afa.zst)   │ │[default: .a3m.gz]   │ │--output-extension-o<str>File extension for   │ │output MSA files     │ │(e.g., .a3m, .a3m.gz,│ │.a3m.zst, .afa,      │ │.afa.gz, .afa.zst)   │ │[default: .a3m.gz]   │ │--max-sequences,--ma…<int>Maximum number of    │ │sequences to keep in │ │each MSA             │ │[default: 10000]     │ │--max-identity,--id<float>Maximum pairwise     │ │sequence identity (%)│ │[default: 90.0]      │ │--min-coverage,--cov<float>Minimum coverage with│ │query (%)            │ │[default: 50.0]      │ │--num-workers-j<int>Number of parallel   │ │workers (defaults to │ │min(CPU_COUNT, 16))  │ │--verbose-vEnable verbose       │ │logging              │ │--install-completionInstall completion   │ │for the current      │ │shell.               │ │--show-completionShow completion for  │ │the current shell, to│ │copy it or customize │ │the installation.    │ │--helpShow this message and│ │exit.                │ ╰───────────────────────────────────────────────────────────────╯
filter Usage: atomworks msa filter [OPTIONS] {input_dir} [output_dir] Filter MSA files using HHfilter to reduce sequence count and  redundancy. This command applies HHfilter to MSA files to reduce their size by: 1. Limiting the maximum number of sequences 2. Filtering by maximum pairwise sequence identity 3. Filtering by minimum coverage with the query sequence 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. Examples:     # Filter files in a separate output directory     atomworks msa filter ./msas ./filtered_msas --max-sequences 1000     # Convert uncompressed MSA files to compressed ones while  filtering     atomworks msa filter ./msas ./filtered_msas  --input-extension .a3m --output-extension .a3m.gz  --max-sequences 1000     # Filter multiple directories using glob patterns     atomworks msa filter "0*" ./filtered_msas --max-sequences 1000     atomworks msa filter "*/msas" ./filtered_msas  --max-sequences 1000 ╭─ Arguments ───────────────────────────────────────────────────╮ │*input_dir <str>Source directory containing│ │MSA files to filter        │ │(supports glob patterns    │ │like '0*')                 │ │[required]                 │ │output_dir<directory>Destination directory for  │ │filtered files. If not     │ │provided uses the input    │ │paths with the specified   │ │output extension.          │ ╰───────────────────────────────────────────────────────────────╯ ╭─ Options ─────────────────────────────────────────────────────╮ │--input-extension-i<str>File extension for   │ │input MSA files      │ │(e.g., .a3m, .a3m.gz,│ │.a3m.zst, .afa,      │ │.afa.gz, .afa.zst)   │ │[default: .a3m.gz]   │ │--output-extension-o<str>File extension for   │ │output MSA files     │ │(e.g., .a3m, .a3m.gz,│ │.a3m.zst, .afa,      │ │.afa.gz, .afa.zst)   │ │[default: .a3m.gz]   │ │--max-sequences,--ma…<int>Maximum number of    │ │sequences to keep in │ │each MSA             │ │[default: 10000]     │ │--max-identity,--id<float>Maximum pairwise     │ │sequence identity (%)│ │[default: 90.0]      │ │--min-coverage,--cov<float>Minimum coverage with│ │query (%)            │ │[default: 50.0]      │ │--num-workers-j<int>Number of parallel   │ │workers (defaults to │ │min(CPU_COUNT, 16))  │ │--verbose-vEnable verbose       │ │logging              │ │--install-completionInstall completion   │ │for the current      │ │shell.               │ │--show-completionShow completion for  │ │the current shell, to│ │copy it or customize │ │the installation.    │ │--helpShow this message and│ │exit.                │ ╰───────────────────────────────────────────────────────────────╯

Generate#

generate Usage: atomworks msa generate [OPTIONS] {csv_file} {output_dir} Generate MSAs from sequences in a CSV file using MMseqs2 or  HHblits. Examples: # Single-column CSV atomworks msa generate sequences.csv output_msas/ # Multi-column CSV atomworks msa generate data.csv output_msas/ --sequence-column seq # With custom parameters atomworks msa generate sequences.csv output_msas/ --gpu --max-final-sequences 5000 --threads 16 ╭─ Arguments ───────────────────────────────────────────────────╮ │*csv_file  <file>CSV file containing protein│ │sequences                  │ │[required]                 │ │*output_dir<directory>Output directory for       │ │generated MSA files        │ │[required]                 │ ╰───────────────────────────────────────────────────────────────╯ ╭─ Options ─────────────────────────────────────────────────────╮ │--sequence-co…-c<str>Name of column │ │containing     │ │sequences      │ │(required if   │ │CSV has        │ │multiple       │ │columns)       │ │--sharding-pa…-s<str>Directory      │ │sharding       │ │pattern (e.g., │ │'/0:2/')       │ │[default:      │ │/0:2/]         │ │--output-exte…-o<str>Output file    │ │extension      │ │(.a3m, .a3m.gz,│ │.a3m.zst, .afa,│ │.afa.gz,       │ │.afa.zst)      │ │[default:      │ │.a3m.gz]       │ │--gpu--no-gpu(MMseqs2) Use  │ │GPU            │ │acceleration   │ │(auto-detects  │ │if not         │ │specified)     │ │--num-iterati…-n<int>(MMseqs2)      │ │Number of      │ │search         │ │iterations     │ │[default: 3]   │ │--max-final-s…<int>Maximum number │ │of sequences in│ │final MSAs     │ │[default:      │ │10000]         │ │--use-env--no-env(MMseqs2)      │ │Include        │ │environmental  │ │(metagenomic)  │ │database       │ │[default:      │ │use-env]       │ │--threads-j<int>Number of CPU  │ │threads for    │ │search         │ │operations     │ │(used by both  │ │MMseqs2 and    │ │HHblits)       │ │[default: 4]   │ │--sensitivity<float>(MMseqs2)      │ │Sensitivity    │ │(lower =       │ │faster, sparser│ │MSAs)          │ │[default: 8.0] │ │--verbose-vEnable verbose │ │logging        │ │--check-exist…--no-check-e…Check for      │ │existing MSAs  │ │before         │ │generation     │ │[default:      │ │no-check-exist…│ │--existing-ms…<str>Comma-separated│ │MSA directories│ │to check (uses │ │PROTEIN_MSA_DI…│ │env var if not │ │specified)     │ │--backend-b<str>MSA generation │ │backend:       │ │'mmseqs2'      │ │(default) or   │ │'hhblits'      │ │(CPU-only)     │ │[default:      │ │mmseqs2]       │ │--hhblits-mem<int>(HHblits)      │ │Memory limit in│ │GB             │ │[default: 64]  │ │--install-com…Install        │ │completion for │ │the current    │ │shell.         │ │--show-comple…Show completion│ │for the current│ │shell, to copy │ │it or customize│ │the            │ │installation.  │ │--helpShow this      │ │message and    │ │exit.          │ ╰───────────────────────────────────────────────────────────────╯
generate Usage: atomworks msa generate [OPTIONS] {csv_file} {output_dir} Generate MSAs from sequences in a CSV file using MMseqs2 or  HHblits. Examples: # Single-column CSV atomworks msa generate sequences.csv output_msas/ # Multi-column CSV atomworks msa generate data.csv output_msas/ --sequence-column seq # With custom parameters atomworks msa generate sequences.csv output_msas/ --gpu --max-final-sequences 5000 --threads 16 ╭─ Arguments ───────────────────────────────────────────────────╮ │*csv_file  <file>CSV file containing protein│ │sequences                  │ │[required]                 │ │*output_dir<directory>Output directory for       │ │generated MSA files        │ │[required]                 │ ╰───────────────────────────────────────────────────────────────╯ ╭─ Options ─────────────────────────────────────────────────────╮ │--sequence-co…-c<str>Name of column │ │containing     │ │sequences      │ │(required if   │ │CSV has        │ │multiple       │ │columns)       │ │--sharding-pa…-s<str>Directory      │ │sharding       │ │pattern (e.g., │ │'/0:2/')       │ │[default:      │ │/0:2/]         │ │--output-exte…-o<str>Output file    │ │extension      │ │(.a3m, .a3m.gz,│ │.a3m.zst, .afa,│ │.afa.gz,       │ │.afa.zst)      │ │[default:      │ │.a3m.gz]       │ │--gpu--no-gpu(MMseqs2) Use  │ │GPU            │ │acceleration   │ │(auto-detects  │ │if not         │ │specified)     │ │--num-iterati…-n<int>(MMseqs2)      │ │Number of      │ │search         │ │iterations     │ │[default: 3]   │ │--max-final-s…<int>Maximum number │ │of sequences in│ │final MSAs     │ │[default:      │ │10000]         │ │--use-env--no-env(MMseqs2)      │ │Include        │ │environmental  │ │(metagenomic)  │ │database       │ │[default:      │ │use-env]       │ │--threads-j<int>Number of CPU  │ │threads for    │ │search         │ │operations     │ │(used by both  │ │MMseqs2 and    │ │HHblits)       │ │[default: 4]   │ │--sensitivity<float>(MMseqs2)      │ │Sensitivity    │ │(lower =       │ │faster, sparser│ │MSAs)          │ │[default: 8.0] │ │--verbose-vEnable verbose │ │logging        │ │--check-exist…--no-check-e…Check for      │ │existing MSAs  │ │before         │ │generation     │ │[default:      │ │no-check-exist…│ │--existing-ms…<str>Comma-separated│ │MSA directories│ │to check (uses │ │PROTEIN_MSA_DI…│ │env var if not │ │specified)     │ │--backend-b<str>MSA generation │ │backend:       │ │'mmseqs2'      │ │(default) or   │ │'hhblits'      │ │(CPU-only)     │ │[default:      │ │mmseqs2]       │ │--hhblits-mem<int>(HHblits)      │ │Memory limit in│ │GB             │ │[default: 64]  │ │--install-com…Install        │ │completion for │ │the current    │ │shell.         │ │--show-comple…Show completion│ │for the current│ │shell, to copy │ │it or customize│ │the            │ │installation.  │ │--helpShow this      │ │message and    │ │exit.          │ ╰───────────────────────────────────────────────────────────────╯

Organize#

organize Usage: atomworks msa organize [OPTIONS] {input_dir}  {output_dir} Organize MSA files into a standardized directory structure and  naming convention. MSA files are renamed using the SHA-256 hash of their first  sequence and organized into a directory structure that enables efficient lookup.  Automatic compression/decompression is applied based on the input and output file extensions. The implementation uses smart parallelism: thread-based for  I/O-bound tasks (same compression format) and process-based for CPU-bound tasks  (compression/decompression). This provides excellent performance (~700+ files/second) for typical  workloads. Examples:     # Organize MSA files with default extensions (both .a3m.gz)     atomworks msa organize ./msas ./msas_organized     # Convert uncompressed MSA files to compressed ones     atomworks msa organize ./msas ./msas_organized  --input-extension .a3m --output-extension .a3m.gz     # Convert between compression formats (gzip to zstd)     atomworks msa organize ./msas ./msas_organized  --input-extension .a3m.gz --output-extension .a3m.zst     # Organize with custom sharding pattern     atomworks msa organize ./msas ./msas_organized  --sharding-pattern "/0:2/2:4/"     # Check existing MSAs before organizing     atomworks msa organize ./msas ./msas_organized  --check-existing--existing-msa-dirs ./dir1,./dir2 ╭─ Arguments ───────────────────────────────────────────────────╮ │*input_dir <directory>Source directory containing│ │MSA files to organize      │ │[required]                 │ │*output_dir<directory>Destination directory for  │ │organized MSA files        │ │[required]                 │ ╰───────────────────────────────────────────────────────────────╯ ╭─ Options ─────────────────────────────────────────────────────╮ │--input-extension-i<str>File extension for │ │input MSA files    │ │(e.g., .a3m,       │ │.a3m.gz, .a3m.zst, │ │.afa, .afa.gz,     │ │.afa.zst)          │ │[default: .a3m.gz] │ │--output-extension-o<str>File extension for │ │output MSA files   │ │(e.g., .a3m,       │ │.a3m.gz, .a3m.zst, │ │.afa, .afa.gz,     │ │.afa.zst)          │ │[default: .a3m.gz] │ │--sharding-pattern-s<str>Sharding pattern   │ │for organizing     │ │files (e.g.,       │ │'/0:2/'). Set to   │ │empty string to    │ │disable sharding.  │ │[default: /0:2/]   │ │--copy--moveWhether to copy    │ │(--copy) or move   │ │(--move) input     │ │files              │ │[default: copy]    │ │--num-workers-j<int>Number of parallel │ │workers (defaults  │ │to min(CPU_COUNT,  │ │16))               │ │--check-existingCheck for existing │ │MSAs before        │ │organization       │ │--existing-msa-dirs<str>Comma-separated MSA│ │directories to     │ │check (uses        │ │PROTEIN_MSA_DIRS   │ │env var if not     │ │specified)         │ │--verbose-vEnable verbose     │ │logging            │ │--install-completi…Install completion │ │for the current    │ │shell.             │ │--show-completionShow completion for│ │the current shell, │ │to copy it or      │ │customize the      │ │installation.      │ │--helpShow this message  │ │and exit.          │ ╰───────────────────────────────────────────────────────────────╯
organize Usage: atomworks msa organize [OPTIONS] {input_dir}  {output_dir} Organize MSA files into a standardized directory structure and  naming convention. MSA files are renamed using the SHA-256 hash of their first  sequence and organized into a directory structure that enables efficient lookup.  Automatic compression/decompression is applied based on the input and output file extensions. The implementation uses smart parallelism: thread-based for  I/O-bound tasks (same compression format) and process-based for CPU-bound tasks  (compression/decompression). This provides excellent performance (~700+ files/second) for typical  workloads. Examples:     # Organize MSA files with default extensions (both .a3m.gz)     atomworks msa organize ./msas ./msas_organized     # Convert uncompressed MSA files to compressed ones     atomworks msa organize ./msas ./msas_organized  --input-extension .a3m --output-extension .a3m.gz     # Convert between compression formats (gzip to zstd)     atomworks msa organize ./msas ./msas_organized  --input-extension .a3m.gz --output-extension .a3m.zst     # Organize with custom sharding pattern     atomworks msa organize ./msas ./msas_organized  --sharding-pattern "/0:2/2:4/"     # Check existing MSAs before organizing     atomworks msa organize ./msas ./msas_organized  --check-existing--existing-msa-dirs ./dir1,./dir2 ╭─ Arguments ───────────────────────────────────────────────────╮ │*input_dir <directory>Source directory containing│ │MSA files to organize      │ │[required]                 │ │*output_dir<directory>Destination directory for  │ │organized MSA files        │ │[required]                 │ ╰───────────────────────────────────────────────────────────────╯ ╭─ Options ─────────────────────────────────────────────────────╮ │--input-extension-i<str>File extension for │ │input MSA files    │ │(e.g., .a3m,       │ │.a3m.gz, .a3m.zst, │ │.afa, .afa.gz,     │ │.afa.zst)          │ │[default: .a3m.gz] │ │--output-extension-o<str>File extension for │ │output MSA files   │ │(e.g., .a3m,       │ │.a3m.gz, .a3m.zst, │ │.afa, .afa.gz,     │ │.afa.zst)          │ │[default: .a3m.gz] │ │--sharding-pattern-s<str>Sharding pattern   │ │for organizing     │ │files (e.g.,       │ │'/0:2/'). Set to   │ │empty string to    │ │disable sharding.  │ │[default: /0:2/]   │ │--copy--moveWhether to copy    │ │(--copy) or move   │ │(--move) input     │ │files              │ │[default: copy]    │ │--num-workers-j<int>Number of parallel │ │workers (defaults  │ │to min(CPU_COUNT,  │ │16))               │ │--check-existingCheck for existing │ │MSAs before        │ │organization       │ │--existing-msa-dirs<str>Comma-separated MSA│ │directories to     │ │check (uses        │ │PROTEIN_MSA_DIRS   │ │env var if not     │ │specified)         │ │--verbose-vEnable verbose     │ │logging            │ │--install-completi…Install completion │ │for the current    │ │shell.             │ │--show-completionShow completion for│ │the current shell, │ │to copy it or      │ │customize the      │ │installation.      │ │--helpShow this message  │ │and exit.          │ ╰───────────────────────────────────────────────────────────────╯