VirFoX

VirFoX is a bimodal predictor for viral host factors. The released model combines ISMC protein representations with STRING/SPACE network embeddings and uses a network-guided Forgetting Transformer to score full-length human proteins without the sequence truncation used in earlier baselines.

This repository is the public release of the VirFoX codebase. It keeps the training and inference pipeline, the processed benchmark splits used in the paper, the retained external-host prediction inputs, and the final released result tables.

Highlights

• Full-length protein modeling with ISMC-300M representations
• Sequence and network feature fusion for host-factor prediction
• Distributed FSDP training, resume, and released inference entry points
• Released benchmark/test outputs and external SARS-CoV and HIV prediction tables

Repository Layout

VirFoX/
├── data/
│   ├── fasta_5fold/           # retained train/val/test FASTA splits used in this study
│   ├── fasta_network/         # network-aligned FASTA resources used in preprocessing
│   ├── network_embeddings/    # required HDF5 network embeddings (add locally)
│   └── new_host/              # released external-host prediction inputs
├── models/                    # released VirFoX checkpoints and optional ISMC weights
├── results/
│   ├── tables/                # released evaluation and prediction tables
│   └── manifests/             # retained SHAP summary statistics
├── scripts/
│   ├── analysis/
│   ├── data_prep/
│   └── eval/
├── src/
├── train.py
├── train_kfold.py
├── train_full.py
└── predict.py

Installation

The repository is managed with pixi.

pixi install

Required Assets

Place the released network embeddings under:

• data/network_embeddings/pos_network_embeddings.h5
• data/network_embeddings/neg_network_embeddings.h5
• data/network_embeddings/can_network_embeddings.h5

Optional ISMC initialization weights:

• ISMC-300M: https://huggingface.co/jozhang97/ismc-300m-2024-12
• place the checkpoint at models/ismc_300m_2024_12_v0.pth

Data

data/ stores model inputs, not result tables.

• data/fasta_5fold/ contains the retained benchmark split used for training, validation, and independent test evaluation.
• data/fasta_network/ contains sequence files aligned to the released network embedding space.
• data/new_host/sars_cov_hosts.fasta and data/new_host/hiv_hosts.fasta are the released FASTA inputs for the external SARS-CoV and HIV analyses.
• data/new_host/41586_2021_3493_MOESM6_ESM.xlsx and data/new_host/mbio.00009-23-st001.csv are optional source tables kept for regenerating those external FASTA sets.

The external host-factor FASTA files are matched subsets of the source tables after filtering by sequence availability and released network features. The retained prediction sets therefore contain fewer entries than the original source lists.

Quick Start

Show the main command-line interfaces:

pixi run predict-help
pixi run evaluate-help

Run inference on a FASTA file:

pixi run predict -- \
  --checkpoint models/virfox_final_model_epoch14.pt \
  --fasta data/fasta_5fold/test/pos.fasta \
  --output predictions.csv

Evaluate a released checkpoint on the retained independent test split:

pixi run evaluate -- models/virfox_final_model_epoch14.pt

Regenerate the retained five-fold FASTA split:

pixi run split-kfold

Regenerate the external-host FASTA inputs from the retained source tables:

pixi run prepare-new-host

Training

Main entry points:

pixi run train
pixi run train-kfold
pixi run train-full

These scripts use PyTorch FSDP training and repository-relative paths for logs, checkpoints, data, and model assets.

Released Results

Released result tables are under results/tables/. The public release keeps the final evaluation and prediction outputs used in the study, including:

• independent test-set evaluation tables
• SARS-CoV and HIV host-factor prediction tables
• final model-comparison summaries
• released SHAP summary tables