nbasis: Return the global onsets of an object

In bbuchsbaum/fmrireg: R package for the anlysis of fmri data

Return the global onsets of an object

Description

Convert relative onset times to global (cumulative) onset times across runs. Global onsets are defined as cumulative time over runs, meaning they do not reset to zero for each run. This is useful for:

• Converting run-specific onsets to experiment-wide timings

• Aligning events across multiple runs

• Computing temporal distances between events in different runs

Get the number of basis functions used in a hemodynamic response function (HRF) or model term. For canonical HRFs (like SPM's canonical HRF), this returns 1. For flexible basis sets (like Fourier or B-spline bases), this returns the number of basis functions used to model the response shape.

Usage

nbasis(x, ...)

## S3 method for class 'convolved_term'
nbasis(x, ...)

## S3 method for class 'BSpline'
nbasis(x, ...)

## S3 method for class 'Poly'
nbasis(x, ...)

## S3 method for class 'Scale'
nbasis(x, ...)

## S3 method for class 'ScaleWithin'
nbasis(x, ...)

## S3 method for class 'RobustScale'
nbasis(x, ...)

## S3 method for class 'Standardized'
nbasis(x, ...)

## S3 method for class 'Ident'
nbasis(x, ...)

## S3 method for class 'covariate_convolved_term'
nbasis(x, ...)

Arguments

x	The object to query (typically an HRF, hrfspec, or convolved_term)
...	Additional arguments passed to methods
onsets	A numeric vector of relative onset times within each run/block
blockids	Numeric vector specifying which block/run each onset belongs to

Value

A numeric vector of global onset times where:

• Each onset is adjusted by the cumulative duration of previous runs

• Times are in the same units as the input onsets (typically seconds)

• NA is returned for onsets that exceed their block duration

An integer indicating the number of basis functions:

• 1 for canonical HRFs (e.g., SPM gamma)

• >1 for flexible basis sets (e.g., Fourier, B-spline)

• For convolved terms: number of basis functions per condition

See Also

sampling_frame(), event_model() Return number of basis functions associated with HRF

fmrihrf::HRF_SPMG1(), event_model()

Other timing: durations(), onsets(), split_by_block()

Other hrf: fitted_hrf(), penalty_matrix()

Examples

# Create a sampling frame with three runs
sframe <- sampling_frame(
  blocklens = c(100, 100, 100),  # 100 scans per run
  TR = 2                         # 2 seconds per scan
)

# Define events in each run
run_onsets <- c(10, 20, 30)     # Events at 10s, 20s, 30s
run_ids <- c(1, 2, 3)           # One event per run

# Convert to global onsets
global_times <- global_onsets(
  sframe,
  onsets = run_onsets,
  blockids = run_ids
)
# Returns: c(10, 220, 430)
# Because:
#  - Run 1: 10s
#  - Run 2: 20s + (100 scans * 2s) = 220s
#  - Run 3: 30s + (200 scans * 2s) = 430s
# Check basis functions for different HRF types

# Canonical HRF (single basis)
canonical_hrf <- HRF_SPMG1
nbasis(canonical_hrf)  # Returns: 1

# Fourier basis set
fourier_hrf <- fmrihrf::gen_hrf("fourier", nbasis = 3)
nbasis(fourier_hrf)  # Returns: 3

# Create event model with multiple basis functions
event_data <- data.frame(
  condition = factor(c("A", "B", "A", "B")),
  onsets = c(1, 10, 20, 30),
  run = c(1, 1, 1, 1)
)
sframe <- sampling_frame(blocklens = 50, TR = 2)

# Model with Fourier basis
evmodel <- event_model(
  onsets ~ hrf(condition, basis = "fourier", nbasis = 3),
  data = event_data,
  block = ~run,
  sampling_frame = sframe
)

# Get number of basis functions for model term
nbasis(evmodel)  # Returns: 3 (basis functions per condition)

bbuchsbaum/fmrireg documentation built on June 10, 2025, 8:18 p.m.