af3-msa-injector

name	af3-msa-injector
description	Inject cleaned ColabFold MSA artifacts from `af3-msa-search` into MSA-free AF3 or Protenix inference JSON files to produce complete inputs for downstream inference. Use when AF3 JSON contains empty `unpairedMsa`/`pairedMsa` fields or Protenix JSON lacks `unpairedMsaPath`/`pairedMsaPath`, including single-file and batch directory processing.

AF3 Protenix MSA Injector

Inject processed_msas outputs into inference JSONs generated by AF3 pipelines and af3-json-converter. Run from repository root and prefer .venv/bin/python.

Quick Start

1. Inject into one AF3 JSON (default: write inline unpairedMsa and pairedMsa):

.venv/bin/python skills/af3-msa-injector/scripts/inject_msa_into_inference_json.py \
  --input /abs/path/to/job_xxx.json \
  --output /abs/path/to/job_xxx.with_msa.json \
  --msa-root /abs/path/to/localcolabfold_msa_YYYYmmdd_HHMMSS

2. Inject into one Protenix JSON (write *MsaPath fields):

.venv/bin/python skills/af3-msa-injector/scripts/inject_msa_into_inference_json.py \
  --input /abs/path/to/job_xxx.protenix.json \
  --output /abs/path/to/job_xxx.protenix.with_msa.json \
  --msa-root /abs/path/to/localcolabfold_msa_YYYYmmdd_HHMMSS \
  --format protenix

3. Batch-process a JSON directory:

.venv/bin/python skills/af3-msa-injector/scripts/inject_msa_into_inference_json.py \
  --input /abs/path/to/af3_json_dir \
  --output /abs/path/to/af3_json_dir_with_msa \
  --msa-root /abs/path/to/localcolabfold_msa_YYYYmmdd_HHMMSS \
  --glob '*.json'

Matching Rules

MSA search is purely sequence-driven — the same protein sequence always produces the same MSA regardless of chain identity or naming.

For each protein (AF3) or proteinChain (Protenix) entry in the input JSON:

1. The sequence is normalised (whitespace stripped, uppercased).
2. SHA256(normalised_sequence) is computed.
3. The hash is looked up in the MSA index built from processed_msas/.

A match means the A3M query sequence has the identical SHA-256 hash. If the hash does not match, the entry is reported as missing.

Input Contract

• --msa-root accepts either:
  • localcolabfold run root containing processed_msas/, or
  • the processed_msas/ directory itself.
• processed_msas must contain cleaned files:
  • .../unpairedMSA/*_unpaired_msa.a3m
  • .../pairedMSA/*_paired_msa.a3m

Important Flags

• --format auto|af3|protenix: force or auto-detect JSON dialect.
• --af3-write inline|path: AF3 write mode (default inline).
• --path-style auto|abs|rel|container: style for written *Path values.
  • auto (default): protenix -> container, af3 -> abs
  • container: write /mnt/input/... paths for Docker portability
• --protenix-msa-mode external|copy: for Protenix path writing.
  • copy (default): materialize MSA files under each JSON directory (_msa/) and reference them
  • external: keep references to source MSA files
  • note: --path-style container requires --protenix-msa-mode copy
• --strict 0|1: fail on any unmatched protein entry (default 1).
• --dry-run 0|1: compute and report matches without writing files.

Failure Handling

• If no cleaned A3M files are found under processed_msas, stop and fix MSA preprocessing first.
• If --strict 1 and any protein entry cannot find MSA, fail with non-zero exit and inspect [Warn] logs.
• Missing MSA means the protein sequence was not included in the upstream MSA search run. Re-run the search with the missing sequences.

Resources

• scripts/inject_msa_into_inference_json.py: deterministic CLI for MSA injection into AF3/Protenix JSON.