Skip to contents

Compute profile-likelihood curves for fitted model targets

Source: R/profile.R
profile.drmTMB.Rd

profile() computes and returns the full likelihood-profile curve for one or more direct profile_targets(). It is a diagnostic companion to confint.drmTMB(). Use confint.drmTMB() for interval tables, especially with the fast endpoint engine; use profile() followed by plot() when you need to see whether a target has a peaked, flat, one-sided, or boundary-like likelihood shape.

Usage

# S3 method for class 'drmTMB'
profile(
  fitted,
  parm,
  level = 0.95,
  trace = FALSE,
  profile_precision = c("default", "fast"),
  profile_maxit = NULL,
  compare = FALSE,
  first_pass_ystep = 0.5,
  first_pass_ytol = 2,
  ...
)

Arguments

fitted

A drmTMB fit.

parm

Character or integer vector selecting direct profile targets. Use profile_targets() to inspect available names. Unlike confint.drmTMB(), this helper always uses the full TMB::tmbprofile() curve because the curve itself is the diagnostic.

level

Confidence level used for the likelihood-ratio cutoff and interval endpoint annotations.

trace

Logical; passed to TMB::tmbprofile().

profile_precision

Profile-control shortcut. "default" leaves TMB::tmbprofile() controls unchanged. "fast" supplies ystep = 0.5 and ytol = 2 unless the caller supplies those controls in ....

profile_maxit

Optional positive whole number passed to TMB::tmbprofile() as maxit.

compare

Logical; if TRUE, run a coarse first-pass profile and then the requested profile controls so the returned object can compare curve shape and elapsed time.

first_pass_ystep, first_pass_ytol

Coarse TMB::tmbprofile() controls used only when compare = TRUE. The dense pass uses profile_precision, profile_maxit, and ....

...

Additional arguments passed to TMB::tmbprofile(). drmTMB supplies the profiled obj, name, lincomb, and trace arguments internally; set the profile target with parm.

Value

A data frame with class "profile.drmTMB". The main columns are parm, profile_value, profile_value_link, objective, delta_objective, delta_deviance, estimate, profile_pass, elapsed, profile_source, conf.low, conf.high, conf.status, and profile.message.

Details

The returned x-axis values are transformed to the same scale shown by profile_targets(). For example, SD and scale targets are shown on their public positive scale, and correlation targets are shown on the correlation scale. The y-axis diagnostic is likelihood-ratio distance, 2 * (profile_nll - min(profile_nll)), so a flatter curve indicates weaker likelihood support around the fitted value.

Examples

dat <- data.frame(y = c(0.2, 0.5, 1.1, 1.4), x = c(-1, 0, 1, 2))
fit <- drmTMB(bf(y ~ x, sigma ~ 1), data = dat)
prof <- profile(fit, parm = "sigma", profile_precision = "fast")
head(prof)
#>    parm         target_class  dpar       term level profile_value
#> 1 sigma distributional-scale sigma (constant)  0.95    0.03629271
#> 2 sigma distributional-scale sigma (constant)  0.95    0.03819929
#> 3 sigma distributional-scale sigma (constant)  0.95    0.04020602
#> 4 sigma distributional-scale sigma (constant)  0.95    0.04454130
#> 5 sigma distributional-scale sigma (constant)  0.95    0.04934403
#> 6 sigma distributional-scale sigma (constant)  0.95    0.05466463
#>   profile_value_link objective delta_objective delta_deviance   estimate
#> 1          -3.316138 -2.755920       2.3756817      4.7513635 0.06708207
#> 2          -3.264938 -3.216175       1.9154267      3.8308534 0.06708207
#> 3          -3.213738 -3.611699       1.5199025      3.0398050 0.06708207
#> 4          -3.111338 -4.233143       0.8984585      1.7969171 0.06708207
#> 5          -3.008938 -4.663648       0.4679533      0.9359066 0.06708207
#> 6          -2.906538 -4.938575       0.1930270      0.3860539 0.06708207
#>   link_estimate profile_pass elapsed  profile_controls
#> 1     -2.701838      profile   0.012 ystep=0.5, ytol=2
#> 2     -2.701838      profile   0.012 ystep=0.5, ytol=2
#> 3     -2.701838      profile   0.012 ystep=0.5, ytol=2
#> 4     -2.701838      profile   0.012 ystep=0.5, ytol=2
#> 5     -2.701838      profile   0.012 ystep=0.5, ytol=2
#> 6     -2.701838      profile   0.012 ystep=0.5, ytol=2
#>                              profile_source   conf.low conf.high conf.status
#> 1 TMB::tmbprofile via stats::profile.drmTMB 0.03817676 0.1644423     profile
#> 2 TMB::tmbprofile via stats::profile.drmTMB 0.03817676 0.1644423     profile
#> 3 TMB::tmbprofile via stats::profile.drmTMB 0.03817676 0.1644423     profile
#> 4 TMB::tmbprofile via stats::profile.drmTMB 0.03817676 0.1644423     profile
#> 5 TMB::tmbprofile via stats::profile.drmTMB 0.03817676 0.1644423     profile
#> 6 TMB::tmbprofile via stats::profile.drmTMB 0.03817676 0.1644423     profile
#>   profile.message    scale transformation tmb_parameter index
#> 1              ok response            exp    beta_sigma     1
#> 2              ok response            exp    beta_sigma     1
#> 3              ok response            exp    beta_sigma     1
#> 4              ok response            exp    beta_sigma     1
#> 5              ok response            exp    beta_sigma     1
#> 6              ok response            exp    beta_sigma     1
if (requireNamespace("ggplot2", quietly = TRUE)) {
  plot(prof)
}