MMSeqs#

MMseqs2 integration module for fast protein sequence searching.

This module provides Python bindings and utilities for MMseqs2 (Many-vs-Many sequence searching), enabling fast similarity searches against large protein databases. It also includes utilities for FoldComp database manipulation and result parsing.

Key Features:

  • Fast similarity search using MMseqs2

  • Support for FoldComp compressed structure databases

  • Query file handling with sequence filtering

  • Comprehensive result parsing and filtering

  • Multi-threaded searching capability

Classes:

ValueRange: Annotation class for parameter range validation. QueryFile: Class for managing query protein sequences. MMseqsResult: Dataclass for storing search results.

Functions:

_createdb: Convert FASTA to MMseqs2 database format. _createindex: Create MMseqs2 database index for fast searches. _search: Perform MMseqs2 similarity search. _convertalis: Convert MMseqs2 results to alignment format. extract_fasta_foldcomp: Extract FASTA sequences from FoldComp database.

class mDeepFRI.mmseqs.QueryFile(filepath: str)#

Class for handling FASTA files with sequences to query against MMseqs2 database.

Parameters:

filepath (str) – Path to FASTA file.

filepath#

Path to FASTA file.

Type:

str

sequences#

Dictionary with sequence IDs as keys and sequences as values.

Type:

Dict[str, str]

__init__(filepath: str) → None#
filter_sequences(condition: Callable[[str], bool] | None = None)#

Filter sequences by a custom condition.

Parameters:

condition (callable) – A lambda function that takes a sequence as input and returns a boolean value.

Returns:

None

Example

>>> from mDeepFRI.mmseqs import QueryFile
>>> query_file = QueryFile("path/to/file.fasta")
>>> query_file.load_sequences()
>>> query_file.filter_sequences(lambda seq: 50 <= len(seq) <= 200)
>>> query_file.filter_sequences(lambda seq: 'ATG' in seq)  # filter by presence of 'ATG' motif
>>> query_file.filter_sequences(lambda seq: seq.count('N') < 5) # filter by number of 'N' characters
load_ids(ids: Iterable[str]) → None#

Load sequences by ID from FASTA file. The file is indexed with samtools faidx to speed up the process. Sequences are stored in a dictionary with sequence IDs as keys and sequences as values.

Note

This method allows to load only sequences with specified IDs, which can be useful when working with large FASTA files. samtools faidx works with uncompressed FASTA files, and files compressed with bgzip. If compression is wrong, the file will be automatically re-compressed.

Parameters:

ids (List[str]) – List of sequence IDs to load.

Returns:

None

Raises:

ValueError – If sequence with specified ID is not found in FASTA file.

Example

>>> from mDeepFRI.mmseqs import QueryFile
>>> query_file = QueryFile("path/to/file.fasta")
>>> query_file.load_ids(["seq1", "seq2"])
load_sequences(ids: list[str] | None = None, sort: bool = True) → None#

Load sequences from FASTA file. Sequences are stored in a dictionary with sequence IDs as keys and sequences as values.

Note

This method should be called only if maniuplating sequences directly is needed.

Returns:

None

Example

>>> from mDeepFRI.mmseqs import QueryFile
>>> query_file = QueryFile("path/to/file.fasta")
>>> query_file.load_sequences()
remove_selenocysteine() → list[str]#

Remove sequences containing selenocysteine (U) and return their IDs.

Returns:

list[str] – IDs of sequences that were removed.

Raises:

ValueError – If no sequences are loaded.

remove_sequences(ids: List[str])#

Remove sequences by ID.

Parameters:

ids (List[str]) – List of sequence IDs to remove.

Returns:

None

Example

>>> from mDeepFRI.mmseqs import QueryFile
>>> query_file = QueryFile("path/to/file.fasta")
>>> query_file.load_sequences()
>>> query_file.remove_sequences(["seq1", "seq2"])
search(database_path: str, eval: float = 0.0001, mmseqs_sensitivity: Annotated[float, ValueRange(min=1.0, max=7.5)] = 5.7, index_target: bool = False, tmpdir=None, threads: int = 1)#

Queries sequences against MMseqs2 database. The search results are stored in a tabular format.

Parameters:

  • database_path (str) – Path to MMseqs2 database or database FASTA.

  • eval (float) – Maximum e-value for MMseqs2 search.

  • mmseqs_sensitivity (float) – Sensitivity value for MMseqs2 search.

  • index_target (bool) – Create index for target database. Advised for repeated searches.

  • tmpdir (str) – Path to temporary directory. MMseqs2 creates a lot of temporary files. For large queries, needs to be set to a directory with enough space.

  • threads (int) – Number of threads to use.

Returns:

MMseqsResult – MMseqs2 search results.

Example

>>> from mDeepFRI.mmseqs import QueryFile
>>> query_file = QueryFile("path/to/file.fasta")
>>> query_file.load_sequences()
>>> query_file.filter_sequences(min_length=50, max_length=200)
>>> result = query_file.search("path/to/database")

Description#

Python bindings and utilities for MMseqs2 fast similarity search. Includes helpers for FoldComp databases, query filtering, and parsed search results.

Key Features#

  • Fast search: Many-vs-many searches via MMseqs2 binaries bundled with the package

  • FoldComp support: Extract FASTA sequences from compressed structure databases

  • Query handling: Filter sequences by length and quality before search

  • Result parsing: Access top hits, targets, and coverage/identity metrics

Example#

from mDeepFRI.mmseqs import QueryFile

# Prepare query sequences
qf = QueryFile("proteins.fasta")
qf.load_sequences()
qf.filter_sequences(min_length=30)

# Search against an MMseqs2 database
result = qf.search(
   database="pdb100.mmseqsDB",
   eval=1e-3,
   mmseqs_sensitivity=4,
   threads=8,
)

# Save raw results
result.save("database_search/pdb100_results.tsv")