Design-Kernel Group Embedding (DKGE) turns subject-level GLM outputs into a shared, design-aware latent space. It preserves the structure of experimental designs, supports cross-validated contrasts, and provides transport utilities for mapping parcellated fields onto common anchor or voxel representations.
Key capabilities
- Flexible design kernels – encode factorial structure, smoothness, and interactions to control how effects align across subjects.
- Robust contrasts and inference – LOSO/K-fold cross-fitting, analytic approximations, and bootstrap utilities for medoid or voxel maps.
- Transport & rendering – barycentric kNN and C++-accelerated Sinkhorn mappers with warm starts, anchor graph smoothing, and voxel decoders.
- Classifier localisation – cross-fitted latent classifiers with decoder, Haufe, and LOCO maps for bias-aware whole-brain interpretation.
- Component interpretability – convenience helpers for projecting new data, rotating components, and summarising variance explained.
Installation
# install.packages("remotes")
remotes::install_github("bbuchsbaum/dkge")The package depends on RcppArmadillo, future, multivarious, and other CRAN libraries; these install automatically.
Getting started
library(dkge)
# simulate three subjects with four effects and five clusters
set.seed(1)
betas <- replicate(3, matrix(rnorm(4 * 5), 4, 5), simplify = FALSE)
designs <- replicate(3, qr.Q(qr(matrix(rnorm(60 * 4), 60, 4))), simplify = FALSE)
# fit DKGE with an identity kernel and rank 2
fit <- dkge(betas, designs, kernel = diag(4), rank = 2)
# project subjects into component space
scores <- dkge_project_btil(fit, fit$Btil)
str(scores, max.level = 1)See the vignettes for full workflows:
Helper constructors
DKGE now provides small helper constructors that validate common orchestration inputs. They shorten calls to dkge_pipeline() and prediction helpers while keeping backward compatibility with raw lists.
kernel <- diag(nrow(betas[[1]]))
transport <- dkge_transport_spec(
centroids = centroids,
sizes = sizes,
medoid = 2
)
inference <- dkge_inference_spec(B = 1000, tail = "two.sided")
cls_spec <- dkge_classification_spec(targets = ~ condition, method = "lda")
results <- dkge_pipeline(
betas = betas,
designs = designs,
kernel = kernel,
contrasts = contrasts,
transport = transport,
inference = inference,
classification = cls_spec
)To score new subjects without manually assembling B_list, use dkge_predict_subjects():
pred <- dkge_predict_subjects(fit, betas = new_subjects, contrasts = my_contrasts)Documentation & support
Project home and documentation: https://github.com/bbuchsbaum/dkge. Issues and feature requests are welcome on the GitHub tracker.