---
title: "Getting started with R package `ctrdata` for clinical trial information"
author: "Ralf Herold"
date: "`r Sys.Date()`"
output:
  rmarkdown::html_vignette:
    toc: true
vignette: >
  %\VignetteIndexEntry{Getting started}
  %\VignetteKeywords{ctrdata,vignette}
  %\VignettePackage{ctrdata}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
#
knitr::opts_chunk$set(eval = FALSE)
#
```

## Install package `ctrdata` on a R system

The R Project website ([https://www.r-project.org/](https://www.r-project.org/)) 
provides installers for the R system. 

Alternatively, the R system can be used from software products such as R Studio 
([https://www.rstudio.com/products/RStudio/](https://www.rstudio.com/products/RStudio/)), 
which includes an open source integrated development environment (IDE), or Microsoft R Open 
([https://mran.microsoft.com/open/](https://mran.microsoft.com/open/)). 

General information on the `ctrdata` package is available here: [https://github.com/rfhb/ctrdata](https://github.com/rfhb/ctrdata). 

```{r install_ctrdata, eval=FALSE}
install.packages("ctrdata")
```

The above should install package `ctrdata` into the user's library. 
If this installation does not succeed, the following sections offer potential solutions. 

For using the development version of package `ctrdata`, install from GitHub: 

```{r, eval=FALSE}
# install preparatory package
install.packages(c("devtools", "httr"))
# note: unset build_opts so that vignettes are built
devtools::install_github("rfhb/ctrdata", build_opts = "")
```

## Mongo database

A remote or a local mongo database server can be used with the package `ctrdata`. 
Suggested installation instructions for a local database server are 
[here](https://docs.mongodb.com/manual/administration/install-community/). 
An example of a remote mongo database server is [here](https://www.mongodb.com/cloud/atlas). 

## Internet access via proxy? 

Functions in package `ctrdata` that start with `ctr...` require access to internet 
resources via `https`. Package `ctrdata` checks and _automatically uses_ the proxy 
that is set under MS Windows in system settings. 

However, proxy settings need to be set by the user for other operating systems 
and for authenticating proxies, such as follows: 

```{r, eval=FALSE}
Sys.setenv(https_proxy = "your_proxy.server.domain:8080")
Sys.setenv(https_proxy_user = "userid:password")
```

## Additional installation aspects for MS Windows

On MS Windows, it seems recommended to not use UNC notation (such as `\\server\directory`) 
for specifying the user's library location: 

```{r, eval=FALSE}
.libPaths("D:/my/directory/")
```

As noted in the README for package `ctrdata`, on MS Windows the cygwin environment has 
to be installed, into the local directory `c:\cygwin`. The applications php, bash, perl, 
cat and sed in the cygwin environment are required for function `ctrLoadQueryIntoDb()` 
of package `ctrdata` (other functions in the package do not have this requirement). 
The installation of a minimal cygwin environment on MS Windows can be done 
from package `ctrdata` as follows: 

```{r, eval=FALSE}
ctrdata::installCygwinWindowsDoInstall() 
```

If need be, a proxy can be specified: 

```{r, eval=FALSE}
ctrdata::installCygwinWindowsDoInstall(proxy = "proxy.server.domain:8080") 
```

Users who want or need to install cygwin manually can download the setup executable 
from [here](https://cygwin.com/). In MS Windows command window or Powershell window, 
use the following command line. The parameters are explained 
[here](https://cygwin.com/faq/faq.html#faq.setup.cli).

```{bash, eval=FALSE}
setup-x86_64.exe --no-admin --quiet-mode --verbose --upgrade-also --root c:/cygwin 
--site http://www.mirrorservice.org/sites/sourceware.org/pub/cygwin/ 
--packages perl,php-jsonc,php-simplexml
```

## Attach package `ctrdata`

```{r attach_ctrdata}
library(ctrdata)
```

## Open register's advanced search page in browser

These functions open the browser, where the user can start searching for trials of interest. 

```{r show_brower_search_pages}
ctrOpenSearchPagesInBrowser()

# Please review and respect register copyrights:
ctrOpenSearchPagesInBrowser(copyright = TRUE)

# Open browser with example search:
ctrOpenSearchPagesInBrowser(input = "cancer&age=under-18",
                            register = "EUCTR")
```

## Click search parameters and execute search in browser 

Refine the search until the trials of interest are listed in the browser. 
Currently, the total number of trials that can be retrieved with package 
`ctrdata` is intentionally set to 5000 (CTGOV). 

## Copy address from browser address bar to clipboard

Using operating system functions. 

## Get address from clipboard

The next steps are executed in the R environment: 

```{r get_query_from_browser}
q <- ctrGetQueryUrlFromBrowser()
# Found search query from EUCTR.
# [1] "cancer&age=under-18"

# Open browser with this query
# Note the register needs to be specified
# when it cannot be deduced from the query
ctrOpenSearchPagesInBrowser(input = q, 
                            register = "EUCTR")
```

## Retrieve protocol-related information, transform, save to database, check

```{r execute_load_query, eval=FALSE}
# Use search q that was defined in previous step: 
ctrLoadQueryIntoDb(queryterm = q)

# Alternatively, use the following to retrieve a couple of trial records: 
ctrLoadQueryIntoDb(queryterm = "cancer&age=under-18", 
                   register = "EUCTR")
# If no parameters are given for a database connection: uses mongodb
# on localhost, port 27017, database "users", collection "ctrdata"

# Show which queries have been downloaded into the database so far
dbQueryHistory()
#       query-timestamp query-register query-records                  query-term
# 1 2016-01-13-10-51-56          CTGOV          5233 type=Intr&cond=cancer&age=0
# 2 2016-01-13-10-40-16          EUCTR           910         cancer&age=under-18
```

## Analyse information on clinical trials

```{r analyse_query_database}
# find names of fields of interest in database:
dbFindFields(namepart = "status", 
             allmatches = TRUE)
# [1] "overall_status"  "b1_sponsor.b31_and_b32_status_of_the_sponsor" 
# [3] "p_end_of_trial_status" "location.status"

# Get all records that have values in all specified fields.
# Note that b31_... is a field within the array b1_...
result <- dbGetFieldsIntoDf(fields = c("b1_sponsor.b31_and_b32_status_of_the_sponsor", 
                                       "p_end_of_trial_status"))

# Tabulate the status of the clinical trial on the date of information retrieval
with(result, 
     table("Status"       = p_end_of_trial_status, 
           "Sponsor type" = b1_sponsor.b31_and_b32_status_of_the_sponsor))
#                 Sponsor type
# Status                  Commercial Non-Commercial
#   Completed                    138             30
#   Not Authorised                 3              0
#   Ongoing                      339            290
#   Prematurely Ended             35              4
#   Restarted                      8              0
#   Temporarily Halted            14              4
```
