Nothing
#' Survival Model Families
#'
#' Use \code{survreg_family()} to choose a parametric survival model and its
#' distribution. Use \code{finegray_family()} to study a particular event
#' when other event types may occur first.
#'
#' Supply the resulting specification as the \code{family} argument to
#' \code{mfp2()}. \code{survreg_family()} can also be used with
#' \code{mfpi()}; Fine--Gray models cannot.
#'
#' Both functions require a survival response. For Fine--Gray models, the
#' response must identify the possible event types. Supply an \code{id}
#' to \code{mfp2()} when observations use start and stop times.
#'
#' @param dist Survival-time distribution accepted by
#' [survival::survreg()]. The default is \code{"weibull"}.
#' @param scale Scale of the chosen distribution. The default, \code{0},
#' estimates it from the data; a positive value fixes it.
#' @param parms Optional parameters for the chosen distribution, as accepted
#' by [survival::survreg()].
#' @param etype Event type of interest in a Fine--Gray model: one of the
#' event levels of the multi-state \code{Surv()} response, such as
#' \code{"cause1"}. If \code{NULL}, the first event type (the first
#' non-censoring level) is used. The censoring level cannot be used.
#' @param timefix Whether to correct small differences in event times caused
#' by rounding. The default is \code{TRUE}.
#'
#' @return A family specification for the \code{family} argument of
#' [mfp2()]. The specification from \code{survreg_family()} can also be
#' used with [mfpi()].
#'
#' @examples
#' survreg_spec <- survreg_family(dist = "weibull")
#' finegray_spec <- finegray_family(etype = "cause1")
#'
#' \donttest{
#' # Parametric Weibull survival model.
#' data("gbsg")
#' fit_survreg <- mfp2(
#' survival::Surv(rectime, censrec) ~ age + nodes,
#' data = gbsg,
#' family = survreg_spec,
#' df = 1,
#' select = 1,
#' cycles = 1,
#' verbose = FALSE
#' )
#'
#' # Fine--Gray model for the first of two competing event types.
#' set.seed(42)
#' n <- 160
#' x <- stats::rnorm(n)
#' cause1_time <- stats::rexp(n, rate = exp(0.3 * x) / 8)
#' cause2_time <- stats::rexp(n, rate = exp(-0.2 * x) / 10)
#' censor_time <- stats::rexp(n, rate = 1 / 15)
#' event <- ifelse(
#' censor_time < pmin(cause1_time, cause2_time), 0L,
#' ifelse(cause1_time <= cause2_time, 1L, 2L)
#' )
#' competing_data <- data.frame(
#' time = pmin(cause1_time, cause2_time, censor_time),
#' event = factor(
#' event,
#' levels = 0:2,
#' labels = c("censor", "cause1", "cause2")
#' ),
#' x = x
#' )
#' fit_finegray <- mfp2(
#' survival::Surv(time, event) ~ x,
#' data = competing_data,
#' family = finegray_spec,
#' df = 1,
#' select = 1,
#' cycles = 1,
#' verbose = FALSE
#' )
#' }
#' @seealso [survival::survreg()], [mfp2()], [mfpi()]
#' @rdname survival_families
#' @export
survreg_family <- function(dist = "weibull", scale = 0, parms = NULL) {
scale_supplied <- !missing(scale)
if (!(is.character(dist) && length(dist) == 1L && !is.na(dist) && nzchar(dist)) &&
!is.list(dist)) {
stop(
"! `dist` must be one distribution name or a distribution list accepted by `survival::survreg()`.",
call. = FALSE
)
}
# Fail fast on an unrecognized built-in distribution name rather than deferring
# the error to fit time. A `dist` supplied as a list is treated as a custom
# distribution object and passed through unchecked; custom distributions
# registered into `survival::survreg.distributions` at runtime are likewise
# not validated here.
if (is.character(dist)) {
valid_dists <- names(survival::survreg.distributions)
if (!dist %in% valid_dists) {
stop(
"! `dist` = \"", dist, "\" is not a recognized `survreg` distribution. ",
"Built-in choices are: ", paste(valid_dists, collapse = ", "), ". ",
"A custom distribution can be supplied as a list instead.",
call. = FALSE
)
}
}
if (!is.numeric(scale) || length(scale) != 1L || anyNA(scale) ||
!is.finite(scale) || scale < 0) {
stop("! `scale` must be one finite non-negative number.", call. = FALSE)
}
if (!is.null(parms)) {
parms_flat <- unlist(parms, use.names = TRUE)
if (!is.numeric(parms_flat) || length(parms_flat) < 1L ||
anyNA(parms_flat) || any(!is.finite(parms_flat))) {
stop("! `parms` must be `NULL` or a finite numeric value/vector.", call. = FALSE)
}
}
structure(
list(
family = "survreg",
dist = dist,
scale = unname(scale),
scale_supplied = scale_supplied,
parms = parms,
prepared = NULL
),
class = c("mfp2_survreg_family", "mfp2_family")
)
}
#' @param strata_action How \code{strata()} terms in the model formula affect
#' a Fine--Gray model:
#' \describe{
#' \item{\code{"both"}}{The default. Allows both the censoring pattern
#' and the baseline event pattern to differ between strata.}
#' \item{\code{"censoring"}}{Allows the censoring pattern to differ
#' between strata, while using a common baseline event pattern.}
#' \item{\code{"baseline"}}{Allows the baseline event pattern to differ
#' between strata, while estimating a common censoring pattern.}
#' }
#'
#' @references
#' Fine JP, Gray RJ (1999). A proportional hazards model for the
#' subdistribution of a competing risk. \emph{Journal of the American
#' Statistical Association}, 94(446), 496--509.
#' \doi{10.1080/01621459.1999.10474144}
#'
#' Zhou B, Latouche A, Rocha V, Fine JP (2011). Competing risks regression
#' for stratified data. \emph{Biometrics}, 67(2), 661--670.
#' \doi{10.1111/j.1541-0420.2010.01493.x}
#'
#' @rdname survival_families
#' @export
finegray_family <- function(etype = NULL, timefix = TRUE,
strata_action = c("both", "censoring", "baseline")) {
if (!is.null(etype)) {
if (!is.atomic(etype) || is.matrix(etype) || !is.null(dim(etype)) ||
length(etype) < 1L || anyNA(etype)) {
stop("! `etype` must be `NULL` or a non-missing event-state value.", call. = FALSE)
}
if (length(etype) > 1L) {
warning("Only the first value of `etype` is used.", call. = FALSE)
etype <- etype[1L]
}
}
if (!is.logical(timefix) || length(timefix) != 1L || is.na(timefix)) {
stop("! `timefix` must be `TRUE` or `FALSE`.", call. = FALSE)
}
strata_action <- match.arg(strata_action)
structure(
list(
family = "finegray",
etype = etype,
timefix = timefix,
strata_action = strata_action,
prepared = NULL
),
class = c("mfp2_finegray_family", "mfp2_family")
)
}
#' GEE Family Specification
#'
#' Use \code{gee_family()} with [mfp2()] to model outcomes measured more
#' than once within independent groups, such as repeated measurements from
#' the same person. Supply the group identifier through \code{mfp2()}'s
#' \code{id} argument. If measurement order matters, supply \code{waves}.
#'
#' @param family Response family: a family object, function, or name for
#' \code{gaussian}, \code{binomial}, \code{poisson}, or \code{Gamma},
#' with any link the family supports, for example
#' \code{binomial(link = "probit")}. The default is
#' \code{stats::gaussian()}.
#' @param corstr Assumed pattern of association between measurements in
#' the same group: \code{"exchangeable"} (default),
#' \code{"independence"}, or \code{"ar1"}.
#' @param std.err Method for calculating standard errors:
#' \code{"san.se"} (the default), \code{"jack"}, \code{"j1s"}, or
#' \code{"fij"}. \code{"san.se"} gives robust sandwich standard errors
#' with the finite-cluster correction \eqn{K/(K-1)}, where \eqn{K} is the
#' number of clusters, as in Stata's \code{xtgee}; they are therefore
#' slightly larger than those reported by [geepack::geeglm()]. The
#' jackknife estimators are used unchanged.
#' @param reference_dispersion Optional positive value that scales the
#' quasi-likelihood part of GEE AIC and BIC scores. The score divides
#' that part by this value; the penalty for model complexity is not
#' divided by it. If \code{NULL} (the default), \code{mfp2()} estimates
#' the value. It does not set the scale used for the final model's
#' standard errors. It cannot be supplied with p-value selection.
#' @param qbic_penalty For BIC selection, whether the complexity penalty
#' uses the number of independent \code{"clusters"} (default) or the
#' number of \code{"observations"}. This setting does not affect AIC
#' or p-value selection.
#'
#' @details
#' All three selection criteria in [mfp2()] are available for GEE models.
#' The default is \code{criterion = "aic"}, which uses QICu. BIC selection
#' uses a BIC-like score based on quasi-likelihood, and p-value selection
#' uses approximate tests for GEE. Under AIC or BIC selection,
#' \code{select = 1} does not force a predictor into the model; use the
#' \code{keep} argument of [mfp2()] instead.
#'
#' @return A family specification to supply as the \code{family} argument
#' of [mfp2()].
#'
#' @references
#' Pan, W. (2001). Akaike's information criterion in generalized estimating
#' equations. \emph{Biometrics}, 57, 120--125.\cr
#' Halekoh, U., Højsgaard, S. and Yan, J. (2006). The R package geepack
#' for generalized estimating equations. \emph{Journal of Statistical
#' Software}, 15(2), 1--11.
#'
#' @seealso [mfp2()], [geepack::geeglm()]
#'
#' @examples
#' set.seed(1)
#' d <- data.frame(id = rep(1:40, each = 3), x = runif(120, 1, 5))
#' d$y <- log(d$x) + rnorm(40, sd = 0.5)[d$id] + rnorm(120, sd = 0.3)
#'
#' # GEE models require geepack.
#' if (requireNamespace("geepack", quietly = TRUE)) {
#' fit_gee <- mfp2(
#' y ~ fp(x, df = 2),
#' data = d,
#' family = gee_family(gaussian(), corstr = "exchangeable"),
#' id = d$id,
#' verbose = FALSE
#' )
#' coef(fit_gee)
#' }
#'
#' @export
gee_family <- function(family = stats::gaussian(),
corstr = c("exchangeable", "independence", "ar1"),
std.err = c("san.se", "jack", "j1s", "fij"),
reference_dispersion = NULL,
qbic_penalty = c("clusters", "observations")) {
# geepack is in Suggests: fail here rather than in the middle of fitting.
mfp2_require_geepack()
# Temporary geepack compatibility boundary: geeglm() currently fails to
# remove an explicitly supplied scale.value from its model.frame() call. The
# scalar is then compared with observation-length variables and raises
# "variable lengths differ (found for '(scale.value)')". Do not expose
# scale.fix or scale.value in mfp2 until that upstream error is corrected.
# Keep the defaults, validation, storage, and complete internal propagation
# in place so future support requires only promoting these two assignments
# back to formal arguments and removing this compatibility comment.
scale.fix <- FALSE
scale.value <- 1
# Resolve the inner response family through the shared normalizer so names,
# functions, and family objects are all accepted, then restrict to the GLM
# families geepack supports for QIC.
family_arg <- deparse(substitute(family))
info <- normalize_family_argument(family, family_arg = family_arg)
response_family <- info$family
inner_string <- info$family_string
supported <- c("gaussian", "binomial", "poisson", "Gamma")
if (!inner_string %in% supported) {
stop(
sprintf(
"! `family` for `gee_family()` must be one of %s; got '%s'.",
paste(supported, collapse = ", "), inner_string
),
call. = FALSE
)
}
if (!inherits(response_family, "family")) {
stop("! `gee_family()` requires an ordinary GLM response family.", call. = FALSE)
}
corstr <- match.arg(corstr)
std.err <- match.arg(std.err)
qbic_penalty <- match.arg(qbic_penalty)
if (!is.null(reference_dispersion) &&
(!is.numeric(reference_dispersion) ||
length(reference_dispersion) != 1L ||
!is.finite(reference_dispersion) || reference_dispersion <= 0)) {
stop("`reference_dispersion` must be NULL or a positive finite number.",
call. = FALSE)
}
# Keep the complete validation contract in place even while these values are
# internally fixed. When geepack supports scale.value reliably, promoting
# the assignments above to public arguments must not require rebuilding any
# validation or downstream fitting logic.
if (!is.logical(scale.fix) || length(scale.fix) != 1L || is.na(scale.fix)) {
stop("! `scale.fix` must be a single non-missing logical value.", call. = FALSE)
}
if (!is.numeric(scale.value) || length(scale.value) != 1L ||
is.na(scale.value) || !is.finite(scale.value) || scale.value <= 0) {
stop("! `scale.value` must be a single finite positive number.", call. = FALSE)
}
structure(
list(
family = "gee",
response_family = response_family,
response_family_string = inner_string,
corstr = corstr,
std.err = std.err,
scale.fix = scale.fix,
scale.value = unname(scale.value),
reference_dispersion = if (is.null(reference_dispersion)) NULL else
unname(reference_dispersion),
qbic_penalty = qbic_penalty,
prepared = NULL
),
class = c("mfp2_gee_family", "mfp2_family")
)
}
#' Multinomial Logistic Family
#'
#' Use \code{multinomial_family()} with [mfp2()] or [mfpi()] when the outcome
#' has at least three categories with no natural order. Choose one category
#' as the reference; the model describes each other category in relation
#' to it.
#'
#' Each predictor has one selected linear or curved form shared across the
#' category comparisons. The strength and direction of its association
#' may differ between categories.
#'
#' @param reference Optional reference category. For a factor response,
#' give a factor level; for a count-matrix response, give a column name
#' or its one-based column number. If \code{NULL}, the first factor level
#' or count-matrix column is used. Character and numeric category labels
#' are converted to factor levels before the reference is chosen.
#'
#' @details
#' The response can be a factor, a vector of character or numeric category
#' labels, or a numeric matrix of category counts. It must contain at least
#' three categories. Counts must be nonnegative whole numbers, every row
#' must have at least one count, and every category must be represented in
#' the weighted data.
#'
#' @return A family specification to supply as the \code{family} argument
#' of [mfp2()] or [mfpi()].
#'
#' @examples
#' set.seed(43)
#' n <- 150
#' multinomial_data <- data.frame(
#' x1 = stats::rnorm(n),
#' x2 = stats::runif(n, -1, 1)
#' )
#' eta_b <- with(multinomial_data, 0.4 * x1 - 0.2 * x2)
#' eta_c <- with(multinomial_data, -0.3 * x1 + 0.5 * x2)
#' denominator <- 1 + exp(eta_b) + exp(eta_c)
#' probabilities <- cbind(
#' A = 1 / denominator,
#' B = exp(eta_b) / denominator,
#' C = exp(eta_c) / denominator
#' )
#' multinomial_data$y <- factor(vapply(
#' seq_len(n),
#' function(i) sample(c("A", "B", "C"), 1, prob = probabilities[i, ]),
#' character(1)
#' ))
#'
#' fit_multinomial <- mfp2(
#' y ~ x1 + x2,
#' data = multinomial_data,
#' family = multinomial_family(reference = "A"),
#' df = 1,
#' select = 1,
#' cycles = 1,
#' verbose = FALSE
#' )
#' predict(
#' fit_multinomial,
#' newdata = multinomial_data[1:3, ],
#' type = "response",
#' se.fit = FALSE
#' )
#'
#' @seealso [mfp2()], [mfpi()]
#' @export
multinomial_family <- function(reference = NULL) {
if (!is.null(reference) &&
(length(reference) != 1L || is.na(reference) ||
!(is.character(reference) || is.numeric(reference)))) {
stop(
"! `reference` must be `NULL` or one non-missing response level.",
call. = FALSE
)
}
structure(
list(family = "multinomial", reference = reference, prepared = NULL),
class = c("mfp2_multinomial_family", "mfp2_family")
)
}
#' Ordinal Family
#'
#' Use \code{ordinal_family()} with [mfp2()] or [mfpi()] when the outcome
#' has categories with a meaningful order, such as low, medium, and high.
#' The default \code{"logistic"} link gives a proportional-odds model.
#' The optional \pkg{rms} package (version 7.0-0 or later) is required.
#'
#' @param link Relationship used to model the ordered outcome. Choose
#' \code{"logistic"} (default), \code{"probit"}, \code{"loglog"},
#' \code{"cloglog"}, or \code{"cauchit"}.
#'
#' @details
#' Supply the outcome as an ordered factor to specify the category order.
#' Numeric outcomes are ordered from smallest to largest. Character
#' outcomes and unordered factors are ordered alphabetically; \code{mfp2()}
#' reports the order it has assumed. If alphabetical order is not the
#' intended order, convert the outcome to an ordered factor before fitting.
#'
#' A positive predictor coefficient indicates an association with higher
#' outcome categories. Optional case weights must be finite and strictly
#' positive. They are used without normalisation in selection and final fitting.
#' BIC uses the number of fitted rows as its sample size.
#'
#' @return A family specification to supply as the \code{family} argument
#' of [mfp2()] or [mfpi()].
#'
#' @examples
#' ordinal_family()
#' ordinal_family(link = "probit")
#'
#' \donttest{
#' if (requireNamespace("rms", quietly = TRUE) &&
#' utils::packageVersion("rms") >= "7.0-0") {
#' set.seed(44)
#' n <- 180
#' ordinal_data <- data.frame(
#' x1 = stats::rnorm(n),
#' x2 = stats::rbinom(n, 1, 0.5)
#' )
#' latent <- with(ordinal_data, 0.6 * x1 + 0.5 * x2 + stats::rlogis(n))
#' ordinal_data$y <- ordered(
#' cut(
#' latent,
#' breaks = stats::quantile(latent, probs = seq(0, 1, length.out = 5)),
#' include.lowest = TRUE,
#' labels = c("low", "medium", "high", "very high")
#' )
#' )
#'
#' fit_ordinal <- mfp2(
#' y ~ x1 + x2,
#' data = ordinal_data,
#' family = ordinal_family(link = "logistic"),
#' df = 1,
#' select = 1,
#' cycles = 1,
#' verbose = FALSE
#' )
#' predict(
#' fit_ordinal,
#' newdata = ordinal_data[1:3, ],
#' type = "response"
#' )
#' }
#' }
#'
#' @seealso [mfp2()], [mfpi()]
#' @export
ordinal_family <- function(link = c("logistic", "probit", "loglog",
"cloglog", "cauchit")) {
link <- match.arg(link)
structure(
list(family = "ordinal", link = link, prepared = NULL),
class = c("mfp2_ordinal_family", "mfp2_family")
)
}
#' Negative-Binomial Family
#'
#' Use \code{negbin_family()} with [mfp2()] or [mfpi()] for overdispersed
#' count outcomes. The regression coefficients and the negative-binomial
#' dispersion parameter \eqn{\theta} are estimated jointly by maximum
#' likelihood with [fastglm::fastglm_nb()], using the variance function
#' \eqn{\mu + \mu^2 / \theta}.
#'
#' \code{family = "negbin"} is shorthand for
#' \code{negbin_family(link = "log")} and gives the same model.
#'
#' @param link Link function relating the expected count \eqn{\mu} to the
#' linear predictor \eqn{\eta}. One of \code{"log"} (the default,
#' \eqn{\log\mu = \eta}), \code{"sqrt"} (\eqn{\sqrt{\mu} = \eta}), or
#' \code{"identity"} (\eqn{\mu = \eta}). These are the links supported by
#' [fastglm::fastglm_nb()].
#'
#' @details
#' The response must contain finite, nonnegative integer counts.
#'
#' Coefficients, fitted functions, contrasts, and \code{type = "link"}
#' predictions are on the scale of the chosen link: the log mean, the
#' square root of the mean, or the mean itself. \code{type = "response"}
#' predictions are expected counts. Response-scale standard errors use the
#' delta method with the derivative of the chosen inverse link. An offset
#' is added to the linear predictor on the same link scale; for example,
#' \code{log(exposure)} is the usual exposure offset only for the log link.
#'
#' The log link gives a positive mean for every linear predictor. The square-root
#' and identity links do not: the square-root link requires a positive linear
#' predictor, and the identity link requires a positive mean, for every
#' observation. A fit that does not meet these requirements, or does not
#' converge, is not used. During the FP power search such a candidate is
#' skipped and reported in a warning, as for other candidates that cannot be
#' fitted. If the null, linear, or final model cannot be fitted, model fitting
#' stops with an error. The link is never changed, and fitted values are never
#' adjusted, to make a fit succeed. Positive covariates, such as those with
#' a positive \code{shift}, help keep these links valid.
#'
#' Negative-binomial models require the suggested \pkg{fastglm} package
#' (version 0.1.1 or later). Generalized estimating equations via
#' [gee_family()] do not support negative-binomial responses.
#'
#' @return A family specification to supply as the \code{family} argument
#' of [mfp2()] or [mfpi()].
#'
#' @examples
#' negbin_family()
#' negbin_family(link = "sqrt")
#'
#' if (requireNamespace("fastglm", quietly = TRUE) &&
#' "fastglm_nb" %in% getNamespaceExports("fastglm")) {
#' set.seed(45)
#' n <- 200
#' count_data <- data.frame(x = stats::runif(n, 1, 4))
#' count_data$y <- stats::rnbinom(
#' n,
#' mu = with(count_data, (0.8 + 0.6 * x)^2),
#' size = 3
#' )
#'
#' fit_sqrt <- mfp2(
#' y ~ fp(x, df = 1),
#' data = count_data,
#' family = negbin_family(link = "sqrt"),
#' verbose = FALSE
#' )
#' predict(fit_sqrt, newdata = count_data[1:3, ], type = "response")
#' }
#'
#' @seealso [mfp2()], [mfpi()], [fastglm::fastglm_nb()]
#' @export
negbin_family <- function(link = c("log", "sqrt", "identity")) {
link <- mfp2_validate_negbin_link(link, default_allowed = TRUE)
structure(
list(family = "negbin", link = link),
class = c("mfp2_negbin_family", "mfp2_family")
)
}
#' Validate a Negative-Binomial Link Specification
#'
#' @param link Candidate link specification.
#' @param default_allowed Whether the unmodified constructor default
#' `c("log", "sqrt", "identity")` may be supplied and resolved to `"log"`.
#'
#' @return The validated link as a character scalar.
#'
#' @keywords internal
#' @noRd
mfp2_validate_negbin_link <- function(link, default_allowed = FALSE) {
supported <- mfp2_negbin_links()
if (isTRUE(default_allowed) && identical(link, supported)) {
return("log")
}
supported_text <- paste0('"', supported, '"', collapse = ", ")
if (is.function(link) || inherits(link, "link-glm")) {
stop(
"! `link` for `negbin_family()` must be given by name, not as a function or link object.",
"\ni Supported links are: ", supported_text, ".",
call. = FALSE
)
}
if (!is.character(link) || length(link) != 1L || is.na(link) ||
!nzchar(link)) {
stop(
"! `link` for `negbin_family()` must be a single character string.",
"\ni Supported links are: ", supported_text, ".",
call. = FALSE
)
}
if (!link %in% supported) {
stop(
sprintf(
"! Unsupported link for `negbin_family()`: '%s'.",
link
),
"\ni Supported links are: ", supported_text,
". These are the links available in `fastglm::fastglm_nb()`.",
call. = FALSE
)
}
link
}
#' Links Supported for Negative-Binomial Models
#'
#' @return Character vector of supported negative-binomial links.
#'
#' @keywords internal
#' @noRd
mfp2_negbin_links <- function() {
c("log", "sqrt", "identity")
}
#' Resolve the Link of a Negative-Binomial Family Specification
#'
#' Accepts the normalized [negbin_family()] object and, for direct internal
#' helper calls, the legacy character label `"negbin"`, which denotes the log
#' link.
#'
#' @param family Negative-binomial family specification.
#'
#' @return The link as a character scalar.
#'
#' @keywords internal
#' @noRd
mfp2_negbin_link <- function(family) {
if (inherits(family, "mfp2_negbin_family")) {
return(mfp2_validate_negbin_link(family$link))
}
if (is.character(family) && length(family) == 1L &&
identical(as.vector(family), "negbin")) {
return("log")
}
stop(
"Internal error: expected a negative-binomial family specification.",
call. = FALSE
)
}
#' Does This Family Fit an Ordinary Intercept?
#'
#' Predicate used by the MFP/MFPI engine to decide whether the fitted-model
#' design matrix should carry an intercept column. Cox and Fine--Gray models
#' condition on the baseline hazard and therefore have no ordinary intercept;
#' every other supported family does.
#'
#' @param family_string Character scalar giving the canonical family name, one
#' of `"gaussian"`, `"binomial"`, `"poisson"`, `"Gamma"`,
#' `"inverse.gaussian"`, `"negbin"`, `"multinomial"`, `"ordinal"`, `"cox"`,
#' `"survreg"`, or `"finegray"`.
#'
#' @return `TRUE` when the family fits an ordinary intercept and `FALSE`
#' otherwise.
#'
#' @keywords internal
#' @noRd
mfp2_family_has_intercept <- function(family_string) {
!family_string %in% c("cox", "finegray")
}
#' Does the Candidate-Model Design Matrix Need an Explicit Intercept Column?
#'
#' The repeated candidate-model fits used by MFP need an explicit all-ones
#' intercept column only when the low-level fitter would otherwise estimate an
#' ordinary intercept from `x`. Ordinal models handled by `rms::orm.fit()` are
#' the exception: they estimate threshold intercepts internally, so no explicit
#' column is required in the caller-supplied design matrix.
#'
#' @param family_string Canonical family name, as documented in
#' `mfp2_family_has_intercept()`.
#'
#' @return `TRUE` if the candidate-model design matrix requires an explicit
#' intercept column, `FALSE` otherwise.
#'
#' @keywords internal
#' @noRd
mfp2_candidate_matrix_has_intercept <- function(family_string) {
mfp2_family_has_intercept(family_string) &&
!identical(family_string, "ordinal")
}
#' Does This Family Report an Event Count Rather Than a Continuous Deviance?
#'
#' Cox and Fine--Gray models are compared by event count when constructing
#' summary tables, since they lack an ordinary log-likelihood based
#' observation count.
#'
#' @param family_string Canonical family name.
#'
#' @return `TRUE` for Cox and Fine--Gray models, `FALSE` otherwise.
#'
#' @keywords internal
#' @noRd
mfp2_family_uses_event_count <- function(family_string) {
family_string %in% c("cox", "finegray")
}
#' Is This Family a Proportional-Hazards Model?
#'
#' Cox and Fine--Gray subdistribution hazards are both fitted through the
#' partial likelihood of a proportional-hazards structure.
#'
#' @param family_string Canonical family name.
#'
#' @return `TRUE` for `"cox"` and `"finegray"`; `FALSE` otherwise.
#'
#' @keywords internal
#' @noRd
mfp2_family_is_ph <- function(family_string) {
family_string %in% c("cox", "finegray")
}
#' Is This a Survival Family?
#'
#' Survival families are Cox proportional hazards, parametric accelerated
#' failure time via `survival::survreg()`, and Fine--Gray subdistribution
#' hazards.
#'
#' @param family_string Canonical family name.
#'
#' @return `TRUE` for `"cox"`, `"survreg"`, and `"finegray"`; `FALSE`
#' otherwise.
#'
#' @keywords internal
#' @noRd
mfp2_family_is_survival <- function(family_string) {
family_string %in% c("cox", "survreg", "finegray")
}
#' Is This a Likelihood GLM Family?
#'
#' Predicate distinguishing the six standard likelihood GLM families accepted
#' by `mfp2()` from multinomial, ordinal, and survival families that require
#' specialised fitters.
#'
#' @param family_string Canonical family name.
#'
#' @return `TRUE` when `family_string` is one of `"gaussian"`, `"binomial"`,
#' `"poisson"`, `"Gamma"`, `"inverse.gaussian"`, or `"negbin"`; `FALSE`
#' otherwise.
#'
#' @keywords internal
#' @noRd
mfp2_family_is_glm <- function(family_string) {
family_string %in% c(
"gaussian", "binomial", "poisson", "Gamma",
"inverse.gaussian", "negbin"
)
}
#' Is This the Multinomial Family?
#'
#' @param family_string Canonical family name.
#'
#' @return `TRUE` when `family_string` is exactly `"multinomial"`, `FALSE`
#' otherwise.
#'
#' @keywords internal
#' @noRd
mfp2_family_is_multinomial <- function(family_string) {
identical(family_string, "multinomial")
}
#' Is This the Ordinal (Proportional-Odds) Family?
#'
#' @param family_string Canonical family name.
#'
#' @return `TRUE` when `family_string` is exactly `"ordinal"`, `FALSE`
#' otherwise.
#'
#' @keywords internal
#' @noRd
mfp2_family_is_ordinal <- function(family_string) {
identical(family_string, "ordinal")
}
#' Number of Logits Fitted by the Family
#'
#' Reports the number of logit predictors estimated by the family. Every
#' non-multinomial family fits a single linear predictor. Multinomial models
#' fit one predictor per non-reference class; that number is stored in the
#' prepared-family metadata during model setup.
#'
#' @param family Prepared family object.
#' @param family_string Canonical family name.
#'
#' @return Integer scalar giving the number of fitted logit predictors.
#'
#' @keywords internal
#' @noRd
mfp2_family_n_logits <- function(family, family_string) {
if (!mfp2_family_is_multinomial(family_string)) return(1L)
if (is.null(family$prepared$n_logits)) {
stop("Internal error: multinomial family has not been prepared.", call. = FALSE)
}
as.integer(family$prepared$n_logits)
}
#' Number of Response Classes in a Multinomial Outcome
#'
#' Determines the number of response classes for a candidate multinomial
#' outcome. Class-count matrices are counted directly by the number of
#' columns; label vectors are counted by their number of unique levels after
#' coercion to a factor. Values that do not match any accepted response shape
#' return `NA_integer_`.
#'
#' @param y Response object: a class-count matrix, a factor, or a vector of
#' character, numeric, or logical class labels.
#'
#' @return Integer scalar with the number of response classes, or
#' `NA_integer_` for unsupported shapes.
#'
#' @keywords internal
#' @noRd
mfp2_multinomial_n_classes <- function(y) {
if (is.matrix(y)) return(ncol(y))
if (is.factor(y)) return(nlevels(y))
if (is.null(dim(y)) &&
(is.character(y) || is.numeric(y) || is.logical(y))) {
return(nlevels(factor(y)))
}
NA_integer_
}
#' Does the Family Estimate a Dispersion Parameter?
#'
#' Matches the nuisance-parameter convention of [stats::logLik()] so that
#' MFP information-criterion comparisons treat estimated dispersion as an
#' additional parameter. Recent versions of R let a family declare a fixed
#' dispersion explicitly; older family objects omit that field, in which case
#' the three traditional dispersion families (Gaussian, Gamma, inverse
#' Gaussian) estimate it from the fitted model.
#'
#' @param family Family object.
#' @param family_string Canonical family name.
#'
#' @return `TRUE` when the family estimates a dispersion parameter from the
#' fitted model, `FALSE` otherwise. Non-GLM and negative-binomial families
#' always return `FALSE`.
#'
#' @keywords internal
#' @noRd
mfp2_glm_estimates_dispersion <- function(family, family_string) {
if (!mfp2_family_is_glm(family_string) ||
identical(family_string, "negbin")) {
return(FALSE)
}
dispersion <- if (is.list(family)) family$dispersion else NULL
if (!is.null(dispersion)) {
return(length(dispersion) == 1L && is.na(dispersion))
}
family_string %in% c("gaussian", "Gamma", "inverse.gaussian")
}
#' Strip Prepared-Family Metadata Before Returning the Fitted Model
#'
#' Removes the internal caches attached to a prepared family object so that
#' the returned `mfp2` result does not carry MFP-specific fitting metadata.
#' The `mfp2_fit_flags` attribute and any `prepared` list slot are cleared;
#' the remainder of the family is left unchanged.
#'
#' @param family Prepared family object, possibly inheriting from
#' `"mfp2_family"`.
#'
#' @return The same family object with the `mfp2_fit_flags` attribute and
#' `prepared` slot removed.
#'
#' @keywords internal
#' @noRd
mfp2_strip_prepared_family <- function(family) {
attr(family, "mfp2_fit_flags") <- NULL
if (inherits(family, "mfp2_family")) family$prepared <- NULL
family
}
#' Prepare a `survreg`-Compatible Family for Repeated MFP Candidate Fits
#'
#' Builds the transformed response expected by [survival::survreg.fit()] once
#' per MFP analysis so it is not recomputed for every candidate model. This
#' function reproduces the non-formula portion of [survival::survreg()],
#' including distribution look-up, response validation, and reparameterisation
#' for censored, left-truncated, and interval-censored data.
#'
#' @param family Family object created by [survreg_family()]; must inherit
#' from `"mfp2_survreg_family"`.
#' @param y Response, typically a [survival::Surv()] object of one of the
#' censoring types supported by [survival::survreg()].
#' @param weights Optional numeric vector of strictly positive observation
#' weights. If `NULL`, all weights are set to `1`.
#' @param strata Optional stratification vector or factor used by
#' `survival::survreg()` to fit distinct scale parameters per stratum. May be
#' `NULL` for an unstratified analysis.
#'
#' @return A prepared family object carrying the transformed response,
#' validated weights, distribution list, and strata definition in a
#' `prepared` list slot, ready for repeated calls to
#' [survival::survreg.fit()] during MFP selection.
#'
#' @keywords internal
#' @noRd
prepare_survreg_family <- function(family, y, weights, strata = NULL) {
if (!inherits(family, "mfp2_survreg_family")) {
stop("Internal error: invalid survreg family specification.", call. = FALSE)
}
n <- NROW(y)
if (is.null(weights)) weights <- rep.int(1, n)
if (!is.numeric(weights) || length(weights) != n || anyNA(weights) ||
any(!is.finite(weights)) || any(weights <= 0)) {
stop("! `weights` must contain one finite positive value per observation.", call. = FALSE)
}
distributions <- survival::survreg.distributions
requested_dist <- family$dist
if (is.character(requested_dist)) {
dist_name <- tryCatch(
match.arg(requested_dist, names(distributions)),
error = function(e) {
stop("Invalid `survreg` distribution: ", conditionMessage(e), call. = FALSE)
}
)
dlist <- distributions[[dist_name]]
} else {
dist_name <- requested_dist
dlist <- requested_dist
}
distribution_test <- utils::getFromNamespace("survregDtest", "survival")
if (!is.list(dlist) || !isTRUE(distribution_test(dlist))) {
stop("! Invalid distribution object supplied to `survreg_family()`.", call. = FALSE)
}
y_fit <- y
type <- attr(y_fit, "type", exact = TRUE)
logcorrect <- 0
# For log-time distributions, an interval (0, upper] is mathematically left
# censored at its finite upper boundary. Convert it before applying log() so
# log(0) never enters the transformed interval. Keep this explicit local
# allow-list because upstream survival releases have historically misspelled
# the Log logistic distribution name in the corresponding boundary branch.
log_time_names <- c(
"Weibull", "Exponential", "Rayleigh", "Log Normal",
"Log logistic"
)
if (identical(type, "interval") && dlist$name %in% log_time_names) {
fix <- y_fit[, 1L] == 0 & y_fit[, 3L] == 3
if (any(fix)) {
y_fit[fix, ] <- cbind(y_fit[fix, 2L], 1, 2)
}
}
if (!is.null(dlist$trans)) {
exact <- y_fit[, NCOL(y_fit)] == 1
if (any(exact)) {
logcorrect <- sum(
weights[exact] * log(dlist$dtrans(y_fit[exact, 1L]))
)
}
if (identical(type, "interval")) {
if (any(y_fit[, 3L] == 3)) {
y_fit <- cbind(dlist$trans(y_fit[, 1:2, drop = FALSE]), y_fit[, 3L])
} else {
y_fit <- cbind(dlist$trans(y_fit[, 1L]), y_fit[, 3L])
}
} else if (identical(type, "left")) {
y_fit <- cbind(dlist$trans(y_fit[, 1L]), 2 - y_fit[, 2L])
} else {
y_fit <- cbind(dlist$trans(y_fit[, 1L]), y_fit[, 2L])
}
if (!all(is.finite(y_fit))) {
stop("! Invalid survival times for the requested `survreg` distribution.", call. = FALSE)
}
} else {
if (identical(type, "left")) {
y_fit[, 2L] <- 2 - y_fit[, 2L]
} else if (identical(type, "interval") && all(y_fit[, 3L] < 3)) {
y_fit <- y_fit[, c(1L, 3L), drop = FALSE]
}
}
distribution_has_fixed_scale <- !is.null(dlist$scale)
fit_scale <- family$scale
if (!is.null(dlist$scale)) {
if (isTRUE(family$scale_supplied)) {
warning(
dlist$name, " has a fixed scale; the value supplied to `survreg_family()` is ignored.",
call. = FALSE
)
}
fit_scale <- dlist$scale
}
if (!is.null(dlist$dist)) {
dlist <- if (is.atomic(dlist$dist)) {
distributions[[dlist$dist]]
} else {
dlist$dist
}
}
default_parms <- dlist$parms
requested_parms <- family$parms
if (is.null(default_parms)) {
if (!is.null(requested_parms)) {
stop("! The requested `survreg` distribution has no optional parameters.", call. = FALSE)
}
fit_parms <- NULL
} else {
if (!is.numeric(default_parms)) {
stop("Internal error: default survreg distribution parameters are not numeric.", call. = FALSE)
}
fit_parms <- default_parms
if (!is.null(requested_parms)) {
supplied <- unlist(requested_parms, use.names = TRUE)
if (is.null(names(supplied)) || any(!nzchar(names(supplied)))) {
if (length(supplied) != length(fit_parms)) {
stop(
"! Unnamed `parms` must have the same length as the distribution defaults.",
call. = FALSE
)
}
fit_parms[] <- supplied
} else {
invalid <- setdiff(names(supplied), names(fit_parms))
if (length(invalid) > 0L) {
stop(
"! Invalid `survreg` parameter name(s): ",
paste(invalid, collapse = ", "), ".",
call. = FALSE
)
}
fit_parms[names(supplied)] <- supplied
}
}
}
if (is.null(strata)) {
strata_factor <- factor(rep.int(1L, NROW(y_fit)))
} else {
strata_factor <- droplevels(normalize_cox_strata(strata, nobs = NROW(y_fit)))
}
nstrat <- nlevels(strata_factor)
if (fit_scale > 0 && nstrat > 1L) {
stop("! A fixed `survreg` scale cannot be combined with multiple scale strata.", call. = FALSE)
}
family$prepared <- list(
y = y_fit,
y_original = y,
dist = dlist,
dist_requested = requested_dist,
scale = fit_scale,
distribution_has_fixed_scale = distribution_has_fixed_scale,
parms = fit_parms,
logcorrect = logcorrect,
strata = as.integer(strata_factor),
strata_factor = strata_factor,
strata_supplied = !is.null(strata),
nstrat = nstrat,
n_original = NROW(y)
)
family
}
#' Prepare a Fine--Gray Subdistribution Family for MFP Candidate Fits
#'
#' Runs [survival::finegray()] once at the beginning of an MFP analysis and
#' retains the input-row mapping needed to expand each dynamically generated
#' fractional-polynomial candidate design matrix to the expanded weighted
#' data set. Repeating this expansion for every candidate model would be both
#' expensive and unnecessary, so the mapping is cached in the prepared
#' family's `prepared` slot.
#'
#' @param family Family object created by [finegray_family()]; must inherit
#' from `"mfp2_finegray_family"`.
#' @param y Multi-state right-censored response, typically a
#' [survival::Surv()] object with a factor-valued event column identifying
#' the competing causes.
#' @param weights Optional numeric vector of strictly positive observation
#' weights aligned with `y`. If `NULL`, unit weights are used.
#' @param strata Optional stratification vector or factor used by
#' [survival::finegray()] to stratify estimation of the censoring
#' distribution.
#' @param id Optional subject identifier vector. Required for a start--stop
#' multi-state response and optional for ordinary one-row-per-subject data.
#' @param offset Optional numeric offset vector aligned with `y`.
#'
#' @return A prepared Fine--Gray family object carrying the expanded response,
#' expansion weights, row-index mapping, event-of-interest indicator, and
#' strata definition in its `prepared` slot.
#'
#' @keywords internal
#' @noRd
prepare_finegray_family <- function(family, y, weights, strata = NULL, id = NULL,
offset = NULL) {
if (!inherits(family, "mfp2_finegray_family")) {
stop("Internal error: invalid Fine--Gray family specification.", call. = FALSE)
}
n <- NROW(y)
if (is.null(weights)) weights <- rep.int(1, n)
if (!is.numeric(weights) || length(weights) != n || anyNA(weights) ||
any(!is.finite(weights)) || any(weights <= 0)) {
stop("! `weights` must contain one finite positive value per observation.", call. = FALSE)
}
if (is.null(offset)) offset <- rep.int(0, n)
if (!is.numeric(offset) || length(offset) != n || anyNA(offset) ||
any(!is.finite(offset))) {
stop("! `offset` must contain one finite numeric value per observation.", call. = FALSE)
}
if (!is.null(id)) {
if (!is.atomic(id) || is.matrix(id) || !is.null(dim(id))) {
stop("! `id` must be an atomic vector or factor.", call. = FALSE)
}
if (length(id) != n || anyNA(id)) {
stop("! `id` must contain one non-missing subject identifier per observation.", call. = FALSE)
}
}
type <- attr(y, "type", exact = TRUE)
if (identical(type, "mcounting") && is.null(id)) {
stop("! Start--stop Fine--Gray data require the `id` argument.", call. = FALSE)
}
# Check a named event type here so that the censoring level or a misspelled
# level gets a clear message instead of survival::finegray()'s generic one.
states <- attr(y, "states", exact = TRUE)
if (!is.null(family$etype) && !is.numeric(family$etype) && !is.null(states) &&
!as.character(family$etype) %in% states) {
stop(
sprintf(
"! `etype = \"%s\"` is not an event type in the response.\ni Event types: %s. The censoring level cannot be used as `etype`.",
as.character(family$etype), paste(states, collapse = ", ")
),
call. = FALSE
)
}
original_row <- seq_len(n)
subject_id <- if (is.null(id)) original_row else id
d <- data.frame(
.mfp2_row_id = original_row,
.mfp2_subject_id = subject_id,
check.names = FALSE
)
d[[".mfp2_response"]] <- y
strata_action <- if (!is.null(family$strata_action)) family$strata_action else "both"
strata_factor <- if (is.null(strata)) {
NULL
} else {
normalize_cox_strata(strata, nobs = n)
}
rhs <- c(".mfp2_row_id", ".mfp2_subject_id")
# Pass strata to finegray() for stratified censoring weights when
# strata_action is "both" or "censoring". When "baseline", the censoring
# distribution is estimated pooling across strata (Zhou et al. ctype = 2).
stratify_censoring <- strata_action %in% c("both", "censoring")
if (!is.null(strata_factor) && stratify_censoring) {
d[[".mfp2_censor_strata"]] <- strata_factor
rhs <- c(rhs, "strata(.mfp2_censor_strata)")
}
fg_formula <- stats::as.formula(
paste(".mfp2_response ~", paste(rhs, collapse = " + ")),
env = environment()
)
fg_args <- list(
formula = fg_formula,
data = d,
weights = weights,
prefix = ".mfp2_fg",
count = ".mfp2_fg_count",
timefix = family$timefix
)
if (!is.null(family$etype)) fg_args$etype <- family$etype
if (identical(type, "mcounting")) fg_args$id <- subject_id
fg <- tryCatch(
do.call(survival::finegray, fg_args),
error = function(e) {
stop("Fine--Gray data preparation failed: ", conditionMessage(e), call. = FALSE)
}
)
required <- c(
".mfp2_row_id", ".mfp2_subject_id", ".mfp2_fgstart",
".mfp2_fgstop", ".mfp2_fgstatus", ".mfp2_fgwt"
)
missing_required <- setdiff(required, names(fg))
if (length(missing_required) > 0L) {
stop(
"Internal error: `finegray()` output is missing: ",
paste(missing_required, collapse = ", "), ".",
call. = FALSE
)
}
row_map <- as.integer(fg[[".mfp2_row_id"]])
y_fg <- survival::Surv(
fg[[".mfp2_fgstart"]],
fg[[".mfp2_fgstop"]],
fg[[".mfp2_fgstatus"]]
)
# When strata_action is "both" or "baseline", strata must be passed through
# to the weighted Cox fit for baseline subdistribution hazard stratification.
# Expand the original-row strata along the row_map so it aligns with the
# Fine--Gray pseudo-observations.
stratify_baseline <- strata_action %in% c("both", "baseline")
strata_expanded <- if (!is.null(strata_factor) && stratify_baseline) {
strata_factor[row_map]
} else {
NULL
}
family$prepared <- list(
y = y_fg,
weights = as.numeric(fg[[".mfp2_fgwt"]]),
row_map = row_map,
# The offset is invariant across all FP candidates. Expand it once along
# with the response and Fine--Gray weights instead of indexing the original
# vector for every weighted Cox fit.
offset_expanded = as.numeric(offset[row_map]),
subject_id = fg[[".mfp2_subject_id"]],
subject_id_original = subject_id,
# Expanded strata for baseline subdistribution hazard stratification.
# NULL when strata_action = "censoring" or when no strata are present.
strata_expanded = strata_expanded,
strata_expanded_codes = if (!is.null(strata_expanded)) {
as.integer(strata_expanded)
} else {
NULL
},
strata_original = if (!is.null(strata_factor) && stratify_baseline) {
strata_factor
} else {
NULL
},
event = attr(fg, "event", exact = TRUE),
nevents = sum(fg[[".mfp2_fgstatus"]] > 0),
n_original = n,
n_expanded = nrow(fg)
)
family
}
#' Prepare a Multinomial Family for MFP Candidate Fits
#'
#' Normalises the multinomial response, weights, and optional offset to the
#' compact representation expected by the direct baseline-category candidate
#' fitter and by the retained [nnet::multinom()] fit. This includes coercing
#' the response to a factor with the requested reference level, storing the
#' class order, and caching the number of response classes so that later
#' calls do not re-derive it.
#'
#' @param family Family object created by [multinomial_family()]; must
#' inherit from `"mfp2_multinomial_family"`.
#' @param y Response, one of: a factor, a character or numeric class-label
#' vector with at least three classes, or a numeric matrix with at least
#' three nonnegative integer class-count columns.
#' @param weights Optional numeric vector of strictly positive observation
#' weights. Unit weights are used when `NULL`.
#' @param offset Optional class-offset matrix (`n` by `C`) or
#' reference-logit offset matrix (`n` by `C - 1`).
#' @param has_offset Logical flag indicating whether an offset was supplied.
#' Defaults to `!is.null(offset)` and is exposed as an argument so callers
#' can override the detection.
#'
#' @return A prepared family object carrying the normalised response, class
#' labels, reference class, weights, offset, and class count in its
#' `prepared` slot.
#'
#' @keywords internal
#' @noRd
prepare_multinomial_family <- function(family, y, weights, offset = NULL,
has_offset = !is.null(offset)) {
if (!inherits(family, "mfp2_multinomial_family")) {
stop("Internal error: invalid multinomial family specification.", call. = FALSE)
}
n <- NROW(y)
if (is.null(weights)) weights <- rep.int(1, n)
if (!is.matrix(y)) {
if (!is.factor(y)) {
response_names <- names(y)
y <- factor(y)
names(y) <- response_names
}
levels_original <- levels(y)
reference <- family$reference
if (is.null(reference)) reference <- levels_original[[1L]]
reference <- as.character(reference)
if (!reference %in% levels_original) {
stop("! Multinomial `reference` is not a response level.", call. = FALSE)
}
levels_internal <- c(reference, setdiff(levels_original, reference))
y_native <- factor(y, levels = levels_internal)
y_matrix <- nnet::class.ind(y_native)
colnames(y_matrix) <- levels_internal
row_totals <- rep.int(1, n)
} else {
y_matrix <- unclass(y)
levels_original <- colnames(y_matrix)
if (is.null(levels_original) || any(!nzchar(levels_original))) {
levels_original <- paste0("class", seq_len(ncol(y_matrix)))
colnames(y_matrix) <- levels_original
}
if (anyDuplicated(levels_original)) {
stop("! Multinomial count-response column names must be unique.", call. = FALSE)
}
reference <- family$reference
if (is.null(reference)) {
reference_index <- 1L
} else if (is.numeric(reference)) {
reference_index <- as.integer(reference)
if (reference != reference_index || reference_index < 1L ||
reference_index > ncol(y_matrix)) {
stop("! Numeric multinomial `reference` is outside the response columns.", call. = FALSE)
}
} else {
reference_index <- match(as.character(reference), levels_original)
if (is.na(reference_index)) {
stop("! Multinomial `reference` is not a response column.", call. = FALSE)
}
}
reference <- levels_original[[reference_index]]
levels_internal <- c(reference, setdiff(levels_original, reference))
y_matrix <- y_matrix[, levels_internal, drop = FALSE]
y_native <- y_matrix
row_totals <- rowSums(y_matrix)
}
class_totals <- colSums(y_matrix * as.numeric(weights))
empty_classes <- names(class_totals)[class_totals <= 0]
if (length(empty_classes) > 0L) {
stop(
"! Every multinomial class must have positive weighted support; empty class(es): ",
paste(empty_classes, collapse = ", "), ".",
call. = FALSE
)
}
row_totals <- as.numeric(row_totals)
case_weights <- as.numeric(weights)
family$reference <- reference
family$prepared <- list(
y = y_native,
y_matrix = y_matrix,
# nnet::multinom() performs these two transformations internally. Cache
# them here because the direct nnet.default() candidate path reuses the
# same response and case weights for every transformed design.
y_fit = y_matrix / row_totals,
case_weights = case_weights,
effective_weights = case_weights * row_totals,
levels = levels_internal,
original_levels = levels_original,
reference = reference,
nonreference = levels_internal[-1L],
n_classes = ncol(y_matrix),
n_logits = ncol(y_matrix) - 1L,
row_totals = row_totals,
effective_n = sum(case_weights * row_totals),
has_offset = isTRUE(has_offset)
)
family$prepared$offset_matrix <- mfp2_prepare_multinomial_offset(
offset = offset,
prepared = family$prepared,
nobs = n,
has_offset = has_offset
)
family
}
#' Normalise a Multinomial Offset for Fitting
#'
#' Normalises a user-supplied multinomial offset once at the public fitting
#' boundary. Both the direct candidate fitter and the retained
#' [nnet::multinom()] fit then share the same class order and
#' reference-contrast representation, so the offset does not have to be
#' re-derived for every candidate model.
#'
#' @param offset Optional class-offset matrix (`n` by `C`) or
#' reference-logit offset matrix (`n` by `C - 1`).
#' @param prepared Prepared-multinomial metadata list, typically the
#' `prepared` slot of a family object.
#' @param nobs Integer number of observations.
#' @param has_offset Logical flag indicating whether an offset was supplied.
#'
#' @return An `n` by `C - 1` reference-logit offset matrix, or `NULL` when
#' `has_offset` is `FALSE`.
#'
#' @keywords internal
#' @noRd
mfp2_prepare_multinomial_offset <- function(offset, prepared, nobs,
has_offset) {
if (!isTRUE(has_offset)) return(NULL)
c_classes <- prepared$n_classes
q_logits <- prepared$n_logits
if (!is.numeric(offset) || anyNA(offset) || any(!is.finite(offset))) {
stop("! Multinomial offsets must be finite and numeric.", call. = FALSE)
}
if (is.null(dim(offset))) {
if (q_logits != 1L || length(offset) != nobs) {
stop(
"! Multinomial offsets must be an n x C class matrix or an n x (C - 1) reference-logit matrix.",
call. = FALSE
)
}
offset <- matrix(offset, ncol = 1L)
}
if (!is.matrix(offset) || nrow(offset) != nobs ||
!ncol(offset) %in% c(q_logits, c_classes)) {
stop(
"! Multinomial offsets must be an n x C class matrix or an n x (C - 1) reference-logit matrix.",
call. = FALSE
)
}
if (ncol(offset) == q_logits) {
logit_offset <- unclass(offset)
if (!is.null(colnames(logit_offset)) &&
all(prepared$nonreference %in% colnames(logit_offset))) {
logit_offset <- logit_offset[, prepared$nonreference, drop = FALSE]
}
result <- cbind(0, logit_offset)
colnames(result) <- prepared$levels
return(result)
}
result <- unclass(offset)
if (!is.null(colnames(result)) &&
all(prepared$levels %in% colnames(result))) {
result <- result[, prepared$levels, drop = FALSE]
} else {
original_index <- match(prepared$levels, prepared$original_levels)
result <- result[, original_index, drop = FALSE]
}
result <- sweep(result, 1L, result[, 1L], "-")
colnames(result) <- prepared$levels
result
}
#' Multinomial Offset for Prediction
#'
#' Returns a class-logit offset matrix suitable for prediction. Prediction
#' paths need an explicit zero matrix so that class-logit arithmetic can
#' remain branch-free even when no offset was supplied at fitting time.
#' Fitting preparation instead stores `NULL` for no offset, so this helper
#' materialises the zero matrix on demand.
#'
#' @param offset Optional class-offset matrix supplied at prediction, or
#' `NULL`.
#' @param family Prepared multinomial family object.
#' @param nobs Integer number of prediction rows.
#' @param has_offset Logical flag indicating whether a prediction-time offset
#' was supplied.
#'
#' @return An `n` by `C - 1` reference-logit offset matrix. When `has_offset`
#' is `FALSE`, the matrix is filled with zeros.
#'
#' @keywords internal
#' @noRd
mfp2_multinomial_offset <- function(offset, family, nobs, has_offset) {
prepared <- family$prepared
if (!isTRUE(has_offset)) {
return(matrix(
0,
nrow = nobs,
ncol = prepared$n_classes,
dimnames = list(NULL, prepared$levels)
))
}
mfp2_prepare_multinomial_offset(
offset = offset,
prepared = prepared,
nobs = nobs,
has_offset = TRUE
)
}
# Encode the ordinal response into integer codes 1..k once, so every candidate
# fit reuses the same compact representation. The category order follows
# rms::orm(): an ordered factor uses its level order; a numeric response is
# ordered ascending; a character or unordered factor is ordered by
# sort(unique()), i.e. alphabetically. When the order is inferred from an
# unordered categorical, an informational message names the assumed order so a
# wrong (alphabetical) ordering is catchable.
#' Prepare an Ordinal (Proportional-Odds) Family for MFP Candidate Fits
#'
#' Coerces the ordinal response to the compact representation used by both
#' the MFP candidate-model path and the retained `rms::orm()` fit. The
#' category order follows [rms::orm()]: ordered factors keep their level
#' order; numeric responses are ordered ascending; character or unordered
#' factor responses are ordered by `sort(unique())` (alphabetically). When
#' the order has to be inferred from an unordered categorical response, an
#' informational message names the assumed order so that an unintended
#' alphabetical ordering can be spotted and corrected.
#'
#' @param family Family object created by [ordinal_family()]; must inherit
#' from `"mfp2_ordinal_family"`.
#' @param y Ordinal response. An ordered factor is recommended so that the
#' category order is explicit.
#' @param weights Optional finite, strictly positive numeric case weights.
#' They are cached without normalisation; NULL uses unit weights.
#' @param offset Optional numeric offset vector.
#' @param has_offset Logical flag indicating whether an offset was supplied.
#'
#' @return A prepared family object carrying the ordered response, category
#' labels, weights, and offset in its `prepared` slot.
#'
#' @keywords internal
#' @noRd
prepare_ordinal_family <- function(family, y, weights, offset = NULL,
has_offset = !is.null(offset)) {
if (!inherits(family, "mfp2_ordinal_family")) {
stop("Internal error: invalid ordinal family specification.", call. = FALSE)
}
if (!requireNamespace("rms", quietly = TRUE)) {
stop(
"! `family = ordinal_family()` requires the `rms` package. ",
"Install it with install.packages(\"rms\").",
call. = FALSE
)
}
if (utils::packageVersion("rms") < "7.0-0") {
stop(
"! `family = ordinal_family()` requires `rms` version 7.0-0 or later. ",
"Update it with install.packages(\"rms\").",
call. = FALSE
)
}
# Validate once and reuse the same unnormalised case weights in every fit.
validate_model_weights(weights, nobs = NROW(y))
if (is.null(weights)) weights <- rep.int(1, NROW(y))
if (!is.null(dim(y))) {
stop("! The ordinal response must be a vector, not a matrix.", call. = FALSE)
}
inferred_order <- FALSE
if (is.ordered(y)) {
# Matrix-interface callers can supply a factor that still carries levels
# removed by an earlier subset. orm.fit() bases its intercept count on the
# observed response values, so retain the same invariant here and recode the
# response contiguously to 1..k.
y <- droplevels(y)
levels_ordered <- levels(y)
codes <- as.integer(y)
} else if (is.factor(y)) {
# Unordered factor: rms orders by sort(unique()) = sorted level labels.
y <- droplevels(y)
levels_ordered <- sort(unique(as.character(y)))
codes <- match(as.character(y), levels_ordered)
inferred_order <- TRUE
} else if (is.numeric(y)) {
levels_ordered <- sort(unique(y))
codes <- match(y, levels_ordered)
} else if (is.character(y) || is.logical(y)) {
levels_ordered <- sort(unique(as.character(y)))
codes <- match(as.character(y), levels_ordered)
inferred_order <- TRUE
} else {
stop(
"! The ordinal response must be an ordered factor, factor, numeric, ",
"integer, character, or logical vector.",
call. = FALSE
)
}
levels_labels <- as.character(levels_ordered)
k <- length(levels_labels)
if (inferred_order) {
message(
"Ordinal response order inferred as: ",
paste(levels_labels, collapse = " < "),
". Supply an ordered factor or numeric codes to set a different order."
)
}
family$prepared <- list(
y = as.integer(codes), # integer codes 1..k in ascending order
levels = levels_labels,
n_classes = k,
n_intercepts = k - 1L,
link = family$link,
inferred_order = inferred_order,
n_original = length(codes),
weights = weights,
has_offset = isTRUE(has_offset),
offset = if (isTRUE(has_offset)) as.numeric(offset) else NULL
)
family
}
#' Dispatch Family-Specific Preparation Before MFP Selection
#'
#' Top-level dispatcher that routes each supported family to its dedicated
#' `prepare_*` helper. This is called once at the start of an MFP analysis so
#' that the family-specific response transformation, weight handling, offset
#' setup, and any cached metadata are constructed a single time and reused
#' across every candidate model fit.
#'
#' @param family Family object supplied by the user. Its concrete class
#' determines which specialised preparation routine is invoked.
#' @param family_string Canonical family name used by the MFP engine.
#' @param y Response object.
#' @param weights Optional numeric vector of observation weights.
#' @param strata Optional stratification vector or matrix used by survival
#' families.
#' @param id Optional subject identifier used by Fine--Gray models.
#' @param offset Optional numeric offset (or class-offset matrix for
#' multinomial models).
#' @param has_offset Logical flag indicating whether an offset was supplied.
#' Defaults to `!is.null(offset)`.
#'
#' @return The prepared family object, with any family-specific caches
#' populated in its `prepared` slot. Families that require no special
#' preparation are returned unchanged.
#'
#' @keywords internal
#' @noRd
prepare_family_for_fit <- function(family, family_string, y, weights,
strata = NULL, id = NULL, offset = NULL,
has_offset = !is.null(offset),
waves = NULL, control = NULL) {
if (identical(family_string, "gee")) {
family <- prepare_gee_family(
family, y = y, id = id, waves = waves, weights = weights,
offset = offset, control = control
)
return(list(family = family, strata = strata))
}
if (identical(family_string, "survreg")) {
family <- prepare_survreg_family(family, y, weights, strata)
return(list(family = family, strata = strata))
}
if (identical(family_string, "finegray")) {
family <- prepare_finegray_family(
family, y, weights, strata, id, offset = offset
)
# Strata handling depends on strata_action (Zhou et al. 2011):
# "both" — strata used for censoring (in finegray) AND baseline hazard
# "censoring"— strata used for censoring only; baseline hazard is common
# "baseline" — strata used for baseline hazard only; censoring is pooled
# The expanded strata for the Cox fit are stored in family$prepared by
# prepare_finegray_family() and consumed by fit_finegray(); return NULL
# here because fit_finegray reads them from prepared$strata_expanded
# (not from the strata argument passed through fit_model).
return(list(family = family, strata = NULL))
}
if (identical(family_string, "multinomial")) {
family <- prepare_multinomial_family(
family, y, weights, offset = offset, has_offset = has_offset
)
return(list(family = family, strata = strata))
}
if (identical(family_string, "cox")) {
if (!is.null(strata)) {
# Keep the normalized factor for the retained formula fit and cache the
# low-level integer representation used by every coxph.fit() candidate.
attr(strata, "mfp2_integer_codes") <- as.integer(strata)
}
return(list(family = family, strata = strata))
}
if (identical(family_string, "ordinal")) {
family <- prepare_ordinal_family(
family, y, weights, offset = offset, has_offset = has_offset
)
return(list(family = family, strata = strata))
}
if (mfp2_family_is_glm(family_string)) {
# These family properties are invariant across every candidate fit. Cache
# them on the resolved family object so fit_glm() does not rediscover them
# inside the repeated FP search.
attr(family, "mfp2_fit_flags") <- list(
is_gaussian = identical(family_string, "gaussian"),
is_negbin = identical(family_string, "negbin"),
estimates_dispersion = mfp2_glm_estimates_dispersion(
family = family,
family_string = family_string
)
)
if (identical(family_string, "negbin")) {
attr(family, "mfp2_fit_flags")$negbin_link <- mfp2_negbin_link(family)
}
}
list(family = family, strata = strata)
}
#' Normalize and validate a model family
#'
#' @param family Character family name, GLM family function/object, or an mfp2
#' survival-family specification.
#' @param family_arg Character label used in error messages for function inputs.
#'
#' @return A list with elements:
#' \describe{
#' \item{\code{family}}{A resolved fitting-family object or character label.}
#' \item{\code{family_string}}{The normalized character family name.}
#' }
#'
#' @keywords internal
#' @noRd
normalize_family_argument <- function(family, family_arg = deparse(substitute(family))) {
allowed_glm_families <- c(
"gaussian", "binomial", "poisson", "Gamma", "inverse.gaussian"
)
allowed_families <- c(
allowed_glm_families, "negbin", "multinomial", "cox", "survreg",
"finegray", "ordinal"
)
family_arg <- paste(family_arg, collapse = " ")
if (inherits(family, "mfp2_family")) {
family_string <- family$family
if (!is.character(family_string) || length(family_string) != 1L ||
!family_string %in% c("survreg", "finegray", "multinomial", "ordinal",
"gee", "negbin")) {
stop("! Invalid mfp2 family specification.", call. = FALSE)
}
if (identical(family_string, "negbin")) {
if (!inherits(family, "mfp2_negbin_family")) {
stop("! Invalid mfp2 family specification.", call. = FALSE)
}
# Re-validate in case the specification was modified after construction.
mfp2_validate_negbin_link(family$link)
}
return(list(family = family, family_string = family_string))
}
if (is.character(family)) {
if (length(family) != 1L) {
stop(
sprintf(
"! `family` must be a single character string; got %d values: %s.",
length(family),
paste(family, collapse = ", ")
),
"\ni Supported character families are: gaussian, binomial, poisson, Gamma, inverse.gaussian, negbin, multinomial, cox, survreg, finegray.",
call. = FALSE
)
}
family_key <- tolower(family)
family <- switch(
family_key,
gaussian = "gaussian",
binomial = "binomial",
poisson = "poisson",
gamma = "Gamma",
inverse.gaussian = "inverse.gaussian",
negbin = "negbin",
multinomial = "multinomial",
cox = "cox",
survreg = "survreg",
finegray = "finegray",
ordinal = "ordinal",
family
)
if (grepl("^quasi", family_key)) {
stop(
sprintf("! Family '%s' has no likelihood and is not supported by likelihood-based MFP selection.", family_key),
call. = FALSE
)
}
if (!family %in% allowed_families) {
stop(
sprintf("! Invalid family: '%s'.", family),
sprintf(
"\ni Supported character families are: %s.",
paste(allowed_families, collapse = ", ")
),
call. = FALSE
)
}
family_obj <- if (identical(family, "cox")) {
family
} else if (identical(family, "negbin")) {
# Backward-compatible shorthand for negbin_family(link = "log").
negbin_family(link = "log")
} else if (identical(family, "multinomial")) {
multinomial_family()
} else if (identical(family, "survreg")) {
survreg_family()
} else if (identical(family, "finegray")) {
finegray_family()
} else if (identical(family, "ordinal")) {
ordinal_family()
} else {
switch(
family,
gaussian = stats::gaussian(),
binomial = stats::binomial(),
poisson = stats::poisson(),
Gamma = stats::Gamma(),
inverse.gaussian = stats::inverse.gaussian()
)
}
return(list(
family = family_obj,
family_string = family
))
}
if (is.function(family)) {
family_obj <- tryCatch(
family(),
error = function(e) {
stop(
sprintf(
"! Could not create a family object from the provided function `%s`. Error: %s",
family_arg,
conditionMessage(e)
),
call. = FALSE
)
}
)
if (!inherits(family_obj, "family")) {
stop(
sprintf(
"! The provided function `%s` did not return a valid GLM family object.",
family_arg
),
call. = FALSE
)
}
family_string <- family_obj$family
if (identical(family_string, "cox")) {
stop(
"! `cox` must be specified as a character string, not as a function.",
call. = FALSE
)
}
if (grepl("^quasi", tolower(family_string))) {
stop(
sprintf(
"! Family returned by `%s` has no likelihood and is not supported by likelihood-based MFP selection.",
family_arg
),
call. = FALSE
)
}
if (!family_string %in% allowed_glm_families) {
stop(
sprintf(
"! Invalid family returned by `%s`: '%s'. Supported families are: %s.",
family_arg,
family_string,
paste(allowed_glm_families, collapse = ", ")
),
call. = FALSE
)
}
return(list(
family = family_obj,
family_string = family_string
))
}
if (inherits(family, "family")) {
family_string <- family$family
if (identical(family_string, "cox")) {
stop(
"! `cox` must be specified as a character string, not as a family object.",
call. = FALSE
)
}
if (grepl("^quasi", tolower(family_string))) {
stop(
"! Quasi families have no likelihood and are not supported by likelihood-based MFP selection.",
call. = FALSE
)
}
if (!family_string %in% allowed_glm_families) {
stop(
sprintf(
"! Invalid family: '%s'. Supported families are: %s.",
family_string,
paste(allowed_glm_families, collapse = ", ")
),
call. = FALSE
)
}
return(list(
family = family,
family_string = family_string
))
}
stop(
"! `family` must be a character string, a GLM family function/object, or an mfp2 family specification.",
call. = FALSE
)
}
#' Extract family name for the formula interface
#'
#' Internal helper used by `mfp2.formula()` to determine the family name before
#' calling `mfp2.default()`. This is needed because the formula interface must
#' know whether Cox-specific formula terms such as `strata()` are allowed, but
#' family validation and normalization are still handled by `mfp2.default()`.
#'
#' @param family A character family name, a GLM family function, or a GLM family
#' object.
#'
#' @return A single character string giving the family name.
#'
#' @keywords internal
#' @noRd
get_family_string_formula <- function(family, family_arg = deparse(substitute(family))) {
normalize_family_argument(
family,
family_arg = family_arg
)$family_string
}
#' Resolve a model family once for repeated internal fits
#'
#' @param family Character family name, family function, family object, or an
#' mfp2 survival-family specification.
#' @return A resolved GLM family object, the character Cox label, or an mfp2
#' family specification (including negative-binomial specifications).
#' @keywords internal
#' @noRd
resolve_fit_model_family <- function(family) {
normalize_family_argument(family)$family
}
#' Validate response against model family
#'
#' Validates the response object `y` after the family has been normalized.
#' This function checks only response shape and family-specific admissibility;
#' it does not modify `y`.
#'
#' @param y Response vector, matrix, factor, or `survival::Surv()` object.
#' @param family_string Normalized supported family name.
#' @param nobs Expected number of observations.
#'
#' @return Invisibly returns `TRUE`.
#'
#' @keywords internal
#' @noRd
validate_family_response <- function(y, family_string, nobs) {
if (!is.character(family_string) || length(family_string) != 1L) {
stop("! `family_string` must be a single character string.", call. = FALSE)
}
if (!is.numeric(nobs) || length(nobs) != 1L ||
anyNA(nobs) || !is.finite(nobs) || nobs < 1L) {
stop("! `nobs` must be a positive finite scalar.", call. = FALSE)
}
if (family_string == "cox") {
if (!survival::is.Surv(y)) {
stop(
"! For `family = 'cox'`, `y` must be a `survival::Surv()` object.",
call. = FALSE
)
}
if (NROW(y) != nobs) {
stop(
paste0(
"! `y` has ", NROW(y), " rows but `x` has ", nobs,
" rows; they must match."
),
call. = FALSE
)
}
type <- attr(y, "type", exact = TRUE)
if (!identical(type, "right")) {
stop(
paste0(
"! Only right-censored survival data are currently supported; ",
"`y` has censoring type '", type, "'."
),
call. = FALSE
)
}
if (anyNA(y) || any(!is.finite(as.matrix(y)))) {
stop(
"! For `family = 'cox'`, `y` must contain only finite, non-missing values.",
call. = FALSE
)
}
return(invisible(TRUE))
}
if (family_string == "survreg") {
if (!survival::is.Surv(y)) {
stop(
"! For `family = survreg_family()`, `y` must be a `survival::Surv()` object.",
call. = FALSE
)
}
if (NROW(y) != nobs) {
stop("! `y` and `x` must contain the same number of observations.", call. = FALSE)
}
type <- attr(y, "type", exact = TRUE)
if (!type %in% c("right", "left", "interval", "interval2")) {
stop(
sprintf("! `survreg` does not support survival response type '%s'.", type),
call. = FALSE
)
}
if (anyNA(y) || any(!is.finite(as.matrix(y)))) {
stop("! The parametric survival response must contain only finite, non-missing values.", call. = FALSE)
}
return(invisible(TRUE))
}
if (family_string == "finegray") {
if (!survival::is.Surv(y)) {
stop(
"! For `family = finegray_family()`, `y` must be a multi-state `survival::Surv()` object.",
call. = FALSE
)
}
if (NROW(y) != nobs) {
stop("! `y` and `x` must contain the same number of observations.", call. = FALSE)
}
type <- attr(y, "type", exact = TRUE)
if (!type %in% c("mright", "mcounting")) {
stop(
sprintf("! Fine--Gray requires a multi-state response; `y` has type '%s'.", type),
call. = FALSE
)
}
states <- attr(y, "states", exact = TRUE)
if (length(states) < 2L) {
stop("! Fine--Gray requires at least two event states.", call. = FALSE)
}
if (anyNA(y) || any(!is.finite(as.matrix(y)))) {
stop("! The Fine--Gray response must contain only finite, non-missing values.", call. = FALSE)
}
return(invisible(TRUE))
}
if (survival::is.Surv(y)) {
stop(
paste0(
"! Response is a `survival::Surv()` object but family = '",
family_string, "'. Select `family = 'cox'`, `survreg_family()`, or ",
"`finegray_family()` as appropriate."
),
call. = FALSE
)
}
if (NROW(y) != nobs) {
stop(
paste0(
"! `y` has ", NROW(y), " observations but `x` has ", nobs,
" rows; they must match."
),
call. = FALSE
)
}
if (is.data.frame(y)) {
stop(
"! `y` must not be a data frame.",
call. = FALSE
)
}
if (family_string == "multinomial") {
is_label_vector <- is.factor(y) ||
(is.null(dim(y)) &&
(is.character(y) || is.numeric(y) || is.logical(y)))
if (is_label_vector) {
if (anyNA(y)) {
stop("! Multinomial class-label responses must not contain missing values.", call. = FALSE)
}
if (is.numeric(y) && any(!is.finite(y))) {
stop("! Numeric multinomial class labels must be finite.", call. = FALSE)
}
if (nlevels(if (is.factor(y)) y else factor(y)) < 3L) {
stop(
"! Multinomial class-label responses must contain at least three classes.",
call. = FALSE
)
}
return(invisible(TRUE))
}
if (!is.matrix(y) || !is.numeric(y) || ncol(y) < 3L) {
stop(
"! For `family = \"multinomial\"`, `y` must be a factor or character/numeric class-label vector with at least three classes, or a numeric count matrix with at least three columns.",
call. = FALSE
)
}
if (anyNA(y) || any(!is.finite(y)) || any(y < 0) || any(y != floor(y))) {
stop("! Multinomial response counts must be finite non-negative integers.", call. = FALSE)
}
if (any(rowSums(y) <= 0)) {
stop("! Every multinomial count-response row must contain at least one trial.", call. = FALSE)
}
return(invisible(TRUE))
}
if (family_string == "ordinal") {
if (!is.null(dim(y))) {
stop("! For `family = ordinal_family()`, `y` must be a vector, not a matrix.", call. = FALSE)
}
if (!(is.factor(y) || is.numeric(y) || is.character(y) || is.logical(y))) {
stop(
"! For `family = ordinal_family()`, `y` must be an ordered factor, factor, numeric, integer, character, or logical vector.",
call. = FALSE
)
}
if (anyNA(y)) {
stop("! The ordinal response must not contain missing values.", call. = FALSE)
}
if (is.numeric(y) && any(!is.finite(y))) {
stop("! A numeric ordinal response must contain only finite values.", call. = FALSE)
}
n_levels <- if (is.factor(y)) nlevels(droplevels(y)) else length(unique(y))
if (n_levels < 3L) {
stop(
"! An ordinal response must have at least three distinct ordered categories; ",
"use `family = 'binomial'` for a two-level response.",
call. = FALSE
)
}
return(invisible(TRUE))
}
if (is.matrix(y)) {
if (family_string != "binomial") {
stop(
"! Matrix responses are only supported for `family = 'binomial'`.\n",
"i For grouped binomial counts, use `y = cbind(successes, failures)`.",
call. = FALSE
)
}
if (!is.numeric(y) || ncol(y) != 2L) {
stop(
"! For `family = 'binomial'`, matrix `y` must be a numeric two-column matrix.\n",
"i Use `y = cbind(successes, failures)`.",
call. = FALSE
)
}
if (anyNA(y) || any(!is.finite(y)) || any(y < 0) ||
any(y != floor(y))) {
stop(
paste0(
"! For `family = 'binomial'`, matrix `y` counts must be finite, ",
"non-missing, non-negative integers."
),
call. = FALSE
)
}
if (any(rowSums(y) <= 0)) {
stop(
"! For `family = 'binomial'`, each row of matrix `y` must contain at least one trial.",
call. = FALSE
)
}
return(invisible(TRUE))
}
if (family_string == "gaussian") {
if (!is.numeric(y)) {
stop(
"! For `family = 'gaussian'`, `y` must be a numeric vector.",
call. = FALSE
)
}
if (anyNA(y) || any(!is.finite(y))) {
stop(
"! For `family = 'gaussian'`, `y` must contain only finite, non-missing values.",
call. = FALSE
)
}
return(invisible(TRUE))
}
if (family_string %in% c("Gamma", "inverse.gaussian")) {
if (!is.numeric(y)) {
stop(
sprintf("! For `family = '%s'`, `y` must be a numeric vector.", family_string),
call. = FALSE
)
}
if (anyNA(y) || any(!is.finite(y)) || any(y <= 0)) {
stop(
sprintf(
"! For `family = '%s'`, `y` must contain only finite, non-missing, strictly positive values.",
family_string
),
call. = FALSE
)
}
return(invisible(TRUE))
}
if (family_string == "negbin") {
if (!is.numeric(y)) {
stop(
"! For `family = 'negbin'`, `y` must be a numeric vector of counts.",
call. = FALSE
)
}
if (anyNA(y) || any(!is.finite(y)) || any(y < 0) || any(y != floor(y))) {
stop(
"! For `family = 'negbin'`, `y` must contain only finite, non-missing, non-negative integer counts.",
call. = FALSE
)
}
return(invisible(TRUE))
}
if (family_string == "poisson") {
if (!is.numeric(y)) {
stop(
"! For `family = 'poisson'`, `y` must be a numeric vector.",
call. = FALSE
)
}
if (anyNA(y) || any(!is.finite(y)) || any(y < 0) ||
any(y != floor(y))) {
stop(
paste0(
"! For `family = 'poisson'`, `y` must contain only finite, ",
"non-missing, non-negative integer counts."
),
call. = FALSE
)
}
return(invisible(TRUE))
}
if (family_string == "binomial") {
if (is.factor(y)) {
if (nlevels(y) != 2L) {
stop(
"! For `family = 'binomial'`, factor `y` must have exactly two levels.",
call. = FALSE
)
}
if (anyNA(y)) {
stop(
"! For `family = 'binomial'`, factor `y` must not contain missing values.",
call. = FALSE
)
}
return(invisible(TRUE))
}
if (is.numeric(y)) {
if (anyNA(y) || any(!is.finite(y))) {
stop(
"! For `family = 'binomial'`, numeric `y` must contain only finite, non-missing values.",
call. = FALSE
)
}
if (any(y < 0 | y > 1)) {
stop(
"! For `family = 'binomial'`, numeric `y` must contain values in [0, 1].",
call. = FALSE
)
}
return(invisible(TRUE))
}
stop(
"! For `family = 'binomial'`, `y` must be a numeric vector, two-level factor, or numeric two-column matrix.",
call. = FALSE
)
}
stop(
paste0("! Unsupported family: '", family_string, "'."),
call. = FALSE
)
}
Any scripts or data that you put into this service are public.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.