--- title: "Frequently asked questions" subtitle: "workflowr version `r utils::packageVersion('workflowr')`" author: "John Blischak" date: "`r Sys.Date()`" output: rmarkdown::html_vignette: toc: true vignette: > %\VignetteIndexEntry{Frequently asked questions} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ## Why isn't my website displaying online? Occasionally 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 `master` branch 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](wflow-01-getting-started.html), 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][gh-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][gh-status] 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][gh-troubleshooting]. ## Can I make my workflowr website private? Yes. While it it is **not** possible to make a [GitHub Pages][gh-pages] site private (the default setup described in the ["Getting Started" vignette][vig-getting-started]), 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: * You can host a private site on [GitLab Pages][gl-pages] and grant access to collaborators. All they need is a GitLab.com account (and they can use a social account, e.g. Twitter, to login to GitLab.com) - [Deploy your site with GitLab Pages][vig-gitlab] * You can deploy a password-protected site using [Amazon Web Services][aws] (requires familiarity with cloud technologies) - [Deploy your site with AWS][deploy-aws] To see all the currently documented deployment options, see the vignette [Alternative strategies for deploying workflowr websites][vig-deploy]. ## How should I manage large data files in a workflowr project? 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][vig-data] for various options for versioning the large data files used in your workflowr project. ## How can I include external images in my website? 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/`. 1. 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") ``` 1. Move the image file(s) to `docs/assets/` 1. 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.: ``` ![](assets/external.png) ``` 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)` 1. Run `wflow_build()` to confirm the external image file(s) are properly displayed 1. 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 ...") ``` 1. 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](https://imgur.com/), [Figshare](https://figshare.com/), 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. ## How can I save a figure in a vector graphics format (e.g. PDF)? 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'}`r ''` 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](https://yihui.org/knitr/options/) globally: ```` ```{r setup, dev='svg'}`r ''` 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')}`r ''` 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}`r ''` 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}`r ''` 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}`r ''` 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) ``` ```` ## Can I include Shiny apps in my website? 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][shiny-external-resources] than the standard for an Rmd-based website. [shiny-external-resources]: https://rmarkdown.rstudio.com/authoring_shiny_prerendered.html#external_resources 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](https://www.shinyapps.io/), and then embed it directly into your document by calling `knitr::include_app()` inside a code chunk, as shown below: ````markdown `r ''````{r shiny-app} knitr::include_app("https://.shinyapps.io//") ``` ```` 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. ## Can I change "X" on my website? Almost certainly yes, but some things are easier to customize than others. The vignette [Customize your research website](wflow-02-customization.html) provides some ideas that are simple to implement. Check out the documentation for [rmarkdown][] and [Twitter Bootstrap][Bootstrap] for inspiration. ## How can I suppress the workflowr report? 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: TRUE ``` And 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: TRUE ``` ## Why am I not getting the same result with wflow_build() as with the RStudio Knit HTML button? `wflow_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][issues] and provide a small reproducible example. ## How should I install packages to use with a workflowr project? 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_decompress1 ``` The 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: 1. Always restart your R session after installing new packages (Ctrl/Command+Shift+F10 in RStudio) 1. Open R from a directory that is not a workflowr project when installing new packages 1. Delete `.Rprofile` with `wflow_remove(".Rprofile")` and manually load workflowr with `library(workflowr)` every time you start a new R session ## Can I create a single HTML or PDF file of one of my workflowr R Markdown files? Yes! 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. ### Working directory 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. ### PDF To convert a single analysis to PDF, use `pdf_document()`. Note that this requires a functional LaTeX setup. ```{r render-single-page-pdf, eval=FALSE} library("rmarkdown") # Create analysis/file.pdf render("analysis/file.Rmd", pdf_document(), knit_root_dir = "..") ``` ### HTML 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()`. ```{r render-single-page-html-1, eval=FALSE} 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. ```{r render-single-page-html-2, eval=FALSE} 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. ```{r render-single-page-html-3, eval=FALSE} 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): ```{r render-single-page-html-4, eval=FALSE} 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. ```{r render-single-page-html-5, eval=FALSE} # use the workflowr::wflow_html settings in analysis/_site.yml render("analysis/file.Rmd", knit_root_dir = "..") ``` ### RStudio Knit button 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][issue-261] for more details. [issue-261]: https://github.com/workflowr/workflowr/issues/261 ## Can I use R notebooks with workflowr? 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: console ``` Second, 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. ````markdown `r ''````{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: 1. 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()`. 2. 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 --- ``` ## Can I use a Git hosting service that uses the HTTP protocol? 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** 1. Configure the remote with `wflow_git_remote()` and `protocol = "ssh"` 1. You can use `wflow_git_push()` and `wflow_git_pull()` 1. 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/Password** 1. You can't use `wflow_git_remote()`. Instead use either a. `git2r::remote_add()` in R: ``` git2r::remote_add(name = "origin", url = "https://custom-site//.git") ``` a. `git remote add origin` in the terminal: ``` git remote add origin https://custom-site//.git ``` 1. You cannot use `wflow_git_push()` and `wflow_git_pull()`. Instead run `git push` and `git pull` in the terminal 1. The embedded links to past versions of the files will be correct because they will be based off of your remote URL ## How should I pronounce and spell workflowr? There are multiple options for pronouncing workflowr: 1. workflow + er 1. workflow + R 1. work + flower 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. [aws]: https://aws.amazon.com/s3/ [Bootstrap]: https://getbootstrap.com/ [deploy-aws]: wflow-08-deploy.html#amazon-s3-password-protected [gh-pages]: https://pages.github.com/ [gh-status]: https://www.githubstatus.com/ [gh-troubleshooting]: https://docs.github.com/articles/troubleshooting-github-pages-builds [gl-pages]: https://docs.gitlab.com/user/project/pages/index.html [issues]: https://github.com/workflowr/workflowr/issues [rmarkdown]: https://rmarkdown.rstudio.com/ [vig-data]: wflow-10-data.html [vig-deploy]: wflow-08-deploy.html [vig-getting-started]: wflow-01-getting-started.html [vig-gitlab]: wflow-06-gitlab.html