
Recommend a smooth basis dimension k via effective complexity "knee" detection
Source:R/recommend_k.R
recommend_k.RdThis function takes a "clusters_results" object produced by
testing_through_time, refits the underlying brms model
for a grid of k values, computes model comparison criteria
(loo, waic), and identifies a recommended
smooth basis dimension via an automatic "knee" detection procedure on the
effective number of parameters (either p_loo or p_waic).
Arguments
- object
An object of class
"clusters_results"as returned bytesting_through_time. The object must contain a fitted brms model in its$modelslot.- k_min
Numeric; minimum value of the smooth basis dimension
kto consider.- k_max
Numeric; maximum value of the smooth basis dimension
kto consider.- k_step
Numeric; step size between successive
kvalues. The sequence of tested values isseq(k_min, k_max, by = k_step).- criterion
Character vector of model comparison criteria to add via
add_criterion. Defaults toc("waic", "loo").- knee_method
Character; method for knee detection. One of:
"geometric": standard geometric elbow on the rawp_*values;"geometric_smooth": geometric elbow on a loess-smoothed curve ofp_*vsk, with weights1 / SE(p_*)^2when available (recommended whenp_*estimates are noisy).
- loess_span
Numeric; smoothing parameter passed to
loesswhenknee_method = "geometric_smooth". Defaults to0.75.- cores
Numeric; number of parallel cores to use.
- verbose
Logical; if
TRUE(default), prints progress messages while refitting models for differentkvalues.
Value
An object of class "recommend_k_results", which is a list
with elements:
models: named list of refittedbrmsfitobjects, one perkvalue;comparison: data frame summarising model criteria for eachk(one row perk), includingp_*and its SE;k_values: numeric vector ofkvalues that were evaluated;recommended_k: thekvalue identified as the knee based on the chosen effective complexity measure and method;plot: aggplot2object displayingp_*as a function ofkwith error bars and the knee highlighted;knee_on: the complexity measure used ("p_loo"or"p_waic");knee_method: the knee detection method used.
Details
For each k in seq(k_min, k_max, by = k_step), the function:
updates all
s(..., k = ...)terms in the original brms formula to use the new valuek, and refits the model viaupdate();calls
add_criterionto compute the requested criteria, and extractsp_looorp_waicand their standard errors (where available);builds a comparison table of criteria values across
k.
To recommend a basis dimension, the function treats the chosen complexity
measure (p_loo or p_waic) as a function of k and uses
an elbow (knee) method:
knee_method = "geometric"applies the geometric knee procedure directly top_*vsk;knee_method = "geometric_smooth"first fits a loess curvep_* ~ k(with weights1 / SE(p_*)^2when available), then applies the geometric knee to the smoothed curve. This reduces the influence of noisyp_*estimates.
The resulting plot shows p_* vs k with:
points and a line for the raw
p_*estimates;vertical error bars
± SE(p_*)(when SEs are available);(optionally) a dashed line for the smoothed
p_*curve;a vertical dashed line at the recommended
k(knee).
Examples
if (FALSE) { # \dontrun{
# Not run: Bayesian model fitting involves computationally
# intensive Stan compilation and MCMC sampling.
# Generate a small, reproducible EEG-like example
set.seed(123)
eeg_data <- expand.grid(
participant = sprintf("participant_%02d", seq_len(10) ),
condition = c("cond1", "cond2"),
trial = seq_len(length.out = 5),
time = seq(from = -0.2, to = 0.6, by = 0.01),
KEEP.OUT.ATTRS = FALSE,
stringsAsFactors = FALSE
)
eeg_data <- eeg_data |>
mutate(
eeg = 0.8 * exp(-((time - 0.3) / 0.09)^2) * (condition == "cond2") +
rnorm(nrow(eeg_data), sd = 0.5)
)
# fit a time-resolved GAMM
res <- testing_through_time(
data = eeg_data,
participant_id = "participant",
outcome_id = "eeg",
time_id = "time",
predictor_id = NA,
kvalue = 20,
multilevel = "summary"
)
# recommend an optimal smooth basis dimension k
k_res <- recommend_k(
object = res,
k_min = 10,
k_max = 40,
k_step = 5
)
# print summary in the console
summary(k_res)
# extract the recommended k value
k_res$recommended_k
# access the comparison table
k_res$comparison
# visualise effective complexity vs. k
k_res$plot
} # }