Reporting with R¶
This guide provides information about how to design reports with R over Opal data.
R being a programming language, any text editor could be used. In this guide we recommend to use the RStudio editor as it has reporting features integrated. RStudio is cross-platform, free of charge (Open Source Edition) and is available as a Desktop or a Server application. The Server flavor is more suitable for teams (shared development environment) and when restrictive security constraints apply (IP white-listing).
Prerequisites¶
In order to be able to interact with a Opal server, the prerequisites are the following:
- having R installed both on client and on server sides
- having R package opal installed
- having access to a Opal server
Design of a Report Tutorial¶
A report in Opal is essentially a R script enhanced with presentation directives. This reporting capability is brought by the knitr R package. As the report IS a R script, it can be executed in different contexts:
- R console
- RStudio editor
- Shell script
- Opal
See more information about Report Execution Flows.
The following steps will walk you through the design of a report, tested in a development environment (R console/RStudio), then deployed in a production environment (Shell script/Opal).
First Step: Write a R Script¶
Report data are coming first, so start with writing a R script that:
- connects to a Opal server
- assign some Opal data to the remote R session
- analyze, transform the data from the remote R session
- end remote R session
Example
See an example of such a script: opal.R.
Run it in a R console or RStudio.
Second Step: Turn R script to R markdown¶
The R script can be enhanced with presentation directives as specified by knitr. We will chose the specific R report format based on Markdown. Detailed documentation can be found in the R Markdown article.
Example
See an example of such a report: opal-dev.Rmd.
You can run it in RStudio as described in the Using R Markdown article.
See the Opal Reporting with R output.
Third Step: Prepare for Deployment¶
As you might have noticed the opal-dev.Rmd contains the credentials of the user connecting to the Opal server. These can be externalized. Credentials will be provided by the context of execution as R options:
- Shell script
- Opal
See documentation about opal.login function for available R options.
Example
See an example of a production report opal-prod.Rmd. Note that no user credentials is provided. RStudio cannot execute it as usual as the editor does not knit the report in the current R session.
To execute this report you can use the opal.report helper function that will knit it for you. See an example of a R shell script running it: opal-exec.R.
For executing it in Opal, see instructions on how to specify the R options in the Reports Administration documentation.
Final Step: Schedule Report Execution¶
Once a report design is done, it is possible to register it in Opal in order to:
- publish it so that it can be executed manually by other users,
- execute it periodically,
- archive and publish the reports generated.
For more details see Reports Administration.
If you have written a shell script, such as opal-exec.R example, it can be executed as any cron task.
Advanced Examples¶
See advanced examples in the table folder, where opal-table.Rmd features:
- R Markdown sub-reports,
- inline css-styling,
- access to Opal variables description.
The result of this report is a document that presents the data dictionary of a Opal table with figures and summary statistics.