spiritR: a workflow to enable direct upload of a clinical trial protocol to clinicaltrials.gov

Aaron Conway


The SPIRIT statement

The SPIRIT (Standard Protocol Items for Interventional Trials) statement outlines recommendations for a minimum set of elements to be addressed in a clinical trial protocol (Chan et al. 2013). In order to assist clinical trial protocol development, the spiritR package provides an Rmarkdown template containing each of the elements from the SPIRIT statement. The Rmarkdown template provides hyperlinks to the relevant section of the SPIRIT statement webpage for guidance.

Registering a clinical trial

Pre-registering core study design aspects of a clinical trial minimises the potential for reporting bias. Professional bodies, including the International Committee of Medical Journal Editors, as well as regulatory laws, such as the US Food and Drug Administration Amendment Act, mandate that clinical trials are registered (Califf et al. 2012; De Angelis et al. 2005). The largest clinical trial registry in the world is clinicaltrials.gov.

The typical workflow for researchers planning a randomized controlled trial is to initially generate a clinical trial protocol using word processing software. The information required to register a protocol in the clinicaltrials.gov registry is then cut and paste from that document into the relevant section of the clinicaltrials.gov webpage. The spiritR package aims to reduce the repetition involved in this process.

Clinicaltrials.gov permits xml documents that contain the elements required for clinical trial registration to be automatically uploaded through their application programming interface (API). The spiritR package uses functions from the xml2 R package to develop an xml document in a format that adheres to clinicaltrials.gov requirements (Wickham, Hester, and Ooms 2018). The httr package is then used to generate a http POST request with parameters needed to interact with the clinicaltrials.gov API (Wickham 2018).

Writing a protocol using the spiritR Rmarkdown template

Once installed, the spiritR Rmarkdown template will be available in RStudio. This template will only work for interventional trials. There are options to register Observational and Epidemiological studies on clinicaltrials.gov but this template will not meet the requirements for the xml upload for these other types of studies.

At the beginning of the Rmarkdown template are several R code chunks. Contained within these R code chunks are templates to create a list of object names with instructions for what content should be assigned to each. Assigning information to these values is vital to the intended workflow and will achieve two purposes:

  1. To populate a table at the begining of the protocol document displaying the World Health Organization Registration Data Set; and

  2. To populate an xml document that can be uploaded directly to the clinicaltrials.gov registry using the create_ctxml() function.

It will be easiest to enter the required information into the code chunks by running
?create_ctxml() in the console so that you can concurrently view descriptions of the
parameters to be included in the viewer panel.

Once the lists and objects are created and each section of the protocol template has been completed, the user can proceed to uploading their protocol to clinicaltrials.gov.

For clarification regarding the content to be assigned to these parameters, please refer to the data element definitions provided by clinicaltrials.gov.

Uploading a clinical trial protocol to clinicaltrials.gov

Create the initial xml document

The create_ctxml() function will create the initial xml document containing elements common to all clinical trial protocols. First be sure to run the code chunks in the Rmarkdown spiritR clinical trial protocol containing the lists of arguments. Then, create an xml document by calling ctxml <- do.call(spiritR::create_ctxml, args_ctxml).

Add arms, interventions, outcomes, conditions and keywords to the xml document

This family of functions will add nodespaces to the initial xml document generated from create_ctxml() with elements that are unique to a particular clinical trial. For example, every clinical trial must have at least one primary outcome and likely multiple secondary outcomes. However, the total number of primary and secondary outcomes will vary between studies. As such, the add_pr_outcome() and add_sec_outcome() functions are included in the spiritR package so that clinical trial protocol authors can tailor the xml document for upload to clinicaltrials.gov with the specific number of outcomes and details of their study. Likewise, all clinical trials must have at least one arm testing one intervention but the total number can vary. The add_arm(), add_intervention(), add_condition() and add_keyword() functions provide the functionality to add xml nodespaces containing this information to the initial xml document.

Inspect the structure of the xml document

The print_ctxml() function is provided to permit the user to check the structure of the xml document produced by calling the create_ctxml() and relevant add_functions() prior to attempting to upload the document to clinicaltrials.gov.

Upload the xml document to clinicaltrials.gov

After the complete xml document is generated by calling the create_ctxml() and relevant add_functions(), the user can upload it to clinicaltrials.gov using upload_ctxml(). Arguments for upload_ctxml() include:

  1. The ctxml object;
  2. The organisation name associated with a clinicaltrials.gov account;
  3. Username for a clinicaltrials.gov account; and
  4. Password for a clinicaltrials.gov account.

There are three possible outcomes for a call to upload_ctxml(). As per the guidance from clinicaltrials.gov, a correct http POST request will generate a list that contains two elements. The ‘content’ element is a list of the messages parsed from the XML response. The ‘response’ elements is the original XML response.

It is possible that a failed upload could be due to incorrect input parameters such as the organization name, username or password for the account.

Even in the event of a successful upload, this function has been programmed with the http POST request ‘autoRELEASE’ argument set to FALSE. This means that users will need to log-in to clinicaltrials.gov directly to inspect their upload, attend to any warning messages that may have been alerted, and then ‘release’ the submission for PRS review by clinicaltrials.gov.


Califf, Robert M, Deborah A Zarin, Judith M Kramer, Rachel E Sherman, Laura H Aberle, and Asba Tasneem. 2012. “Characteristics of Clinical Trials Registered in ClinicalTrials. Gov, 2007-2010.” JAMA 307 (17). American Medical Association: 1838–47.

Chan, An-Wen, Jennifer M Tetzlaff, Douglas G Altman, Andreas Laupacis, Peter C Gøtzsche, Karmela Krleža-Jeri’c, Asbjørn Hr’objartsson, et al. 2013. “SPIRIT 2013 Statement: Defining Standard Protocol Items for Clinical Trials.” Annals of Internal Medicine 158 (3): 200–207.

De Angelis, Catherine, Jeffrey M Drazen, Frank A Frizelle, Charlotte Haug, John Hoey, Richard Horton, Sheldon Kotzin, et al. 2005. “Clinical Trial Registration: A Statement from the International Committee of Medical Journal Editors.” Circulation 111 (10). Am Heart Assoc: 1337–8.

Wickham, Hadley. 2018. Httr: Tools for Working with URLs and HTTP. https://CRAN.R-project.org/package=httr.

Wickham, Hadley, James Hester, and Jeroen Ooms. 2018. Xml2: Parse XML. https://CRAN.R-project.org/package=xml2.