`FoldseekApp`#

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

Bases: MMseqsLikeApp

A reusable handle to the Foldseek command line program.

Parameters:

pathpath-like, optional: Path to the foldseek executable.

Attributes:

tmp_dirPath: The temporary directory required for some MMseqs2 and Foldseek commands.

Examples

>>> structure_path = path_to_structures / "1aki.cif"
>>> future = FoldseekApp().create_db(structure_path, threads=1)

cluster(sequence_db: SequenceDatabase[Any], **kwargs: Any) → CommandSetup[ClusterDatabase[Any]]#

Cluster a structure database using the cascaded cluster workflow.

Parameters:

sequence_dbSequenceDatabase: The structure database to cluster.
**kwargs: Additional command line options.

Returns:

futureFuture of ClusterDatabase: A handle resolving to the created cluster database.

Examples

>>> app = FoldseekApp()
>>> database = app.create_db(path_to_structures / "1aki.cif").result()
>>> clusters = app.cluster(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_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 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_multimer_report(alignment_db: AlignmentDatabase[Any], output_path: PathLike[str] | str | None = None, **kwargs: Any) → CommandSetup[Path | IO[bytes]]#

Export complex-level hits as a report using createmultimerreport.

Parameters:

alignment_dbAlignmentDatabase: The complex-level hits from search_multimers().
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 row gives the query and target identifier, the matched chains, the TM-score in both directions, the superimposition and the assignment ID.

Examples

>>> app = FoldseekApp()
>>> database = app.create_db(path_to_structures / "1k6p.cif").result()
>>> hits = app.search_multimers(database, database, threads=1).result()
>>> report_file = app.create_multimer_report(hits, threads=1).result()
>>> with open(report_file.name) as file:
...     query, target, query_chains, target_chains = file.readline().split()[:4]
>>> print(query, target, query_chains, target_chains)
1k6p 1k6p A,B A,B
>>> report_file.close()

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()

link_db(source: PathLike[str] | str, destination: PathLike[str] | str, **kwargs: Any) → CommandSetup[Path]#

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()

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()

search(query_db: SequenceDatabase[Any], target_db: SequenceDatabase[Any], **kwargs: Any) → CommandSetup[AlignmentDatabase[Any]]#

Search a target database for structural matches using search.

Parameters:

query_db, target_dbSequenceDatabase: The query and target structure databases.
**kwargs: Additional command line options.

Returns:

futureFuture of AlignmentDatabase: A handle resolving to the alignment database containing the search results.

Examples

>>> app = FoldseekApp()
>>> database = app.create_db(path_to_structures / "1aki.cif").result()
>>> alignment_db = app.search(database, database, threads=1).result()

search_multimers(query_db: SequenceDatabase[Any], target_db: SequenceDatabase[Any], **kwargs: Any) → CommandSetup[AlignmentDatabase[Any]]#

Search multi-chain structures against each other using multimersearch.

In contrast to search() the hits are reported per complex instead of per chain.

Parameters:

query_db, target_dbSequenceDatabase: The query and target structure databases. Chains of the same structure must share their structure identifier, which is the case for databases created from multi-chain files.
**kwargs: Additional command line options.

Returns:

futureFuture of AlignmentDatabase: A handle resolving to the alignment database containing the complex-level hits.

See also

create_multimer_report: Reads the chain assignment of each complex-level hit.

Examples

>>> app = FoldseekApp()
>>> database = app.create_db(path_to_structures / "1k6p.cif").result()
>>> hits = app.search_multimers(database, database, threads=1).result()
>>> isinstance(hits, AlignmentDatabase)
True

search_reciprocal_best_hits(query_db: SequenceDatabase[Any], target_db: SequenceDatabase[Any], **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 structure databases.
**kwargs: Additional command line options.

Returns:

futureFuture of AlignmentDatabase: A handle resolving to the alignment database containing the reciprocal best hits.

Examples

>>> app = FoldseekApp()
>>> database = app.create_db(path_to_structures / "1aki.cif").result()
>>> hits = app.search_reciprocal_best_hits(database, database, threads=1)
>>> isinstance(hits.result(), AlignmentDatabase)
True

structure_align(alignment_db: AlignmentDatabase[Any], **kwargs: Any) → CommandSetup[AlignmentDatabase[Any]]#

Recompute structural alignments of a result database using structurealign.

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.
**kwargs: Additional command line options.

Returns:

futureFuture of AlignmentDatabase: A handle resolving to the alignment database containing the recomputed alignments.

Examples

>>> app = FoldseekApp()
>>> database = app.create_db(path_to_structures / "1aki.cif").result()
>>> hits = app.search(database, database, threads=1).result()
>>> realigned = app.structure_align(hits, threads=1).result()
>>> isinstance(realigned, AlignmentDatabase)
True

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']

FoldseekApp#

`FoldseekApp`#