Skip to content

5.3 Deploying Rmarkdown

In this session:#

You will deploy and schedule reports in the form of R Markdown documents to RStudio Connect.

R Markdown Reports#

Note for non-R users:#

  • R Markdown is a form of literate programming, where you embed R code chunks into Markdown text
  • This means you write the body of your document using markdown, with chunks of R interspersed in the markdown.
  • During rendering of the report:
    • The R code chunks are executed
    • Any output from these chunks are rendered as intermediate markdown with embedded figures (for the plots)
    • Then this intermediate Markdown document is converted to the final format
  • The final format is typically HTML, but it could also be PDF, Word or Powerpoint, among many other formats.

In essence, it's a powerful way to mix narrative text with code that renders out to a variety of popular and easy to distribute formats suitable for non-R-users.

Solving the copy-and-paste nightmare#

image

  • One of the advantages of creating automated reports is that it shortens the cycle of content creation to content consumption.

  • Rather than manually editing a report, then emailing the report, Connect lets you publish an HTML report, so you can share your work as a content URL.

Rendering a report#

  • To create a report, press the "knit" button

Deploying a report to Connect#

When you deploy a report to Connect, you have choice between publishing:

  • With source code
    • Giving you the option to schedule the report on Connect
    • This is the more flexible option!!!
  • Final document only
    • This would effectively be a static report

image

Deploying a report (with source code) to Connect#

Refreshing a report from Connect, and viewing the history#

  • Connects keeps the rendered versions of a report, and allows you to manually trigger a referesh (if you published with source code!)

Other static content#

Can Connect host other HTML, Word, PDF, content?

  • Yes, using the rsconnect::deployDoc() function

  • As an admin you will probably not do this, but your R data scientists can use the rsconnect package to script deployments.

  • See rstudio.github.io/rsconnect/

What about plots?

  • Yes

Caveats:

  • Only content generated from an R Markdown document can be emailed.

Parameterized Markdown#

Parameterized reports allow users to specify some parameters to customize the analysis in a report.

References:

RStudio Connect recognizes parameterized Markdown and automatically creates an input pane.

Knitting with parameters in the IDE#

Parameterized Markdown in Connect#

Collaborators and (optionally) viewers can create a new variant of a report. This lets non-R users create their own customized variants.

Private and public reports:

  • For whom:
    • Private : creator.
    • Public: normal access control
  • By who: collaborators

Scheduled and emailed reports:

  • Variants inherit all of the functionality of regular reports.

image

Creating a variant parameterized Markdown in Connect#

  • Use the fly-out pane on the left to enter new parameters and save variants.

Scheduling#

Scheduling a report#

If you deployed an R Markdown with code then you can:

  • Schedule the report to run again
  • Email the report

You can do this by changing settings in the "Schedule" tab

You can change:

  • Schedule frequency
  • Whether to republish the output
  • Whether to send email, and the recipients

image

Distribution permissions#

Collaborators can set up email to:

User type Action
Viewers Ad-hoc and Scheduled
Collaborators Ad-hoc and Scheduled
Other Users Scheduled

Viewers can send email to:

User type Action
Themselves Ad-hoc

A general purpose scheduler?#

The idea that you can turn any R script into a scheduled report is very powerful.

Some possibilities:

  • ETL (extract, transform, load)
  • Perform a regular batch job
  • Scrape data from website and store in a database
    • Assuming you have the legal permission to do so, of course!

image

Can you give me the same report for XXX?#

Create a second scheduled report for your favorite company…

….without leaving Connect

image

Copy and paste nightmare revisited#

image

Deployment history#

The report rendering history is retained for:

  • Scheduled reports
  • On-demand renderings
  • Re-deploys (rendered and static content)

As the Connect sys-admin, you can configure how much history to keep

  • See the Jobs section of the Admin guide.

Email#

Emailing reports#

RStudio Connect allows you to:

  • customize whether or not an email is sent
  • add email attachments
  • specify the email subject line
  • dynamically change the email messages
  • include plots and tables in the email body

A convenient interface is the blastula package. For more information, read the corresponding RStudio blog post and inspect the examples in the Blastula Email Gallery

image

Further reading on email customization#

Study the Connect user guide Chapter 9: R Markdown, in particular:

Databases and scaling#

Databases and scaling#

How do you secure data access to databases from R Markdown?

Do you need to worry about scaling reports?

  • No
  • The reason is that R Markdown reports are static HTML, and is not expensive to serve

Your turn#

Next complete the exercise.

Signs of success:

  • You deployed a Markdown report to Connect
  • You created a scheduled update
  • You triggered a run of the report and found the email in your Roundcube inbox