OncoEvoFM

OncoEvoFM is a pretrained transformer that turns somatic mutations and optional copy-number alterations into sample-level embeddings. This release contains the full 48.5-million-parameter checkpoint and frozen feature assets. The Python implementation is provided by the separate oncoevofm package.

The model uses 12 transformer layers with a hidden size of 512 and a 64-dimensional clonal bottleneck. All original task heads are retained.

Setup

Requires Python 3.12 or 3.13 and oncoevofm (tested version: 0.1.1).

python -m pip install "git+https://github.com/amlopeza/OncoEvoFM.git"

Demo

This complete example uses the Transformers API. The installed oncoevofm package must be imported to register the custom model and processor.

Set MODEL_ID to a local model directory containing the complete release, or to its published Hugging Face repository ID. A Hub ID automatically downloads and caches the required model files.

import torch
import oncoevofm  # Registers the custom classes with Transformers.
from transformers import AutoModel, AutoProcessor

MODEL_ID = "."  # Or "owner/OncoEvoFM" for a published Hugging Face repository.
model = AutoModel.from_pretrained(MODEL_ID, trust_remote_code=False).eval()
processor = AutoProcessor.from_pretrained(MODEL_ID, trust_remote_code=False)

samples = [{
    "mutations": [{
        "gene": "KRAS",
        "chromosome": "12",
        "start": 25398285,
        "variant_classification": "Missense_Mutation",
        "variant_type": "SNP",
        "consequence": "missense_variant",
        "hgvsp": "p.G12C",
        "t_alt_count": 180,
        "t_ref_count": 250,
    }],
    # Optional copy-number segments:
    # "cna": [{"chromosome": "9", "start": 21900000, "seg_mean": -1.8}],
}]

inputs = processor(samples).to(model.device)
with torch.inference_mode():
    embeddings = model(**inputs)

print(embeddings["e_patient"].shape)         # torch.Size([1, 512])
print(embeddings["e_clonal"].shape)          # torch.Size([1, 512])
print(embeddings["z_clonal"].shape)          # torch.Size([1, 64])
print(embeddings["e_process"].shape)         # torch.Size([1, 512])
print(embeddings["e_lineage"].shape)         # torch.Size([1, 512])
print(embeddings["e_assay"].shape)           # torch.Size([1, 512])
print(embeddings["pathway_states"].shape)    # torch.Size([1, 16, 512])
print(embeddings["last_hidden_state"].shape) # torch.Size([1, 1, 512])
print(embeddings["z_mu"].shape)              # torch.Size([1, 64])
print(embeddings["z_logvar"].shape)          # torch.Size([1, 64])

# Remove padding to obtain one event-embedding tensor per sample.
event_embeddings = [
    states[mask]
    for states, mask in zip(embeddings["last_hidden_state"], inputs["pad_mask"])
]
print(event_embeddings[0].shape)  # torch.Size([1, 512])

Each sample contains a mutations list and an optional cna list. Genomic coordinates use GRCh37/hg19. VAF and depth can be derived from alternate and reference read counts. The processor preserves sample order and loads the frozen feature assets automatically.

The demo disables dropout with eval() and gradients with torch.inference_mode(). Outputs stay on the model device; use .cpu().numpy() to convert a tensor to a NumPy array. With a compatible GPU runtime, call model.to("cuda") before processing the samples.

Embedding outputs

The forward call returns the following named tensors:

Output Shape for B samples Description
e_patient B × 512 Patient summary
e_clonal B × 512 Clonal summary before the bottleneck
z_clonal B × 64 Clonal latent; equals z_mu in evaluation mode
e_process B × 512 Process summary
e_lineage B × 512 Lineage summary
e_assay B × 512 Assay summary
pathway_states B × 16 × 512 Learned pathway/register-token states
last_hidden_state B × S × 512 Event states padded to the batch event-token count S
z_mu B × 64 Clonal latent mean
z_logvar B × 64 Clonal latent log-variance

The demo also constructs event_embeddings: a list of B unpadded tensors, each Nᵢ × 512, using inputs["pad_mask"]. Nᵢ is the number of encoded event tokens in sample i. These names describe training roles; they do not guarantee isolated biological factors.

AACR Project GENIE acknowledgment

OncoEvoFM training used AACR Project GENIE version 19.0-public.

We thank the American Association for Cancer Research for the funding and material resources supporting the AACR Project GENIE registry. We also thank the consortium members for contributing and sharing their data. The OncoEvoFM authors are responsible for the analyses and interpretations presented here.

Citation: The AACR Project GENIE Consortium. AACR Project GENIE: Powering Precision Medicine through an International Consortium. Cancer Discovery. 2017;7(8):818–831.

License

The OncoEvoFM model weights (model.safetensors) are licensed under Creative Commons Attribution 4.0 International (CC BY 4.0).

Commercial use, modification, fine-tuning, and redistribution are permitted under the license. When sharing the weights or modified versions, give appropriate attribution, retain supplied notices, link to the license, and indicate any changes. Do not impose additional legal or technical restrictions on the rights granted by the license.

There is no requirement to contribute improvements back to this project or publicly release modified weights. This license notice covers the model weights; the separately distributed oncoevofm code and training datasets remain subject to their own applicable terms.

See the full license terms.

Downloads last month
27
Safetensors
Model size
48.5M params
Tensor type
F32
·
Inference Providers NEW
This model isn't deployed by any Inference Provider. 🙋 Ask for provider support