molforge.wrappers.msa¶

msa ¶

Local homology search — producing MSAs without a public server.

molforge's AF3-class folding wrappers have always sourced alignments from ColabFold's public MMseqs2 server. This subpackage is the local alternative: the same search, against a database you control, on a machine you can inspect.

:class:MMseqs2 — fast profile search (Steinegger & Söding 2017), returning a :class:~molforge.sequence.MultipleSequenceAlignment.

Each engine needs its own pre-built database; molforge deliberately does not download or build those, since they run to hundreds of gigabytes and only need making once. The engines' errors name the command that does it.

MMseqs2 ¶

MMseqs2(
    *,
    database: str | PathLike[str] | None = None,
    sensitivity: float | None = None,
    max_seqs: int | None = None,
    threads: int | None = None,
    executable: str = "mmseqs",
    timeout: float | None = None,
)

Search a sequence against a local MMseqs2 database.

Parameters:

Name	Type	Description	Default
`database`	`str \| PathLike[str] \| None`	Path to a pre-built MMseqs2 database — the `outpath` given to `mmseqs databases`, without any suffix. `None` falls back to `$MOLFORGE_MSA_DB`; with neither, searching raises :class:`MSADatabaseNotFoundError` naming the command that builds one.	`None`
`sensitivity`	`float \| None`	MMseqs2's `-s`. Higher finds more remote homologues and costs more time; `None` leaves MMseqs2's own default. 7.5 is the usual choice when depth matters more than speed.	`None`
`max_seqs`	`int \| None`	Cap on hits taken through to alignment (`--max-seqs`). This is a search cap, not the MSA depth a model sees — subsample the returned alignment for that.	`None`
`threads`	`int \| None`	`--threads`. `None` lets MMseqs2 choose.	`None`
`executable`	`str`	Name or path of the `mmseqs` binary.	`'mmseqs'`
`timeout`	`float \| None`	Seconds before the search is abandoned. `None` waits indefinitely, which is often right: a sensitive search against UniRef90 legitimately takes a long time.	`None`

Example

from molforge.wrappers.msa import MMseqs2 engine = MMseqs2(database="/data/uniref90", sensitivity=7.5) msa = engine.search("MKQHKAMIVAL...") # doctest: +SKIP msa.depth # doctest: +SKIP 2041 shallow = msa.subsample(32, seed=0) # doctest: +SKIP

search ¶

search(sequence: str) -> MultipleSequenceAlignment

Search sequence and return the alignment.

Parameters:

Name	Type	Description	Default
`sequence`	`str`	A one-letter amino-acid sequence.	required

Returns:

Name	Type	Description
`A`	`MultipleSequenceAlignment`	class:`~molforge.sequence.MultipleSequenceAlignment` whose
	`MultipleSequenceAlignment`	query is `sequence` and whose hits are labelled with the
	`MultipleSequenceAlignment`	database they came from.

Raises:

Type	Description
`ValueError`	If `sequence` is empty.
`MMseqs2NotInstalledError`	If the binary isn't on `$PATH`.
`MSADatabaseNotFoundError`	If no database is configured.
`RuntimeError`	If a search step fails or produces no alignment.

MMseqs2NotInstalledError ¶

Bases: RuntimeError

Raised when the mmseqs binary isn't on $PATH.

MSADatabaseNotFoundError ¶

Bases: RuntimeError

Raised when no MMseqs2 database was given, or the path isn't one.

mmseqs2 ¶

MMseqs2 homology search — a local alternative to the public MSA server.

molforge's AF3-class folding wrappers have always sourced their alignments from ColabFold's public MMseqs2 server. That is fine for a handful of predictions and increasingly hard to defend at scale: it is a shared community resource, it rate-limits, it requires network access from wherever the job runs, and it means the single most influential input to a prediction is produced somewhere you cannot inspect or reproduce.

MMseqs2 <https://github.com/soedinglab/MMseqs2>_ (Steinegger & Söding, 2017) is the same search, run locally against a database you control.

Installation::

conda install -c conda-forge -c bioconda mmseqs2
# or: brew install mmseqs2

The database¶

search needs a pre-built MMseqs2 database — a raw FASTA will not do. Building one is a one-off:

.. code-block:: bash

mmseqs databases UniRef90 /data/uniref90 /tmp/mmseqs-tmp

Expect hundreds of gigabytes and hours of wall clock. molforge deliberately does not wrap that step: it is not something anyone should be able to trigger by accident from a notebook, and it only needs doing once per machine. Point molforge at the result with database= or by setting $MOLFORGE_MSA_DB.

What comes back¶

A :class:~molforge.sequence.MultipleSequenceAlignment, ready to subsample down a depth ladder or hand to a folding engine. Searches are cached on the same content-addressed basis as every other molforge engine result, which matters more here than usual — a deep search is minutes to hours, and the same query against the same database is the same answer.

MMseqs2NotInstalledError ¶

Bases: RuntimeError

Raised when the mmseqs binary isn't on $PATH.

MSADatabaseNotFoundError ¶

Bases: RuntimeError

Raised when no MMseqs2 database was given, or the path isn't one.

MMseqs2 ¶

MMseqs2(
    *,
    database: str | PathLike[str] | None = None,
    sensitivity: float | None = None,
    max_seqs: int | None = None,
    threads: int | None = None,
    executable: str = "mmseqs",
    timeout: float | None = None,
)

Search a sequence against a local MMseqs2 database.

Parameters:

Name	Type	Description	Default
`database`	`str \| PathLike[str] \| None`	Path to a pre-built MMseqs2 database — the `outpath` given to `mmseqs databases`, without any suffix. `None` falls back to `$MOLFORGE_MSA_DB`; with neither, searching raises :class:`MSADatabaseNotFoundError` naming the command that builds one.	`None`
`sensitivity`	`float \| None`	MMseqs2's `-s`. Higher finds more remote homologues and costs more time; `None` leaves MMseqs2's own default. 7.5 is the usual choice when depth matters more than speed.	`None`
`max_seqs`	`int \| None`	Cap on hits taken through to alignment (`--max-seqs`). This is a search cap, not the MSA depth a model sees — subsample the returned alignment for that.	`None`
`threads`	`int \| None`	`--threads`. `None` lets MMseqs2 choose.	`None`
`executable`	`str`	Name or path of the `mmseqs` binary.	`'mmseqs'`
`timeout`	`float \| None`	Seconds before the search is abandoned. `None` waits indefinitely, which is often right: a sensitive search against UniRef90 legitimately takes a long time.	`None`

Example

from molforge.wrappers.msa import MMseqs2 engine = MMseqs2(database="/data/uniref90", sensitivity=7.5) msa = engine.search("MKQHKAMIVAL...") # doctest: +SKIP msa.depth # doctest: +SKIP 2041 shallow = msa.subsample(32, seed=0) # doctest: +SKIP

search ¶

search(sequence: str) -> MultipleSequenceAlignment

Search sequence and return the alignment.

Parameters:

Name	Type	Description	Default
`sequence`	`str`	A one-letter amino-acid sequence.	required

Returns:

Name	Type	Description
`A`	`MultipleSequenceAlignment`	class:`~molforge.sequence.MultipleSequenceAlignment` whose
	`MultipleSequenceAlignment`	query is `sequence` and whose hits are labelled with the
	`MultipleSequenceAlignment`	database they came from.

Raises:

Type	Description
`ValueError`	If `sequence` is empty.
`MMseqs2NotInstalledError`	If the binary isn't on `$PATH`.
`MSADatabaseNotFoundError`	If no database is configured.
`RuntimeError`	If a search step fails or produces no alignment.