Two ways to render R Markdown documents
I saw this tweet a couple of days ago and decided to look for ways to use R Markdown more at work.
R Markdown provides an authoring framework for data science. You can use a single R Markdown file to both save and execute code, and generate high quality reports that can be shared with an audience. R Markdown is a program for making dynamic documents with R. An R Markdown document is written in markdown, an easy-to-write plain text format with the file extension.Rmd. It can contain chunks of embedded R code. It has a number of great features. R Normal Distribution Functions. Density, distribution function, quantile function and random generation for the normal distribution with mean equal to ‘mean’.
TIL you can embed a 'code download' button in an HTML #rmarkdown doc so that users can click to download your source .Rmd from the rendered HTML version...without GitHub 🤩 #rstats
YAML:
---
output:
html_document:
code_download: true
---
Test: https://t.co/bp7w7XKF8bpic.twitter.com/uMQK0mvYcF
It’s not like I haven’t tried to use R Markdown before1, but at the time of this post, I hadn’t been able to find a way to effectively incorporate R Markdown at work for various reasons. Since then, however, I added a couple of new tools to my data analysis toolbox2, which I felt might help make it work this time using R Markdown more at work.
Render R Markdown from Vim (without opening R)
And there was a Vim plug-in for R Markdown indeed! In fact, a quick online search led me to three relevant/required Vim plug-ins: vim-rmarkdown, vim-pandoc, and vim-pandoc-syntax.
Following the plug-in instructions, as well as this helpful configuration tip, I was up and running with vim-rmarkdown plug-in in no time.
Figure 1: Rendering R Markdown Document from within Vim
In addition to the syntax highlighting (from vim-pandoc/vim-pandoc-syntax plug-ins), the vim-rmarkdown plug-in provides a function to render a source R Markdown document into output types of interest (e.g., html) from within the source R Markdown document in Vim. :RMarkdown command does the job, and it displays successful run message once the rendering is complete3.
Render R Markdown (and send email) from R
R Markdown documents can also be rendered from R too, by the usual rmarkdown::render() function. Generally one can review the rendered output by clicking the output file, but what if such clicking/reviewing is not an option? That’s a challenge I’m facing at work. Ok, maybe there’s a way to click/review a remote file, and if that’s the case, then nobody hasn’t told me how to just yet :)
I’m sure there’s a better way, but the workaround I came up with has two steps:
- Render R Markdown document (rmarkdown::render())
- Send an email to self with rendered output as attachment (sendmailR::sendmail()).
I didn’t know about the sendmailR package before, but the package lets you send emails from within R. I ended up writing a couple of wrapper functions (saved in my personal package) so that rendering and sending email can be done all at once by a single function call. Yes there are some drawbacks4, but I’ve been happy with the workflow so far.
Output Metadata¶
We normally think of R Markdown documents as producing a single outputartifact, such as an HTML or PDF file. The rmarkdown package allows reportauthors to emit additional output metadata from their report. RStudio Connecttakes advantage of this metadata, allowing output files, custom emailsubjects, and additional email attachments.
There are two ways to set output metadata: in the YAML header and in R codechunks.
The YAML header is a good place to configure default values for metadata thatyou always want to emit. All output metadata lives under thermd_output_metadata section in the YAML:
You can also use R code to set output metadata. This is useful if you wantmetadata to vary based on conditions or variables within your code.
Your R code can also read the current state of your output metadata. This canhelp you gradually alter this information as the report runs.
Note
The rmd_output_metadata names starting with rsc_ are reserved for use with RStudio Connect.
Output Files¶
Introduction to Output Files¶
Output files are files that live alongside your rendered report. They couldbe plots, data files, or other artifacts generated from the R code in yourreport. Output files will be available via HTTP, and they will be versioned inthe same way as your report. Output files are also subject to the same accesscontrols as your report.
Connect will not process any output files that exist outside the workingdirectory of the report that is rendering. That means that you cannot useabsolute paths (e.g., /root/file.csv) or relative paths (e.g., ../file.csv).
How to Work with Output Files¶
There are two ways to specify which files should be treated as output files.The first is to list the file names in the R Markdown YAML header'srmd_output_metadata section under rsc_output_files, like so:
rsc_output_files takes a list of names of files that should be availableafter the report has rendered. If you list a file that does not exist afterrendering your report, Connect will log a message but continue trying toprocessing the other files listed. If the output files are not generatedduring the rendering of your report, then you need to list them as resourcefiles when you upload your report to Connect. See ResourceFiles for more information.
It is also possible to specify the list of output files from R code.For example:
Output files can be contained within sub-directories; the relative directorystructure is maintained.
To include a directory:
You can also make a link to share an output file from your report using thestandard Markdown links as supported in R Markdown. For example, if you want toshare a file named data.csv, you make a link to it in your report like this:
Because output files are versioned along with the rendering of their report,they also benefit from historical views. In the example above, if you viewa historical rendering of the report, when you click on the data.csv link,you will get a download of the file from the same point in time as the report.
Accessing output files over HTTP¶
Content deployed to http://connect.mycompany.com/content/42/ will have itsoutput files available under that URL path. An output file nameddaily-summary.csv will be available at the URLhttp://connect.mycompany.com/content/42/daily-summary.csv.
The URL for your content is the same as its 'Open Solo' location and isavailable in the RStudio Connect dashboard.
Resource Files¶
If you want RStudio Connect to host a file that you have in your report's sourcedirectory on your computer, and that file is not generated by the report whenyou render it, then you will need to mark that file as a resource file. Like anoutput file, a resource file can be a plot, a data file, or any other artifactthat exists as a file. You can use the RStudio IDE to select resource files, oryou can list them in the R Markdown header:
Unlike rsc_output_files, the resource_files key is not nested underrmd_output_metadata. If you do not list your resource files underresource_files, then you will need to add them manually using the 'AddMore...' button when deploying from the IDE. See the Publishingsection for more information on publishing additionalresource files.
Email Customization¶
RStudio Connect makes it easy to schedule reports that distribute emails. Theseemails, by default, contain a link to the report. However, it is possible tofully customize the email, and distribute results directly tousers without requiring them to leave their inbox.
There are two approaches for customizing email in Connect. One approach is todirectly set R Markdown OutputMetadata. This option is the mostflexible, but also the hardest to use. The second approach is to use theblastula package. Using the blastulapackage is the easiest way to get started and is recommended for most use cases.
Getting Started with Custom Emails¶
To get started with custom emails, we recommend using theblastula package. The easiest way tostart is by installing the package and using the included example:
This command will create a new folder in your workspace with a number of examplefiles. In general, the approach when using blastula is to create a new RMarkdown document responsible for crafting the email. This R Markdown documentis then attached to your original document by including the following code inthe main R Markdown file:
Info
This code is an example from the final code chunk found inconnect-example-main.Rmd Rendering the main report will create a previewof the custom email. When you publish to RStudio Connect, simply include thechild R Markdown document responsible for the email as a supporting file.
Using R Markdown Metadata¶
Instead of using the blastula package, it is possible to construct custom emails using R Markdown Output Metadata. A quick summary of the output metadata options are:
| Option | Description |
|---|---|
rsc_email_subject | A character string giving the email subject line |
rsc_email_body_text | A character string to be used as the plain-text body of the email |
rsc_email_body_html | A character string that results in HTML to be rendered in the body of the email |
rsc_email_attachments | A list of relative file paths for files to be attached to the email |
rsc_email_images | A named list, where the key matches the CID name of the image in the email body, and the object is a base64 encoded image. |
rsc_email_supress_scheduled | A boolean, whether to send the scheduled email (FALSE) or suppress the email (TRUE) |
rsc_email_suppress_report_attachment | A boolean, whether to include the rendered report as an attachment to the email |
To set an option, use code like:
The following sections describe the individual options in more detail.
Email Subject¶
You can customize the subject line used when an email of a report isgenerated. RStudio Connect uses the output metadata entry namedrsc_email_subject as email subject. A report without an rsc_email_subjectentry uses its published document name.
Use the YAML header to specify a simple, static text override of the emailsubject:
Set the email subject in an R code chunk if you need to dynamically build thesubject:
The RSC_EMAIL_SUBJECT environment variable contains the name of yourpublished report, which also acts as the default email subject. Thisenvironment variable is helpful if you want to add, but not fully replace thesubject.
Note
The value of RSC_EMAIL_SUBJECT is computed when your report is rendered.Changes to the report name will be incorporated into subsequent renderings.
You can also read the current subject from the output metadata toincrementally compose a final subject.
Email Body¶
A report can customize the message body used when an email for that report issent. RStudio Connect uses the output metadata entry namedrsc_email_body_text for plain-text bodies and rsc_email_body_html for HTMLbodies. A report with neither entry uses an automatically generated,plain-text body with a link to the report's URL.
Text Message Bodies¶
Use the YAML header to specify a simple, static text override of the emailbody:
The message in the email client would look similar to the following:
Set the body text in an R code chunk if you need to dynamically build themessage:
You can also read the current body from the output metadata toincrementally compose a final body.
The glue package can help with more complicatedformatting.
HTML Message Bodies¶
The rsc_email_body_html attribute specifies an HTML-formatted message body.RStudio Connect sets the content-type of the message so that most emailclients will display the HTML message correctly.
Note
Use rsc_email_body_text together with rsc_email_body_html to supply textthat older email clients can display while allowing newer clients to displayyour rich content.
The YAML header can specify a simple, static HTML override of the email body:
You can build the HTML message dynamically:
Composing and styling HTML email messages is different than buildingtraditional web pages. Email messages cannot embed scripts nor referenceexternal stylesheets. Email clients may implement additional restrictions.
Note
Not all email clients display HTML messages exactly the same. Send yourselfa test message to check basic formatting, then confirm with your audiencethat the message appears correctly in their email client.
Embedding Images in HTML Email¶
Info
For emails including images or tables, we highly recommend using the blastula package.
R Markdown List
It is possible to embed images, such as plots, within HTML email, using thersc_email_images attribute in rmd_output_metadata. The embedded image musthave a Content ID that is used in the body of the HTML and when providing theimage to rsc_email_images, and the image itself must be base64-encoded. Hereis an example:
Including URLs and Other Details¶
You may want to customize your email with a link to the location of the reportin RStudio Connect or to give your email recipients a way to manage their emailsubscription. RStudio Connect provides the R Markdown render with environmentvariables that can be referenced from your code.
| Variable Name | Example Value |
|---|---|
RSC_REPORT_NAME | 'Quarterly Sales Summary' |
RSC_REPORT_RENDERING_URL | 'http://rsc.company.com/content/42/_rev1/' |
RSC_REPORT_SUBSCRIPTION_URL | 'http://rsc.company.com/connect/#/apps/42/subscriptions' |
RSC_REPORT_URL | 'http://rsc.company.com/content/42/' |
Note
The value of RSC_REPORT_NAME is computed when your report is rendered.Changes to the report name will be incorporated into subsequent renderings.
The final values of the URL environment variables are not known prior to rendering. RStudio Connect renders your document using placeholder values for these environment variables. The placeholder values are replaced when constructing the final email message. These URLs are not appropriate for use in the body of your report.
Use the Sys.getenv() function to get the values for these environmentvariables in your report. When rendering your report outside of RStudio Connect,these environment variables will not have values. Use the second argument toSys.getenv() to provide a temporary value.
You can use these variables anywhere within your email body or footer.
Email Attachments¶
An attachment is an output file that will be attached to an emailed report. Youcan specify email attachments as an argument to theblastulaattach_connect_emailfunction, or using the rsc_email_attachments R Markdown Output Metadata.
For example, using blastula:
For example, using output metadata:
For nested files, include the relative path:
An email attachment will be accessible via HTTP just like an output file, andyou can make a link to it in your report in the same way.
Some mail systems have limitations on attachments in email messages.Attachments from your report need to follow the restrictions enforced by yourorganization. Connect is not aware of those limitations. Please work withyour systems administrators / IT organization if you have trouble deliveringfile attachments.
Conditionally Sending Email¶
By default, reports can be configured to run on a regular schedule. However, youmay only want to send an email to stakeholders under certain conditions. Forexample, you could have a report that runs every day to check supply levels, butonly sends an email notification if supplies dip below a critical threshold.
This behavior can be configured with the blastula package or using R MarkdownOutput Metadata.
Using blastula you can craft an if statement around the call to attach_connect_email:
Using R Markdown Output Metadata follows a similar pattern with an if statement:
Suppress Attaching Report To Email¶
By default, Connect adds the generated document as an attachment to emailmessages for that report. You can prevent this attachment from your R Markdownreport by giving the rsc_email_suppress_report_attachment metadata property alogical (Boolean) value or using the attach_output = FALSE argument inblastula::attach_connect_email.
Note
Attachments configured by the rsc_email_attachments metadata property(seecEmail Attachments) are still attachedand not affected by the rsc_email_suppress_report_attachment setting.
Tracking Visits¶
Connect records visits to R Markdown documents and lets you see:
- Which documents were viewed
- When the documents were viewed
- Who viewed the documents
Details about visits are also recorded for parameterized R Markdown documentsand other types of rendered and static content.
An overview of recent activity is available in the RStudio Connect dashboard.See the Content Settings Panel section to learn more.
Rmarkdown Png
Details about each visit are available through the InstrumentationAPIs. Use these records to perform your ownanalysis. Code examples showing how to obtain this data can be found in theUser Activity section of the RStudio Connect:Server API Cookbook.