--- title: "How to write an intensity or cumulative intensity function for vectorized models" author: "TA Trikalinos" date: "2026-08-28" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{How to write an intensity or cumulative intensity function for vectorized models} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r, include = FALSE} set.seed(20260828) knitr::opts_chunk$set( collapse = TRUE, comment = "#>" ) library(nhppp) ``` ## 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 - `lambda(t)` or `lambda(t, a)`, - `Lambda(t)` or `Lambda(t, a)`, and `Lambda_inv(z)` or `Lambda_inv(z, a)`, 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: ```{r closure} 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): ```{r container-shape, eval = FALSE} lambda_args = list( shared = list(...), # row-invariant parameters, any type; stored ONCE row_args = data.frame(...) # one row per point process ) ``` - `shared` holds anything that is the same for every point process: scalars, vectors, matrices, spline bases, fitted model objects. It is never replicated across processes, so a large shared object costs its size once -- not once per process. - `row_args` holds parameters that vary by point process: a `data.frame` (or `data.table` -- accepted as-is, read-only, never coerced or copied) with **one row per point process**, in the same order as the rows of the rate or majorizer matrix. The samplers validate the row count. Inside your function, access both channels through the second argument: ```{r container-use} 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: ```{r inversion} 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: - **`NA` in, `NA` out.** The sampler calls `Lambda_inv` on `NA`-padded matrices (padding marks processes that have run out of events). Plain arithmetic propagates `NA` automatically; only special-case code (`if (z > ...)`, table lookups) needs care -- use vectorized constructs (`ifelse()`, `pmin()`/`pmax()`, `approxfun(..., rule = 2)`). - With `output = "long"` on the conditioned path, `Lambda_inv` receives the event **vector** rather than a matrix, with `row_args` subset to one row per event. The same elementwise code covers both cases without change. ## 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: ```{r majorizer} 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)$. ```{r worked-example} 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 ``` ## Anti-patterns - **Do not** replicate row-invariant parameters into `row_args` (`row_args = data.frame(scale = rep(0.2, n))`): it works, but costs `n` copies of what `shared` stores once. At $10^6$--$10^7$ processes this is real memory. - **Do not** rely on the deprecated conventions: a flat `lambda_args = list(...)` (all-shared, kept working for released code), the nested `vector_arguments` element, and the separate `Lambda_inv_args` all emit deprecation warnings and will eventually be removed. New code uses `shared`/`row_args` and one `Lambda_args` for the pair. - **Do not** write functions that expect the container by name (`function(t, lambda_args)` called as `lambda(t, lambda_args = ...)`): the delivery is positional; name the second formal whatever you like, but do not depend on the name. - **Do not** modify `a` inside the function (in particular, no `data.table` by-reference operations on `a$row_args`): the container is read-only shared state; mutating it corrupts subsequent calls, including the resampling rounds of the conditioned thinning samplers. - **Do not** branch on scalar tests (`if (t < 1) ...`) -- `t` is a matrix; use vectorized alternatives.