Skip to contents

neurogam provides tools to analyse time-resolved effects with Bayesian generalised additive multilevel models (BGAMMs). Built on brms, it combines smooth estimation of temporal dynamics, posterior inference, and detection and visualisation of connected regions exceeding a posterior-odds threshold (a.k.a. “clusters”).

The package supports three types of analysis:

Analysis Typical applications Coordinates
Temporal (1D) EMG or M/EEG time courses (e.g., ERPs), pupillometry, time-resolved representational similarity analysis (RSA) or decoding accuracy, movement trajectories, etc. Time
Temporal generalisation (2D) Cross-temporal decoding or representational-generalisation matrices Training time x testing time
Spatio-temporal (3D) Sensor-level M/EEG smooths over projected sensor position and time Sensor adjacency x time

Installation

Install the development version from GitHub:

if (!requireNamespace("pak") ) install.packages("pak")
pak::pkg_install("lnalborczyk/neurogam")

Quick start: temporal (1D) analysis

library(tidyverse)

# Generate a small EEG-like example
eeg_data <- expand.grid(
    participant = sprintf("participant_%02d", seq_len(9) ),
    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)
        )

eeg_data |> 
    summarise(eeg = mean(eeg), .by = c(time, condition, participant) ) |>
    ggplot(aes(x = time, y = eeg, group = participant, colour = condition) ) +
    geom_line() +
    facet_wrap(~participant)

Fit a Bayesian GAMM

The following one-sample analysis tests whether the time-resolved outcome differs from its null reference. Setting predictor_id = NA selects the one-sample analysis; use a binary predictor name (e.g., "condition") to analyse a two-condition contrast.

We generally recommend starting with multilevel = "summary", which retains participant-level information while avoiding the cost of a trial-by-trial multilevel fit. An aggregate group-only model (multilevel = "group") is also available, but it does not represent between-participant variability in the same way.

library(neurogam)

# Fit the model and identify clusters
results_1d <- testing_through_time(
    data = eeg_data,
    participant_id = "participant",
    outcome_id = "eeg",
    time_id = "time",
    predictor_id = NA,
    multilevel = "summary",
    baseline_window = c(-0.2, -0.1),
    threshold = 10
    )

# Optional: save the result so subsequent analyses need no refitting
saveRDS(object = results_1d, "neurogam_results_1d.rds")

Inspect and visualise results

# Summarise the results
print(results_1d)
summary(results_1d)

# Visualise the results
plot(results_1d)
plot(results_1d, type = "predictions")
plot(results_1d, type = "clusters")

Posterior predictive checks

Posterior predictive checks (PPCs) are important for evaluating model adequacy. neurogam provides a convenient ppc() method; brms::pp_check(results$model) provides additional options.

ppc(object = results_1d, ppc_type = "participant")
brms::pp_check(results_1d$model)

See the bayesplot PPC reference for further diagnostics.

Reuse an existing fit

previous_model lets you recompute predictions and cluster detection without refitting the same model, for example to examine sensitivity to the posterior-odds threshold. Keep the data, predictor specification, and model structure compatible with the original fit.

results_1d_stricter <- testing_through_time(
    data = eeg_data,
    previous_model = results_1d$model,
    participant_id = "participant",
    outcome_id = "eeg",
    time_id = "time",
    predictor_id = NA,
    multilevel = "summary",
    threshold = 20
    )

plot(results_1d_stricter, type = "clusters")

Cross-temporal generalisation (2D)

For modelling a temporal-generalisation matrix, supply two temporal coordinates using time_id. A typical long-format dataset has one row per participant, training time, and testing time (and, if applicable, condition or other predictor).

# Illustrative input: `ctg_data` must contain participant, time1,
# time2, accuracy, and any predictor columns used in the model.
results_2d <- testing_through_time(
    data = ctg_data,
    participant_id = "participant",
    outcome_id = "accuracy",
    time_id = c("time1", "time2"),
    predictor_id = NA,
    chance_level = 0.5,
    multilevel = "summary",
    threshold = 10
    )

summary(results_2d)

plot(results_2d, type = "predictions")   # posterior heatmap
plot(results_2d, type = "clusters")      # cluster membership map

The 2D smooth is fitted over both temporal coordinates. The standardised result view exposes cluster_summary and cluster_membership in the same way as for 1D data, with locations identified by their two time coordinates.

Spatio-temporal sensor-by-time modelling (3D)

For sensor-level M/EEG, neurogam can model responses over two projected sensor coordinates plus time. Unlike a regular three-dimensional voxel grid, connected clusters are defined over the actual sensors and their adjacency graph, together with temporal neighbours. Interpolated scalp images are used for display only.

The long-format input should contain a participant identifier, sensor identifier, time, observed outcome, and two projected sensor positions (for example, xproj and yproj). The same sensor should have consistent spatial coordinates throughout the analysis.

# Illustrative input: `eeg_st` contains subject, channel, time,
# xproj, yproj, voltage, and any predictors used by the model.
results_st <- testing_through_time(
    data = eeg_st,
    participant_id = "subject",
    outcome_id = "voltage",
    time_id = "time",
    sensor_id = "channel",
    space_id = c("xproj", "yproj"),
    predictor_id = NA,
    multilevel = "summary",
    threshold = 10,
    threshold_type = "above",
    adjacency_k = 4L
    )

print(results_st)
summary(results_st)

view_st <- as_neurogam_result_view(results_st)
view_st$cluster_summary

When no sensor adjacency is supplied, the package can construct an approximate graph from projected positions. For confirmatory applications, supplying a well-justified montage-specific adjacency graph is preferable.

# Observed, predicted, and residual scalp maps
plot(
    results_st,
    type = "topography",
    observed_data = eeg_st,
    outcome_id = "voltage",
    sensor_id = "channel",
    participant_id = "subject",
    n_times = 6
    )

# Faceted sensor time courses with detected cluster segments
plot(
    results_st,
    type = "trajectories",
    observed_data = eeg_st,
    outcome_id = "voltage",
    sensor_id = "channel",
    participant_id = "subject",
    layout = "facets",
    cluster_style = "segments"
    )

# Convenient shorthands for prediction-only and cluster-highlighted traces
plot(results_st, type = "predictions", observed_data = eeg_st)
plot(results_st, type = "clusters", observed_data = eeg_st)

Choosing the smooth basis dimension

The smooth basis dimension k limits the flexibility of the fitted time course; it is not the model’s effective degrees of freedom. Appropriate values depend on the signal’s temporal dynamics, sampling density, preprocessing, and the amount of information available. Increase k where needed, check that it is not overly restrictive, and use posterior predictive checks and model comparison as complementary diagnostics. recommend_k() can fit and compare candidate models using LOO-based criteria, although this can be computationally expensive:

k_res <- recommend_k(
    object = results_1d,
    k_min = 10,
    k_max = 40,
    k_step = 5,
    criterion = "loo"
    )

summary(k_res)

Using neurogam from Python or Julia

Python (rpy2)

rpy2 allows Python workflows (e.g., MNE-Python) to call neurogam. First convert the data to a long-form table, with the columns required by the chosen analysis.

import rpy2.robjects as robjects
from rpy2.robjects import default_converter, pandas2ri
from rpy2.robjects.conversion import localconverter
from rpy2.robjects.packages import importr

neurogam = importr("neurogam")

# Example: long_df = epochs.to_data_frame(long_format=True)
# Adapt column names to the neurogam API before conversion.
with localconverter(default_converter + pandas2ri.converter):
    long_df_r = robjects.conversion.py2rpy(long_df)

results = neurogam.testing_through_time(
    data=long_df_r,
    participant_id="participant",
    outcome_id="eeg",
    time_id="time",
    predictor_id="condition",
    threshold=10
    )

Julia (RCall)

Julia users can access R functions via RCall.jl (thanks to Benedikt Ehinger for the original example).

# loading the RCall module
using RCall

# importing the neurogam R package
@rimport neurogam

# assuming long_df is some M/EEG data reshaped in long format
results = neurogam.testing_through_time(data=long_df, threshold=10)

Citation

When using neurogam, please cite:

As neurogam builds on brms, please also cite the relevant publications:

Getting help

For bug reports, questions, or feature requests, open a GitHub issue, preferably with a minimal reproducible example, session information, and the version of neurogam you are using.