diff --git a/README.md b/README.md index 55909c62..be49be50 100644 --- a/README.md +++ b/README.md @@ -150,6 +150,8 @@ If you are using the MSA server via colabfold_batch, you can also use the `--af3 colabfold_batch input_sequences.fasta out_dir --af3-json ``` +For complexes, the paired MSA is written into each chain's `unpairedMsa` field (with the paired rows placed first, aligned across chains), while `pairedMsa` is left empty. This follows the recommendation in the [AlphaFold3 documentation](https://github.com/google-deepmind/alphafold3/blob/main/docs/input.md#msa-pairing), since AlphaFold3 would otherwise re-pair a user-provided `pairedMsa` internally by matching UniProt organism IDs in the sequence headers, which is not supported by the MMseqs2 paired A3M headers. When running AlphaFold3 on such json inputs, use `--resolve_msa_overlaps=false` to prevent the deduplication procedure from destroying the sequence positioning in the unpaired MSA. + #### Including non-protein molecules in FASTA AlphaFold3 supports non-protein components such as ligands and nucleic acids in input complexes. To include these in the generated json file, you can specify them directly in your FASTA input using the following format, `molecule type|sequence|(copies)`. As molecue types, dna, rna, ccd, smiles are allowed. diff --git a/colabfold/utils.py b/colabfold/utils.py index 0d3314f2..a5389d31 100644 --- a/colabfold/utils.py +++ b/colabfold/utils.py @@ -330,10 +330,29 @@ def _int_id_to_str_id(self, i: int) -> str: i = i // 26 - 1 return "".join(output) + @staticmethod + def merge_paired_msa_into_unpaired( + unpairedmsa: Optional[List[str]], pairedmsa: Optional[List[str]] + ) -> Optional[List[str]]: + if pairedmsa is None: + return unpairedmsa + if unpairedmsa is None: + return list(pairedmsa) + merged = [] + for paired, unpaired in zip(pairedmsa, unpairedmsa): + if paired and unpaired: + merged.append(paired.rstrip("\n") + "\n" + unpaired) + else: + merged.append(paired or unpaired or "") + return merged + def make_af3_input(self, name: str, query_seqs_unique: List[str], query_seqs_cardinality: List[int], unpairedmsa: List[str], pairedmsa: List[str], ) -> dict: + # paired sequences are provided via unpairedMsa only, as recommended by the AlphaFold3 documentation. + unpairedmsa = self.merge_paired_msa_into_unpaired(unpairedmsa, pairedmsa) + pairedmsa = None sequences: list[dict] = [] chain_id_count = 0 for i in range(len(query_seqs_unique)): # NOTE: This will not work if there's no protein sequences diff --git a/tests/test_utils.py b/tests/test_utils.py index 8d1429cc..cedb4745 100644 --- a/tests/test_utils.py +++ b/tests/test_utils.py @@ -139,3 +139,59 @@ def test_convert_pdb_to_mmcif_parse_with_alphafold(pytestconfig, tmp_path): ) assert len(parsing_result.errors) == 0 + + +def test_af3_merge_paired_msa_into_unpaired(): + from colabfold.utils import AF3Utils + + query_seqs_unique = ["AAAA", "GGGG"] + query_seqs_cardinality = [1, 1] + # Per-chain unpaired A3Ms (first entry is the query itself) + unpaired_msa = [ + ">query\nAAAA\n>u1\nAAta\n", + ">query\nGGGG\n>u2\nGGgg\n", + ] + # Per-chain paired A3Ms: row-aligned across chains, gap-only dummy row + # for chains without a hit for that species + paired_msa = [ + ">query\nAAAA\n>p1\nAA--\n>p2\n--AA\n", + ">query\nGGGG\n>p1\n----\n>p2\nGGGG\n", + ] + + # Without a paired MSA, nothing changes and pairedMsa stays empty + af3 = AF3Utils("test", query_seqs_unique, query_seqs_cardinality, unpaired_msa, None) + for i, seq in enumerate(af3.content["sequences"]): + assert seq["protein"]["unpairedMsa"] == unpaired_msa[i] + assert seq["protein"]["pairedMsa"] == "" + + # With a paired MSA, the paired rows are merged into unpairedMsa (paired + # block first, query sequence as the first entry) and pairedMsa is left + # empty so AF3 does not re-pair the MSA by header name matching + af3 = AF3Utils("test", query_seqs_unique, query_seqs_cardinality, unpaired_msa, paired_msa) + expected_unpaired = [ + paired_msa[0] + unpaired_msa[0], + paired_msa[1] + unpaired_msa[1], + ] + for i, seq in enumerate(af3.content["sequences"]): + assert seq["protein"]["unpairedMsa"] == expected_unpaired[i] + # First MSA entry must be exactly the query sequence (AF3 requirement) + a3m_lines = seq["protein"]["unpairedMsa"].splitlines() + assert a3m_lines[1] == query_seqs_unique[i] + assert seq["protein"]["pairedMsa"] == "" + + +def test_af3_merge_paired_msa_into_unpaired_paired_only(): + from colabfold.utils import AF3Utils + + query_seqs_unique = ["AAAA", "GGGG"] + query_seqs_cardinality = [1, 1] + paired_msa = [ + ">query\nAAAA\n>p1\nAA--\n", + ">query\nGGGG\n>p1\n----\n", + ] + + # paired-only mode: no unpaired MSA available + af3 = AF3Utils("test", query_seqs_unique, query_seqs_cardinality, None, paired_msa) + for i, seq in enumerate(af3.content["sequences"]): + assert seq["protein"]["unpairedMsa"] == paired_msa[i] + assert seq["protein"]["pairedMsa"] == ""