Skip to contents

Compute one-dimensional profile-likelihood curves and confidence intervals for selected parameters by fixing one parameter at a time and re-optimizing the remaining parameters.

Usage

profile_likelihood(
  object,
  parameters = NULL,
  level = 0.95,
  n_points = 21,
  span = 3,
  grid = NULL,
  optim_method = "L-BFGS-B",
  control = list(factr = 1e+07, maxit = 400),
  parameter_pairs = NULL
)

Arguments

object

A fitted mars or pub_bias object. mars profiling currently excludes LASSO, location-scale and fixed-heterogeneity fits.

parameters

Optional parameter specification. May be NULL (default: all random-effects parameters), numeric indices into the optimizer parameter vector, or parameter names. Fixed-effect parameters use the column names of object$design_matrix; random-effects parameters use names tau1, tau2, .... These name optimizer parameters: for UN, they are Cholesky-factor entries, not entries of the exported Tau matrix.

level

Confidence level for profile-likelihood intervals. Default 0.95.

n_points

Number of grid points used per profiled parameter. Default 21.

span

Automatic grid width. For coefficients, the grid extends this many selected coefficient SEs on each side; positive nuisance parameters use a multiplicative span. Default 3.

grid

Optional custom grid specification:

  • numeric vector: reused for each parameter

  • named list of numeric vectors keyed by parameter name

  • unnamed list of numeric vectors with one entry per profiled parameter.

optim_method

Optimization method passed to optim(). Default "L-BFGS-B".

control

Control list passed to optim() for each conditional fit.

parameter_pairs

Optional 2D parameter-pair specification. May be a character vector of length 2, a numeric vector of length 2, or a list of such pairs.

Value

A list containing per-parameter profile grids and profile-likelihood confidence intervals. The profiles component contains one data frame per one-dimensional profile. The surfaces component contains optional two-dimensional grids with x, y, objective, converged, and cutoff entries.

Details

The profiled objective is reported on a deviance-like scale. For standard mars models this is the fitted objective, equivalent to -2 log L up to constants that do not depend on the profiled parameters. For publication-bias models the same -2 log L scaling is used. Lower values therefore indicate better-supported parameter values.

For a one-dimensional profile, the x-axis is the fixed value of the selected parameter and the y-axis is the deviance-scale objective after all remaining parameters have been re-optimized. The profile-likelihood interval contains values whose objective is no more than qchisq(level, df = 1) above the fitted minimum.

For a two-dimensional profile surface, the x- and y-axes are the two fixed parameter values and the contours show the deviance-scale objective after all other parameters have been re-optimized. The cutoff contour uses qchisq(level, df = 2) above the fitted minimum and can be interpreted as an approximate joint confidence region for the parameter pair.

The profiling likelihood is checked against the original fitted objective. Stored outcome indices preserve missing outcomes and reordered study rows. Failed conditional fits are flagged and excluded from interval interpolation; a profile with no converged finite evaluations raises an error. Expand the grid when an interval endpoint is not bracketed. Wald chi-square cutoffs are approximate; variance boundaries require special interpretation. Coefficient profiles require ML; REML is supported only for heterogeneity profiles.

Examples

# \donttest{
fit <- mars(
  data = teacher_expectancy,
  studyID = "study",
  effectID = NULL,
  sample_size = NULL,
  formula = yi ~ 1,
  variance = "vi",
  varcov_type = "univariate",
  structure = "univariate"
)
prof <- profile_likelihood(fit, parameters = "tau1", n_points = 7)
#> Warning: Profile interval for tau1 is not bracketed on both sides; expand the grid or inspect a parameter boundary.
plot(prof)

# }