How do I explain a complicated function in Rmarkdown? - r

Question

I have a somewhat complicated R function (different parts refer to various equations I'd like to explain.)
I want to write my code using R Markdown, but I need to be able to explain the different parts of the function in the document. A bit like literate programming.
I wonder if it is possible to split the function definition across different code chunks, or maybe insert markdown comments inside the function definition?
I'd like the end result to look something like this:
complicated = function(x) {
I use x^2 in the example so it is math, and yet short. Here it is in the actual R code:
x^2
}
This doesn't work:
``` {r}
complicated = function(x) {
```
explain the function with some math $x^$.
``` {r}
x^2
}
```
The following actually does work:
``` {r chunk1, echo=FALSE}
complicated=function(x) {
x^2
}
```
``` {r chunk1, echo=1:2, eval=F}
```
In the complicated function I use x^2 as an example.
Though it is a bit tricky, because if lines in the function change, I have to edit everything again. Also in the Rmd file, you don't actually see the code described by the comments.
Note:
Maybe it is possible to somehow have the relevant chunks written to a file without being evaluated, and then the file read in? I didn't manage to figure out a way yet...

Answer 1

Here's one way, though I admit it's a little bit of a hack.
---
title: "Split Function"
output: html_document
---
```{r funcdef}
myfunc <- function(x) {
x <- x + 1
x <- x * 2
return(x)
}
```
```{r funcdef1, echo = FALSE, eval = FALSE, include = FALSE}
x <- NULL
x <- x + 1
x <- x * 2
return(x)
```
First line:
```{r funcdef1, echo=2, eval = FALSE}
```
Now the last two:
```{r funcdef1, echo=3:4, eval = FALSE}
```
Done!
Explanation:
the first chunk funcdef is the full function definition, needed if we want to use it;
the second chunk includes the first line (that I do not echo, omitted with echo=-1) that is there so that the others do not err with 'x' not found (even if I do not eval or include); notice that it uses the same chunk name and has nothing in it
same for the third chunk
the reason I have to break out the body of the function without the function header and enclosing braces is that echo= using numbers allows us to subset which expressions are included, not which lines ... and a function declaration is one expression
Two things I don't really like about this:
It requires you to include the body of the function twice, so maintenance has more overhead than required;
It thinks x is being used, when all I really want is to reference the code.
Frankly, this may not be much better than including the portions of code within each subsequent chunk (and set eval=FALSE).

Answer 2

I found a nice answer to this question, though it looks a bit like a knitr bug. I hope it doesn't get fixed. It turns out that references to chunks work in Rmd just like in Rnw. You just have to use <<chunk name>> to refer back to a chunk.
So, here is the answer:
```{r Xsquare, eval=F}
x^2
```
We just need to take x and raise it to the second power: $x^2$.
Now let us put it together:
```{r complicated, eval=T}
complicated = function(x) {
<<Xsquare>>
}
```
Simple, right?
Turns out in Rstudio it works only when we knit everything together, but not on running a single chunk. Almost makes sense.
To solve this, in run the following: knit("filename.Rmd") in the console.