How to write an intensity or cumulative intensity function for vectorized models

TA Trikalinos

2026-08-28

What this vignette shows

The vectorized samplers take user functions in two roles: an intensity lambda for the thinning samplers (vdraw_intensity(), vdraw_intensity_step()), and a cumulative intensity pair Lambda / Lambda_inv for the inversion sampler (vdraw_cumulative_intensity()). This vignette states the calling contract these functions must satisfy, shows the canonical way to pass parameters – including parameters that differ across the simulated point processes – and collects the idioms and anti-patterns.

The calling contract

Every user function is called elementwise-vectorized: it receives an array of time points (or of \(\Lambda\)-values, for Lambda_inv) and must return an object of the same shape, computed element by element. The samplers call

where a is the argument container you supplied (next section), passed as the second positional argument; the name of the second formal is yours to choose. When you supply no container the function is called with a single argument, so a plain closure works:

l <- function(t) 0.5 * sqrt(t)
Z <- vdraw_intensity(
  lambda = l,
  lambda_maj_matrix = matrix(1.2, nrow = 100, ncol = 5),
  rate_matrix_t_min = 1, rate_matrix_t_max = 5
)

The shape of the first argument depends on the sampler: the thinning samplers pass a matrix of candidate times with one row per point process; the inversion sampler passes a two-column matrix of interval bounds to Lambda and a matrix of \(\Lambda\)-values to Lambda_inv (also one row per process). Elementwise arithmetic preserves shape automatically, so you rarely need to think about it – but it matters for how per-process parameters align, below.

Passing parameters: the structured container

All of the function’s parameters live in one container with two channels (slots):

lambda_args = list(
  shared   = list(...), # row-invariant parameters, any type; stored ONCE
  row_args = data.frame(...) # one row per point process
)

Inside your function, access both channels through the second argument:

l <- function(t, a) {
  a$shared$scale * t^a$row_args$exponent
}
n <- 1000
args <- list(
  shared = list(scale = 0.2),
  row_args = data.frame(exponent = seq(0.5, 1.5, length.out = n))
)
Z <- vdraw_intensity(
  lambda = l, lambda_args = args,
  lambda_maj_matrix = matrix(3, nrow = n, ncol = 5),
  rate_matrix_t_min = 1, rate_matrix_t_max = 5
)

Why this aligns. t arrives as an n x M matrix and a$row_args$exponent is a length-n vector. R recycles vectors down the columns of a matrix, and the matrix has one row per process – so t^a$row_args$exponent raises every entry of row \(i\) to exponent[i]. This column-major recycling is the relied-upon R idiom: write the function as if t were a column of times for all processes at once, index nothing by hand.

Rejection resampling is handled for you. The conditioned thinning samplers redraw only the point processes that failed the condition. In those rounds your function receives a with row_args already subset to the processes being redrawn, still aligned row-for-row with the candidate matrix. Do not cache row indices between calls.

Cumulative intensity pairs

Lambda must be continuous and increasing in t for each process, and Lambda_inv must be its inverse. One container serves both functions – there is a single Lambda_args, delivered to Lambda and Lambda_inv alike, so write the pair against the same parameterization:

L <- function(t, a) (a$shared$r + a$row_args$d) * t
Li <- function(z, a) z / (a$shared$r + a$row_args$d)
n <- 1000
ctr <- list(
  shared = list(r = 0.4),
  row_args = data.frame(d = runif(n, 0, 0.4))
)
Z <- vdraw_cumulative_intensity(
  Lambda = L, Lambda_inv = Li,
  t_min = rep(0, n), t_max = rep(10, n),
  Lambda_args = ctr
)

Two additional requirements:

Majorizers from the same function

get_step_majorizer() accepts the same container through fun_args, so the sampler’s lambda doubles as the input for majorizer construction – no hand-written wrapper:

l <- function(t, a) a$shared$scale * t^a$row_args$exponent
n <- 1000
args <- list(
  shared = list(scale = 0.2),
  row_args = data.frame(exponent = seq(0.5, 1.5, length.out = n))
)
breaks_mat <- matrix(rep(seq(1, 5, length.out = 6), each = n), nrow = n)
lmaj <- get_step_majorizer(
  fun = l, breaks = breaks_mat, is_monotone = TRUE, fun_args = args
)
Z <- vdraw_intensity(
  lambda = l, lambda_args = args, lambda_maj_matrix = lmaj,
  rate_matrix_t_min = 1, rate_matrix_t_max = 5
)

If lambda ever exceeds the majorizer, the kernels stop with a “Majorizer” error rather than silently sampling the wrong process – prefer a slightly generous majorizer over a tight one you have not verified.

A complete example: heterogeneous population, both algorithms

A population where each person carries a frailty and a shape parameter, and the same model is sampled by thinning (only lambda known) and by inversion (closed-form Lambda and inverse): \(\lambda_i(t) = w_i \, t^{p_i}\), so \(\Lambda_i(t) = w_i \, t^{p_i + 1} / (p_i + 1)\).

n <- 2000
pop <- data.frame(
  w = rgamma(n, shape = 4, rate = 4), # frailty, mean 1
  p = runif(n, 0.5, 1.5)
)
args <- list(row_args = pop) # no shared channel needed; that is fine

l <- function(t, a) a$row_args$w * t^a$row_args$p
L <- function(t, a) a$row_args$w * t^(a$row_args$p + 1) / (a$row_args$p + 1)
Li <- function(z, a) (z * (a$row_args$p + 1) / a$row_args$w)^(1 / (a$row_args$p + 1))

breaks_mat <- matrix(rep(seq(0, 3, length.out = 7), each = n), nrow = n)
Z_thin <- vdraw_intensity(
  lambda = l, lambda_args = args,
  lambda_maj_matrix = get_step_majorizer(
    fun = l, breaks = breaks_mat, is_monotone = TRUE, fun_args = args
  ),
  rate_matrix_t_min = 0, rate_matrix_t_max = 3
)
Z_inv <- vdraw_cumulative_intensity(
  Lambda = L, Lambda_inv = Li,
  t_min = rep(0, n), t_max = rep(3, n),
  Lambda_args = args
)

# the two exact algorithms sample the same process
suppressWarnings(stats::ks.test(
  as.vector(Z_thin[!is.na(Z_thin)]),
  as.vector(Z_inv[!is.na(Z_inv)])
))$p.value
#> [1] 0.6577164

Anti-patterns