What defines the setup chunk?

maelle · April 3, 2019, 8:26am

Until today I thought the "setup chunk" of an R Markdown document was the one with a "setup" label, but I can't find any reference, so am now wondering what makes a chunk the setup chunk. Its label? Its position? Its containing knitr::opts_knit$set? Thanks!

maelle · April 3, 2019, 8:29am

E.g. in

github.com

rstudio/rmarkdown-book/blob/345b4386fa777c65b8166815ed01ef1bf70e0d93/03-documents.Rmd#L560


- **Working directory**: The current working directory inside a notebook chunk is always the directory containing the notebook `.Rmd` file. This makes it easier to use relative paths inside notebook chunks, and also matches the behavior when knitting, making it easier to write code that works identically both interactively and in a standalone render.


    You'll get a warning if you try to change the working directory inside a notebook chunk, and the directory will revert back to the notebook's directory once the chunk is finished executing. You can suppress this warning by using the `warnings = FALSE` chunk option.


    If it is necessary to execute notebook chunks in a different directory, you can change the working directory for **all** your chunks by using the **knitr** `root.dir` option. For instance, to execute all notebook chunks in the grandparent folder of the notebook:


    ```r
    knitr::opts_knit$set(root.dir = normalizePath(".."))
    ```


    This option is only effective when used inside the setup chunk. Also note that, as in **knitr**, the `root.dir` chunk option applies only to chunks; relative paths in Markdown are still relative to the notebook's parent folder.


- **Warnings**: Inside a notebook chunk, warnings are always displayed immediately rather than being held until the end, as in `options(warn = 1)`.


- **Plots**: Plots emitted from a chunk are rendered to match the width of the editor at the time the chunk was executed. The height of the plot is determined by the [golden ratio](https://en.wikipedia.org/wiki/Golden_ratio). The plot's display list is saved, too, and the plot is re-rendered to match the editor's width when the editor is resized.


    You can use the `fig.width`, `fig.height`, and `fig.asp` chunk options to manually specify the size of rendered plots in the notebook; you can also use `knitr::opts_chunk$set(fig.width = ..., fig.height = ...)` in the setup chunk to to set a default rendered size. Note, however, specifying a chunk size manually suppresses the generation of the display list, so plots with manually specified sizes will be resized using simple image scaling when the notebook editor is resized.


To execute an inline R expression in the notebook, put your cursor inside the chunk and press `Ctrl + Enter` (macOS: `Cmd + Enter`). As in the execution of ordinary chunks, the content of the expression will be sent to the R console for evaluation. The results will appear in a small pop-up window next to the code (Figure \@ref(fig:notebook-inline-output)).


```{r notebook-inline-output, echo=FALSE, fig.cap='Output from an inline R expression in the notebook.', out.width='40%', fig.align='center'}

I see "This option is only effective when used inside the setup chunk." but it does not say what makes a chunk a setup chunk

rlesur · April 3, 2019, 12:32pm

My guess is that the setup chunk is used only in the context of the RStudio IDE and defined by its label.
See for instance these lines of the RStudio IDE source code:

github.com

rstudio/rstudio/blob/cf5076a88a219a275a2d128191c12c1f8f4e3890/src/cpp/session/modules/rmarkdown/NotebookQueue.cpp#L261-L266


// get the chunk label to see if this is the setup chunk 
std::string label;
json::readObject(execContext_->options().chunkOptions(), "label", 
      &label);
if (label == "setup")
   saveSetupContext();

mara · April 3, 2019, 1:58pm

I think it's the scope of the chunk that makes it "setup-y"— e.g. from the knitr documentation

opts_chunk$set() can change the default global options in a document (e.g. put this in a code chunk: knitr::opts_chunk$set(comment=NA, fig.width=6, fig.height=6) ).

apreshill · April 3, 2019, 2:19pm

You are right- the links are scarce on this one. Here is a snippet from R4DS:

"There is one chunk name that imbues special behaviour: setup . When you’re in a notebook mode, the chunk named setup will be run automatically once, before any other code is run."

And a bit more from R Markdown: The Definitive Guide in the Notebooks chapter:

"If it is necessary to execute notebook chunks in a different directory, you can change the working directory for all your chunks by using the knitr root.dir option...This option is only effective when used inside the setup chunk."

cderv · April 3, 2019, 8:47pm

Also, I think the setup chunk is only something useful for IDE feature as it was already pointed out in this discussion.

However, it is also useful for shiny prerendered document were the setup chunk is expected to be labelled setup. A chunk with label setup means the setup context.

It is an alias for c("render", "server-start").

github.com

rstudio/rmarkdown/blob/53ff6f2ae282944e70a61ee6c12e806169e5de7a/R/shiny_prerendered.R#L389


      
          
          # Record which context="data" chunks are actually executed during
          # the current render as well as the file names they are saved with.
          # We'll use this later to determine which .RData files in the _data
          # directory should actually be loaded (as some could be from chunks
          # that used to be cached / were cached under different names)
          shiny_prerendered_option_hook <- function(input, encoding) {
            function(options) {
          
              # convert chunk labels to contexts as necessary
              if (options$label %in% c("setup", "data", "server_start", "server"))
                options$context <- options$label
          
              if (identical(options$context, "data")) {
                data_file <- shiny_prerendered_data_file_name(options$label,
                                                              options$cache > 0)
                data_file <- to_utf8(data_file, encoding)
                data_dir <- shiny_prerendered_data_dir(input, create = TRUE)
                index_file <- shiny_prerendered_data_chunks_index(data_dir)
                conn <- file(index_file, open = "ab", encoding = "UTF-8")
                on.exit(close(conn), add = TRUE)

I really wonder if this setup chunk does not come from this shiny thing inside Rmd with the context thing.

Apart from that, a chunk named setup is useful for some IDE behaviour for Rmd and Notebook.

maelle · April 4, 2019, 8:01am

Thanks everyone!

So we'll keep never unnaming that chunk in the namer package.

system · April 11, 2019, 8:01am

This topic was automatically closed 7 days after the last reply. New replies are no longer allowed.

If you have a query related to it or one of the replies, start a new topic and refer back with a link.