Metadata-Version: 2.4
Name: scigantic-msa
Version: 0.2.0
Summary: Get a protein MSA once from the ColabFold MMseqs2 server, or bring your own A3M, and write the input files for AlphaFold 3, Boltz, Chai-1, ColabFold, OpenFold3 or Protenix.
Author: Scigantic
License: MIT
Project-URL: Homepage, https://github.com/Scigantic/scigantic-msa
Project-URL: Repository, https://github.com/Scigantic/scigantic-msa
Project-URL: Issues, https://github.com/Scigantic/scigantic-msa/issues
Keywords: msa,a3m,protein,alphafold3,boltz,chai,colabfold,openfold,protenix,structure-prediction
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Environment :: Console
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: chai
Requires-Dist: pyarrow>=12; extra == "chai"
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: pyarrow>=12; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Dynamic: license-file

# scigantic-msa

Get a multiple sequence alignment (MSA) for a protein sequence once, and
write the input files for the structure predictor you are about to run:
AlphaFold 3, Boltz, Chai-1, ColabFold, OpenFold3 or Protenix.

The alignment comes from the ColabFold MMseqs2 server (or NVIDIA's MSA
Search, if you have a key), or from an A3M file you already have. There is
no account and no login, and nothing is stored on our side.

## Install

```
pip install scigantic-msa            # or: uv tool install scigantic-msa
pip install 'scigantic-msa[chai]'    # adds pyarrow, needed for Chai-1 files
```

Python 3.10 or newer. The core has no dependencies.

## Privacy

Your sequence may be unpublished, so read this before you run a search.

- `run` and `MSA().get()` send the sequence to a third-party server:
  api.colabfold.com by default. The public ColabFold server needs no login
  to read a result, and the job id is a hash of the sequence, so anyone who
  knows the sequence can download the result. Treat a submission there as
  publishing the sequence.
- The Python API refuses to send anything unless you pass `remote=True`.
  The command line says which server will receive the sequence and asks
  once; `--yes` skips the question for scripts. Without a terminal and
  without `--yes`, it stops and sends nothing.
- `convert` and `MSA().from_a3m()` make no network connection at all.
- The only network traffic is to the server you chose. The tool never
  contacts a Scigantic server.
- The sequence is never written to a log. Results are kept in a local cache
  (`~/.cache/scigantic-msa`, or `SCIGANTIC_MSA_CACHE`) so the same sequence
  is not submitted twice; delete the directory to forget them, or pass
  `--no-cache`.
- `SCIGANTIC_MSA_NO_REMOTE=1` blocks every search, whatever the code asks.

The public ColabFold server is a shared resource with a rate limit of about
one new job per minute per IP address. This client backs off, honours
Retry-After, resumes a job from its id instead of submitting it again, and
gives up after a bounded wait. To use your own server, pass `--host URL`
(or `MSA(host=URL)`).

## Command line

```
scigantic-msa run SEQ_OR_FASTA --model boltz --out job/
scigantic-msa run chains.fasta --model af3 --out job/ --yes
scigantic-msa convert my_alignment.a3m --model protenix --out job/
scigantic-msa version
```

`--model` is one of `af3`, `boltz`, `chai`, `colabfold`, `openfold3`,
`protenix`. A FASTA file with several records is one complex, one chain per
record; `:` inside a sequence also separates chains. `convert` takes one
A3M (or `.a3m.gz`, or Stockholm `.sto`) per chain, in chain order.
`--server nvidia` uses NVIDIA's hosted MSA Search and needs
`NVIDIA_API_KEY`.

After writing the files, the command prints the command to run the model
on them.

## Python

Every adapter takes one result, or a list of results for the chains of a
complex. The result carries its sequence; if you also pass the sequence,
it must match.

AlphaFold 3:

```python
import json
from scigantic_msa import MSA
from scigantic_msa.adapters import AlphaFold3
result = MSA().get(sequence, remote=True)
json.dump(AlphaFold3.prepare(result, name="job"), open("job.json", "w"))
```

Boltz:

```python
from scigantic_msa import MSA
from scigantic_msa.adapters import Boltz
result = MSA().get(sequence, remote=True)
yaml_text = Boltz.prepare(result, out_dir="boltz/")
open("job.yaml", "w").write(yaml_text)        # then: boltz predict job.yaml
```

Chai-1:

```python
from scigantic_msa import MSA
from scigantic_msa.adapters import Chai
result = MSA().get(sequence, remote=True)
msa_dir = Chai.prepare(result, out_dir="chai_msas/")
open("job.fasta", "w").write(Chai.fasta(result))   # chai-lab fold --msa-directory chai_msas/ job.fasta out/
```

Protenix:

```python
import json
from scigantic_msa import MSA
from scigantic_msa.adapters import Protenix
result = MSA().get(sequence, remote=True)
json.dump(Protenix.prepare(result, out_dir="protenix_msas/"), open("job.json", "w"))
```

ColabFold and OpenFold3 work the same way: `ColabFold.prepare(result,
out_dir=...)` returns the path of the A3M for `colabfold_batch`, and
`OpenFold3.prepare(result, out_dir=...)` returns the query JSON as a dict.

With an alignment you already have, and no network:

```python
result = MSA().from_a3m("my_alignment.a3m", sequence=sequence)
```

## Checks

- An A3M is checked strictly: the first record must be the query (no gaps,
  no lowercase), only `A-Z`, `a-z` and `-` are allowed, and every row must
  have as many match columns as the query has residues.
- Each adapter reads back what it wrote: every file it names exists, is not
  empty, starts with the chain's sequence, and has the name the model looks
  for. Chai-1 skips a chain's MSA without an error when the file name is
  wrong, and Protenix ignores a file in `precomputed_msa_dir` that is not
  called `pairing.a3m` or `non_pairing.a3m`; here both are errors.
- `Protenix.check(path_or_jobs)` runs the same checks on any Protenix input
  JSON, including a missing `*MsaPath`, which would make Protenix start its
  own MSA search and send the sequence to a server.

## Complexes

Each chain gets its own unpaired MSA. Rows are paired across chains only
where the rows say the species: an NCBI taxid (from ColabFold's taxonomy
output, or `TaxID=` / `OX=` in headers) or a UniProt species code.
Environmental and metagenomic hits have none and stay unpaired. When
pairing is not possible the tool says why, for example "no species is
shared by all chains; the chains get unpaired MSAs".

| model | how pairing is passed on |
| --- | --- |
| AlphaFold 3 | paired rows first in `unpairedMsa`; run with `--resolve_msa_overlaps=false` (UniProt rows go in `pairedMsa` instead, and AF3 pairs them) |
| Boltz | one CSV per chain; paired rows share a key |
| Chai-1 | `pairing_key` column |
| ColabFold | the complex A3M layout, paired rows first |
| OpenFold3 | `colabfold_paired.a3m` per chain |
| Protenix | `pairing.a3m` per chain, with headers Protenix reads the species from; Protenix pairs them |

## Formats

The file layouts follow the models' own code: AlphaFold 3
`folding_input.py`, Boltz `main.py` and `parse/csv.py`, Chai-1
`aligned_pqt.py`, ColabFold `input.py`, OpenFold3 0.5.1
`inference_query_format.py`, and Protenix 2.0.0 `runner/msa_search.py`,
`protenix/data/msa/msa_featurizer.py` and `msa_utils.py`.

## Data sources and attribution

The alignments come from the server you chose, under its terms:

- ColabFold MMseqs2 server, run by the ColabFold team. Cite Mirdita et al.,
  ColabFold: making protein folding accessible to all, Nature Methods 19,
  679-682 (2022), and the databases it searches (UniRef30 and the ColabFold
  environmental database).
- NVIDIA MSA Search (experimental here), under NVIDIA's API trial terms.

Every adapter that writes files also writes `scigantic-msa-attribution.json`
next to them, with the server, mode, date and the terms to credit.

## Settings

| variable | meaning |
| --- | --- |
| `SCIGANTIC_MSA_CACHE` | cache directory (default `~/.cache/scigantic-msa`) |
| `SCIGANTIC_MSA_NO_REMOTE=1` | never send a sequence to any server |
| `SCIGANTIC_MSA_COLABFOLD_URL` | another ColabFold MMseqs2 server |
| `SCIGANTIC_MSA_CONTACT` | text added to the User-Agent sent to the server, such as an email address |
| `NVIDIA_API_KEY` | key for `--server nvidia` |

## Development

```
pip install -e '.[dev]'
pytest
```

The tests run offline against small real alignment files in
`tests/fixtures/real` and a local HTTP server standing in for the ColabFold
and NVIDIA APIs. `tests/test_predictors.py` loads the output with Boltz's
and Chai-1's own parsers when interpreters with those packages are given;
see the file for how.

## License

MIT. The alignments are under the terms of the server and databases they
came from.
