---
title: "Patient-Level Prediction Installation Guide"
author: "Jenna Reps, Peter R. Rijnbeek, Egill Fridgeirsson"
date: '`r Sys.Date()`'
output: rmarkdown::html_vignette
vignette: >
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteIndexEntry{Patient-Level Prediction Installation Guide}
  %\VignetteEncoding{UTF-8}
---

# Introduction

This vignette describes how you need to install the Observational Health Data Science and Informatics (OHDSI) [`PatientLevelPrediction`](https://github.com/OHDSI/PatientLevelPrediction) package under Windows, Mac, and Linux.

# Software Prerequisites

## Windows Users

Under Windows the OHDSI Patient Level Prediction (PLP) package requires installing:

-   R (<https://cran.r-project.org/> ) - (R \>= 4.0.0, but latest is recommended)
-   Rstudio (<https://posit.co/> )
-   Java 
-   RTools (<https://cran.r-project.org/bin/windows/Rtools/>)

## Mac/Linux Users

Under Mac and Linux the OHDSI Patient Level Prediction (PLP) package requires installing:

-   R (<https://cran.r-project.org/> ) - (R \>= 4.0.0, but latest is recommended)
-   Rstudio (<https://posit.co/> )
-   Java 
-   Xcode command line tools(run in terminal: xcode-select --install) [MAC USERS ONLY]

# Installing the Package

The preferred way to install the package is by using `remotes`, which will automatically install the latest release and all the latest dependencies.

If you do not want the official release you could install the bleeding edge version of the package (latest develop branch).

Note that the latest develop branch could contain bugs, please report them to us if you experience problems.

## Installing PatientLevelPrediction using remotes

To install using `remotes` run:

```{r, echo = TRUE, message = FALSE, warning = FALSE,tidy=FALSE,eval=FALSE}
install.packages("remotes")
remotes::install_github("OHDSI/PatientLevelPrediction")
```

When installing make sure to close any other Rstudio sessions that are using `PatientLevelPrediction` or any dependency. Keeping Rstudio sessions open can cause locks that prevent the package installing.

# Creating Python Reticulate Environment

Many of the classifiers in the `PatientLevelPrediction` use a Python backend. To set up a python environment run:

```{r, echo = TRUE, message = FALSE, warning = FALSE,tidy=FALSE,eval=FALSE}
library(PatientLevelPrediction)
reticulate::install_miniconda()
configurePython(envname = "r-reticulate", envtype = "conda")
```

# Installation issues

Installation issues need to be posted in our issue tracker: <https://github.com/OHDSI/PatientLevelPrediction/issues>

The list below provides solutions for some common issues:

1.  If you have an error when trying to install a package in R saying **'Dependancy X not available ...'** then this can sometimes be fixed by running `install.packages('X')` and then once that completes trying to reinstall the package that had the error.

2.  I have found that using the github `remotes` to install packages can be impacted if you have **multiple R sessions** open as one session with a library open can cause the library to be locked and this can prevent an install of a package that depends on that library.

## Common issues

### python environment Mac/linux users:

to make sure R uses the r-reticulate python environment you may need to edit your .Rprofile with the location of the python binary for the PLP environment. Edit the .Rprofile by running:

```{r eval=FALSE}
usethis::edit_r_profile()
```

and add

```{r eval=FALSE}
Sys.setenv(PATH = paste("your python bin location", Sys.getenv("PATH"), sep = ":"))
```

to the file then save. Where your python bin location is the location returned by

```{r eval=FALSE}
reticulate::conda_list()
```

e.g., My PLP virtual environment location was /anaconda3/envs/PLP/bin/python so I added:\
Sys.setenv(PATH = paste("/anaconda3/envs/PLP/bin", Sys.getenv("PATH"), sep=":"))

# Acknowledgments

Considerable work has been dedicated to provide the `PatientLevelPrediction` package.

```{r tidy=TRUE,eval=TRUE}
citation("PatientLevelPrediction")
```

**Please reference this paper if you use the PLP Package in your work:**

[Reps JM, Schuemie MJ, Suchard MA, Ryan PB, Rijnbeek PR. Design and implementation of a standardized framework to generate and evaluate patient-level prediction models using observational healthcare data. J Am Med Inform Assoc. 2018;25(8):969-975.](https://dx.doi.org/10.1093/jamia/ocy032)

This work is supported in part through the National Science Foundation grant IIS 1251151.