psychonetrics (version 0.15)

penalize: Penalized Maximum Likelihood Functions

Description

Functions for penalized maximum likelihood (PML) and penalized full-information maximum likelihood (PFIML) estimation. penalize adds an L1 (LASSO) or elastic net penalty to specified model parameters. unpenalize removes the penalty. penaltyVector extracts the per-free-parameter penalty strengths. refit performs post-selection inference by fixing penalized zeros and re-running with standard ML (or FIML for PFIML) estimation to obtain standard errors.

Usage

penalize(x, matrix, row, col, lambda, group, verbose, log = TRUE)
unpenalize(x, matrix, row, col, group, verbose, log = TRUE)
penaltyVector(x)
refit(x, threshold = 1e-8, verbose, log = TRUE, ...)

Value

penalize, unpenalize, and refit return an object of class psychonetrics (psychonetrics-class). penaltyVector returns a numeric vector of penalty strengths per free parameter.

Arguments

x

A psychonetrics model.

matrix

Character vector of matrix name(s) to penalize/unpenalize. If missing, defaults to the matrices returned by defaultPenalizeMatrices(x) for penalize, or all currently penalized matrices for unpenalize.

row

Integer or character indicating specific row(s) of the matrix. If missing, the entire matrix is penalized/unpenalized.

col

Integer or character indicating specific column(s) of the matrix. If missing, the entire matrix is penalized/unpenalized.

lambda

Numeric, the penalty strength per parameter. If missing, uses the global x@penalty$lambda.

group

Integer indicating specific group(s). If missing, all groups are included.

verbose

Logical, should messages be printed?

log

Logical, should the log be updated?

threshold

For refit: threshold below which penalized parameters are considered zero and fixed.

...

Additional arguments passed to runmodel in refit.

Author

Sacha Epskamp

Details

Penalized ML estimation uses the "PML" estimator, which wraps the standard ML fit function and gradient with an additional penalty term. For models with missing data, the "PFIML" estimator wraps the FIML fit function and gradient with the same penalty. The ISTA (Iterative Shrinkage-Thresholding Algorithm) proximal gradient optimizer is used automatically for both PML and PFIML models.

For symmetric matrices (e.g., omega), only off-diagonal elements are penalized by default. For non-symmetric matrices (e.g., beta), all elements are penalized.

The refit function is used for post-selection inference: after a penalized model is estimated, refit fixes parameters that were shrunk to zero and re-estimates the model with standard ML (for PML) or FIML (for PFIML) to obtain valid standard errors and fit indices.

Model constructors (e.g., ggm, lvm, var1) accept penalty_lambda, penalty_alpha, and penalize_matrices arguments for convenient PML/PFIML setup. When missing = "auto" (the default), specifying estimator = "PML" with missing data will automatically switch to "PFIML".

See Also

find_penalized_lambda for automatic lambda selection via EBIC grid search, runmodel for running models (calls find_penalized_lambda automatically when penalty_lambda = NA), ggm and other model constructors for the penalty_lambda, penalty_alpha, and penalize_matrices arguments.

Examples

# \donttest{
# Load bfi data from psych package:
library("psychTools")
library("dplyr")
data(bfi)

ConsData <- bfi %>%
  select(A1:A5) %>%
  na.omit

vars <- names(ConsData)

# Penalized GGM estimation with manual lambda:
mod <- ggm(ConsData, vars = vars, estimator = "PML", penalty_lambda = 0.1)
mod <- mod %>% runmodel

# Post-selection refit for standard errors:
mod_refit <- mod %>% refit
mod_refit %>% parameters

# Manual unpenalize: free a specific edge from the penalty:
mod2 <- ggm(ConsData, vars = vars, estimator = "PML", penalty_lambda = 0.1)
mod2 <- unpenalize(mod2, "omega", row = 1, col = 2)
mod2 <- mod2 %>% runmodel
# }