R Language Support
==================

TripleBlind's ecosystem can be accessed from the R programming language using
the Reticulate (https://rstudio.github.io/reticulate) interoperability package.
Reticulate allows R to seamlessly interact with Python.

1. Installation

The standard Comprehensive R Archive Network (aka CRAN) supports Reticulate.
Scripts can install the package using the standard install.packages()
functionality.  All example scripts take care of this at the beginning, so
nothing additional is needed beyond a working R Studio setup.

A functional Python environment is also required.  You can check for Python
by running:
   python --version
If that command fails, or if the Python version is not 3.7 you should obtain
a copy.  Then install the TripleBlind SDK using:
   pip install -r requirements.txt

Once you have Python set up you can set the path of your Python interpreter in
RStudio in Preferences -> Python. If you are using conda (reticulate will offer
to install miniconda for you if you do not have Python interpreter) you can use
conda_list() to show the paths of your conda environments. Alternately, you can add a
call to the Reticulate method use_python("/path/to/python/version") to point
to a specific version before running a script.

The tripleblind SDK uses an environment variable named TB_API_CONFIG to set the path
of the config file. You can set this for RStudio by creating a file named ~/.Renviron
and adding "TB_API_CONFIG=/path/to/tripleblind.yaml". You can also on the startup
of an RStudio session run Sys.setenv("TB_API_CONFIG" = "/path/to/tripleblind.yaml")
before reticulate is imported.

2. Usage

The Reticulate package must first be loaded in your R script, using:
   library(reticulate)
After that, the TripleBlind library can be started using:
   tb <- import("tripleblind")

Once loaded, all TripleBlind methods are available from within R.  For example
the Python code:
   tb.util.set_script_dir_current()
   tb.initialize(api_token=tb.config.example_user1["token"])
looks like this in R:
   tb$util$set_script_dir_current()
   tb$initialize(api_token = tb$config$example_user1[["token"]])

As you can see, existing Python scripts can be easily converted to R.

3. Examples

You can open the examples in RStudio with the "Create New Project" button at the
top left. This will set the example directory as the working directory and make
all of the scripts for the example available in the RStudio file explorer. If running
outside the context of a project you can set the working directory via the RStudio
menu bar or the 'setwd' command.


This preview comes with four examples based on the standard TripleBlind SDK
examples.  These illustrate the basics of using the library within R:

  * Blind_Sample
    Locate assets on the TripleBlind router and retrieve mock data.

  * Blind_Join
    Use the Blind_Join method to find matching values in private datasets.

  * PSI
    Use the Private Set Intersection method to identify overlapping records in
    three independent datasets.

  * Tabular_Data
    Train a Pytorch neural network and invoke it from within R.


4. Reference Links

  * R Website:
    https://www.r-project.org/
  * R For macOS
    https://cran.r-project.org/bin/macosx/ "Title"
  * R for Windows (4.1.0)
    https://cran.r-project.org/bin/windows/base/
  * R Studio
    https://www.rstudio.com
    https://www.rstudio.com/products/rstudio/download
  * R Libraries
    * reticulate: https://rstudio.github.io/reticulate/
    * stringr: https://www.rdocumentation.org/packages/stringr/versions/1.4.0
    * dplyr: https://cran.r-project.org/web/packages/dplyr/readme/README.html
