DPYD 5-FU Toxicity Prediction

Overview

This repository contains the source code used to generate Nucleotide Transformer v3 (NTv3) embeddings for genomic variants and to train and evaluate an artificial neural network (ANN) for the prediction of variants associated with 5-fluorouracil (5-FU) toxicity.

The analysis consists of two main stages:

1. NTv3 embedding generation — reference and alternate genomic sequences are generated for each variant using the hg38 human genome assembly. NTv3 embeddings are then extracted at the variant position.
2. Model training and evaluation — the difference between the alternate and reference embeddings is calculated (ΔEmbed = REF − ALT) and used as input to an ANN classifier. Model performance is assessed using stratified 10-fold cross-validation on the training dataset, followed by evaluation on predefined validation and blind test datasets.

---

Installation

Python 3.10 is recommended to reproduce the environment used for this analysis.

Clone the repository and create a virtual environment:

git clone <REPOSITORY_URL>
cd DPYD-5FU

python -m venv .venv
source .venv/bin/activate

On Windows:

.venv\Scripts\activate

Install the required Python dependencies:

python -m pip install --upgrade pip
pip install -r requirements.txt

GPU acceleration is strongly recommended for generating the NTv3 embeddings.

---

Input data

Place the input variant metadata file in the data/ directory. By default, the embedding-generation workflow uses:

data/Final_DPYD_variant_data_REF_ALT_NT3_pre_train_embed.csv

At minimum, the following columns are required for NTv3 embedding generation:

Column	Description
POS	1-based genomic position
REF	Reference allele
ALT	Alternate allele

The model-training workflow additionally requires:

Column	Description
Label	Binary class label (0 or 1)
Dataset	Dataset assignment: Training, Validation, or Test

See data/README.md for additional information on the input data.

---

Running the analysis

Option 1: Jupyter notebooks

Start JupyterLab from the repository root:

jupyter lab

Run the notebooks in the following order:

notebooks/01_generate_NTv3_embeddings.ipynb
notebooks/02_train_evaluate_ANN.ipynb

Option 2: Python scripts

From the repository root, generate the NTv3 embeddings using:

python src/generate_NTv3_embeddings.py

The ANN can then be trained and evaluated using:

python src/train_ANN.py

Command-line options for each script can be viewed using:

python src/generate_NTv3_embeddings.py --help
python src/train_ANN.py --help

---

Default embedding outputs

The embedding-generation workflow produces the following files:

results/Final_DPYD_variant_ALL_NTv3_data.csv
results/DPYD_NTv3_post_train_embeddings.npz
results/NTv3_post_train_checkpoint.jsonl

The .npz file contains the reference, alternate, and difference embeddings:

REF_NT3_post_train_embed
ALT_NT3_post_train_embed
delta_post_train_embed

The checkpoint file allows an interrupted embedding-generation run to resume without recomputing variants that were successfully completed. The checkpoint should not be reused with a different input dataset or after changing the order of the variants.

---

Default model-training outputs

The model-training workflow saves its outputs to:

results/model_training/

The following files are generated:

ANN_10fold_CV_results.csv
ANN_10fold_CV_summary.csv
ANN_validation_test_results.csv
ANN_validation_predictions.csv
ANN_test_predictions.csv
ANN_training_history.csv
ANN_final_model.keras
ANN_model_config.json
ANN_environment.json

These files contain the individual and summarized 10-fold cross-validation results, validation and test set performance, model predictions, training history, final trained ANN, model configuration, and software environment information.

See results/README.md for additional descriptions of these output files.

---

NTv3 model access

The analysis uses the InstaDeepAI/NTv3_650M_post model through Hugging Face with trust_remote_code=True.

Users are responsible for satisfying any access requirements and license terms associated with the NTv3 model and its weights. The license applied to the source code in this repository does not supersede or modify the license associated with the NTv3 model.

---

Contact

Adam Serghini
University of Calgary
adam.serghini@ucalgary.ca