MMseqsApp#

class biotite.application_v2.mmseqs.MMseqsApp(path: PathLike[str] | str = 'mmseqs')[source]#

Bases: MMseqsLikeApp

A reusable handle to the MMseqs2 command line program.

Parameters:
pathpath-like, optional

Path to the mmseqs executable.

Attributes:
tmp_dirPath

The temporary directory required for some MMseqs2 and Foldseek commands.

Examples

>>> future = MMseqsApp().create_db(path_to_sequences / "prot.fasta")
>>> isinstance(future.result(), SequenceDatabase)
True
align(alignment_db: AlignmentDatabase[Any], matrix: SubstitutionMatrix[Any, Any] | None = None, gap_penalty: int | tuple[int, int] | None = None, **kwargs: Any) → CommandSetup[AlignmentDatabase[Any]]#

Recompute the gapped alignments of a result database using align.

This allows realigning the hits found by search() with different alignment parameters, without repeating the expensive prefilter stage.

Parameters:
alignment_dbAlignmentDatabase

The result database whose hits are aligned.

matrixSubstitutionMatrix, optional

A custom symmetric substitution matrix. By default, the standard MMseqs2 matrix is used.

gap_penaltyint or tuple of (int, int), optional

The negative gap penalty. A single value applies to both opening and extension. A tuple gives the respective affine penalties.

**kwargs

Additional command line options.

Returns:
futureFuture of AlignmentDatabase

A handle resolving to the alignment database containing the recomputed alignments.

Examples

>>> app = MMseqsApp()
>>> database = app.create_db(path_to_sequences / "cas9.fasta").result()
>>> alignment_db = app.search(database, database, threads=1).result()
>>> realigned_db = app.align(alignment_db, gap_penalty=(-15, -2), threads=1).result()
cluster(sequence_db: SequenceDatabase[Any], matrix: SubstitutionMatrix[Any, Any] | None = None, gap_penalty: int | tuple[int, int] | None = None, **kwargs: Any) → CommandSetup[ClusterDatabase[Any]]#

Cluster a sequence database using the cascaded cluster workflow.

Parameters:
sequence_dbSequenceDatabase

The database to cluster.

matrixSubstitutionMatrix, optional

A custom symmetric substitution matrix. By default, the standard MMseqs2 matrix is used.

gap_penaltyint or tuple of (int, int), optional

The negative gap penalty. A single value applies to both opening and extension. A tuple gives the respective affine penalties.

**kwargs

Additional command line options.

Returns:
futureFuture of ClusterDatabase

A handle resolving to the created cluster database.

See also

cluster_linear

The faster but less sensitive alternative.

Examples

>>> app = MMseqsApp()
>>> database = app.create_db(path_to_sequences / "cas9.fasta").result()
>>> clusters = app.cluster(database, min_seq_id=0.9, threads=1).result()
>>> isinstance(clusters, ClusterDatabase)
True
cluster_linear(sequence_db: SequenceDatabase[Any], matrix: SubstitutionMatrix[Any, Any] | None = None, gap_penalty: int | tuple[int, int] | None = None, **kwargs: Any) → CommandSetup[ClusterDatabase[Any]]#

Cluster a sequence database using the linclust workflow.

The run time is linear in the database size, at the expense of sensitivity compared to cluster().

Parameters:
sequence_dbSequenceDatabase

The database to cluster.

matrixSubstitutionMatrix, optional

A custom symmetric substitution matrix. By default, the standard MMseqs2 matrix is used.

gap_penaltyint or tuple of (int, int), optional

The negative gap penalty. A single value applies to both opening and extension. A tuple gives the respective affine penalties.

**kwargs

Additional command line options.

Returns:
futureFuture of ClusterDatabase

A handle resolving to the created cluster database.

Examples

>>> app = MMseqsApp()
>>> database = app.create_db(path_to_sequences / "cas9.fasta").result()
>>> clusters = app.cluster_linear(database, threads=1).result()
>>> isinstance(clusters, ClusterDatabase)
True
convert_alignments(alignment_db: AlignmentDatabase[Any], output_path: PathLike[str] | str | None = None, format_mode: AlignmentFormatMode | None = None, **kwargs: Any) → CommandSetup[Path | IO[bytes]]#

Export pairwise alignments in a human-readable format using convertalis.

Parameters:
alignment_dbAlignmentDatabase

The alignment database to export.

output_pathpath-like, optional

The output path. If omitted, the output is written to a temporary binary file.

format_modeAlignmentFormatMode, optional

The output format. By default, the application writes a BLAST-like table.

**kwargs

Additional command line options.

Returns:
futureFuture of Path or binary file

A handle resolving to the output path, or to the temporary file if output_path is omitted.

Examples

>>> app = MMseqsApp()
>>> database = app.create_db(path_to_sequences / "prot.fasta").result()
>>> alignments = app.search(database, database, threads=1).result()
>>> alignment_file = app.convert_alignments(alignments).result()
>>> len(alignment_file.readline()) > 0
True
>>> alignment_file.close()
convert_msa(msa_path: PathLike[str] | str | IO[str], **kwargs: Any) → CommandSetup[MSADatabase[Any]]#

Create an MSA database from a Stockholm file using convertmsa.

Parameters:
msa_pathpath-like or text file

The MSA file to convert. Must be in Stockholm format, optionally gzip-compressed.

**kwargs

Additional command line options.

Returns:
futureFuture of MSADatabase

A handle resolving to the created MSA database.

Examples

>>> import tempfile
>>> app = MMseqsApp()
>>> with tempfile.NamedTemporaryFile(
...     "w", suffix=".sto", delete_on_close=False
... ) as msa_file:
...     print("# STOCKHOLM 1.0", file=msa_file)
...     print("#=GF AC query", file=msa_file)
...     print("seq0 NLYIQWLKDGGPSSGRPPPS", file=msa_file)
...     print("seq1 NLYIQWLKD-GPSSGRPPPA", file=msa_file)
...     print("//", file=msa_file)
...     # Close the file, so that the application can read it on Windows
...     msa_file.close()
...     msa_db = app.convert_msa(msa_file.name).result()
convert_to_fasta(sequence_db: SequenceDatabase[Any], fasta_path: PathLike[str] | str | None = None, **kwargs: Any) → CommandSetup[Path | IO[bytes]]#

Export a sequence database in FASTA format using convert2fasta.

Parameters:
sequence_dbSequenceDatabase

The database to export.

fasta_pathpath-like, optional

The output FASTA path. If omitted, the output is written to a temporary binary file.

**kwargs

Additional command line options.

Returns:
futureFuture of Path or binary file

A handle resolving to the output path, or to the temporary file if fasta_path is omitted.

Examples

>>> app = MMseqsApp()
>>> database = app.create_db(path_to_sequences / "prot.fasta").result()
>>> fasta_file = app.convert_to_fasta(database).result()
>>> fasta_file.read().startswith(b">")
True
>>> fasta_file.close()
create_db(input_paths: Iterable[PathLike[str] | str | IO[str]] | PathLike[str] | str | IO[str], db_type: DatabaseType | None = None, **kwargs: Any) → CommandSetup[SequenceDatabase[Any]]#

Create a sequence or structure database using createdb.

Parameters:
input_pathspath-like, text file or iterable thereof

FASTA/FASTQ inputs for MMseqs2, or structural inputs for Foldseek. A text file must expose its file-system path through its name attribute, and pending writes must be flushed before calling this method.

db_typeDatabaseType, optional

The type of the input sequences. By default, MMseqs2 detects the type automatically. This option is not supported by Foldseek.

**kwargs

Additional command line options.

Returns:
futureFuture of SequenceDatabase

A handle resolving to the created sequence database.

Examples

>>> database = MMseqsApp().create_db(path_to_sequences / "prot.fasta").result()
create_index(sequence_db: SequenceDatabase[Any], **kwargs: Any) → CommandSetup[SequenceDatabase[Any]]#

Precompute the k-mer index of a sequence database using createindex.

Parameters:
sequence_dbSequenceDatabase

The database to create the index for. The index is added in place to this database.

**kwargs

Additional command line options.

Returns:
futureFuture of SequenceDatabase

A handle resolving to the indexed database. As the index is added in place, this is the same database object as sequence_db.

Notes

Without a precomputed index, each search() call computes it anew. Hence, creating it once accelerates repeated searches against the same database.

Examples

>>> app = MMseqsApp()
>>> database = app.create_db(path_to_sequences / "cas9.fasta").result()
>>> indexed_database = app.create_index(database, threads=1).result()
>>> indexed_database is database
True
create_sub_db(subset: Database[Any] | PathLike[str] | str, sequence_db: SequenceDatabase[Any], **kwargs: Any) → CommandSetup[SequenceDatabase[Any]]#

Create a sequence database containing a selected subset using createsubdb.

Parameters:
subsetDatabase or path-like

A database or file defining the retained database keys.

sequence_dbSequenceDatabase

The source sequence database.

**kwargs

Additional command line options.

Returns:
futureFuture of SequenceDatabase

A handle resolving to the created subset database.

Examples

>>> app = MMseqsApp()
>>> database = app.create_db(path_to_sequences / "prot.fasta").result()
>>> # Trivial case: Select all entries from the original database
>>> subset = app.create_sub_db(database, database).result()
create_tsv(result_db: AlignmentDatabase[Any] | ClusterDatabase[Any], output_path: PathLike[str] | str | None = None, **kwargs: Any) → CommandSetup[Path | IO[bytes]]#

Export a result database as a tab-separated file using createtsv.

In contrast to convert_alignments() the identifiers are taken from the input databases, which makes this the way to read the result of MMseqsApp.cluster().

Parameters:
result_dbAlignmentDatabase or ClusterDatabase

The result database to export.

output_pathpath-like, optional

The output path. If omitted, the output is written to a temporary binary file.

**kwargs

Additional command line options.

Returns:
futureFuture of Path or binary file

A handle resolving to the output path, or to the temporary file if output_path is omitted.

Examples

>>> app = MMseqsApp()
>>> database = app.create_db(path_to_sequences / "cas9.fasta").result()
>>> clusters = app.cluster(database, threads=1).result()
>>> tsv_file = app.create_tsv(clusters, threads=1).result()
>>> print(tsv_file.readline().decode().split()[0])
sp|Q99ZW2.1|CAS9_STRP1
>>> tsv_file.close()
databases(name: str, **kwargs: Any) → CommandSetup[SequenceDatabase[Any]]#

Download and prepare a named database using databases.

Parameters:
namestr

The database name understood by the application.

**kwargs

Additional command line options.

Returns:
futureFuture of SequenceDatabase

A handle resolving to the downloaded sequence database.

Examples

>>> database = MMseqsApp().databases("UniRef50").result()

Create a symbolic database link using lndb.

This is an advanced feature. For more details consult the MMseqs2 database format

Parameters:
sourcepath-like

The source database prefix.

destinationpath-like

The destination database prefix.

**kwargs

Additional command line options.

Returns:
futureFuture of Path

A handle resolving to the destination prefix.

Examples

>>> import tempfile
>>> from pathlib import Path
>>> app = MMseqsApp()
>>> database = app.create_db(path_to_sequences / "prot.fasta").result()
>>> with tempfile.NamedTemporaryFile() as link_file:
...     link_path = Path(link_file.name)
>>> _ = app.link_db(database.name, link_path).result()
>>> link_path.is_symlink()
True
>>> link_path.unlink()
msa_to_profile(msa_db: MSADatabase[Any], match_mode: ProfileMatchMode | None = None, **kwargs: Any) → CommandSetup[ProfileDatabase[Any]]#

Convert an MSA database into a profile database using msa2profile.

Parameters:
msa_dbMSADatabase

The MSA database to create the profiles from.

match_modeProfileMatchMode, optional

Defines which MSA columns become profile columns. By default, the columns are defined by the first sequence of each MSA, i.e. the profile is kept in the coordinate frame of the query sequence.

**kwargs

Additional command line options.

Returns:
futureFuture of ProfileDatabase

A handle resolving to the created profile database.

Examples

>>> a3m_file = FastaFile.read(path_to_sequences / "1a00_A_uniref90.a3m")
>>> msa = get_a3m_alignments(a3m_file)
>>> app = MMseqsApp()
>>> msa_db = create_database_from_msa(app, {"query": msa})
>>> profile_db = app.msa_to_profile(msa_db, threads=1).result()
profile_to_consensus(profile_db: ProfileDatabase[Any], **kwargs: Any) → CommandSetup[SequenceDatabase[Any]]#

Extract the consensus sequence of each profile using profile2consensus.

Parameters:
profile_dbProfileDatabase

The profile database to extract the sequences from.

**kwargs

Additional command line options.

Returns:
futureFuture of SequenceDatabase

A handle resolving to the sequence database containing the consensus sequences.

See also

profile_to_sequences

Extracts the representative sequence instead, i.e. the first sequence of the underlying MSA.

Examples

>>> app = MMseqsApp()
>>> database = app.create_db(path_to_sequences / "cas9.fasta").result()
>>> hits = app.search(database, database, threads=1).result()
>>> profiles = app.result_to_profile(hits, threads=1).result()
>>> consensus_db = app.profile_to_consensus(profiles, threads=1).result()
>>> isinstance(consensus_db, SequenceDatabase)
True
profile_to_pssm(profile_db: ProfileDatabase[Any], output_path: PathLike[str] | str | None = None, **kwargs: Any) → CommandSetup[Path | IO[bytes]]#

Export profiles as position-specific scoring matrices using profile2pssm.

Parameters:
profile_dbProfileDatabase

The profile database to export.

output_pathpath-like, optional

The output path. If omitted, the output is written to a temporary binary file.

**kwargs

Additional command line options.

Returns:
futureFuture of Path or binary file

A handle resolving to the output path, or to the temporary file if output_path is omitted.

Notes

Each profile is preceded by a line naming its database key and is followed by one row per profile column, giving the consensus residue and the integer score for each amino acid.

Examples

>>> app = MMseqsApp()
>>> database = app.create_db(path_to_sequences / "cas9.fasta").result()
>>> hits = app.search(database, database, threads=1).result()
>>> profiles = app.result_to_profile(hits, threads=1).result()
>>> pssm_file = app.profile_to_pssm(profiles, threads=1).result()
>>> with open(pssm_file.name) as file:
...     for line in file.readlines()[:20]:
...         print(line, end="")
Query profile of sequence 0
Pos Cns A C D E F G H I K L M N P Q R S T V W Y
0 M -2 -1 -3 -2 0 -3 -1 0 -2 1 7 -2 -2 0 -1 -3 -2 0 -1 -1
1 K -1 -2 3 0 -3 -2 -1 -3 4 -2 -2 0 -1 0 0 -1 1 -2 -3 -2
2 K -1 -3 -1 0 -3 -2 0 -3 5 -3 -2 0 -1 0 2 -1 -2 -3 -2 -2
3 P -1 -2 -2 0 -3 -2 -1 -3 2 -3 -3 -2 8 0 0 -1 -2 -3 -3 -2
4 Y -2 -2 -4 -2 3 -3 1 -2 -2 -1 -1 -3 -3 -2 -2 -3 -3 -2 2 8
5 S 0 0 -1 0 -2 -1 -1 -2 -1 -2 -2 0 0 -1 -1 4 2 -2 -2 -2
6 I -2 -1 -4 -4 0 -4 -3 5 -3 1 0 -4 -3 -3 -3 -3 -2 1 -2 -1
7 G 0 -2 -2 -2 -3 6 -2 -4 -2 -4 -3 -1 -2 -2 -2 -1 -3 -4 -2 -3
8 L -2 -1 -4 -3 0 -4 -3 0 -3 5 1 -4 -3 -2 -2 -3 -2 0 -1 -1
9 D -2 -3 6 0 -3 -1 -1 -3 -1 -4 -3 0 -2 -1 -1 -1 -2 -4 -4 -3
10 I -2 -1 -3 -4 0 -4 -3 5 -3 1 0 -4 -3 -3 -3 -3 -2 1 -2 -1
11 G 0 -2 -2 -2 -3 6 -2 -4 -3 -4 -3 -1 -2 -2 -2 -1 -2 -4 -2 -3
12 T 0 0 -1 -1 -2 -1 -2 -1 -1 -1 -1 0 -1 -1 -1 0 5 0 -2 -2
13 N -2 -2 0 0 -3 0 0 -3 -1 -3 -3 6 -2 0 -1 0 -1 -3 -3 -2
14 S 0 0 0 0 -2 0 -1 -3 -1 -3 -2 0 -1 0 -1 5 0 -2 -2 -2
15 V -1 0 -3 -3 -1 -3 -3 1 -3 0 0 -3 -2 -3 -3 -2 -1 4 -2 -1
16 G 0 -2 -1 -2 -3 6 -2 -4 -2 -4 -3 0 -2 -2 -2 -1 -2 -4 -2 -3
17 W -3 -2 -5 -3 0 -3 -2 -3 -4 -2 -2 -4 -3 -2 -3 -3 -3 -3 12 1
>>> pssm_file.close()
profile_to_sequences(profile_db: ProfileDatabase[Any], **kwargs: Any) → CommandSetup[SequenceDatabase[Any]]#

Extract the representative sequence of each profile using profile2repseq.

Parameters:
profile_dbProfileDatabase

The profile database to extract the sequences from.

**kwargs

Additional command line options.

Returns:
futureFuture of SequenceDatabase

A handle resolving to the sequence database containing the representative sequences.

Notes

For a profile created via msa_to_profile() the representative sequence is the first sequence of the MSA, i.e. the query sequence for MSAs created via result_to_msa().

Examples

>>> a3m_file = FastaFile.read(path_to_sequences / "1a00_A_uniref90.a3m")
>>> msa = get_a3m_alignments(a3m_file)
>>> app = MMseqsApp()
>>> msa_db = create_database_from_msa(app, {"query": msa})
>>> profile_db = app.msa_to_profile(msa_db, threads=1).result()
>>> sequence_db = app.profile_to_sequences(profile_db, threads=1).result()
>>> # The representative sequence of the profile is the query of the MSA
>>> sequences = get_sequences_from_database(app, sequence_db)
>>> sequences["query"] == str(msa[0].sequences[0])
True
result_to_msa(alignment_db: AlignmentDatabase[Any], msa_format_mode: MSAFormatMode | None = None, **kwargs: Any) → CommandSetup[MSADatabase[Any]]#

Convert pairwise alignment results into multiple alignments using result2msa.

Parameters:
alignment_dbAlignmentDatabase

The pairwise alignment results.

msa_format_modeMSAFormatMode, optional

The multiple alignment format. The flat-file MSAFormatMode.STOCKHOLM mode is not supported because this method returns an MSADatabase.

**kwargs

Additional command line options.

Returns:
futureFuture of MSADatabase

A handle resolving to the created MSA database.

Examples

>>> app = MMseqsApp()
>>> database = app.create_db(path_to_sequences / "prot.fasta").result()
>>> alignments = app.search(database, database, threads=1).result()
>>> msa_database = app.result_to_msa(alignments, threads=1).result()
result_to_profile(alignment_db: AlignmentDatabase[Any], **kwargs: Any) → CommandSetup[ProfileDatabase[Any]]#

Compute a profile per query from search results using result2profile.

In contrast to the two-step route via result_to_msa() and msa_to_profile() this creates the profiles directly.

Parameters:
alignment_dbAlignmentDatabase

The pairwise alignment results to summarize.

**kwargs

Additional command line options.

Returns:
futureFuture of ProfileDatabase

A handle resolving to the created profile database.

Examples

>>> app = MMseqsApp()
>>> database = app.create_db(path_to_sequences / "cas9.fasta").result()
>>> hits = app.search(database, database, threads=1).result()
>>> profiles = app.result_to_profile(hits, threads=1).result()
>>> isinstance(profiles, ProfileDatabase)
True
search(query_db: SequenceDatabase[Any] | ProfileDatabase[Any], target_db: SequenceDatabase[Any], matrix: SubstitutionMatrix[Any, Any] | None = None, gap_penalty: int | tuple[int, int] | None = None, **kwargs: Any) → CommandSetup[AlignmentDatabase[Any]]#

Search a target database for matches to every query using search.

Parameters:
query_dbSequenceDatabase or ProfileDatabase

The query database. If a ProfileDatabase is given, a more sensitive profile-to-sequence search is performed.

target_dbSequenceDatabase

The target database.

matrixSubstitutionMatrix, optional

A custom symmetric substitution matrix. By default, the standard MMseqs2 matrix is used.

gap_penaltyint or tuple of (int, int), optional

The negative gap penalty. A single value applies to both opening and extension. A tuple gives the respective affine penalties.

**kwargs

Additional command line options.

Returns:
futureFuture of AlignmentDatabase

A handle resolving to the alignment database containing the search results.

Examples

>>> app = MMseqsApp()
>>> database = app.create_db(path_to_sequences / "cas9.fasta").result()
>>> matrix = SubstitutionMatrix.std_protein_matrix()
>>> alignment_db = app.search(
...     database, database, matrix=matrix,
...     gap_penalty=(-11, -1), threads=1,
... ).result()
search_reciprocal_best_hits(query_db: SequenceDatabase[Any], target_db: SequenceDatabase[Any], matrix: SubstitutionMatrix[Any, Any] | None = None, gap_penalty: int | tuple[int, int] | None = None, **kwargs: Any) → CommandSetup[AlignmentDatabase[Any]]#

Find reciprocal best hits between two databases using rbh.

Only hits that are the best hit in both search directions are reported.

Parameters:
query_db, target_dbSequenceDatabase

The query and target databases.

matrixSubstitutionMatrix, optional

A custom symmetric substitution matrix.By default, the standard MMseqs2 matrix is used.

gap_penaltyint or tuple of (int, int), optional

The negative gap penalty. A single value applies to both opening and extension. A tuple gives the respective affine penalties.

**kwargs

Additional command line options.

Returns:
futureFuture of AlignmentDatabase

A handle resolving to the alignment database containing the reciprocal best hits.

Examples

>>> app = MMseqsApp()
>>> database = app.create_db(path_to_sequences / "cas9.fasta").result()
>>> hits = app.search_reciprocal_best_hits(database, database, threads=1).result()
unpack_db(database: Database[Any], directory: PathLike[str] | str, **kwargs: Any) → CommandSetup[Path]#

Write each entry of a database into a separate file using unpackdb.

This is an advanced feature. For more details consult the MMseqs2 database format

Parameters:
databaseDatabase

The database to unpack. Any type of database is accepted, as the entry content is copied verbatim.

directorypath-like

The directory the files are written to. It is created, if it does not exist.

**kwargs

Additional command line options.

Returns:
futureFuture of Path

A handle resolving to the directory containing the written files.

Notes

A database stores all of its entries concatenated in a single data file, addressed by byte offsets in an accompanying index. This command reverses that packing: it writes the raw content of each entry into its own file, without interpreting it. Hence it is the general way to read entries of a database that no dedicated conversion command covers.

By default each file is named after the identifier of its entry, taken from the lookup file of the database. Only databases created from named input have such a file, so for a sub-database such as the header database, and for result databases such as an AlignmentDatabase, the numeric database key is used instead. The unpack_name_mode option selects the scheme explicitly (see UnpackNameMode) and unpack_suffix appends a file extension.

The written content is the entry data with its terminating null byte removed. A trailing newline that is part of the entry is kept, so for a sequence database each file contains the sequence followed by a line break. What an entry comprises depends on the database: a single sequence for a SequenceDatabase, or all hits of one query for an AlignmentDatabase. Note that the latter are written in the internal representation, which refers to targets by their database key, hence convert_alignments() is usually the better choice for reading alignments.

Examples

>>> import tempfile
>>> app = MMseqsApp()
>>> database = app.create_db(path_to_sequences / "prot.fasta").result()
>>> with tempfile.TemporaryDirectory() as directory:
...     unpacked = app.unpack_db(database, directory, threads=1).result()
...     print(sorted(path.name for path in unpacked.iterdir()))
['protein']
On this page
Edit on GitHub
Show Source