-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathhelp.qmd
83 lines (49 loc) · 10.2 KB
/
help.qmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
---
title: "Looking for help"
toc-location: left
reference-location: margin
citation-location: margin
---
::: {style="width: 75%; margin-left: auto; margin-right: auto;"}
```{r, echo = FALSE, fig.cap = "Wisdom of the Ancients (xkcd 979).", fig.link = "https://xkcd.com/"}
knitr::include_graphics("https://imgs.xkcd.com/comics/wisdom_of_the_ancients.png")
```
:::
## The Google Search Paradox
As you make your first tentative forays into the R programming environment, you will on occasion experience the jarring dislocation of an R error, a typically bright red eruption of your R console, perhaps symbolic of your code exploding before your eyes. Here is one of the more infamous errors you are likely to encounter:
<pre style='color:red'>object of type 'closure' is not subsettable</pre>
Never mind what this particular error means.^[Though check out Jenny Bryan's talk at the 2020 RStudio Conference: https://rstudio.com/resources/rstudioconf-2020/object-of-type-closure-is-not-subsettable/] The point is that it can be terribly frustrating when you encounter it or one of its kin.
Troubleshooting these errors can often be an additional source of anxiety and frustration, especially early on, as you simply lack the words required to describe your problem accurately and, thus, to formulate the question whose answer you so desperately need. I like to refer to this unhappy circumstance as the _Google Search Paradox_ because you will inevitably find yourself staring at an empty search bar, wondering what words to give to Google. It's also a bit like [Meno's Paradox](https://plato.stanford.edu/entries/epistemic-paradoxes/#MenParInqPuzAboGaiKno), or the Paradox of Inquiry. For if you could properly state your question, it's probably the case that you already know the answer. So, you either know and thus don't need to ask, or need to ask, but don't know how.
Of course, the situation is not nearly so dire as this. In truth, you always know at least a little about your problem - you do have the error itself after all! - and can thus Google your way through to an answer - eventually, anyway. But life is fleeting, as they say, and time is short, so you should probably avoid the brute force approach, relying instead on searching _efficiently_. To help you with that (and to help you get _better_ with that), this page provides a brief annotated list of where to look for answers, starting from within R itself!
## R helpers
Typically, though not always, R code will have lots of supporting documentation. These come in two varieties: function help pages and vignettes. If you are having trouble a single function to work properly, you may find its help page more useful. If you are having trouble getting through some analysis and you cannot pinpoint the exact reason for your trouble, the vignettes are probably where you should look. There are a couple of ways to access this documentation.
1. From within R, you can use the `help()` and `?...` functions to access short-form documentation. Examples include `help("plot")` and `?plot`. This will call up the function's documentation page and display it in your computer's graphical device.
2. `help.search(...)` and `??...` both provide means of searching through help pages to find multiple functions with the same name (and potentially the same or similar uses). Simply replace the ellipses (three dots) with a character string and these functions will return all help pages with that string. So if you want to carry out a cluster analysis, typing `??cluster` will search for any functions in your installed packages that use the word cluster.
3. The [rdrr.io](https://rdrr.io/) website provides access to all function help pages online. If you Google an R function, a link to its documentation on this website is typically the first that you will see. For the best search results, I recommend Googling "_R \<package name\> \<function name\>_."
4. From within R, you can also access the vignettes using some combination of `vignette()`, `browseVignettes()`, and `RShowDoc()`.
+ The function `vignette()` with no argument specified will bring up a list of all available vignettes, organized by package. If you want the vignettes for a particular R package, you can also type `vignette(package = ...)`, for example, `vignette(package = "grid")` will bring up the vignettes for the __grid__ package.
+ `browseVignettes()` will open a locally hosted HTML page in your browser with links to all available R vignettes. This is actually quite helpful, and you should give it a try when you get a chance. Just browsing through these vignettes will give you a great feel for all that you can do in R.
+ `RShowDoc()` is mostly for opening a single vignette. This is usefully paired with `vignette()`, which will give you the name of the vignette and package, so that you can, for example, call `RShowDoc(what = "plotExample", package = "grid")`. This will bring up the "plotExample" vignette from the __grid__ package.
5. Package authors have lots of resources for sharing their documentation now, including websites designed specifically to present both function help pages and vignettes. Here is an example of the [website for the __colorspace__](http://colorspace.r-forge.r-project.org/) package.
6. Finally, you can access all available documentation for official R packages by navigating the Comprehensive R Archive Network (CRAN) website, here: [https://cran.r-project.org/](https://cran.r-project.org/).
## RStudio helpers
While RStudio provides loads of support to R users, here we mention some of the more important ones.
1. [RStudio How To Articles](https://support.rstudio.com/hc/en-us/categories/200035113-Documentation) provide loads of how-to guides for working with R and RStudio. This is a very comprehensive suite of useful documentation.
2. [RStudio Cheatsheets](https://rstudio.com/resources/cheatsheets/) strive to communicate package information in a single, concise poster format with lots of visual queues and simple definitions. These can be really helpful when you need a quick refresher on the use of some bit of code.
3. [RStudio Community](https://community.rstudio.com/) is an online forum where individuals ask and answer questions about R and RStudio. They have a very strict code of conduct for their members that emphasizes mutual respect and inclusivity, so you will generally find the discussions here much more friendly and supportive. Use of this forum is highly recommended.
4. [RStudio Education](https://education.rstudio.com/) is a very, very recent development by RStudio (it came online in 2020), and it is simply amazing as a resource for not only learning R itself, but also learning how to _teach_ R.
Please note that, with the exception of number 4, these RStudio help tools can be accessed within the RStudio IDE under the _Help_ tab.
## R Community helpers
The R community refers to R users who are actively communicating with and supporting other R users. As there are lots and lots of engaged R users these days, and more and more every day, the community is definitely thriving. There is also an expanding ethos within this community driven largely by RStudio and its code of conduct, so you will generally find R users to be a friendly bunch (if a little hoity-toity). So, let's talk about where you can engage with this community. We have already mentioned one, RStudio Community, but here we will list some more.
1. [Stack Overflow](https://stackoverflow.com/) is a forum for programmers in all programming languages to ask and answer questions, much like RStudio Community. It's just been around longer (2008 to be exact), which means its code of conduct has evolved over time to address a number of unanticipated issues. The consequence is that answers to questions will run the gamut from being respectful and clear to downright insulting. Still, it is a rich resource for addressing your R coding issues. And it has gotten a lot better.
2. [ROpenSci](https://ropensci.org/) is an R programming community focused on promoting open and reproducible research in science. They have a [forum](https://discuss.ropensci.org/) much like RStudio Community, a [blog](https://ropensci.org/blog/) with helpful news and overviews of the packages in their ecosystem, and a rich [suite of webpages](https://docs.ropensci.org/) for their supported R packages, which you can explore [here](https://ropensci.org/packages/).
3. [R-bloggers](https://www.r-bloggers.com/) is a clearinghouse for R related content, basically an aggregator of content from individual blogs. It is worth perusing every now and then to pick up the occasional gem of R understanding.
4. The [#rstats Twitter community](https://twitter.com/search?q=%23rstats&src=typd) is something. Use this if you use Twitter, I guess...
5. The [rstats subreddit](https://www.reddit.com/r/rstats/) is a helpful community of Redditors that are pretty good about answering questions you might have.
## Other resources
1. The UCLA Institute for Digital Research & Education offers [Statistical Consulting](https://stats.idre.ucla.edu/r/) geared toward R. This is a tremendous resource for both R and statistics and is highly recommended.
## Reproducible examples
Others have likely asked the same question you want to ask, so you will not always need to make a post yourself. But, in the off chance that you do find yourself confronted with a question never asked before, you need to make sure you provide R users with all the information and resources they need to help troubleshoot your code and to do so with the least effort possible. This involves providing a "*repr*oducible *ex*ample" or _reprex_. There are two essential ingredients to a reprex:
1. It needs to be __reproducible__, obviously. That means you need to make sure you provide everything needed to reproduce your error as is, for instance, all `library()` calls in your code.
2. It needs to be __minimal__. In other words, do not include anything extraneous or burdensome, like a 400 MB data object. A much smaller R object should suffice.
A lot has been written about how to put together a reprex, so rather than belabor the point here, it is perhaps best to direct you to Jenny Bryan's [reprex package](https://reprex.tidyverse.org/), which will walk you through the process of submitting a help request on the various forums mentioned above.