---
title: "Keras/TensorFlow installation and configuration"
output: 
  rmarkdown::html_vignette:
    toc: true
    toc_depth: 3
    vignette: >
      %\VignetteIndexEntry{Keras/TensorFlow installation and configuration}
      %\VignetteEngine{knitr::rmarkdown}
      %\VignetteEncoding{UTF-8}
bibliography: references.bib
geometry: margin=3cm
fontsize: 12pt
---

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

## Installation

**digitalDLSorteR** is based on Deep Neural Network (DNN) models. To use them, [keras](https://cran.r-project.org/package=keras) package (available on CRAN), a high-level neural networks API implemented in Python, is used. [keras](https://cran.r-project.org/package=keras) R package works as an interface between these two languages by using the [reticulate](https://cran.r-project.org/package=reticulate) package. Therefore, [keras](https://cran.r-project.org/package=keras) requires a Python interpreter to work. We recommend using conda environments to provide a Python interpreter with all its dependencies covered. If you already have a conda environment compatible with [keras](https://cran.r-project.org/package=keras) requirements, the package is supposed to find it automatically during the installation. Otherwise, [keras](https://cran.r-project.org/package=keras) will create a new environment called `r-reticulate` with all these dependencies covered. There are other ways to install a functionally back-end and customized installations are possible, see <https://keras.rstudio.com/reference/install_keras.html> and <https://tensorflow.rstudio.com/installation/> for more details.

In addition, **digitalDLSorteR** provides the `installTFpython` function, a helper function to install miniconda (if needed) and create a conda environment called `digitaldlsorter-env` with all dependencies covered (a Python interpreter with tensorflow >= 2.2). We recommend using `installTFpython` to install tensorFlow Python library. 

```{r, eval = FALSE}
installTFpython(install.conda = TRUE)
```

## Common errors with [keras](https://cran.r-project.org/package=keras)

### [keras](https://cran.r-project.org/package=keras) package does not find any functional Python environment

If you experiment errors related to its installation and/or [keras](https://cran.r-project.org/package=keras) is not able to find a functional Python environment, you can manually install the conda environment by following these steps:

First, in case you don't have miniconda installed, use the following R code using [reticulate](https://cran.r-project.org/package=reticulate):

```{r, eval = FALSE}
reticulate::install_miniconda()
reticulate::conda_create(
  envname = "digitaldlsorter-env", 
  packages = "python==3.7.11"
)
```

Or type in a Terminal:

```{bash}
conda create --name digitaldlsorter-env python=3.7 tensorflow=2.1
```

Then, instead of using `keras::install_keras()` function, run the following code chunk using the [tensorflow](https://cran.r-project.org/package=tensorflow) R package. This code will create a Python interpreter with [tensorflow](https://cran.r-project.org/package=tensorflow) with all its dependencies covered.

```{r, eval = FALSE}
tensorflow::install_tensorflow(
  method = "conda", 
  conda = reticulate::conda_binary("auto"), 
  envname = "digitaldlsorter-env", 
  version = "2.1.0-cpu",
)
```

Finally, although it is automatically done by **digitalDLSorteR**, if [keras](https://cran.r-project.org/package=keras) still does not recognize the functional environment, set this new environment as the selected Python environment:

```{r}
tensorflow::use_condaenv("digitaldlsorter-env")
```

If the Python-interpreter problems do not disappear, it is possible to set manually the interpreter that will be used with [reticulate](https://cran.r-project.org/package=reticulate). See the following guide: <https://rstudio.github.io/reticulate/articles/versions.html>. And of course, don't hesitate to tell us your problem, we'll try to help you.

### Eager execution

Depending on [tensorflow](https://cran.r-project.org/package=tensorflow) version used as back-end, you are likely to experiment an error related to eager execution. Eager execution is an imperative, define-by-run interface where operations are executed immediately as they are called. However, it is only available on [tensorflow](https://cran.r-project.org/package=tensorflow) versions later than 1.9. You can disable this option by the following line of code or change your [tensorflow](https://cran.r-project.org/package=tensorflow) version used as back-end.

```{r}
tensorflow::tf$compat$v1$disable_eager_execution()
```
