---
title: "Install R package ctrdata"
author: "Ralf Herold"
date: 2024-01-14
output:
  rmarkdown::pdf_document:
    toc: true
    number_sections: true
    latex_engine: xelatex
  rmarkdown::html_vignette:
    toc: true
vignette: >
  %\VignetteIndexEntry{Install R package ctrdata}
  %\VignetteKeywords{ctrdata,vignette}
  %\VignettePackage{ctrdata}
  %\VignetteEncoding{UTF-8}
  %\VignetteEngine{knitr::rmarkdown}
editor_options:
  chunk_output_type: console
---

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

# Install package `ctrdata` on an R system

The R Project website ([https://www.r-project.org/](https://www.r-project.org/)) provides installers for the R system. It can be used with software products and graphical user interfaces such as [R Studio](https://www.rstudio.com/products/RStudio/), or [Microsoft R Open](https://mran.microsoft.com/open/), or from [Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=Ikuyadeu.r). 

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

In R, execute:

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

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

```{r, eval=FALSE}
# install package under development
install.packages(c("remotes"))
remotes::install_github("rfhb/ctrdata", dependencies = TRUE, build_vignettes = TRUE)
```

Either of the above should install package `ctrdata` into the user's library.

## Internet access via proxy

Functions in package `ctrdata` that start with `ctr...` require access to trial registers over the internet via the `https` protocol. Many organisations use transparent proxies that may _not_ require users to do any configurations. However, if necessary, package `ctrdata` can use proxy settings set by users in their R session such as follows:

```{r, eval=FALSE}
Sys.setenv(https_proxy = "your_proxy.server.domain:8080") # if needed
Sys.setenv(https_proxy_user = "your_userid:your_password") # if needed
```

## Databases to use

At this time, a PostgreSQL, DuckDB, an SQLite or a MongoDB (local or remote) database can be used with the package `ctrdata`. A full SQLite database is provided in the R package [`RSQLite`](https://rsqlite.r-dbi.org/). Suggested installation instructions for PostgreSQL are [here](https://www.postgresql.org/download/) and for a local MongoDB server are [here](https://docs.mongodb.com/manual/administration/install-community/); a remote MongoDB database server is accessible [here](https://www.mongodb.com/cloud/atlas). See [here](https://github.com/ropensci/nodbi#benchmark) for a speed comparison of the databases; recommended: DuckDB, PostgreSQL or MongoDB local server. 

Purpose | Function call
-------------------- | --------------------
Create **SQLite** database connection | `dbc <- nodbi::src_sqlite(dbname = "name_of_my_database", collection = "name_of_my_collection")`
Create **MongoDB** database connection | `dbc <- nodbi::src_mongo(db = "name_of_my_database", collection = "name_of_my_collection")`
Create **PostgreSQL** database connection | `dbc <- nodbi::src_postgres(dbname = "name_of_my_database"); dbc[["collection"]] <- "name_of_my_collection"`
Create **DuckDB** database connection | `dbc <- nodbi::src_duckdb(dbname = "name_of_my_database", collection = "name_of_my_collection")`
Use connection with `ctrdata` functions | `ctrdata::{ctrLoadQueryIntoDb, dbQueryHistory, dbFindIdsUniqueTrials, dbFindFields, dbGetFieldsIntoDf}(con = dbc, ...)`

## Attach package `ctrdata`

After completing the installation, attach the package from the user's library. This will also check the availability of the additional installation requirements as mentioned above:

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

Remember to respect the registers' terms and conditions (see `ctrOpenSearchPagesInBrowser(copyright = TRUE)`). Please cite this package in any publication as follows: Ralf Herold (2024). ctrdata: Retrieve and Analyze Clinical Trials in Public Registers. R package version 1.16.0. https://cran.r-project.org/package=ctrdata
