Create README.md

README.md

@@ -0,0 +1,121 @@
+---
+library_name: transformers
+base_model: duttaprat/HViLM-base
+datasets:
+  - duttaprat/HVUE-v2
+pipeline_tag: text-classification
+tags:
+  - genomics
+  - virology
+  - dna
+  - virus
+  - host-tropism
+  - hvue-v2
+license: apache-2.0
+---
+
+# HViLM-Tropism
+
+**HViLM-Tropism** is the official HViLM model for binary host tropism classification: human-tropic versus non-human-tropic viruses.
+
+- **Fine-tuned from:** [duttaprat/HViLM-base](https://huggingface.co/duttaprat/HViLM-base)
+- **Benchmark:** [duttaprat/HVUE-v2](https://huggingface.co/datasets/duttaprat/HVUE-v2)
+- **HVUE v2 configuration:** `Host_Tropism/standard_95_1000bp`
+- **Checkpoint selection:** best validation F1 (`checkpoint-14000`)
+- **Input:** virus nucleotide sequence
+- **Output:** non-human-tropic vs. human-tropic
+
+This repository contains a **standalone full fine-tuned checkpoint**, so users can load `duttaprat/HViLM-Tropism` directly without separately loading `HViLM-base`.
+
+## Label Mapping
+
+| ID | Label |
+|---:|---|
+| 0 | `NON_HUMAN_TROPIC` |
+| 1 | `HUMAN_TROPIC` |
+
+## Performance
+
+Held-out HVUE v2 test set, standard 1000-nt configuration:
+
+| Metric | Score |
+|---|---:|
+| Accuracy | 96.49 |
+| F1 | 74.49 |
+| MCC | 48.99 |
+| Precision | 74.96 |
+| Recall | 74.04 |
+
+## Class Imbalance
+
+The HVUE v2 Host Tropism benchmark is strongly imbalanced. Accuracy should therefore be interpreted together with F1 and MCC. HViLM retains substantially stronger minority-class discrimination than vanilla DNABERT-2 trained on the same imbalanced setting and avoids majority-class collapse without explicit class balancing.
+
+## Training Details
+
+- **Fine-tuning method:** LoRA
+- **LoRA rank:** 8
+- **LoRA alpha:** 16
+- **Target modules:** query and value projections across all 12 transformer layers
+- **Approximate trainable LoRA parameters:** ~0.3M
+- **Learning rate:** 3e-5
+- **Maximum input length:** 250 BPE tokens (approximately 1000 nt)
+- **Early stopping:** patience 3, monitored using validation F1
+- **Hardware:** NVIDIA A40 GPU
+
+The released repository contains the full task-specific model weights rather than only the LoRA adapter.
+
+## Usage
+
+```python
+import torch
+from transformers import AutoTokenizer, AutoModelForSequenceClassification
+
+model_id = "duttaprat/HViLM-Tropism"
+
+tokenizer = AutoTokenizer.from_pretrained(model_id, trust_remote_code=True)
+model = AutoModelForSequenceClassification.from_pretrained(
+    model_id,
+    trust_remote_code=True,
+)
+
+sequence = "ATGCGTACGTTAGCCGATCGATTACGCGTACGTAGCTAGC"
+inputs = tokenizer(
+    sequence,
+    return_tensors="pt",
+    truncation=True,
+    max_length=250,
+)
+
+with torch.no_grad():
+    logits = model(**inputs).logits
+
+prediction_id = logits.argmax(dim=-1).item()
+print(model.config.id2label[prediction_id])
+```
+
+Possible outputs are `NON_HUMAN_TROPIC` and `HUMAN_TROPIC`.
+
+## Intended Use
+
+HViLM-Tropism is intended for research and benchmarking of virus sequence-based host association prediction. Host association is biologically context-dependent and may include multi-host, zoonotic, and reverse-zoonotic relationships; predictions should not be interpreted as definitive evidence of host range.
+
+## Related Resources
+
+- [HViLM-base](https://huggingface.co/duttaprat/HViLM-base)
+- [HViLM-Patho](https://huggingface.co/duttaprat/HViLM-Patho)
+- [HViLM-R0](https://huggingface.co/duttaprat/HViLM-R0)
+- [HVUE-v2](https://huggingface.co/datasets/duttaprat/HVUE-v2)
+- [HViLM GitHub repository](https://github.com/duttaprat/HViLM)
+
+## Citation
+
+```bibtex
+@article{dutta2026hvilm,
+  title={HViLM: A foundation model for viral genomics enables multi-task prediction of pathogenicity, transmissibility, and host tropism},
+  author={Dutta, Pratik and Vaska, Jack and Surana, Pallavi and Sathian, Rekha and Chao, Max and Zhou, Zhihan and Liu, Han and Davuluri, Ramana V},
+  journal={bioRxiv},
+  pages={2026--03},
+  year={2026},
+  publisher={Cold Spring Harbor Laboratory}
+}
+```