Fast Stereotype (Reduced-Rank Multinomial) Logistic Regression (C++)

Fits Anderson's stereotype logit model — a reduced-rank multinomial logit for a categorical (nominal or ordinal) response with $K$ distinct observed levels, using a single linear predictor $\eta_i = x_i^\top\beta$ scaled by a category-specific "score" $\phi_k \in [0, 1]$: $$\Pr(Y_i = k \mid x_i) = \frac{\exp(\alpha_k + \phi_k \eta_i)} {\sum_{l=1}^K \exp(\alpha_l + \phi_l \eta_i)}, \qquad \alpha_1 := 0,\ \phi_1 := 0,\ \phi_K := 1,$$ with free intercepts $\alpha_2, \ldots, \alpha_K$ and free interior scores $\phi_2, \ldots, \phi_{K-1}$ reparameterized via unconstrained $\gamma_1, \ldots, \gamma_{K-2}$ as cumulative softmax-style partial sums, $\phi_{j} = \left(\sum_{r \le j-2} e^{\gamma_r}\right) \big/ \left(1 + \sum_r e^{\gamma_r}\right)$ for $j = 2, \ldots, K-1$, which guarantees $0 = \phi_1 \le \phi_2 \le \cdots \le \phi_{K-1} \le \phi_K = 1$ without an explicit constraint. A single $\hat\beta$ therefore governs the covariate effect for every category, with the fitted $\hat\phi_k$ determining how much of that effect applies to category $k$ — collapsing categories with similar fitted scores are "stereotyped" together, which is the model's namesake use case (a parsimony-inducing alternative to full multinomial or ordinal cumulative-link models when categories are not clearly ordered but the covariate effect is plausibly one-dimensional). K = 2 reduces exactly to ordinary binary logistic regression ($\phi_2 = 1$ by construction, no $\gamma$ parameters). At least 2 distinct observed outcome categories are required; fewer throws an error. Fitting optimizes the joint parameter vector $[\alpha_2, \ldots, \alpha_K, \beta, \gamma_1, \ldots, \gamma_{K-2}]$ via optimization_alg (default "newton_raphson"), using this model's analytic gradient and Hessian.

Usage

fast_stereotype_logit_cpp(
  X,
  y,
  maxit = 100L,
  tol = 1e-08,
  smart_cold_start = TRUE,
  fixed_idx = NULL,
  fixed_values = NULL,
  optimization_alg = "newton_raphson",
  warm_start_fisher_info = NULL,
  warm_start_params = NULL,
  warm_start_beta = NULL,
  estimate_only = FALSE
)

Arguments

X: A numeric matrix of predictors (no intercept column needed; the category intercepts alpha serve that role).
y: A numeric vector of categorical (nominal or ordinal) responses; only the set of distinct values matters (mapped to $1, \ldots, K$ by sorted rank), not their numeric coding or order.
maxit: Maximum number of optimizer iterations.
tol: Convergence tolerance.
smart_cold_start: Present for interface parity with sibling functions but currently has no effect: starting values always come from initialize_params() (log empirical category-count ratios for alpha, zero for beta/gamma) unless overridden by warm_start_params/warm_start_beta.
fixed_idx: Optional 1-indexed positions (into the joint parameter vector, alpha first) of parameters to hold fixed.
fixed_values: Optional values, parallel to fixed_idx, of the fixed parameters.
optimization_alg: Optimization algorithm (default "newton_raphson").
warm_start_fisher_info: Optional initial curvature matrix for the first optimizer iteration.
warm_start_params: Optional starting values for the full joint parameter vector. Takes precedence over warm_start_beta.
warm_start_beta: Optional starting values for $\beta$ alone (ignored if warm_start_params is supplied).
estimate_only: If TRUE, skip computing the observed-information matrix and return only point estimates.

Value

A list with components b ($\hat\beta$), alpha (the $K-1$ free intercepts), scores_raw (the raw $\hat\gamma$ reparameterization parameters, length $\max(0, K-2)$; recover $\hat\phi$ from these via the cumulative-softmax formula above), params (the full fitted joint parameter vector), neg_loglik, converged, and, unless estimate_only = TRUE, fisher_information (the negative Hessian of the log-likelihood at the fitted parameters — despite the name, this is the observed, not expected, information).

Fast Stereotype (Reduced-Rank Multinomial) Logistic Regression (C++)

Usage

Arguments

Value

See also