Navigating FACET Model Weights and Protein Backbone Torsion Prediction

Decoding Protein Backbone Torsion From NMR Chemical Shifts

Nuclear magnetic resonance spectroscopy provides atomic-resolution insights into protein structure, but translating raw chemical shifts into backbone torsion angles remains a persistent computational bottleneck. Traditional prediction engines relied heavily on database lookup heuristics, which often struggled when experimental assignments were incomplete, noisy, or derived from flexible loop regions. FACET approaches this challenge by pairing a PyTorch encoder with a dense retrieval index, mapping NMR chemical shifts directly to phi and psi dihedral angles GitHub maxzinke/facet-nmr.

Getting these models into production required navigating distribution constraints that catch many scientific Python packages off guard. When artifact sizes outpace standard packaging limits, elegant engineering choices are required to maintain a seamless developer experience.

Why Model Weights Live on Hugging Face

Python packaging has strict physical boundaries. PyPI enforces a rigid 100 MB per-file upload limit, making it impossible to bundle large machine learning artifacts directly inside a standard distribution wheel Hugging Face facet-weights. FACET’s core retrieval index, facet_retrieval_index.npz, clocks in at 132.6 MB.

Rather than compromising on index density or splitting files into awkward multi-part archives, the maintainers decoupled the weights entirely from the Python package. When you install the package via pip, the code distribution stays lean and fast. On first execution, facet/assets.py automatically pulls the necessary parameter files down into ~/.facet/, verifying each download against a pinned SHA-256 hash Hugging Face facet-weights. Hosting the index separately on Hugging Face under DOI 10.57967/hf/10248 also means that corrected Biological Magnetic Resonance Bank (BMRB) reference entries and retrained model weights can propagate to users instantly without forcing a complete PyPI package release Hugging Face facet-weights.

Inside the FACET Weight Files and Retrieval Index

The repository on Hugging Face (SiXa18/facet-weights) houses five distinct artifacts that partition the model's parametric and non-parametric components Hugging Face facet-weights:

• facet_v3.pt (5.2 MB): The PyTorch encoder weights powering the neural prediction head.
• facet_v3.onnx (5.2 MB): An ONNX export of the same encoder for runtime flexibility and deployment across non-Python environments.
• facet_retrieval_index.npz (132.6 MB): The massive vector index containing 254,000 residue embeddings paired with ground-truth phi/psi angles and experimental labels.
• facet_retrieval_index.entries.json (2.0 MB): Metadata tracking per-row source identifiers to ensure provenance traceability.
• facet_shift_reference.npz (9.6 MB): An optional mask-safe retrieval reference; if omitted, the pipeline gracefully degrades to the parametric encoder head.

Every file is licensed under CC BY 4.0, ensuring open access for academic research and commercial drug discovery pipelines alike provided proper attribution is maintained Hugging Face facet-weights.

Benchmark Performance and Coordinate Pipeline Corrections

Evaluating backbone torsion predictors requires rigorous cross-validation to prevent data leakage. The benchmark suite for FACET evaluates 745 proteins held out via sequence-similarity clustering, scoring predictions against deposited structures corrected for coordinate pipeline errors GitHub maxzinke/facet-nmr. During preparation of version 0.4.0, the maintainers discovered that every single-model X-ray structure in the evaluation pipeline had its phi and psi angles converted to radians twice—affecting 11.7% of training targets and the benchmark ground truth of 63 entries GitHub maxzinke/facet-nmr.

Once the ground truth was repaired, validated against PDB files with a median deviation of just 0.02°, and the model was retrained, the resulting benchmark figures highlighted clear performance gains GitHub maxzinke/facet-nmr. Across 54,260 residues predicted by both systems, FACET achieves a median phi/psi error of 10.91°, compared to TALOS-N's 11.58° GitHub maxzinke/facet-nmr.

More importantly, FACET emits valid predictions for 100% of the 55,032 total residues in the test set, whereas TALOS-N covers 98.6% GitHub maxzinke/facet-nmr. Head-to-head comparisons show FACET winning 53.8% of individual residue evaluations GitHub maxzinke/facet-nmr. Error reductions hold steady across secondary structure classifications, dropping from 7.4° to 7.0° in helices, 13.6° to 12.8° in strands, and 19.3° to 18.0° in coils GitHub maxzinke/facet-nmr.

Confidence Tiers and Handling Incomplete Assignments

Raw angle numbers are useless without reliability metrics in structural biology. FACET categorizes outputs into four distinct confidence tiers during inference GitHub maxzinke/facet-nmr:

1. High: Comprising 76.3% of predictions with a 9.3° median error and 9.9% error rate above 25°. These are written directly to restraint files with a ±20° window GitHub maxzinke/facet-nmr.
2. Medium: Accounting for 15.8% of data with a 19.9° median error and 40.2% error rate above 25°, included via --include-medium with a ±35° restraint window GitHub maxzinke/facet-nmr.
3. Low: Representing 3.2% of predictions with a 59.8° error and 67.8% rate above 25°; excluded from structural restraints GitHub maxzinke/facet-nmr.
4. Flexible: Holding 4.6% share with a 20.8° median error and 43.0% rate above 25° GitHub maxzinke/facet-nmr.

Flexible classifications are particularly revealing. Rather than representing model failure, this tier flags residues where retrieved neighbors do not cluster tightly—the exact computational signature of conformational averaging in chemical shift space GitHub maxzinke/facet-nmr.

The pipeline also handles missing assignments gracefully. For instance, 75 proteins in the benchmark lack alpha-proton (HA) shifts entirely due to perdeuteration or selective labeling schemes GitHub maxzinke/facet-nmr. On those 7,824 sparse residues, FACET records a 9.6° median error versus TALOS-N's 10.3°, proving that the retrieval-augmented architecture absorbs missing input dimensions without breaking down GitHub maxzinke/facet-nmr. Furthermore, testing an opt-in mask-safe fallback (--mask-safe-fallback) revealed that forcing fallback paths actually degraded performance on real data, validating the default encoder-retrieval routing GitHub maxzinke/facet-nmr.

Practical Integration and Deterministic Asset Verification

Using FACET in a local environment requires minimal boilerplate. You install the package via pip and run predictions directly from chemical shift tables, NMRPipe/TALOS input formats, CSV files, NEF, or NMR-STAR entries GitHub maxzinke/facet-nmr:

facet predict shifts.tab --all

Behind the scenes, asset resolution is entirely deterministic. Environment variables like $FACET_HOME allow custom storage paths, while setting FACET_NO_DOWNLOAD=1 locks down execution in air-gapped clusters where automatic remote fetches are prohibited GitHub maxzinke/facet-nmr. By separating heavy model weights from executable logic while maintaining cryptographic verification on every downloaded file, FACET provides a robust, transparent blueprint for distributing heavy structural biology models in the Python ecosystem.