Tutorial | R Markdown reports#

Get started#

R Markdown is an R package to create fully reproducible, print-quality documents that incorporate narrative text and code to produce elegant output. You can create this kind of report directly within Dataiku, and then share them on dashboards or deliver them in a variety of static formats for offline reading.

Objectives#

In this tutorial, you will:

  • Create an R Markdown report in Dataiku.

  • Publish it as an insight to a dashboard.

  • Automate report updates using a scenario.

Prerequisites#

  • Dataiku 12.0 or later.

  • An Advanced Analytics Designer or Full Designer user profile.

  • The R integration installed. To get started:

  • The built-in R code environment includes the required packages, such as rmarkdown.

Create the project#

  1. From the Dataiku Design homepage, click + New Project > DSS tutorials > Developer > R Markdown.

  2. From the project homepage, click Go to Flow (or g + f).

Note

You can also download the starter project from this website and import it as a zip file.

Create an R Markdown report#

From the project, create a new R Markdown report:

  1. In the Code menu (</>) of the top navigation bar, select RMarkdown Reports.

  2. Click + New Report.

  3. Leave the default for a Starter document demonstrating R Markdown syntax.

  4. Click Create.

Dataiku screenshot of the dialog to create a new R Markdown report.

Edit an R Markdown report#

Similar to the editor for a webapp, the R Markdown editor is divided into two panes.

  • The left pane allows you to edit the code underlying the report.

  • The right pane gives you several views on the report.

The right pane has three tabs:

Tab

Purpose

Preview

Receive immediate visual feedback on what’s present in the left pane.

Log

Useful for troubleshooting problems.

Settings

Set the report’s output format and code environment.

Add document metadata#

In an R Markdown report, the YAML header (demarcated by three dashes ---) defines the document metadata.

  1. In the R Markdown report editor, click Force Build to create the initial preview.

  2. In the left pane, add a date argument to the YAML header.

    ---
title: "R Markdown report"
date: "`r format(Sys.Date())`"
---

  3. Click Save (cmd/ctrl + s) to see the reloaded preview.

Dataiku screenshot of an R Markdown report showing the force build option.

Add R code#

Instead of the iris dataset, let’s use the Dataiku R API to get a dataframe of the Flow’s initial dataset called churn.

  1. In the left pane, replace the report’s first R code block with the one below.

    library(dataiku)
df <- dkuReadDataset("churn")
hist(df$CustServ_Calls)

  2. Click Save (cmd/ctrl + s) to see the report’s preview reload with a histogram.

Dataiku screenshot of an R Markdown report with a histogram.

Tip

If needed, you can disable the auto-build setting in the Settings tab of the right pane.

Add narrative text#

You can also add narrative text with markdown formatting.

  1. Edit any of the narrative sections of the report — those not within the YAML header or a code block.

  2. Read the rest of the report for examples of inline code and styling.

  3. Click Save to reload the new report preview.

Publish an R Markdown report on a dashboard#

R Markdown reports in Dataiku behave like other types of insights, and so can be published on dashboards.

  1. From the Actions panel of the report, click Publish > Dashboard.

  2. When the report finishes building, click Create to save the report as an insight and add it to the project’s dashboard.

    Dataiku screenshot of the dialog to publish an R Markdown report to a dashboard.

  3. In the dashboard editor, drag the corners of the insight to increase its display dimensions.

  4. Click Save.

  5. Click View.

Create a snapshot of an R Markdown report#

Once you’ve published a report to a dashboard, you’ll want to make sure that updates to the report are present in the dashboard insight.

  1. In the Edit tab of the R Markdown report, make any arbitrary change, and click Save.

  2. Confirm the change is not automatically present in the dashboard insight.

  3. In the Actions panel of the R Markdown report, click Snapshot.

  4. Confirm the change appears in the dashboard insight.

Dataiku screenshot of the snapshot action for an R Markdown report.

Automate an R Markdown report snapshot#

To automate taking these snapshots, use a scenario.

Use an Export R Markdown report scenario step#

The first option is to refresh the dashboard insight with a step in a scenario.

  1. Make another arbitrary change in the R Markdown report.

  2. From the Jobs menu of the top navigation bar, select Scenarios.

  3. Click + New Scenario.

  4. Name it Refresh R Markdown, and click Create.

  5. Navigate to the Steps tab of the scenario.

  6. Click Add Step > Export R Markdown report.

  7. For the RMarkdown report field, select rmarkdown report from the dropdown.

  8. Click Run to trigger the scenario.

    Dataiku screenshot of a scenario building an R Markdown report.

  9. Confirm the latest change is present in the dashboard insight.

Attach an R Markdown report to a mail reporter#

Instead of refreshing the dashboard insight, you can also send the latest report as an attachment in a mail reporter.

  1. Navigate to the Settings tab of the scenario.

  2. Click Add Reporter > Mail.

  3. Click Add Attachment > RMarkdown report.

  4. For the attached report field, select rmarkdownreport.

  5. Complete other necessary details for the mail reporter.

Dataiku screenshot of an R Markdown report included as an attachment to a mail reporter.

Tip

You can see a walkthrough of a scenario reporter in Tutorial | Scenario reporters.

What’s next?#

Congratulations! Using Dataiku, you have created an R Markdown report.

To gain more practice using R with Dataiku, see Tutorial | Dataiku for R users.

You can also learn more in the reference documentation on R Markdown reports or, more generally, on DSS and R.