https://github.com/bbuchsbaum/dkge
https://github.com/bbuchsbaum/dkge
Last synced: 4 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/bbuchsbaum/dkge
- Owner: bbuchsbaum
- Created: 2025-09-20T21:40:00.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2025-09-20T22:58:38.000Z (5 months ago)
- Last Synced: 2025-09-20T23:34:26.152Z (5 months ago)
- Language: R
- Homepage: https://bbuchsbaum.github.io/dkge/
- Size: 172 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# dkge
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
```r
# install.packages("remotes")
remotes::install_github("bbuchsbaum/dkge")
```
The package depends on `RcppArmadillo`, `future`, `multivarious`, and other CRAN libraries; these install automatically.
## Getting started
```r
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:
- `vignette("dkge-workflow")`
- `vignette("dkge-design-kernels")`
- `vignette("dkge-contrasts-inference")`
- `vignette("dkge-dense-rendering")`
- `vignette("dkge-components")`
- `vignette("dkge-performance")`
- `vignette("dkge-weighting")`
## 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.
```r
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()`:
```r
pred <- dkge_predict_subjects(fit, betas = new_subjects, contrasts = my_contrasts)
```
## Documentation & support
Rendered articles and function reference are available at the pkgdown site: . Issues and feature requests are welcome on the [GitHub tracker](https://github.com/bbuchsbaum/dkge/issues).
## Development
- Pull requests are encouraged; please accompany user-facing changes with tests and documentation.
- For large feature work, open an issue to discuss design choices before implementation.
## License
MIT License. See `LICENSE` for details.