Design Report

FACTS Design Report User Guide

Introduction

Purpose and Scope of this document

This document describes usage and how to update the installation of the Design Report Generator, an automated report generation tool, included with FACTS. It is intended for anyone concerned with using the automated report generation facility. The Report Generator is available only for the desktop version of FACTS.

Using the Design Report Generator from FACTS

Software prerequisites

In order to run the report generator directly from FACTS, you will need the following installed on your Windows machine on which you are using FACTS:

  • A reasonably recent version of R (v3.5.3+) along with the R libraries ‘rmarkdown’, ‘xtable’ and ‘stringi’ installed.
  • RStudio (the Design Report Generator uses two packages that come with RStudio – “mathjax” and “pandoc”, these can now be obtained separately but given the ubiquity of RStudio FACTS simply requires you to have that installed).
  • Microsoft Word or Open Office
  • FACTS v7.1 or later
Note

Recently we’ve experienced some problems with “pandoc”, downloading and installing from the pandoc website (https://pandoc.org), then re-starting Windows has fixed them.

Setup

You will need to inform FACTS of the location of R and RStudio on your computer.

To do this start FACTS and go to menu option: “Settings > Options” and then to the “R Configuration” tab.

Figure 1

Select the R and RStudio versions you would like to use.

If the version you wish to use isn’t shown, or the path is incorrect, use the “Edit” button to open a file browser to navigate to the version of R that you wish to use and select the appropriate version of “R.exe”. Similarly for RStudio.exe.

Figure 2

Steps for generating a design report

To generate a design report from FACTS, you will need to do the following sequence of steps:

  1. Simulate your design in FACTS.
Note

In case you have previously generated a report for your design using the report generator, you will need to make sure that the previous version of the report is not open in Word when you generate a new report.

  1. After setting valid R and RStudio versions/paths in Settings > Options, go to the “Simulation” tab and click on the “Design Report” button. A command prompt Window will open detailing the report generation process. The very first run of the design report generation process will take a bit longer than subsequent runs as it will have to install all relevant R packages in a FACTS specific location.

  2. Once the command prompt closes, the Word document will be automatically opened. It will first give you a warning regarding the document containing fields that may refer to other files, click “Yes” and then a subsequent warning regrading update the Table of Contents will appear. Click “Update entire table” and your report should appear.

Figure 3: Example FACTS design report for a Core continuous endpoint design

Usage Notes

Location of the generated Word file

The generated report document is stored in the “results” folder of your FACTS simulation (e.g., if your FACTS project is saved as CoreDesign.facts, the folder named CoreDesign_results is the corresponding ‘results’ folder).

Suggested steps after generating the report

A typical workflow after initially generating the report is as follows:

  1. Review the generated report for correctness, and fix minor typographical and formatting errors if any.
  2. If you would like to use a predefined Word template, you could apply the template to your report.
  3. Modify the default table style and add table cross-references as needed.
  4. Add additional text and figures as needed. For example, you can copy graphs displayed in the FACTS GUI by clicking on the “Export options” button next to the r graph, selecting “Copy image to clipboard” and pasting it in the generated report.

Location of the Report Generator source files

The Design Report Generator uses R and Rmarkdown to create the report document. The script files used by the Report Generator are stored in the “ReportGenerator” folder under your FACTS installation folder. (It might be named something like C:\Program Files (x86)\BerryConsultants\FACTS 7.1.0\ReportGenerator). The files within this folder with file extensions of “.R”, and “.Rmd” are the ones required by the Report Generator. If an updated version of the Report Generator is made available either as a bug-fix or intermediate release, it will consist of updated “.R” and “.Rmd” files. Simply replacing the corresponding files in the original installation folder will deploy the updated version.