1

I'm reading through a tutorial that is using the lme4 package and one of the input options to predict is re.form=Na.

m_lmer <-  lmer(log(beakh) ~ log(wingl) + (1 | taxon), data = d)
d$predict_lmer_population <- predict(m_lmer, re.form = NA)

I want to get help for the predict call, but clearly doing ?predict is incorrect.

I then tried asking for the class of the model:

> class(m_lmer)
[1] "lmerMod"
attr(,"package")
[1] "lme4"

I then tried ?lmerMod which RStudio automagically changed to ?`lmerMod-class`. I get the addition of ` to the name because of the - "special character" but where did class come from?

The help then describes the "merMod" class, not "lmerMod". Why the name change (leading l dropped)?

After some searching in that help I found a link to predict.merMod

Further searching confirmed I could have done: methods('predict') and found the same method, although it is listed predict.merMod* for some reason (added * symbol).

In the end I feel like I would be able to find something similar much more quickly the next time but it still seems very hard to find good help for class methods in R. I'm not sure if this would work the same for S4 or R6 (from the documentation it seems predict.merMod is a S3 method)? It is not clear why the l was dropped from the class name (lmerMod to merMod) or why the -class suffix is needed when asking for help. I feel like I'm missing some extremely basic lesson on R documentation.

Throwing this "help in R" link in for reference that seems to omit class based methods help and also seems like it should just point to some official R documentation website rather than being such a long SO post ... How to get help in R?

Jimbo
  • 2,886
  • 2
  • 29
  • 45
  • 1
    Try `?lme4:::predict.merMod`. When three colons are used, auto-completion captures non-exported functions. – jay.sf Sep 05 '22 at 15:24
  • Thanks @jay.sf that works, although so does `?predict.merMod` - at this point since I worked out how to get that string (in this case) the question is really about how to get help for class methods in general. But thanks for the package specific tip. – Jimbo Sep 05 '22 at 15:26
  • You may also do `methods('predict')` which gives you the currently loaded `predict` methods. – jay.sf Sep 05 '22 at 15:29
  • But the documentation for `methods` suggests that is limited to S3 classes. **Oops** that's only in the title, the description says S3 or S4 (but not R6). Not sure why title is so misleading. – Jimbo Sep 05 '22 at 15:45
  • Here's one that doesn't work, `?bbmle:::mle2.predict`, the correct answer in this case is `` ?`predict,mle2-method` `` obviously #sarcasm – Jimbo Sep 05 '22 at 15:47
  • This is a very good question, I will try to come back and provide an answer. I don't think there's a short one. Part of what you're seeing is the difference between S3 and S4 methods. Part is that too much of method documentation is unenforced/left up to package authors' discretion. Part is the exposure of the underlying class structures in `lme4` (`lmerMod` and `glmerMod` are subclasses of `merMod`). – Ben Bolker Sep 09 '22 at 01:11

1 Answers1

0

This is a very good question. There are a bunch of things going on here, having to do with (1) the difference between S3 and S4 classes and methods, (2) the underlying class structures in lme4.

I want to get help for the predict call, but clearly doing ?predict is incorrect.

?predict gets you help for the generic function which, as you've noticed, isn't useful. In general it's up to the package developers to decide whether their specialized version of a particular method (e.g., the predict() method for merMod objects) is sufficiently special (e.g., has different or unusual arguments) that it should be documented separately. (Writing R Extensions says "If it is necessary or desired to provide an explicit function declaration (in a \usage section) for [a ...] method ...") (emphasis added).

In general, if they're documented, docs for S3 methods will be available as ?function.class, S4 methods will be documented as ?"function,class-method" (which needs quotation marks since it has a hyphen in it).`

The methods() function gives some clues about where to look: if the bbmle and lme4 packages are loaded, predict.merMod* and predict,mle2-method* both show up in the list (the stars mean the functions are hidden, i.e. you can use them by calling predict(my_fit), but the function definitions are not easily available).

I then tried asking for the class of the model:

class(m_lmer) [1] "lmerMod" attr(,"package") [1] "lme4"

lmer() produces an object of class lmerMod, which is a subclass of the merMod class (the other subclass is glmerMod, for GLMMs).

I then tried ?lmerMod which RStudio automagically changed to ?lmerMod-class. I get the addition of ` to the name because of the - "special character" but where did class come from?

I don't know that much about RStudio: the "-class" part is specific to methods for S4 classes.

The help then describes the "merMod" class, not "lmerMod". Why the name change (leading l dropped)?

See above.

The most opaque part of all of this (IMO) is figuring out S4 class hierarchies - if you say methods(class = "lmerMod") you only get two results (getL and show), it's hard to figure out that you need to say methods(class = "merMod") to get most of the available methods (i.e., only a few methods are specific to lmerMod and glmerMod subclasses - most are more general).

According to this answer you can find the subclasses of merMod as follows:

library(lme4)
cls <- getClass("merMod")
names(cls@subclasses)
## [1] "lmerMod"  "glmerMod" "nlmerMod"

How about the other direction?

cls <- getClass("lmerMod")
names(cls@contains)
## [1] "merMod"

(Don't ask me more questions, I really don't understand S4 classes all that well!)

Ben Bolker
  • 211,554
  • 25
  • 370
  • 453
  • Thanks Ben! I haven't used R6 but does this hold up for R6 as well? How do you determine inheritance of R classes? Maybe you could link to another SO answer or just update your answer to indicate how you knew `lmerMod` was a subclass of `merMod`? It looks like the link you provided actually documents some of the strange help method standards (currently 2.1.3 Documenting S4 classes and methods). Seems like it should also be documented on something a bit more user facing as well .... – Jimbo Sep 12 '22 at 17:05
  • I haven't used R6 much so don't really know ... – Ben Bolker Sep 12 '22 at 17:28