Improved the documentation a bit.

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: metafor
-Version: 4.5-4
-Date: 2023-10-23
+Version: 4.5-5
+Date: 2023-10-31
 Title: Meta-Analysis Package for R
 Authors@R: person(given = "Wolfgang", family = "Viechtbauer", role = c("aut","cre"), email = "wvb@metafor-project.org", comment = c(ORCID = "0000-0003-3463-4063"))
 Depends: R (>= 4.0.0), methods, Matrix, metadat, numDeriv

NEWS.md

@@ -1,9 +1,11 @@
-# metafor 4.5-4 (2023-10-23)
+# metafor 4.5-5 (2023-10-31)
 
 - a few minor fixes to the dynamic theming of plots based on the foreground and background colors of the plotting device
 
 - slightly improved flexibility for setting package options
 
+- improved the documentation a bit
+
 # metafor 4.4-0 (2023-09-27)
 
 - added `getmfopt()` and `setmfopt()` functions for getting and setting package options and made some of the options more flexible

R/plot.profile.rma.r

@@ -21,8 +21,8 @@ plot.profile.rma <- function(x, xlim, ylim, pch=19, xlab, ylab, main, refline=TR
 
    ### filter out some arguments for the plot() function
 
-   lplot   <- function(..., time, LB, startmethod, sub1) plot(...)
-   lpoints <- function(..., time, LB, startmethod, sub1, log) points(...) # need 'log' here so profile(res, log="x") doesn't throw a warning
+   lplot   <- function(..., time, LB, startmethod, sub1, sqrt, exp) plot(...)
+   lpoints <- function(..., time, LB, startmethod, sub1, log, sqrt, exp) points(...) # need 'log' here so profile(res, log="x") doesn't throw a warning
 
    #########################################################################
 
@@ -38,11 +38,13 @@ plot.profile.rma <- function(x, xlim, ylim, pch=19, xlab, ylab, main, refline=TR
          xlab <- x$xlab
 
       if (missing.ylab)
-         ylab <- paste(ifelse(x$method=="REML", "Restricted ", ""), "Log-Likelihood", sep="")
+         ylab <- x$ylab
 
       if (missing.main)
          main <- x$title
 
+      ### add the actual vc value to the profile
+
       if (min(x[[1]]) <= x$vc && max(x[[1]]) >= x$vc) {
          pos <- which(x[[1]] >= x$vc)[1]
          x[[1]] <- c(x[[1]][seq_len(pos-1)], x$vc,    x[[1]][pos:length(x[[1]])])
@@ -74,17 +76,15 @@ plot.profile.rma <- function(x, xlim, ylim, pch=19, xlab, ylab, main, refline=TR
          if (missing.xlab) {
             xlab <- x[[j]]$xlab
          } else {
-            if (length(xlab) == 1L) {
+            if (length(xlab) == 1L)
                xlab <- rep(xlab, x$comps)
-            }
          }
 
          if (missing.ylab) {
-            ylab <- paste(ifelse(x[[j]]$method=="REML", "Restricted ", ""), "Log-Likelihood", sep="")
+            ylab <- x[[j]]$ylab
          } else {
-            if (length(ylab) == 1L) {
+            if (length(ylab) == 1L)
                ylab <- rep(ylab, x$comps)
-            }
          }
 
          if (missing.main) {

R/profile.rma.ls.r

@@ -237,7 +237,7 @@ profile.rma.ls <- function(fitted, alpha,
          if (xlim[1] <= vc && xlim[2] >= vc) {
             ylim <- range(c(logLik(x),lls[is.finite(lls)]), na.rm=TRUE)
          } else {
-            ylim <- range(lls[is.finite(lls)])
+            ylim <- range(lls[is.finite(lls)], na.rm=TRUE)
          }
       } else {
          ylim <- rep(logLik(x), 2L)
@@ -265,7 +265,9 @@ profile.rma.ls <- function(fitted, alpha,
       }
    }
 
-   sav <- list(vc=vcs, ll=lls, beta=beta, ci.lb=ci.lb, ci.ub=ci.ub, comps=1, ylim=ylim, method=x$method, vc=vc, maxll=logLik(x), xlab=xlab, title=title)
+   ylab <- paste(ifelse(x$method=="REML", "Restricted ", ""), "Log-Likelihood", sep="")
+
+   sav <- list(vc=vcs, ll=lls, beta=beta, ci.lb=ci.lb, ci.ub=ci.ub, comps=1, ylim=ylim, method=x$method, vc=vc, maxll=logLik(x), xlab=xlab, ylab=ylab, title=title)
    names(sav)[1] <- "alpha"
    class(sav) <- "profile.rma"
 

R/profile.rma.mv.r

@@ -441,7 +441,7 @@ profile.rma.mv <- function(fitted, sigma2, tau2, rho, gamma2, phi,
          if (xlim[1] <= vc && xlim[2] >= vc) {
             ylim <- range(c(logLik(x),lls[is.finite(lls)]), na.rm=TRUE)
          } else {
-            ylim <- range(lls[is.finite(lls)])
+            ylim <- range(lls[is.finite(lls)], na.rm=TRUE)
          }
       } else {
          ylim <- rep(logLik(x), 2L)
@@ -503,7 +503,9 @@ profile.rma.mv <- function(fitted, sigma2, tau2, rho, gamma2, phi,
       }
    }
 
-   sav <- list(vc=vcs, ll=lls, beta=beta, ci.lb=ci.lb, ci.ub=ci.ub, comps=1, ylim=ylim, method=x$method, vc=vc, maxll=logLik(x), xlab=xlab, title=title)
+   ylab <- paste(ifelse(x$method=="REML", "Restricted ", ""), "Log-Likelihood", sep="")
+
+   sav <- list(vc=vcs, ll=lls, beta=beta, ci.lb=ci.lb, ci.ub=ci.ub, comps=1, ylim=ylim, method=x$method, vc=vc, maxll=logLik(x), xlab=xlab, ylab=ylab, title=title)
    names(sav)[1] <- switch(comp, sigma2="sigma2", tau2="tau2", rho="rho", gamma2="gamma2", phi="phi")
    class(sav) <- "profile.rma"
 

R/profile.rma.uni.r

@@ -6,7 +6,7 @@ profile.rma.uni <- function(fitted,
    .chkclass(class(fitted), must="rma.uni", notav=c("rma.gen", "rma.uni.selmodel"))
 
    if (is.element(fitted$method, c("FE","EE","CE")))
-      stop(mstyle$stop("Cannot profile tau2 parameter for equal/fixed-effects models."))
+      stop(mstyle$stop("Cannot profile tau^2 parameter for equal/fixed-effects models."))
 
    if (steps < 2)
       stop(mstyle$stop("Argument 'steps' must be >= 2."))
@@ -67,28 +67,28 @@ profile.rma.uni <- function(fitted,
       } else {
 
          ### min() and max() so the actual value is within the xlim bounds
-         ### could still get NAs for the bounds if the CI is the empty set
+         ### note: could still get NAs for the bounds if the CI is the empty set
 
          vc.lb <- min(x$tau2, vc.ci$random[1,2])
-         vc.ub <- max(.1, x$tau2, vc.ci$random[1,3]) ### if CI is equal to null set, then this still gives vc.ub = .1
+         vc.ub <- max(0.1, x$tau2, vc.ci$random[1,3]) # if CI is equal to null set, then this still gives vc.ub = 0.1
 
       }
 
       if (is.na(vc.lb) || is.na(vc.ub)) {
 
          ### if the CI method fails, try a Wald-type CI for tau^2
 
-         vc.lb <- max( 0, x$tau2 - qnorm(.995) * x$se.tau2)
-         vc.ub <- max(.1, x$tau2 + qnorm(.995) * x$se.tau2)
+         vc.lb <- max(  0, x$tau2 - qnorm(0.995) * x$se.tau2)
+         vc.ub <- max(0.1, x$tau2 + qnorm(0.995) * x$se.tau2)
 
       }
 
       if (is.na(vc.lb) || is.na(vc.ub)) {
 
          ### if this still results in NA bounds, use simple method
 
-         vc.lb <- max( 0, x$tau2/4)
-         vc.ub <- max(.1, x$tau2*4)
+         vc.lb <- max(  0, x$tau2/4)
+         vc.ub <- max(0.1, x$tau2*4)
 
       }
 
@@ -99,21 +99,31 @@ profile.rma.uni <- function(fitted,
 
       xlim <- c(vc.lb, vc.ub)
 
+      if (.isTRUE(ddd$sqrt))
+         xlim <- sqrt(xlim)
+
    } else {
 
       if (length(xlim) != 2L)
          stop(mstyle$stop("Argument 'xlim' should be a vector of length 2."))
 
       xlim <- sort(xlim)
 
+      ### note: if sqrt=TRUE, then xlim is assumed to be given in terms of tau
+
    }
 
    vcs <- seq(xlim[1], xlim[2], length.out=steps)
    #return(vcs)
 
-   if (length(vcs) <= 1L)
+   if (length(vcs) <= 1L) # not sure how this could happen / why this check is needed, but leave it here just in case
       stop(mstyle$stop("Cannot set 'xlim' automatically. Please set this argument manually."))
 
+   ### if sqrt=TRUE, then the sequence of vcs are tau values, so square them for the actual profiling
+
+   if (.isTRUE(ddd$sqrt))
+      vcs <- vcs^2
+
    if (parallel == "no")
       res <- pbapply::pblapply(vcs, .profile.rma.uni, obj=x, parallel=parallel, profile=TRUE)
 
@@ -138,6 +148,15 @@ profile.rma.uni <- function(fitted,
       }
    }
 
+   ### if sqrt=TRUE, then transform the tau^2 values back to tau values
+
+   if (.isTRUE(ddd$sqrt)) {
+      vcs <- sqrt(vcs)
+      vc  <- sqrt(x$tau2)
+   } else {
+      vc <- x$tau2
+   }
+
    lls <- sapply(res, function(x) x$ll)
    beta  <- do.call(rbind, lapply(res, function(x) t(x$beta)))
    ci.lb <- do.call(rbind, lapply(res, function(x) t(x$ci.lb)))
@@ -158,18 +177,27 @@ profile.rma.uni <- function(fitted,
    names(ci.lb) <- rownames(x$beta)
    names(ci.ub) <- rownames(x$beta)
 
+   maxll <- logLik(x)
+
+   if (.isTRUE(ddd$exp)) {
+      lls <- exp(lls)
+      maxll <- exp(maxll)
+   }
+
    if (missing(ylim)) {
 
       if (any(is.finite(lls))) {
-         if (xlim[1] <= x$tau2 && xlim[2] >= x$tau2) {
-            ylim <- range(c(logLik(x),lls[is.finite(lls)]), na.rm=TRUE)
+         if (xlim[1] <= vc && xlim[2] >= vc) {
+            ylim <- range(c(maxll,lls[is.finite(lls)]), na.rm=TRUE)
          } else {
-            ylim <- range(lls[is.finite(lls)])
+            ylim <- range(lls[is.finite(lls)], na.rm=TRUE)
          }
       } else {
-         ylim <- rep(logLik(x), 2L)
+         ylim <- rep(maxll, 2L)
       }
-      ylim <- ylim + c(-0.1, 0.1)
+
+      if (.isFALSE(ddd$exp))
+         ylim <- ylim + c(-0.1, 0.1)
 
    } else {
 
@@ -180,12 +208,26 @@ profile.rma.uni <- function(fitted,
 
    }
 
-   xlab <- expression(paste(tau^2, " Value"))
-   title <- expression(paste("Profile Plot for ", tau^2))
+   if (.isTRUE(ddd$sqrt)) {
+      xlab <- expression(paste(tau, " Value"))
+      title <- expression(paste("Profile Plot for ", tau))
+   } else {
+      xlab <- expression(paste(tau^2, " Value"))
+      title <- expression(paste("Profile Plot for ", tau^2))
+   }
 
-   sav <- list(tau2=vcs, ll=lls, beta=beta, ci.lb=ci.lb, ci.ub=ci.ub, comps=1, xlim=xlim, ylim=ylim, method=x$method, vc=x$tau2, maxll=logLik(x), xlab=xlab, title=title)
+   if (.isTRUE(ddd$exp)) {
+      ylab <- paste(ifelse(x$method=="REML", "Restricted ", ""), "Likelihood", sep="")
+   } else {
+      ylab <- paste(ifelse(x$method=="REML", "Restricted ", ""), "Log-Likelihood", sep="")
+   }
+
+   sav <- list(tau2=vcs, ll=lls, beta=beta, ci.lb=ci.lb, ci.ub=ci.ub, comps=1, xlim=xlim, ylim=ylim, method=x$method, vc=vc, maxll=maxll, xlab=xlab, ylab=ylab, title=title)
    class(sav) <- "profile.rma"
 
+   if (.isTRUE(ddd$sqrt))
+      names(sav)[1] <- "tau"
+
    #########################################################################
 
    if (plot)

R/profile.rma.uni.selmodel.r

@@ -284,7 +284,7 @@ profile.rma.uni.selmodel <- function(fitted, tau2, delta,
          if (xlim[1] <= vc && xlim[2] >= vc) {
             ylim <- range(c(logLik(x),lls[is.finite(lls)]), na.rm=TRUE)
          } else {
-            ylim <- range(lls[is.finite(lls)])
+            ylim <- range(lls[is.finite(lls)], na.rm=TRUE)
          }
       } else {
          ylim <- rep(logLik(x), 2L)
@@ -314,7 +314,9 @@ profile.rma.uni.selmodel <- function(fitted, tau2, delta,
       }
    }
 
-   sav <- list(vc=vcs, ll=lls, beta=beta, ci.lb=ci.lb, ci.ub=ci.ub, comps=1, ylim=ylim, method=x$method, vc=vc, maxll=logLik(x), xlab=xlab, title=title)
+   ylab <- paste(ifelse(x$method=="REML", "Restricted ", ""), "Log-Likelihood", sep="")
+
+   sav <- list(vc=vcs, ll=lls, beta=beta, ci.lb=ci.lb, ci.ub=ci.ub, comps=1, ylim=ylim, method=x$method, vc=vc, maxll=logLik(x), xlab=xlab, ylab=ylab, title=title)
    names(sav)[1] <- switch(comp, tau2="tau2", delta="delta")
    class(sav) <- "profile.rma"
 

R/zzz.r

@@ -1,6 +1,6 @@
 .onAttach <- function(libname, pkgname) {
 
-   ver <- "4.5-4"
+   ver <- "4.5-5"
 
    loadmsg <- paste0("\nLoading the 'metafor' package (version ", ver, "). For an\nintroduction to the package please type: help(metafor)\n")
 

README.md

@@ -5,7 +5,7 @@ metafor: A Meta-Analysis Package for R
 [![R build status](https://github.com/wviechtb/metafor/workflows/R-CMD-check/badge.svg)](https://github.com/wviechtb/metafor/actions)
 [![Code Coverage](https://codecov.io/gh/wviechtb/metafor/branch/master/graph/badge.svg)](https://app.codecov.io/gh/wviechtb/metafor)
 [![CRAN Version](https://www.r-pkg.org/badges/version/metafor)](https://cran.r-project.org/package=metafor)
-[![devel Version](https://img.shields.io/badge/devel-4.5--4-brightgreen.svg)](https://www.metafor-project.org/doku.php/installation#development_version)
+[![devel Version](https://img.shields.io/badge/devel-4.5--5-brightgreen.svg)](https://www.metafor-project.org/doku.php/installation#development_version)
 [![Monthly Downloads](https://cranlogs.r-pkg.org/badges/metafor)](https://cranlogs.r-pkg.org/badges/metafor)
 [![Total Downloads](https://cranlogs.r-pkg.org/badges/grand-total/metafor)](https://cranlogs.r-pkg.org/badges/grand-total/metafor)
 

docs/pkgdown.yml

@@ -3,7 +3,7 @@ pkgdown: 2.0.7
 pkgdown_sha: ~
 articles:
   diagram: pkgdown/diagram.html
-last_built: 2023-10-23T14:15Z
+last_built: 2023-10-31T06:26Z
 urls:
   reference: https://wviechtb.github.io/metafor/reference
   article: https://wviechtb.github.io/metafor/articles