Installation Qualification of rpact

Utilities
This document explains how to perform the Installation Qualification for rpact and highlights the recent changes to the testing process.
Author

Friedrich Pahlke Gernot Wassmer

Published

December 6, 2024

Introduction

As part of the regulatory requirements in GxP environments, the Installation Qualification (IQ) of software is a critical process to ensure that a system is installed correctly and works as intended in the target environment. In the case of the rpact package, the Installation Qualification is performed through the testPackage() function, which provides an essential validation mechanism for ensuring the package meets the required standards. When you run this function, more than 37,000 unit tests are performed and the overall test result is presented in a small report.

From release version 4.1.1 of rpact, a significant change has been introduced regarding the execution of unit tests. Only a single test case remains in the package, which informs users that the unit tests have been moved and are no longer included by default. Full access to all unit tests is restricted to paying customers who possess the necessary credentials (token and secret). These credentials are included in the user-specific rpact validation documentation, provided to all members of the RPACT User Group for each release.

This vignette explains how to perform the Installation Qualification for rpact and highlights the recent changes to the testing process.

Important Update on Unit Tests in the Latest rpact Release

From release version 4.1.1 of rpact, we have streamlined the testing process by moving the full set of unit tests to a private repository. This ensures that testing is both efficient and compliant with CRAN requirements, while maintaining strict adherence to GxP standards. Only paying customers have access to the complete unit test suite, as part of the installation qualification (IQ). The tests are executed automatically through the testPackage() function, and a local or server-based execution of these tests is a crucial step to validate rpact for use in regulated environments.

If you have already conducted your installation qualification using the testPackage() function, nothing changes for you. However, if your IQ was done without using testPackage(), we recommend using the setupPackageTests() function to ensure that the full set of tests is integrated into your local rpact installation. This approach provides you with the flexibility to run the tests using your own testing pipeline, ensuring that the package is fully qualified for use in regulated environments (see section Setup Complete Test Suite of rpact below).

Using testPackage() for Installation Qualification

The testPackage() function is designed to run all the necessary unit tests for validating the installation of rpact. It can download and execute a full set of tests or a subset, depending on the user’s needs and access credentials.

Example Usage

testPackage(
  outDir = "/path/to/output", # absolute path to the output directory
  completeUnitTestSetEnabled = TRUE, 
  types = "tests", 
  connection = list(
    token = "my_token", 
    secret = "my_secret"
  )
)

Note that the outDir parameter must be an absolute path or "." (current working directory). By default, the current working directory is used.

Alternatively, you can run the following code to execute the installation qualification:

setwd("/path/to/output") 
testPackage(
  completeUnitTestSetEnabled = TRUE, 
  types = "tests", 
  connection = list(
    token = "my_token", 
    secret = "my_secret"
  )
)

Parameters

  • outDir: The absolute path to the directory where all test results will be saved. By default, the current working directory is used.
  • completeUnitTestSetEnabled: If TRUE, all existing unit tests will be executed. If FALSE, only a subset of the tests will run.
  • types: The type(s) of tests to run, which can include "tests", "examples", and "vignettes". By default, only the unit tests are run.
  • connection: A list containing the user-specific token and secret. These credentials provide access to the full set of unit tests and are necessary to fulfill regulatory requirements. Credentials change for every rpact release and are provided in the appendix of the user-specific validation documentation (see Fig. 1).

Figure 1: Appendix of the rpact validation documentation

How it Works

When you execute testPackage(), the function creates a subdirectory named rpact-tests in the specified output directory. It then downloads all unit test files from a private repository and copies them to this newly created directory. The full set of tests (or a subset, depending on the parameters) is executed using the built-in testInstalledPackage() function from the tools package. All test results are saved in the file testthat.Rout, located in the rpact-tests directory.

Setup Complete Test Suite of rpact

The setupPackageTests() function ensures that the required test files are securely downloaded and integrated into the local rpact installation. By doing so, users can use their own test pipeline instead of relying on the testPackage() function to execute the tests.

Function Overview

The setupPackageTests() function performs the following operations:

  1. Validation of Directories: It verifies the existence of the rpact package directory and its necessary subdirectories (tests and testthat).
  2. Download and Installation of Tests: Using user-provided credentials (token and secret), the function downloads the complete test suite to a temporary directory. It then copies the tests into the appropriate subdirectories of the local rpact installation.

Parameters

  • token: A string used for authentication during the download of the test suite.
  • secret: A string used for secure authentication alongside the token.

Process Benefits

By leveraging the setupPackageTests() function, users gain access to the following benefits:

  • Automated Compliance: The function ensures the seamless integration of up-to-date test files into the rpact environment, supporting regulatory compliance.
  • Enhanced Flexibility: Once the test suite is installed, users can execute it using their preferred testing pipelines, providing adaptability to different operational setups.

Practical Guidance

To execute the setupPackageTests() function, ensure you have valid credentials (token and secret) obtained as part of the rpact release. These credentials are unique for every release and are provided in the accompanying rpact validation documentation (see Fig. 1), which is shared with members of the RPACT User Group.

Once the test suite is installed using setupPackageTests(), you can use your custom pipelines to perform the installation qualification. If you encounter any issues, we recommend reaching out to the RPACT support team for assistance.

Importance of Installation Qualification

For GxP-compliant environments, running the installation qualification is a mandatory step to ensure that rpact is functioning correctly. The IQ process verifies that the software is installed in a validated state and can be trusted for use in clinical and other regulated research settings.

The rpact validation documentation is over 7,000 pages long and details the formal validation of the package. This documentation, together with the IQ performed using testPackage(), forms the basis for ensuring that rpact is fully validated for use in regulated environments.

Installation Qualification Reminder Message

When loading the rpact package in R, the following message will be displayed by default if the installation qualification (IQ) process has not yet been performed:

Installation qualification for rpact 4.1.1 has not yet been performed.
Please run testPackage() before using the package in GxP relevant environments.

This message serves as a reminder to ensure that the rpact package has undergone the necessary validation steps before being used in GxP-relevant environments. The message will continue to appear every time the package is loaded until the testPackage() function has been successfully executed.

Suppressing the Message

If desired, the reminder message can be suppressed using one of the following method:

Suppress Startup Messages: Load the package using suppressPackageStartupMessages() to prevent the message from being displayed:

suppressPackageStartupMessages(library(rpact))

Installation Qualification Report

As part of the testPackage() function execution, a detailed Installation Qualification (IQ) report is automatically generated to document the testing process and its results. This report is a key deliverable in the validation workflow, ensuring that the rpact package meets the necessary requirements for GxP-compliant environments.

Report Overview

The IQ report provides the following key sections:

  1. Introduction: Outlines the purpose and scope of the IQ process, including its importance for verifying the installation and functionality of rpact in regulated environments.
  2. System Information: Captures details about the system and environment where the IQ process was performed, including:
    • rpact package version and release date
    • R version and platform information
    • Operating system and locale settings
  3. Test Results: Summarizes the outcomes of all executed tests, categorizing them as passed, failed, or passed with warnings. This section highlights any discrepancies that may require resolution to ensure compliance.

Output Formats

The report is automatically generated in two formats:

  • HTML: Suitable for easy viewing in web browsers.
  • PDF: Provides a static, printable format ideal for documentation and archiving purposes.

Both formats are saved to the directory specified by the user argument outDir after running testPackage().

Download Example Report

Using the Report

The IQ report serves as a comprehensive record of the validation process. It should be reviewed carefully to ensure all tests have passed successfully. Any failed tests or warnings should be addressed promptly, as these could indicate potential issues with the rpact installation or its compatibility with the system environment.

For more information on resolving issues or interpreting the results, consult the official rpact documentation or reach out to the support team at .

Importance of the Report

Maintaining an up-to-date IQ report is essential for compliance with GxP regulatory standards. It demonstrates that the software has been installed and validated correctly, providing confidence in its reliability and suitability for critical applications.

Conclusion

Performing the installation qualification using the testPackage() function is essential for validating rpact in GxP environments. Access to the full set of unit tests is restricted to members of the RPACT User Group, who receive user-specific credentials with each release. These credentials, combined with the validation documentation, ensure that the package can be securely and compliantly used in regulated settings. For more information, please visit: www.rpact.com/services/sla.

If you have any questions or need further assistance, please reach out to us at www.rpact.com.