Skip to content

A3M Combiner

A3MCombinerNode merges multiple A3M MSA inputs, each as a dictionary mapping chain IDs to A3M-formatted strings, into a single combined A3M dictionary. It can optionally prefix chain IDs per input index to avoid collisions and auto-renames duplicates with numeric suffixes when needed. The node requires at least one non-empty A3M input and leaves the MSA string contents unchanged.
Preview

Usage

Use A3MCombinerNode when you have several A3M multiple-sequence alignments that must be provided as a single MSA object to downstream structure prediction or analysis nodes. Typical upstream nodes include LoadA3MNode and custom MSA generators that output the MSA type as a dict of {chain_id: a3m_string}. Place this node after all MSA preparation steps and before AlphaFold-style or other biotech nodes that accept one combined MSA input. Connect between one and five inputs (a3m_1–a3m_5); any that are unconnected or empty are ignored. Enable prefix_chains when different inputs reuse the same chain IDs (for example, multiple complexes or runs with chain "A") so that output keys become A3M1_A, A3M2_A, etc., ensuring uniqueness and traceability. For coordinated pipelines, align its chain ID conventions with PDBCombinerNode and FastaCombinerNode so that PDB, FASTA, and A3M refer to chains consistently.

Inputs

FieldRequiredTypeDescriptionExample
a3m_1FalseMSAFirst A3M MSA dictionary to include. Must be a dictionary mapping chain IDs (such as "A", "B", or "A_chain1") to A3M-formatted MSA strings. Ignored if missing, not a dict, or empty.{ "A": ">query/1-120\nMKTAYIAKQRQISFVKSHFSRQ\n>homolog1\nMKTAYIAKQREISFVKSHFSRQ\n" }
a3m_2FalseMSASecond A3M MSA dictionary, merged into the combined output if it is a non-empty dictionary.{ "A": ">query_alt/1-120\nMKTAYIAKQRQISFVKSHFSRQ\n>env_hit1\nMKTAYIAKQRQISFVKSHFTRQ\n" }
a3m_3FalseMSAThird optional A3M MSA dictionary, for example an MSA for another chain or from a different search pipeline.{ "B": ">chainB_query/1-80\nGASSSGSSGSSGGSSGSSGG\n" }
a3m_4FalseMSAFourth optional A3M MSA dictionary. If not connected or if not a non-empty dictionary, it has no effect.{ "A": ">deepmsa_query/1-120\nMKTAYIAKQRQISFVKSHFSRQ\n" }
a3m_5FalseMSAFifth optional A3M MSA dictionary, allowing aggregation of up to five independent MSA sources into a single combined mapping.{ "C": ">chainC_query/1-50\nMSSHHHHHHSSGLVPRGSH\n" }
prefix_chainsFalseBOOLEANIf true, chain IDs from each input are prefixed with "A3M{i}_" based on the input index (e.g., A3M1_A, A3M2_B). If false, original chain IDs are used and collisions are resolved by appending numeric suffixes (_1, _2, ...) instead of overwriting. Default behavior is false.true

Outputs

FieldTypeDescriptionExample
combined_a3mMSASingle merged A3M MSA dictionary constructed from all non-empty inputs. Keys are unique chain IDs (optionally prefixed and/or suffixed) and values are the original A3M-formatted strings. This is the MSA object to feed into downstream prediction or analysis nodes that expect one combined MSA input.{ "A3M1_A": ">query/1-120\nMKTAYIAKQRQISFVKSHFSRQ\n>homolog1\nMKTAYIAKQREISFVKSHFSRQ\n", "A3M2_A": ">query_alt/1-120\nMKTAYIAKQRQISFVKSHFSRQ\n>env_hit1\nMKTAYIAKQRQISFVKSHFTRQ\n", "A3M3_B": ">chainB_query/1-80\nGASSSGSSGSSGGSSGSSGG\n" }

Important Notes

  • Performance: The node only iterates over up to five dictionaries and copies keys/values, so it is lightweight; only extremely large MSAs will noticeably impact time or memory.
  • Limitations: At least one of a3m_1–a3m_5 must be a non-empty dictionary; otherwise the node raises a ValueError indicating that at least one A3M input is required.
  • Behavior: With prefix_chains set to true, chain IDs are prefixed by input index (A3M1_, A3M2_, etc.) and, if needed, numeric suffixes (_1, _2, ...) are added to keep keys unique.
  • Behavior: With prefix_chains set to false, repeated chain IDs across inputs trigger a warning and are disambiguated with numeric suffixes instead of overwriting earlier entries; MSA string contents are never altered.
  • Behavior: The node treats inputs as plain dictionaries and does not validate that value strings are syntactically correct A3M, so upstream processing must ensure valid A3M formatting.

Troubleshooting

  • Common Error 1: Error stating that at least one A3M input is required. This occurs when all a3m_1–a3m_5 are unconnected, None, not dicts, or empty. Connect at least one valid MSA dictionary output or verify that upstream nodes are producing non-empty MSA dictionaries.
  • Common Error 2: Downstream nodes see chain IDs like A3M1_A instead of A. This is caused by prefix_chains being true. Disable prefix_chains or adjust your PDB/FASTA nodes and downstream configuration to expect the prefixed IDs.
  • Common Error 3: PDB or FASTA inputs use chain IDs A, B, but the combined MSA uses A_1, A_2 due to conflict resolution, leading to mismatch in downstream tools that require matching IDs. Ensure chain IDs are unique across MSAs or harmonize naming by applying a similar prefixing/renaming pattern with PDBCombinerNode and FastaCombinerNode.
  • Common Error 4: Connecting a non-dictionary object (for example, a plain string) to an a3m_* input results in that input being ignored. Update the upstream node to output a dictionary of {chain_id: a3m_string} so it is included in the combined result.

Example Pipelines

Example
Example