Align NA-MPNN model card with OFoldX

README.md

@@ -16,21 +16,24 @@ Pre-trained model for joint protein, DNA, and RNA sequence design and scoring fr
 
 ## Disclaimer
 
-This is an unofficial OFoldX implementation of
-[NA-MPNN](https://github.com/baker-laboratory/NA-MPNN). The upstream authors did
-not write, review, or endorse this implementation or model card.
+This is an UNOFFICIAL implementation of the [RNA sequence design and protein-DNA specificity prediction with NA-MPNN](https://www.biorxiv.org/content/10.1101/2025.10.03.679414v2) by Andrew Kubaney, et al.
+
+The OFFICIAL repository of NA-MPNN is at [baker-laboratory/NA-MPNN](https://github.com/baker-laboratory/NA-MPNN).
+
+**The team releasing NA-MPNN did not write this model card for this model so this model card has been written by the OFoldX team.**
 
 ## Model Details
 
-NA-MPNN extends fixed-backbone inverse folding to protein, DNA, RNA, and mixed
-polymer assemblies. It represents each polymer residue with a shared geometric
-message-passing graph while constraining sampled identities to the residue's
-polymer type. The same architecture supports joint sequence design, sequence
-scoring, and protein-DNA specificity prediction.
+NA-MPNN extends fixed-backbone inverse folding to protein, DNA, RNA, and mixed-polymer assemblies. A geometric
+message-passing graph represents polymer residues, and generation restricts identities to the residue's polymer type.
+Separate checkpoints support joint sequence design and protein-DNA specificity prediction.
+
+Please refer to the [Training Details](#training-details) section for more information on the training process.
 
 ### Variants
 
-- **[oteam/nampnn](https://huggingface.co/oteam/nampnn)**: Sequence-design model for protein and nucleic-acid assemblies.
+- **[oteam/nampnn](https://huggingface.co/oteam/nampnn)**: Sequence-design model for protein and nucleic-acid
+  assemblies.
 - **[oteam/nampnn-specificity](https://huggingface.co/oteam/nampnn-specificity)**: Protein-DNA specificity model.
 
 ### Model Specification
@@ -45,93 +48,92 @@ scoring, and protein-DNA specificity prediction.
 - **Upstream license**: [MIT and BSD-3-Clause notices](LICENSE)
 - **Upstream source revision**: `aafa32c87b65046a02db152f6e6235a7078e5fef`
 - **Code**: [ofoldx.models.nampnn](https://github.com/OTeam-AI4S/OFoldX/tree/main/ofoldx/models/nampnn)
-- **Paper**: [RNA sequence design and protein-DNA specificity prediction with NA-MPNN](https://www.biorxiv.org/content/10.1101/2025.10.03.679414v2)
-- **Developed by**: Baker Laboratory
+- **Paper**:
+  [RNA sequence design and protein-DNA specificity prediction with NA-MPNN](https://www.biorxiv.org/content/10.1101/2025.10.03.679414v2)
+- **Developed by**: Andrew Kubaney, Andrew Favor, Lilian McHugh, Raktim Mitra, Robert Pecoraro, Justas Dauparas,
+  Cameron Glasscock, and David Baker
 - **Model type**: Autoregressive message-passing neural network for protein and nucleic-acid sequence design
 - **Original Repository**: [baker-laboratory/NA-MPNN](https://github.com/baker-laboratory/NA-MPNN)
 
 ## Usage
 
-The model depends on the [`ofoldx`](https://github.com/OTeam-AI4S/OFoldX)
-library. Install it with pip:
+The model file depends on the [`ofoldx`](https://ofoldx.valhalla.technology/) library. You can install it using pip:
 
 ```bash
 pip install ofoldx
 ```
 
-### Sequence Design
+### Direct Use
 
-Load the concrete design Pipeline:
+#### Sequence Design
+
+You can use this model directly with a pipeline for joint protein and nucleic-acid sequence design:
 
 ```python
 import ofoldx
 from ofoldx.io import read_structure
 
-structure, report = read_structure("complex.cif")
+structure, _ = read_structure("complex.cif")
 pipeline = ofoldx.pipeline("design", model="oteam/nampnn")
-output = pipeline.design(structure)
+result = pipeline(structure)
 ```
 
-The model's token axis is the 72 canonical classes; the 33 classes of the
-released vocabulary keep their upstream logits and every other class has logit
-`-inf`; a residue whose class is outside that vocabulary is read as its type's
-unknown (`X`, `DNA_X`, `RNA_X`), as upstream. With shared nucleic tokens (the
-released default) an RNA residue is read and sampled as the DNA class of its
-base and designed as the RNA residue. `global_omit_tokens` takes canonical class
-names (`"C"`, `"DNA_T"`); under shared nucleic tokens an RNA base is omitted by
-its DNA class (`"DNA_T"` omits U from RNA rows and T from DNA rows) and an
-`RNA_` name is refused.
-Each candidate's final target is built by the shared design producer, and
-`output.records` holds its design record.
+Each candidate contains the designed molecular target and named sequence scores. Shared nucleic tokens are the released
+default: RNA bases use DNA output classes during prediction and are reconstructed as RNA residues.
 
-### Staged Execution and Scoring
+> [!NOTE]
+> With shared nucleic tokens, `global_omit_tokens` uses DNA class names for both DNA and RNA: `"DNA_T"` excludes T and U,
+> respectively. `RNA_` names are rejected in this mode.
 
-The callable design Pipeline uses the same preparation, computation and decoding
-as its explicit stages:
+#### Sequence Scoring
 
-```python
-prepared = pipeline.prepare(structure)
-raw = pipeline.forward(prepared.input, seed=7)
-result = pipeline.postprocess(prepared, raw)
-result = pipeline(structure, seed=7)
-```
-
-Scoring has its own task Pipeline and reuses the same converted weights:
+You can use this model directly with a pipeline for sequence scoring on a mixed-polymer backbone:
 
 ```python
-scorer = ofoldx.pipeline("score", model="oteam/nampnn")
-score = scorer(structure, num_decoding_orders=8, seed=7)
+import ofoldx
+from ofoldx.io import read_structure
+
+structure, _ = read_structure("complex.cif")
+pipeline = ofoldx.pipeline("score", model="oteam/nampnn")
+result = pipeline(structure, num_decoding_orders=8, seed=7)
 ```
 
-For an in-memory model, construct `NaMpnnScorePipeline` with the designer's
-`model` and `processor`. Its `prepare`, `forward` and `postprocess` stages evaluate
-the observed or explicitly supplied sequence without sampling new identities.
+The result contains designed and global sequence NLL in nats per residue.
+
+See the [pipeline guide](https://github.com/OTeam-AI4S/OFoldX/blob/main/ofoldx/pipelines/README.md) for staged execution with `prepare`, `forward`, and `postprocess`.
 
 ## Training Details
 
+NA-MPNN is trained for structure-conditioned recovery of protein and nucleic-acid sequences.
+
 ### Training Data
 
-NA-MPNN was trained on protein, DNA, RNA, and mixed-polymer structures. The
-design and specificity variants target sequence recovery and protein-DNA
-specificity, respectively.
+NA-MPNN was trained on protein, DNA, RNA, and mixed-polymer structures. The design and specificity variants target
+sequence recovery and protein-DNA specificity, respectively.
 
 ### Training Procedure
 
-`NaMpnnModel.forward` supports protein, DNA, and RNA coordinate
-noise and optional protein-first decoding.
-`ofoldx.models.nampnn.objective.smoothed_loss` provides the polymer-specific
-objective. It supports both shared and
-separate DNA/RNA token layouts and the released aligned target-probability rows;
-masking and reduction remain caller-owned. This covers masked polymer
-sequence recovery; it does not reproduce the upstream specificity-training
-dataset or its complete training orchestration.
+NA-MPNN uses polymer-conditioned sequence recovery, with coordinate noise and optional protein-first decoding.
+
+OFoldX exposes differentiable `forward` and the polymer-specific [`smoothed_loss`][ofoldx.models.nampnn.smoothed_loss]
+for masked sequence recovery. Dataset construction, the upstream specificity-training dataset, and complete training
+orchestration remain the training application's responsibility.
 
 ## Citation
 
-Please cite the upstream preprint,
-[RNA sequence design and protein-DNA specificity prediction with NA-MPNN](https://www.biorxiv.org/content/10.1101/2025.10.03.679414v2).
+```bibtex
+@article{kubaney2025nampnn,
+  author = {Kubaney, Andrew and Favor, Andrew and McHugh, Lilian and Mitra, Raktim and Pecoraro, Robert and Dauparas, Justas and Glasscock, Cameron and Baker, David},
+  title = {RNA sequence design and protein-DNA specificity prediction with NA-MPNN},
+  journal = {bioRxiv},
+  year = {2025},
+  doi = {10.1101/2025.10.03.679414},
+}
+```
 
-If OFoldX supports your research, also cite the OFoldX software:
+> [!NOTE]
+> The artifacts distributed in this repository are part of the OFoldX project.
+> If OFoldX supports your research, please cite the OFoldX project as follows:
 
 ```bibtex
 @software{chen2026ofoldx,
@@ -144,8 +146,9 @@ If OFoldX supports your research, also cite the OFoldX software:
 
 ## Contact
 
-Please use [OFoldX GitHub issues](https://github.com/OTeam-AI4S/OFoldX/issues)
-for questions about this implementation or model card.
+Please use GitHub issues of [OFoldX](https://github.com/OTeam-AI4S/OFoldX/issues) for any questions or comments on the model implementation or model card.
+
+Please contact the authors of the [NA-MPNN paper](https://www.biorxiv.org/content/10.1101/2025.10.03.679414v2) for questions or comments on the paper/model.
 
 ## License
 
@@ -158,3 +161,4 @@ For additional terms and clarifications, please refer to our [License FAQ](licen
 SPDX-License-Identifier: AGPL-3.0-or-later
 ```
 
+[ofoldx.models.nampnn.smoothed_loss]: https://ofoldx.valhalla.technology/models/nampnn/#ofoldx.models.nampnn.smoothed_loss