33  Internal Utility Functions

The examples in Chapter 33 require that the search path contains the following namespaces,

library(groupedHyperframe)
library(groupedHyperframe.random)
library(maxEff)
# Registered S3 method overwritten by 'pROC':
#   method   from            
#   plot.roc spatstat.explore

33.1 'add_numeric_'

The internal class 'add_numeric_' defined in package maxEff v0.2.1 inherits from the class 'call', with additional attributes

• attr(., 'effsize'), a numeric scalar, regression coefficients, i.e., effect size effsize, of the additional numeric predictor
• attr(., 'model'), the regression model with additional numeric predictor

The S3 method dispatch base::print.default() displays each 'add_numeric_' object.

a0[[1L]]

a0[[2L]]

The S3 method dispatch spatstat.geom::with.hyperframe() obtains the selected numeric predictors by passing the call to parameter ee.

s0 |>
  with(ee = a0[[1L]]) |> # ?spatstat.geom::with.hyperframe
  summary.default()
s1 |>
  with(ee = a0[[1L]]) |> # ?spatstat.geom::with.hyperframe
  summary.default()

s0 |>
  with(ee = a0[[2L]]) |> # ?spatstat.geom::with.hyperframe
  summary.default()
s1 |>
  with(ee = a0[[2L]]) |> # ?spatstat.geom::with.hyperframe
  summary.default()

The S3 method dispatch predict.add_numeric_() is the workhorse of the S3 method dispatch predict.add_numeric().

a11 = a0[[1L]] |> 
  predict(newdata = s1)
stopifnot(identical(a1[[1L]], a11))

a12 = a0[[2L]] |> 
  predict(newdata = s1)
stopifnot(identical(a1[[2L]], a12))  

33.2 'add_dummy_'

The internal class 'add_dummy_' defined in package maxEff v0.2.1 inherits from the class 'node1' (Chapter 21), with additional attributes

• attr(., 'p1'), a numeric scalar between 0 and 1, the TRUE probability of the additional logical predictor in the training set
• attr(., 'effsize'), a numeric scalar, the regression coefficients, i.e., effect size effsize, of the additional logical predictor
• attr(., 'model'), the regression model with additional logical predictor

The S3 method dispatch base::print.default() displays each 'add_dummy_' object.

b0[[1L]]

b0[[2L]]

c0[[1L]]

c0[[2L]]

The S3 method dispatch predict.node1() evaluates a dichotomizing rule in a hyperframe. Note that user must call the S3 method dispatch predict.node1() explicitly, otherwise the S3 generic stats::predict() would dispatch to predict.add_dummy_().

b0[[1L]] |> 
  predict.node1(newdata = s0) |>
  table() |> 
  addmargins()  
b0[[1L]] |> 
  predict.node1(newdata = s1) |>
  table() |> 
  addmargins()

b0[[2L]] |> 
  predict.node1(newdata = s0) |>
  table() |> 
  addmargins() 
b0[[2L]] |> 
  predict.node1(newdata = s1) |>
  table() |> 
  addmargins()  

c0[[1L]] |>
  predict.node1(newdata = s0) |>
  table() |> 
  addmargins()
c0[[1L]] |>
  predict.node1(newdata = s1) |>
  table() |> 
  addmargins()

c0[[2L]] |>
  predict.node1(newdata = s0) |>
  table() |> 
  addmargins()
c0[[2L]] |>
  predict.node1(newdata = s1) |>
  table() |> 
  addmargins()

The S3 method dispatch predict.add_dummy_() is the workhorse of the S3 method dispatch predict.add_dummy().

b11 = b0[[1L]] |> 
  predict(newdata = s1)
stopifnot(identical(b1[[1L]], b11))

b12 = b0[[2L]] |> 
  predict(newdata = s1)
stopifnot(identical(b1[[2L]], b12))  

c11 = c0[[1L]] |> 
  predict(newdata = s1)
stopifnot(identical(c1[[1L]], c11))

c12 = c0[[2L]] |> 
  predict(newdata = s1)
stopifnot(identical(c1[[2L]], c12))  

33.3 grouped_rppp()

Function groupedHyperframe.random::grouped_rppp() implements the matrix parameterization using advanced R language operations. The code snippet inside function grouped_rppp() in Section 4.2 cannot be taken outside function grouped_rppp()!

set.seed(37); (n = sample(x = 1:4, size = 3L, replace = TRUE)) 
# [1] 2 3 4
set.seed(39); p_Matern = mapply(
  FUN = mvrnorm2, 
  mu = list(kappa = c(3,2), mu = c(10,5), scale = c(.4,.2), meanlog = c(3,5), sdlog = c(.4,.2)), 
  sd = list(kappa = .2, mu = .5, scale = .05, meanlog = .1, sdlog = .01), 
  MoreArgs = list(n = 3L), 
  SIMPLIFY = FALSE
) |>
  within.list(expr = {
    kappa = pmax(kappa, 1 + .Machine$double.eps)
    mu = pmax(mu, 1 + .Machine$double.eps)
    scale = pmax(scale, .Machine$double.eps)
    sdlog = pmax(sdlog, .Machine$double.eps)
  })

tryCatch(expr = {
  p_Matern |> 
    with.default(expr = {
      spatstat.random::rMatClust(kappa = kappa, scale = scale, mu = mu)
    })
}, error = identity)
# <simpleError: 'scale' should be a single number>

The native pipe operator |> successfully passes the code snippet into function grouped_rppp(), while the pipe operator magrittr::`%>%` (Bache and Wickham 2025, v2.0.4) does not pass the code snippet into function grouped_rppp()!

p_Matern |> 
  with.default(expr = {
    rMatClust(kappa = kappa, scale = scale, mu = mu) |> 
      grouped_rppp(n = n)
  })
# Grouped Hyperframe: ~g1/g2
# 
# 9 g2 nested in
# 3 g1
# 
# Preview of first 10 (or less) rows:
# 
#     ppp g1 g2
# 1 (ppp)  1  1
# 2 (ppp)  1  2
# 3 (ppp)  2  1
# 4 (ppp)  2  2
# 5 (ppp)  2  3
# 6 (ppp)  3  1
# 7 (ppp)  3  2
# 8 (ppp)  3  3
# 9 (ppp)  3  4

library(magrittr)
tryCatch(expr = {
  p_Matern |> 
    with.default(expr = {
      rMatClust(kappa = kappa, scale = scale, mu = mu) %>% 
        grouped_rppp(n = n)
    })
}, error = identity)
# <notSubsettableError in i[[1L]]: object of type 'symbol' is not subsettable>

33.4 mvrnorm2()

Function groupedHyperframe.random::mvrnorm2() is a wrapper of the multivariate normal simulator function MASS::mvrnorm() (Venables and Ripley 2002) to accept the standard deviation(s) \(\sigma\) via parameter sd

• parameter \(\sigma\) sd may be a numeric scalar, indicating an all-equal diagonal-variance zero-covariance matrix;
• parameter \(\sigma\) sd may be a numeric vector of the same length as parameter \(\mu\) mu, indicating a diagonal-variance zero-covariance matrix;
• To specify a full variance-covariance matrix \(\Sigma\), user should use function MASS::mvrnorm() (Venables and Ripley 2002).

set.seed(12); a1 = MASS::mvrnorm(n = 3L, mu = c(0, 0), Sigma = diag(x = .9^2, nrow = 2L))
set.seed(12); a2 = mvrnorm2(n = 3L, mu = c(0, 0), sd = .9)
stopifnot(identical(a1, a2))

set.seed(42); b1 = MASS::mvrnorm(n = 3L, mu = c(0, 0), Sigma = diag(x = c(.9, 1.1)^2, nrow = 2L))
set.seed(42); b2 = mvrnorm2(n = 3L, mu = c(0, 0), sd = c(.9, 1.1))
stopifnot(identical(b1, b2))

(R = matrix(c(1, .5, .5, 1), nrow = 2L)) # correlation matrix
#      [,1] [,2]
# [1,]  1.0  0.5
# [2,]  0.5  1.0
(S = c(.9, 1.1) * R * rep(c(.9, 1.1), each = 2L)) # variance-covariance matrix
#       [,1]  [,2]
# [1,] 0.810 0.495
# [2,] 0.495 1.210
set.seed(23); c1 = MASS::mvrnorm(n = 3L, mu = c(0, 0), Sigma = S)
set.seed(23); c2 = mvrnorm2(n = 3L, mu = c(0, 0), Sigma = S)
stopifnot(identical(c1, c2))

33.5 statusPartition()

Function maxEff::statusPartition() (v0.2.1)

1. splits a left-censored survival::Surv object by its survival status, i.e., observed vs. left-censored;
2. partitions the observed and left-censored subjects, respectively, into test/training sets.

See Section 10.2 for the usage of the terms “split” vs. “partition”.

Consider a toy example of

capacitor_failure = survival::capacitor |> 
  with(expr = survival::Surv(time, status))
capacitor_failure
#  [1]  439   904  1092  1105   572   690   904  1090   315   315   439   628   258   258   347   588   959  1065  1065 
# [20] 1087   216   315   455   473   241   315   332   380   241   241   435   455  1105+ 1105+ 1105+ 1105+ 1090+ 1090+
# [39] 1090+ 1090+  628+  628+  628+  628+  588+  588+  588+  588+ 1087+ 1087+ 1087+ 1087+  473+  473+  473+  473+  380+
# [58]  380+  380+  380+  455+  455+  455+  455+

Function statusPartition() intends to avoid the situation that a Cox proportional hazards model survival::coxph() in one or more of the partitioned data set being degenerate due to the fact that all subjects in that partition being censored.

set.seed(12); id = capacitor_failure |>
  statusPartition(times = 1L, p = .5)
capacitor_failure[id[[1L]], 2L] |> 
  table() # balanced by survival status
# 
#  0  1 
# 16 16

Function statusPartition() is an extension of the very popular function caret::createDataPartition(), which stratifies a Surv object by the quantiles of its survival time (as of package caret v7.0.1).

set.seed(12); id0 = capacitor_failure |>
  caret::createDataPartition(times = 1L, p = .5)
capacitor_failure[id0[[1L]], 2L] |> 
  table()
# 
#  0  1 
# 19 14

33.6 rfactor()

Function groupedHyperframe.random::rfactor() is a wrapper of function base::sample.int(). Function rfactor()

• has first parameter n of the random sample size, similar to functions stats::rlnorm(), stats::rnbinom(), etc.
• returns a factor

set.seed(18); rfactor(n = 20L, prob = c(4,2,3))
#  [1] 2 3 2 1 1 3 1 3 1 1 3 3 1 1 2 1 3 1 2 1
# Levels: 1 2 3

set.seed(18); rfactor(n = 20L, prob = c(4,2,3), levels = letters[1:3])
#  [1] b c b a a c a c a a c c a a b a c a b a
# Levels: a b c

33.7 .rppp()

Function groupedHyperframe.random::.rppp() (v0.2.0) implements the vectorized parameterization using advanced R language operations. The code snippet inside function .rppp() in Section 4.1 cannot be taken outside function .rppp()!

tryCatch(expr = {
  spatstat.random::rMatClust(kappa = c(10, 5), mu = c(8, 4), scale = c(.15, .06))
}, error = identity)
# <simpleError: 'scale' should be a single number>

The native pipe operator |> successfully passes the code snippet into function .rppp(), while the pipe operator magrittr::`%>%` (Bache and Wickham 2025, v2.0.4) does not pass the code snippet into function .rppp()!

set.seed(12); r = rMatClust(kappa = c(10, 5), mu = c(8, 4), scale = c(.15, .06)) |>
  .rppp()
# Point-pattern simulated by `spatstat.random::rMatClust()`
# 

library(magrittr)
tryCatch(expr = {
  rMatClust(kappa = c(10, 5), mu = c(8, 4), scale = c(.15, .06)) %>% 
    .rppp()
}, error = identity)
# <notSubsettableError in i[[1L]]: object of type 'symbol' is not subsettable>

Bache, Stefan Milton, and Hadley Wickham. 2025. magrittr: A Forward-Pipe Operator for R. https://CRAN.R-project.org/package=magrittr.

Venables, William N., and Brian D. Ripley. 2002. Modern Applied Statistics with S. Fourth. New York: Springer. https://www.stats.ox.ac.uk/pub/MASS4/.