Glycan property prediction is an increasingly popular area of machine learning research. Supervised learning approaches have shown promise in glycan modeling; however, the current literature is fragmented regarding datasets and standardized evaluation techniques, hampering progress in understanding these complex, branched carbohydrates that play crucial roles in biological processes. To facilitate progress, we introduce GlycoGym, a comprehensive benchmark suite containing seven biologically relevant supervised learning tasks spanning different domains of glycobiology: glycosylation linkage identification, tissue expression prediction, taxonomy classification, tandem mass spectrometry fragmentation prediction, lectin-glycan interaction modeling, structural property estimation, and nuclear magnetic resonance shift prediction. We additionally publish GlyVerse, a corpus for self-supervised pre-training. We curate tasks into specific training, validation, and test splits using multi-class stratification to ensure that each task tests biologically relevant generalization that transfers to real-life glycan property prediction scenarios. GlycoGym will help the machine learning community to focus their efforts on scientifically relevant glycan prediction problems.

Installation

You can install GlycoGym via pip:

pip install glycogym

Usage

The main intention of this package is to build the benchmark for the upload to Zenodo, everytime the datasets with glycowork or GlyContact get significantly updated.

But one can also use it to build local versions of the benchmark during the update cycles of the Zenodo repository.

from glycogym import build_glycosylation, build_taxonomy, build_tissue, build_lgi

df, mapping = build_glycosylation()
df_taxonomy = build_taxonomy("Kingdom")
df_tissue = build_tissue()
df_r, df_cl, df_cg = build_lgi()

Every builder accepts seed (default 42) and top_k. Pass top_k for a fast smoke test, and keep seed fixed to reproduce the published splits exactly.

Tandem Mass Spectrometry Fragmentation Prediction

One special dataset is the MS fragmentation prediction dataset, which can be built as follows:

from glycogym import build_spectrum

df_ms = build_spectrum(root="path/to/folder/with/pkl/files")

Here, the root argument defined the path to the folder containing the .pkl files comprising the MS fragmentation prediction dataset by CandyCrunch, which can be downloaded from here.

NMR Shift Prediction

Unlike the other tasks, the NMR dataset ships with the package as a 2 MB parquet, so no download is needed:

from glycogym import load_nmr, nmr_baselines

df_nmr = load_nmr()
print(nmr_baselines(df_nmr))

The result is one row per atom, with shift_ppm as the target and the isotope given by element (H for 1H, C for 13C) rather than by a separate column; unmeasured atoms and all non-C/H elements are dropped. Splits are assigned per glycan, not per structure, so all structures of a glycan share a split, and are stratified over {experimental, simulated, both} to preserve the origin ratio. 200,308 atoms over 2,067 glycans and 2,497 structures.

To regenerate the bundle after an upstream update, download the raw GlycoNMR release of Chen et al. and rebuild:

from glycogym import build_nmr, export_nmr

export_nmr(build_nmr(root="path/to/GlycoNMR"))

root must contain GlycoNMR.Exp_processed/, GlycoNMR.Sim_processed/, and GODESS_Chemical_formula.csv. Note that 110 of the 299 experimental files are named by DrugBank accession rather than by sequence and are currently dropped; resolving them would recover about a third of the experimental half.

To convert the result into PyG data objects, rename IUPAC to clean_glycan and pass it to glycontact.learning.nmr_df_to_training_data.

Structural Property Estimation

The second dataset that requires special handling is the structural property estimation dataset. Currently, it needs to be build from the GlyContact package. That can be installed with the following command:

pip install glycontact[ml]

Then, the dataset can be built as follows:

from glycontact.learning import create_dataset

train, val, test = create_dataset(splits=[0.7, 0.2, 0.1])

Zenodo

The latest version of the GlycoGym benchmark can be found on Zenodo: https://doi.org/10.5281/zenodo.17313055

Citation

tbd