Reporting is implemented using the officer
package. Officer provides a lot of control over the generation of both Word and PowerPoint documents. If you feel comfortable programming in R, you can simply use that package directly. Currently ubiquity has support for generating PowerPoint output. Trying to keep track of different slide layouts and their indices can be cumbersome. The following functions have been created to allow slides to be created easily:
system_report_init
- Initialize a new report from a templatesystem_report_slide_title
- Add a title slidesystem_report_slide_section
- Add a slide separating sections in a presentationsystem_report_slide_content
- Add a slide with a title, subtitle and a single area of content taking up the entire slidesystem_report_slide_two_col
- Add a slide with a title, subtitle, and two columns of content with or without headingssystem_report_view_layout
- Generate a PowerPoint file from a template labeling the different elements each slide layoutsystem_report_fetch
- Fetch the officer object for a reportsystem_report_set
- Set the officer object for a reportsystem_report_save
- Save a report to a fileThe workshop (http://workshop.ubiquity.grok.tv) provides an example of how to use these functions. To make a copy of an example script run the following:
This should create the following script
make_report_PowerPoint.R
Generates a PowerPoint presentation from an R scriptThe first step is to initialize a report:
With the report created we can begin adding slides. There are several diffent slide formats with different placeholders for content. Each placehodler can contian a different type of content (text, list, image file, etc). The following list provides a the available content types followed by the format of the content:
"text"
text string of information"list"
vector of paired values (indent level and text), eg. c(1, "Main Bullet", 2 "Sub Bullet")
"imagefile"
string containing path to image file"ggplot"
ggplot object, eg. p = ggplot() + ...
"table"
list containing the table content and other options with the following elements (defaults in parenthesis):
table
Data frame containing the tabular dataheader
Boolean variable to control displaying the header (TRUE
)first_row
Boolean variable to indicate that the first row contains header information (TRUE
)"flextable"
list containing flextable content and other options with the following elements (defaults in parenthesis):
table
Data frame containing the tabular dataheader_top
, header_middle
, header_bottom
(NULL
) a list the same names as the data frame names of the tabular data and values with the header text to show in the tablemerge_header
(TRUE
) Set to true to combine column headers with the same informationtable_body_alignment
, table_header_alignment
(“center”) Controls alignmenttable_autofit
(TRUE
) Automatically fit content, or specify the cell width and height with cwidth
(0.75
) and cheight
(0.25
)table_theme
("theme_vanilla"
) Table themeFirst you may want to add a title slide to the presentation:
cfg = system_report_slide_title(cfg,
title = "Generating Inline Reports",
sub_title = "A Working Example")
Next you may want to add an overview of your analysis. The content
slide provides one placeholder that you can fill with any of the above content types.
cfg = system_report_slide_content(cfg,
title = "Single text area",
content = "This vignette provides examples of how to add different types of slide content" )
The default content type is text, but you may want to add a list. Lists are formatted as vectors with paired elements. The first element contains the indention level and the second element contains the actual text:
lcont = c(1, "Top level item",
2, "This is a sub bullet",
2, "This is another sub bullet")
cfg = system_report_slide_content(cfg,
title = "Lists are pretty straight forward",
content_type = "list",
content = lcont)
If you are running simulations and want to dump ggplot
figures to a file, that is pretty easy as well. Here we will simulate a single dose:
parameters = system_fetch_parameters(cfg)
cfg = system_zero_inputs(cfg)
cfg = system_set_bolus(cfg, state = "At",
times = c( 0.0),
values = c(400.0))
cfg=system_set_option(cfg, group = "simulation",
option = "output_times",
value = seq(0,60,.1))
som = run_simulation_ubiquity(parameters, cfg)
Then we can plot the response in ggplot
:
myfig = ggplot() +
geom_line(data=som$simout, aes(x=ts.days, y=C_ng_ml), color="red") +
xlab("Time (days)")+
ylab("C (ng/ml) (units)")
myfig = gg_log10_yaxis(myfig, ylim_min=1e3, ylim_max=1e5)
myfig = prepare_figure("present", myfig)
Then that figure can be added to a slide:
cfg = system_report_slide_content(cfg,
title = "ggplot objects can be inserted directly",
content_type = "ggplot",
content = myfig)
You can also pull image content from files as well using the imagefile
content type.
cfg = system_report_slide_content(cfg,
title = "Images can be inserted from files",
sub_title = "But the image should have the same aspect ratio as the placeholder",
content_type = "imagefile",
content = system.file("ubinc", "images", "report_image.png", package="ubiquity"))
The benefit of using ggplot
is that it will automatically size the image to the dimensions of the placeholder. To use an image file the image file needs to have the same aspect ratio as the placeholder you want to put it in.
Tabular data can be include too. The simplest method is to use the table
content type and supply a list with an element named table
containing a data frame with the tabular information you want to display:
tcont = list()
tcont$table = parameters
cfg = system_report_slide_content(cfg,
title = "Simple Tables",
content_type = "table",
content = tcont)
This may not be the most attractive way to display tabular information, and for smaller tables it may be a bit poorly formatted. As an alternative the flextable
package can be used by specifying that content type:
tcont = list()
tcont$table = parameters
cfg = system_report_slide_content(cfg,
title = "Flextables",
content_type = "flextable",
content = tcont)
To provide a little more formatting, two column masters are provides. The content_type
argument indicates the type of text that can be included. It should be either "list"
or "text"
. If the left or right content is to contain a table or figure it can be overwritten.
cfg = system_report_slide_two_col(cfg,
title = "Two columns of lists",
sub_title = NULL,
content_type = "list",
left_content = lcont,
right_content_type = "flextable",
right_content = tcont)
You can specify column headers if you like. These be text
, imagefile
, ggplot
, table
or flextable
.
cfg = system_report_slide_two_col(cfg,
title = "ggplot vs imagefile",
sub_title = NULL,
content_type = "list",
left_content_header = "Image file",
left_content_type = 'imagefile',
left_content = system.file("ubinc", "images", "report_image.png", package="ubiquity"),
right_content_header = "ggplot object",
right_content_type = "ggplot",
right_content = myfig)
Finally, after you have added all of your sldies, you will want to put them in a file:
To use a custom template for your organization you need to do the follwoing:
Using your organizational template create slide masters below with the content elements to the right. The title and subtitle elements of the title_slide
and section_slide
should be of the type ctrTitle
and subTitle
, respecitvely. For the rest of the slides the title elements should be of the type title
, and the other elements should simply be of type body
. The format of the body elements should be plain text unless identified parenthetically below.
Master layout name | Content Elements |
---|---|
title_slide | title, subtitle |
section_slide | title, subtitle |
content_text | title, subtitle, main content |
content_list | title, subtitle, main content (list) |
two_content_list | title, subtitle, left, right, left body (list), right body (list) |
two_content_text | title, subtitle, left, right, left body, right body |
two_content_header_list | title, subtitle, left header, right header, left body (list), right body (list) |
two_content_header_text | title, subtitle, left header, right header, left body, right body |
title_only | title |
Each element in a master is identified with an index number (index
) and placeholder label (ph_label
). These values are asigned as the master slide is built, so it can be difficult to find this information through PowerPoint. If you named your template mytemplate.pptx
, then you can have ubiquity produce a slide deck with the masters annotated so you can identify these values:
cfg = build_system()
cfg = system_report_init(cfg, template="mytemplate.pptx")
cfg = system_report_view_layout(cfg)
This should create a file called layout.pptx
that has the layout
name of each slide master in the title. Both the ph_label
and index
of each element will be identified. These slides should look something like:
Master slide layouts
To map your layout information you should use the myOrg
template:
This should create the file myOrg.R
in the current directory. You can edit this file and go to the function named org_pptx_meta
. This returns the variable meta
which contains this mapping information. You need to look at the information in layout.pptx
and make sure it matches the information returned in meta
.
To use your own template you simply need to source the myOrg.R
file at the top of your script and then initialize the report using your own template (mytemplate.pptx
) and the meta information returned from org_pptx_meta
.
source("myOrg.R")
cfg = system_report_init(cfg = cfg,
meta = org_pptx_meta(),
template = "mytemplate.pptx")
Now you can use the other reporting functions to add slides to the default
report.