Update README.md

README.md

@@ -1,3 +1,120 @@
 ---
 license: cc-by-nc-4.0
 ---
+
+# BioXMol — molecular encoder
+
+BioXMol is a graph neural network that turns a molecule (SMILES) into a fixed-length
+embedding. Unlike a structure-only encoder, it was trained with **soft contrastive
+learning** to align molecular structure with biological readouts (Cell Painting
+morphology from JUMP-CP and L1000 transcriptomics), using a momentum (EMA) teacher.
+The result is a structure encoder whose embeddings carry biological signal, intended
+for downstream tasks such as drug-induced liver injury (DILI) prediction.
+
+This repository ships the **molecule branch only**. The biological encoders are used
+during pretraining; at inference you provide only SMILES.
+
+> **Note on usage.** This is a custom Gated-GNN, not a `transformers` model, so it is
+> **not** loadable with `AutoModel.from_pretrained`. Use the lightweight code below,
+> which depends only on `torch` and `rdkit`.
+
+## Files
+
+- `bioxmol_soft_seed{0,1,2}.safetensors` — encoder weights, one per training seed
+- `modeling_bioxmol.py` — self-contained model definition
+- `featurizer.py` — SMILES → graph featurizer (`smiles2graph`)
+- `requirements.txt`
+
+## Installation
+
+```bash
+pip install torch rdkit safetensors huggingface_hub numpy
+```
+
+## Usage
+
+```python
+import torch
+from huggingface_hub import hf_hub_download
+from safetensors.torch import load_file
+from modeling_bioxmol import GatedGraphNeuralNetwork
+from featurizer import smiles2graph
+
+REPO = "arslanmasood/BioXMol"
+
+def load_encoder(seed: int = 0):
+    model = GatedGraphNeuralNetwork(n_edge=1, in_dim=75, n_conv=6, fc_dims=[1024, 128])
+    weights = hf_hub_download(REPO, f"bioxmol_soft_seed{seed}.safetensors")
+    model.load_state_dict(load_file(weights))
+    model.eval()
+    return model
+
+def featurize_batch(smiles_list):
+    graphs = [smiles2graph(s) for s in smiles_list]      # each -> (adj, node_feat)
+    n = max(nf.shape[0] for _, nf in graphs)             # pad to largest molecule
+    adjs, feats, masks = [], [], []
+    for adj, nf in graphs:
+        adj = torch.as_tensor(adj, dtype=torch.float)
+        nf = torch.as_tensor(nf, dtype=torch.float)
+        a = torch.zeros(n, n);            a[:adj.shape[0], :adj.shape[1]] = adj
+        f = torch.zeros(n, nf.shape[1]);  f[:nf.shape[0]] = nf
+        m = torch.zeros(n, 1);            m[:nf.shape[0]] = 1.0     # 1 = real atom
+        adjs.append(a); feats.append(f); masks.append(m)
+    return torch.stack(adjs), torch.stack(feats), torch.stack(masks)
+
+@torch.no_grad()
+def encode(smiles_list, layer="first_fc", seed=0):
+    """layer in {'GNN' (75-d), 'first_fc' (1024-d), 'second_fc' (128-d)}."""
+    model = load_encoder(seed)
+    adj, node_feat, atom_vec = featurize_batch(smiles_list)
+    return model.embed(adj, node_feat, atom_vec, layer=layer)
+
+emb = encode(["CC(=O)Oc1ccccc1C(=O)O", "CN1C=NC2=C1C(=O)N(C(=O)N2C)C"])
+print(emb.shape)   # (2, 1024) for first_fc
+```
+
+## Which embedding to use
+
+| `layer` | Dim | What it is |
+|---|---|---|
+| `GNN` | 75 | sum-pooled node features |
+| `first_fc` | 1024 | hidden representation (recommended default for general reuse) |
+| `second_fc` | 128 | contrastive projection head |
+
+Standardize SMILES the same way the model was pretrained before featurizing, otherwise
+embeddings will be off-distribution.
+
+## Training data
+
+- **JUMP-CP** (Cell Painting morphological profiles) and **LINCS L1000** (transcriptomic
+  signatures) — used for soft-contrastive pretraining.
+- **DILIRank 2.0** — used for downstream evaluation.
+
+Each dataset is governed by its own terms; consult them before redistributing
+derived artifacts.
+
+## Evaluation
+
+Evaluated on DILIRank 2.0, with emphasis on **activity-cliff** ranking (structurally
+similar drug pairs with divergent toxicity), where representation quality is most
+visible. Results vary across seeds; report the per-seed range rather than a single
+peak when citing this model. Standard cross-validation metrics do not separate the
+methods, which is the expected behaviour for this benchmark.
+
+## License
+
+Released under **CC-BY-NC-4.0** (attribution, non-commercial). The associated training
+code inherits **GPLv3** from the upstream framework and is distributed separately.
+A patent application covering the method has been filed; non-commercial research use
+is permitted under this license.
+
+## Citation
+
+```bibtex
+@misc{bioxmol,
+  title  = {BioXMol: multimodal soft-contrastive molecular representations},
+  author = {Masood, Arslan and others},
+  year   = {2026},
+  note   = {Manuscript in preparation}
+}
+```