Machine Learning Immunogenicity and Vaccine Response Analysis

Used for analyzing immune responses and predicting vaccine efficacy using machine learning and advanced data processing techniques. 'Immunaut' integrates both unsupervised and supervised learning methods, managing outliers and capturing immune response variability. It performs multiple rounds of predictive model testing to identify robust immunogenicity signatures that can predict vaccine responsiveness. The platform is designed to handle high-dimensional immune data, enabling researchers to uncover immune predictors and refine personalized vaccination strategies across diverse populations.

immunaut

Ivan Tomic [email protected]

Installation

You can install the released version of immunaut from CRAN with:

install.packages("immunaut")

Or you can install immunaut directly from GitHub with use of following commands:

# install.packages("devtools")
devtools::install_github("atomiclaboratory/immunaut", subdir = 'R-package')

Initial setup

library("immunaut")

# Generate a demo dataset with 1000 subjects, 200 features, 4 clusters, and a 10% probability of missing values
dataset <- generate_demo_data(n_subjects = 1000, n_features = 200, 
                                desired_number_clusters = 4, # Approximate number of clusters
                                cluster_overlap_sd = 35, # Standard deviation for cluster overlap
                                missing_prob = 0.1) # Probability of missing values

# Generate a file header for the dataset to use in downstream analysis
file_header <- generate_file_header(dataset)

settings <- list(
    fileHeader = file_header,
    seed = 1337,
    selectedColumns = colnames(dataset),  # Columns selected for analysis
    # Exclude outcome, age, and gender columns from the analysis
    excludedColumns = c("outcome", "age", "gender"),
    removeNA = TRUE,
    
    # Clustering parameters
    clusterType = "Louvain",
    target_clusters_range = c(3, 4),
    resolution_increments = c(0.1, 0.2, 0.3),
    min_modularities = c(0.4, 0.5, 0.6),
    pickBestClusterMethod = "Overall",  # "Overall", "Modularity", or "Silhouette"
    
    # Preprocessing and Machine Learning settings
    outcome = "immunaut",
    preProcessDataset = c("scale", "center", "medianImpute", "zv"),
    selectedPartitionSplit = 0.7,  # 70% train, 30% test (strictly isolated)
    selectedPackages = c("rpart"),
    trainingTimeout = 180,
    num_cores = 1
)

Example 1: Perform t-SNE, Louvain Clustering, and Machine Learning

# Perform t-SNE and clustering using the 'immunaut' function
result <- immunaut(dataset, settings)

# Plot the clustered t-SNE results using ggplot2
p <- plot_clustered_tsne(result$tsne_clust$info.norm, 
                         result$tsne_clust$cluster_data, 
                         result$settings) 
print(p) # Display the plot

# Machine Learning with Complete Data Isolation:
# 'dataset_ml' contains the dataset with the 'immunaut' cluster assignment column attached.
dataset_ml <- result$dataset$dataset_ml

# auto_simon_ml() partitions the dataset into train/test sets BEFORE preprocessing,
# ensuring zero data leakage between training and testing sets.
model_results <- auto_simon_ml(dataset_ml, settings)

# Inspect model performance on the isolated test partition
for (model_name in names(model_results$models)) {
  m <- model_results$models[[model_name]]
  cat("Model:", model_name, "\n")
  cat("  Accuracy:     ", round(m$predictions$postResample["Accuracy"], 3), "\n")
  cat("  Macro F1:     ", round(m$predictions$macroF1, 3), "\n")
  cat("  AUROC:        ", round(m$predictions$AUROC, 3), "\n")
  cat("  Weighted AUROC:", round(m$predictions$weightedAUROC, 3), "\n")
}

# The fitted preprocessing parameters are preserved for external cohort validation:
print(model_results$preProcessParams)

Example 2: Switch to DBSCAN Clustering

# Update settings for DBSCAN clustering
settings$clusterType <- "Density"
settings$minPtsAdjustmentFactor <- 1.5
settings$epsQuantile <- 0.9

# Run t-SNE and DBSCAN clustering
dbscan_result <- immunaut(dataset, settings)

Example 3: Perform Mclust Clustering

# Update settings for Mclust clustering
settings$clusterType <- "Mclust"
settings$clustGroups <- 3  # Specify the number of clusters for Mclust

# Run t-SNE and Mclust clustering
mclust_result <- immunaut(dataset, settings)
#> [1] "==> cluster_tsne_mclust clustGroups:  3"

Example 4: Perform Hierarchical Clustering

# Update settings for Hierarchical clustering
settings$clusterType <- "Hierarchical"
settings$clustLinkage <- "ward.D2"
settings$clustGroups <- 3

# Run t-SNE and Mclust clustering
hierarchical_result <- immunaut(dataset, settings)

Example 5: Visualize High-Dimensional Feature Space with PCA

# Perform PCA on preprocessed numeric features
feature_cols <- grep("^Feature", names(result$dataset$preprocessed), value = TRUE)
pca_res <- prcomp(result$dataset$preprocessed[, feature_cols], center = TRUE, scale. = TRUE)

pca_df <- data.frame(
  PC1 = pca_res$x[, 1],
  PC2 = pca_res$x[, 2],
  Cluster = factor(result$clusters)
)

library(ggplot2)
ggplot(pca_df, aes(x = PC1, y = PC2, color = Cluster)) +
  geom_point(alpha = 0.7, size = 2.5) +
  stat_ellipse(level = 0.8) +
  scale_color_brewer(palette = "Set1") +
  labs(
    title = "PCA of Clustered Cohort",
    x = "Principal Component 1",
    y = "Principal Component 2",
    color = "Cluster"
  ) +
  theme_classic()

Example 6: Using Pediatric LAIV Vaccination Dataset

library(immunaut)
library(ggplot2)

data("immunautLAIV")


file_header <- generate_file_header(immunautLAIV)

# Base settings (shared across all runs unless overridden):
settings <- list()
settings$fileHeader <- file_header

settings$selectedColumns <- c(
  "H1_HAI_FC","H3_HAI_FC","B_HAI_FC","H1N1_NA_FC","H3_HA_IgA_FC",
  "B_HA_IgA_FC","B_NA_IgA_FC","H1_CD8_IFNg_FC","H3_CD8_IFNg_FC",
  "H3_CD8_IL2_FC","HAB_CD8_IFNg_FC","HAB_CD8_IL2_FC","NC99_H1_FC",
  "SWISS_H3_FC","HK14_H3_FC","KAN_H3_FC","B_PHU_FC","cH7_IgA_FC",
  "N2_FC","cH6_FC"
)
settings$groupingVariables <- c(
  "max_HAI_responder","max_iga_responder","max_mnp_cd4_responder",
  "max_mnp_cd8_responder","year","sex","v0_resp_virus_positive",
  "h1_v2_shed","h3_v2_shed","b_v2_shed","h1_v7_shed","h3_v7_shed",
  "b_v7_shed","h1_v0_seropositive","h3_v0_seropositive","b_v0_seropositive"
)


settings$preProcessDataset <- c("medianImpute","center","scale","corr","nzv","zv")

result <- immunaut(immunautLAIV, settings)

p <- plot_clustered_tsne(result$tsne_clust$info.norm, 
                                result$tsne_clust$cluster_data, 
                                result$settings) 
# Adjust the plot: use Set2 palette and a nice minimal theme
p <- p +
  scale_color_brewer(palette = "Set2") +
  theme_minimal(base_size = 12) +
  labs(
    title    = "Clustered t-SNE of Pediatric LAIV Data",
    subtitle = "Comprehensive Immune Response Dataset (244 Children)",
    color    = "Cluster"
  )

print(p)