vignettes/wflow-05-faq.Rmd
wflow-05-faq.RmdOccasionally your website may not display (or recent updates will not immediately appear), and you may even receive an email from GitHub with the following message:
The page build failed for the
masterbranch with the following error:unable to build page. Please try again later.
For information on troubleshooting Jekyll see:
https://docs.github.com/articles/troubleshooting-jekyll-builds
If you have any questions you can contact us by replying to this email.
If you’ve followed the setup instructions from the Getting started vignette, and especially if the website displayed in the past, it’s very unlikely that you caused the problem. The hosting is provided by GitHub Pages, and it sometimes is delayed or down. Overall for a free service, it is very reliable. If you wait 5 minutes (or 30 minutes at most), your website will likely be back to normal.
If you are anxious to know if there is a problem and when it will be resolved, you can check the website githubstatus.com for the most up-to-date reports directly from GitHub. If you suspect that the problem may have been caused by your recent changes to your website (again, this is unlikely), you can view the GitHub help page Troubleshooting GitHub Pages builds.
Yes. While it it is not possible to make a GitHub Pages site private (the default setup described in the “Getting Started” vignette), there are various other hosting platforms that provide access control. Below are the currently documented options, in order of least to most amount of technical setup required:
To see all the currently documented deployment options, see the vignette Alternative strategies for deploying workflowr websites.
Tracking the changes to your project’s large data files is critical for reproducibility. Unfortunately Git, which is the version control software used by workflowr, was designed to version small files containing code. See the vignette Using large data files with workflowr for various options for versioning the large data files used in your workflowr project.
Image files that are generated by the code executed in the R Markdown files are automatically handled by workflowr. If you’d like to include additional image files to be displayed in your webpages, follow the steps below. The instructions refer to docs/ for the website directory since this is the default. If you are not using GitHub Pages to host the website, you may need to change this. For example, if you are hosting with GitLab Pages, replace docs/ with public/.
Inside the website directory, create a subdirectory named assets to include any file that should be part of the website but is not created by one of the R Markdown files in analysis/:
dir.create("docs/assets")Move the image file(s) to docs/assets/
In the R Markdown file, refer to the image file(s) using the relative path from docs/ (because this is where the HTML files are located), e.g.:
Alternatively, you could use knitr::include_graphics() inside of an R code chunk, which will automatically center the image and also follow the knitr chunk options out.width and out.height:
knitr::include_graphics("assets/external.png", error = FALSE)Note that the image will not be previewed in the R Markdown file inside of RStudio because it is in a different directory than the R Markdown file. You have to set error = FALSE because the function throws an error if it can’t find the file. This breaks the workflowr setup, since the file path only exists once the HTML file is moved to docs/. If you’d like to disable knitr from throwing this error for all the code in your project, add the following line to the .Rprofile in your project: options(knitr.graphics.error = FALSE)
Run wflow_build() to confirm the external image file(s) are properly displayed
Use wflow_git_commit() to commit the file(s) to the Git repo (so that they get pushed to the remote repository, e.g. on GitHub):
wflow_git_commit("docs/assets/external.png", "Add external image of ...")
# If you are adding multiple files, you could use a file glob
wflow_git_commit("docs/assets/*.png", "Add external images of ...")Run wflow_publish() on the R Markdown file that contains the external image file(s)
Another option is to first upload the image, e.g. to Imgur, Figshare, another GitHub repository, etc. Then you can link directly to the image in your Rmd file using the absolute URL. This has the added advantage that the image will automatically display in the Rmd file as you edit it in RStudio. The main disadvantage is that the image isn’t in the same location as the rest of your project files.
The default file format is PNG. This is ideal for displaying figure files on a web page. However, you might need to import a figure into a vector graphics editor (e.g. Illustrator, Inkscape) for final editing for a manuscript. There are multiple options for achieving this.
One option is to switch to the file format SVG. It is a vector graphics format that is also well supported by web browsers. The code chunk below saves the figure file as an SVG:
```{r plot-for-paper, dev='svg'}
library(ggplot2)
data(mtcars)
p <- ggplot(mtcars, aes(x = mpg, y = disp)) + geom_point()
p
```To apply this to every figure file in a particular document, you can create a “setup” chunk at the beginning of the document that sets the knitr chunk option globally:
```{r setup, dev='svg'}
knitr::opts_chunk$set(dev = 'svg')
```Another option is to simultaneously create a PNG for display in the web page and a PDF for further editing. The example code below saves both a PNG and PDF version of the figure, but inserts the PNG into the web page:
```{r plot-for-paper, dev=c('png', 'pdf')}
library(ggplot2)
data(mtcars)
p <- ggplot(mtcars, aes(x = mpg, y = disp)) + geom_point()
p
```The main advantage of the above approaches is that the figure files are still saved in an organized fashion (i.e. the file path is still something like docs/figure/file.Rmd/chunk-name.ext). Furthermore, wflow_publish() will automatically version the figure files regardless of the file extension.
A similar option to the one above is to have two separate code chunks. The advantage of this more verbose option is that you can specify different chunk names (and thus different filenames) and also set different fig.width and fig.height for the website and paper versions. By setting include=FALSE for the second chunk, neither the code nor the PDF figure file is displayed in the web page.
```{r plot-for-paper}
library(ggplot2)
data(mtcars)
p <- ggplot(mtcars, aes(x = mpg, y = disp)) + geom_point()
p
``````{r figure1A, include=FALSE, dev='pdf', fig.height=3, fig.width=9}
p
```However, for the most control, you can always save the figure manually, e.g. using ggsave(). For example, the example chunk below creates a 10x10 inch PNG file that is automatically versioned by workflowr, but also uses ggsave() to save a 5x5 inch PDF file in the subdirectory paper/ (which would need to be manually committed by the user, e.g. with wflow_git_commit()):
```{r plot-for-paper, fig.width=10, fig.height=10}
library(ggplot2)
data(mtcars)
p <- ggplot(mtcars, aes(x = mpg, y = disp)) + geom_point()
p
ggsave("paper/plot-to-edit.pdf", width = 5, height = 5)
```Yes, but not directly. You cannot directly embed the Shiny app into the Rmd file using runtime: shiny_prerendered for two reasons. First, workflowr creates a static website, and the free deployment options (e.g. GitHub Pages), only provide static web hosting. Shiny apps require a dynamic website because they need to call a server to run the R code. Second, even if you setup your own web server, the supporting files (e.g. CSS/JS) for a Shiny app have to be in a different location than the standard for an Rmd-based website.
However, there is still a good option for embedding the Shiny app directly into the web page. You can upload your Shiny app to shinyapps.io, and then embed it directly into your document by calling knitr::include_app() inside a code chunk, as shown below:
```{r shiny-app}
knitr::include_app("https://<user-name>.shinyapps.io/<app-name>/")
```Using this method, the R code for the Shiny app is executed on the servers at shinyapps.io, but your readers are able to explore the app without leaving your website.
Almost certainly yes, but some things are easier to customize than others. The vignette Customize your research website provides some ideas that are simple to implement. Check out the documentation for rmarkdown and Twitter Bootstrap for inspiration.
To suppress the insertion of the workflowr report for all of the files in your project, activate the option suppress_report in the _workflowr.yml file by adding the following line:
suppress_report: TRUEAnd then republishing your project:
wflow_publish("_workflowr.yml", republish = TRUE)To suppress the workflowr report only for a specific file, add the following lines to its YAML header:
workflowr:
suppress_report: TRUEwflow_build() is designed to have the same functionality as the Knit HTML button in RStudio, namely that it knits the HTML file in a separate R session to avoid any clashes with variables or packages in use in the current R session. However, the technical implementations are not identical, and thus informally we have noticed the behavior of the two options occasionally differs. At the moment, we believe that if the file results in an error when using wflow_build(), the file needs to be fixed, regardless of whether the file is able to be built with the RStudio button. If you have a use case that you think should be supported by wflow_build(), please open an Issue and provide a small reproducible example.
When you start a new workflowr project with wflow_start(), it automatically creates a local .Rprofile file that only affects your R session when you run R from within your workflowr project. This is why you see the following lines each time you open R:
Loading .Rprofile for the current workflowr project
This is workflowr version 1.3.0
Run ?workflowr for help getting started
>This is intended to be a convenience so that you don’t have to type library(workflowr) every time you return to your project (or restart your R session). However, the downside is that this has the potential to cause problems when you install new packages. If you attempt to install one of the packages that workflowr depends on, or if you attempt to install a package that then updates one of these dependencies, this may cause an error. For example, here is a typical error caused by updating git2r when the workflowr package is loaded:
Error: package or namespace load failed for ‘git2r’ in get(method, envir = home):
lazy-load database '/usr/local/lib/R/site-library/git2r/R/git2r.rdb' is corrupt
In addition: Warning message:
In get(method, envir = home) : internal error -3 in R_decompress1The short term solution is to restart your current R session, which should fix everything. In the long term, if you start to get this type of error often, you can try one of the following strategies:
.Rprofile with wflow_remove(".Rprofile") and manually load workflowr with library(workflowr) every time you start a new R sessionYes! You can create a single HTML or PDF file to distribute an isolated analysis from your project by directly running the rmarkdown function render(). The main limitation is that any links to other pages will no longer be functional.
You will need to be careful with the working directory in which the code is executed. By default, code in R Markdown documents are executed in the same directory as the file. This is cumbersome, so the default behavior of workflowr is to set the working directory to the root project directory for convenience. To get around this, you can pass knit_root_dir = ".." or knit_root_dir = normalizePath(".") to render(), which both have the effect of running the code in the project root. If you have configured your workflowr project to execute the files in analysis/, then you don’t have to worry about this.
To convert a single analysis to PDF, use pdf_document(). Note that this requires a functional LaTeX setup.
library("rmarkdown")
# Create analysis/file.pdf
render("analysis/file.Rmd", pdf_document(), knit_root_dir = "..")Rendering a single HTML page is slightly more complex because html_document() always includes the navigation bar. If you don’t mind the non-functional navbar at the top of the document, you can simply use html_document().
library("rmarkdown")
# Create analysis/file.html, includes navigation bar
render("analysis/file.Rmd", html_document(), knit_root_dir = "..")The standalone file will be saved as analysis/file.html unless you specify a different name via the argument output_file.
To create a very simple HTML file, you can instead use html_document_base(). This eliminates the navbar, but it may also remove some of the advanced stylistic features of html_document() that you rely on.
library("rmarkdown")
# Create analysis/file.html, no navigation bar nor advanced features
render("analysis/file.Rmd", html_document_base(), knit_root_dir = "..")If you are determined to have a full-featured standalone HTML file without the navigation bar, you can temporarily rename the _site.yml file, which prevents html_document() from including the navbar.
library("rmarkdown")
# Temporarily rename _site.yml
file.rename("analysis/_site.yml", "analysis/_site.yml_tmp")
# Create analysis/file.html, no navigation bar
render("analysis/file.Rmd", html_document(), knit_root_dir = "..")
# Restore _site.yml
file.rename("analysis/_site.yml_tmp", "analysis/_site.yml")If you’d like your standalone HTML file to have a similar appearance to your workflowr website, you can pass the style arguments directly to html_document() so that the theme is similar (copy from your project’s analysis/_site.yml, below are the default values for a new workflowr project):
render("analysis/file.Rmd",
html_document(toc = TRUE, toc_float = TRUE, theme = "cosmo", highlight = "textmate"),
knit_root_dir = "..",
output_file = "standalone.html")Alternatively, if you’d prefer to keep the workflowr report and other workflowr-specific features in the standalone document, don’t use output_file, as this will cause workflowr to insert the warning The custom `fig.path` you set was ignored by workflowr if the analysis contains any figures. Instead, omit both html_document() and output_file. The standalone HTML file will be saved in analysis/ (the standard, non-standalone HTML files are always moved to docs/), and you can move/rename it after it has rendered.
# use the workflowr::wflow_html settings in analysis/_site.yml
render("analysis/file.Rmd", knit_root_dir = "..")Ideally you should also be able to use the RStudio Knit button to conveniently create the standalone HTML or PDF files. For example, you could update the YAML header to have multiple output formats, and then choose the output format that RStudio should create. The workflowr functions like wflow_build() will ignore these other output formats because they use the output format defined in analysis/_site.yml.
---
output:
pdf_document: default
html_document_base: default
workflowr::wflow_html: default
---However, just like when calling render() directly, you’ll need to be careful about the working directory. To execute the code in the project directory, you can manually set the Knit Directory to “Project Directory” (the default is “Document Directory” to match the default behavior of R Markdown files).
Lastly, the RStudio Knit button is somewhat finicky when custom output formats are included (e.g. workflowr, bookdown). If you are having trouble getting it to display the output format you want as an option, try knitting it to the current format. That should update the menu to include all the options you’ve written in the YAML header. See Issue #261 for more details.
Yes! You can use RStudio’s notebook features while you interactively develop your analysis, either directly using the output format rmarkdown::html_notebook() or indirectly with “inline code chunks” in your R Markdown files. However, you need to take a few precautions to make sure your notebook-style usage is compatible with the workflowr options.
First note that the R Markdown files created by wflow_start() and wflow_open() include the lines below in the YAML header. These purposefully disable inline code chunks to proactively prevent any potential incompatibilities with workflowr. To activate inline code chunks, you can either delete these two lines or replace console with inline.
editor_options:
chunk_output_type: consoleSecond, note that the working directory of the inline code chunks can be different than the working directory of the R console. This is very counterintuitive, but the working directory of the inline code chunks is set by the “Knit Directory” setting in RStudio. The setting of “Knit Directory” may be different in your collaborator’s version of RStudio, or even your own RStudio installed on a different computer. Thus it’s not a good idea to rely on this value. Instead, you can explicitly specify the working directory to be used for the inline code chunks by setting the knitr option root.dir in a chunk called setup, which RStudio treats specially. Adding the code chunk below to your R Markdown file will cause all the inline code chunks to be executed from the root of the project directory. This is consistent with the default workflowr setting.
```{r setup}
knitr::opts_knit$set(root.dir = "..")
```If you change the value of knit_root_dir in _workflowr.yml, then you would need to change the value of root.dir in the setup chunk accordingly. Warning that this is fragile, i.e. trying to change root.dir to any arbitrary directory may result in an error. If you’re going to use inline code chunks, it’s best two follow one of the following options:
Execute code in the root of the project directory (the default workflowr setting). Don’t change knit_root_dir in _workflowr.yml. Add the setup chunk defined above to your R Markdown files. Note that this setup chunk will affect RStudio but not the workflowr functions wflow_build() or wflow_publish().
Execute code in the R Markdown directory (named analysis/ by default). Delete the knit_root_dir entry in _workflowr.yml. Don’t explicitly set root.dir in a setup code chunk in your R Markdown files. Ensure that the RStudio setting “Knit Directory” is set to “Document Directory”.
Third, note that if you are using html_notebook(), any settings you specify for it will be ignored when you run wflow_build() or wflow_publish(). This is because the settings in _site.yml override them. If you wish to change the setting of one particular notebook file, as opposed to every file in your project, you can set it with workflowr::wflow_html(). For example, if you want to enable folding of code chunks and disable the table of contents for only this file, you could use the following YAML header.
---
title: "Using R Notebook with workflowr"
output:
html_notebook: default
workflowr::wflow_html:
toc: false
code_folding: show
---Workflowr works best with Git hosting services that use the HTTPS protocol. However, with some minimal upfront configuration, it is possible to use the HTTP protocol.
The configuration differs depending on whether you are authenticating with SSH keys or username/password.
SSH keys
Configure the remote with wflow_git_remote() and protocol = "ssh"
You can use wflow_git_push() and wflow_git_pull()
For the embedded links to past versions of the files to be correct, you need to manually include the URL to the project in _workflowr.yml (for historical reasons, this variable is named github)
github: https://custom-site.com/<username>/<reponame>Username/Password
wflow_git_remote(). Instead use either
git2r::remote_add() in R:
git2r::remote_add(name = "origin", url = "https://custom-site/<username>/<reponame>.git")git remote add origin in the terminal:
git remote add origin https://custom-site/<username>/<reponame>.gitwflow_git_push() and wflow_git_pull(). Instead run git push and git pull in the terminalThere are multiple options for pronouncing workflowr:
I (John) started primarily saying “workflow + er” but have more recently transitioned to saying “workflow + R” more often. You can choose whichever is most natural to you.
Workflowr should be capitalized at the beginning of a sentence, but otherwise the lowercase workflowr should be the preferred option.