FACTS Installation Guide

First Time Setup

Introduction

Purpose of this document

This document describes how to install and verify the installation of the FACTS (Fixed and Adaptive Clinical Trial Simulator) software. It is intended for anyone concerned with the installation of the system.

Scope of this document

This document covers the installation and installation verification FACTS. It is only intended to demonstrate the usage of the software to the extent that it verifies the software will execute properly in the installed environment.

For parameter meanings or detail into the internal workings of the design engines or algorithm check the appropriate System Requirements Document. For appropriate guidance on usage check the User Guides.

Context of this Issue

This document is a guide to the FACTS installation, including both the desktop application and the grid components.

FACTS Overview

FACTS allows designs for a clinical trial to be evaluated and compared to traditional designs, thus allowing designs to be optimized. The designs fit a selected model to endpoints of interest, and evaluate pre-specified decisions based on the properties of the fitted model. These decisions may include changing the patient allocation probabilities, changing the patient population and/or whether the trial should be stopped for success or futility.

System Requirements

Desktop Requirements

FACTS can be run on a standard system laptop or desktop running Windows 10 or 11 with the Windows .NET framework v4 or higher installed and at least 1 GB per core or more memory.

In addition:

  • FACTS is expected to run on a display with a resolution of at least 1024x768 pixels and preferably greater.
  • User choice of non-default Windows styles/themes may result in unexpected and impractical foreground and background color combinations.
  • FACTS 7.0 targets .NET Framework 4.8. Future versions of FACTS will target the latest available .NET Framework version.
  • FACTS is now a 64-bit application and will be installed on the target machine’s Program Files area. Previous to FACTS 6.4 versions of FACTS were 32-bit applications installed on the target machine’s Program Files (x86) area.

Computation Requirements

FACTS relies on running simulations and these simulations can be very computationally intensive. When running simulations, each simulation can be run separately (they do not depend on the results of other simulations) though to do so can be somewhat inefficient – repeatedly starting new processes and generating separate output files for every simulation that will need to be gathered together in a single “simulations.csv” file and then summarized. Thus FACTS allows the user to specify a “packet size” and the total number of simulations for each scenario to be simulated is divided by this packet size to create a set of independent jobs.

If the simulations are run on the users laptop or PC, FACTS will spawn a simulation thread for every core on the local machine up to the maximum number of simulation ‘packets’ that have been requested. The simulations are run at reduced priority so it is possible to continue to use the machine e.g. for email or Word whilst they run. Thus usually 2 or 4 sets of simulations are run in parallel depending on the processor in the laptop or PC.

There are a number of options for speeding up the running of FACTS simulations:

  1. The simplest technically (and the approach we used to take at Berry Consultants) is to have a large multi-core server (say 32 core) remotely accessible to FACTS users and FACTs installed on it. To use, the user copies the “.facts” files to be simulated to a network shared directory which can be accessed from the server. Then after remotely logging into to the server, the user copies these files to a drive on the server, runs the simulations, zips up the results (within the FACTS GUI there is the FACTS File > Export Project menu command to do this) and copies them back to the network shared drive and thence to their local machine.
  2. Use the FACTS network share folder “grid” interface, implemented using file transfers to and from a shared network drive. On a machine that can act as a client to a grid of compute nodes managed by one of the standard grid management packages (they used to be called “SunGrid” and “Condor” but have metamorphosed over the years) a “sweeper script” runs that transfers jobs to the grid. The jobs automatically transfer their results back to this shared drive. FACTS copies the job to a unique subfolder on the shared network location and then watches for a change in the lock file name - “submitted”, “running”, “complete” that are managed by the sweeper script. Once the simulations are complete FACTS copies the results back to the local machine. The fact that the simulations have been submitted to the grid are stored in the “.facts” file. Whenever that “.facts” file is open in FACTS, FACTS will poll the remote network drive to check if the simulations are complete.
  3. A more sophisticated FACTS grid interface that uses a web services to communicate between the FACTS client and a Linux server running a web-server (Apache Tomcat) and database (MySQL). The web service is used to submit jobs and they are stored in the database. A database process then submits them to the grid, once again managed by one of the standard grid management packages. The simulation results are then stored in the database for FACTS to download once complete. This provides a more robust and manageable interface, but it more work to set up. We can provide documentation and scripts and we can assist in setting this up. This is the form of grid that we now use in-house at Berry Consultants.
  4. Technically as 3. (but for a fee) Berry Consultants can set and manage the grid for you in the cloud. Please contact us to discuss your requirements and for pricing. Therefore FACTS is able to offload the simulations from the desktop to be run by an external system. The interface describing the interactions with the external system is described in the FACTS Grid Interface document. With a FACTS Enterprise License, the command line executable files to run simulations externally under either Windows or Linux environments are available upon request.

Desktop Installation

Installation Instructions

The FACTS Desktop installation package consists of:

File Description
setup.exe a Windows installation program
Setup.msi the FACTS Microsoft Installer file
Examples.zip a Zip file containing example FACTS projects
Documents.zip a Zip file containing the FACTS documentation.
Config.xml an XML file containing the local configuration settings.

These files are usually made available for download from Berry Consultants Microsoft App Center site. Download instructions are in a separate document.

Versions of these files with the standard file extensions (.msi and .zip) modified are available it may have been these versions that were downloaded to circumvent firewall restrictions and these files will need to be renamed prior to use.

Installation will take only a few moments.

  • Ensure that all the files have the correct file extension and are located on a local drive on the machine on which FACTS is to be installed. Windows can treat installs from networked drives as less trustworthy than installs from local drives and this can result in an incomplete installation.

  • Right click the setup.exe Windows installation program and select “Run as Administrator”.

  • Follow the instructions on the screen to complete the installation.

  • During FACTS installation you will have to option to enable FACTS to report Analytics back to the App Center. This allows to see how much FACTS is used and which features in FACTS are being used. It does NOT include any user or license information, we can’t see WHO is doing what, only WHAT is being done. Obviously we’d be grateful if you’d enable them.

    Analytics are off by default they will only be enabled of you enable them.

    Once installed analytics can be turned on or off from the FACTS “Settings” menu command.

Config.xml

Included with the FACTS installation files is a configuration file that can be edited to local settings before the install files are distributed to users. It is also possible to provide an updated copy of the configuration file to users and ask them to update their default configuration, it is also possible for users to locally modify their configuration and revert to the installed configuration details.

Prior to installation, a configuration file, ‘config.xml’, is available as one of the installation files. This file can be edited to set up a number of default settings for FACTS.

The settings are listed between the tags: <configuration> <userSettings> and </userSettings> </configurations>, for example:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <userSettings>
    <GridLocation>C:\\work\\grid</GridLocation>
    <GridOpSys>1</GridOpSys>
    <GridListenerDelay>10000</GridListenerDelay>
    <LocalRVersions>
      <value>version="3.3.2" path="C:\\Program Files\\R\\R-3.3.2\\bin\\R.exe" active="1"</value>
      <value>version="RStudio" path="C:\\Program Files\\RStudio\\bin\\RStudio.exe"</value>
    </LocalRVersions>
    <FactsSimulationServicePortURL>http://nowhere.com:8080/axis2/services/FactsSimulationServicePort</FactsSimulationServicePortURL>
    <GridSimMethod>0</GridSimMethod>
  </userSettings>
</configuration>

Specifically, the following values may be adjusted, as desired:

  • LocalRVersions – a list of available R (or RStudio) versions, each one bracketed by the tags and and composed of two parameters “version” which can contain any string to be used to identify that version of R and “path” which should contain location of “.exe” that should be run when the user requests R to be run or a Design Report to be generated.
  • GridSimMethod – 0 or 1, Determines how FACTS tries to connect to the grid, 0 means the network file share & sweeper script method (option 2 above) is to be used, 1 means that the Web Service method (option 3 or 4 above) is to be used
  • If the network file share method is to be used to connect to the grid then:
    • GridLocation – the network location of the network file share.
    • GridOpSys – 0 or 1, the type of the operating system that is running on the nodes of the grid: 0 – Linux, 1 – Windows (the simulation engine executables have different names in the two environments).
    • GridListenerDelay – the delay (in milliseconds) between each poll of the network file share for changes in the state of the simulation results.
  • If the Web Service grid access method is to be used to connect to the grid then:
    • FactsSimulationServicePortURL – specifies the URL to the FACTS web-service endpoint.

Note, this configuration file is only used on the initial load of FACTS – subsequently, a local user configuration file is created in a location under the AppData folder – e.g.:

C:\Users\<user_id>\AppData\Local\Berry_Consultants_Inc\FACTS_File_Loader_Url_<Windows unique file id >\6.1.6.17435\user.config

Any changes made to the configuration from the UI (under the ‘Settings’ menu) are saved to this local file. – and the original config file is only used if the options are reset.

NB, these local configuration are FACTS version and build specific (note the version and build number in the directory) – which means that if a new install is run, local configuration modifications will be lost.

Notes on access permissions

FACTS uses the locations C:\Program Data\BerryConsultants and <user>\AppData\Local\BerryConsultants, we have seen some IT departments set the default access permissions to deny access to these locations contrary to Microsoft’s intention and the access will need to be granted for FACTS to run. When FACTS runs simulations it spawns one or more simulations processes, and we have encountered environments where these processes do not get permission to write to network drives. If these permissions cannot be changed, it will be necessary for users to save their “.facts” file run in a directory on the local drive before running simulations, so the results can be written there and then copied/moved to the network drive once complete.

License Installation

When FACTS is first run, it may require the license to be entered. The user can choose the file when prompted, or cut and paste the information into the dialog box. Alternatively, the file can be dropped in the application folder and it will be picked up when needed. Note, depending on access permissions, it may be necessary to initially load FACTS with admin rights in order to load the license key from file.

Subsequent runs, and subsequent installations of mod level updates, will not require the license to be re-entered.

Installation Verification

Action Expected result Actual result Pass Fail
Verify that the FACTS shortcut appears in the Start Menu and on the user’s desktop Application shortcuts located
Click the application shortcut to launch FACTS (Enter license key as necessary) Application opens.
Click the Help > About menu item About box appears.
Verify the version number is the same as the version specified by Berry Consultants. Version number is correct
If example projects were installed, select File > Examples > [example_file_name] menu item Example project opens.
If example projects were not installed select open and navigate to the location where an example file was saved Example project opens.

Click the File > Save As menu item.

Choose a writeable location on the local drive and save a copy of the design.

 New copy of project created.

Click the Simulation tab, with “Locally” selected,

Click “Select All”

Click “Simulate”

 Simulations start.  After a short while, results are displayed in the GUI.
Click the “View Graph” button. Graph window opens.  Displayed graph updates when graph title selected in list.
The “Design Report” feature in FACTS Core requires that R, R Studio (for mathjax & pandoc), and the R libraries “markdown”, “xtable” and “stringi” are installed. You will also need Microsoft Word installed to be able to open the generated “.docx” file.
In FACTS open the configuration settings and configure the location of R or RStudio on the computer. (See the Design Report User Guide for more details if required).
If the example file used above was not a “FACTS Core” example, repeat the steps above with a FACTS Core example, up to and including the “Run Simulations” step.

Press the “Design Report” button. If you have “R” selected as your FACTS default “R”, this will run in batch mode.

If you have RStudio selected as our default “R”, RStudio will now start. In the terminal window you are shown the text of a function call. Copy and paste this text into the R command line and execute the function.

Once the function is complete you should have a Word file within the “_results” directory that corresponds to the current “.facts” file.
Open the World file and review the contents, it should describe the example you have selected and simulated.
Click the File > Exit menu item Application closed.

Grid Installation

Grid execution requires a separate sweeper script/application to collect FACTS files posted to the shared drive for execution. See the Grid Interface Document for specification of this interface and the HPC Admin Guide for detailed installation instructions.