To be clear, there is a bit of hassle to set-up Python to use your first R package that uses reticulate. The purpose of this document is to help you minimize that hassle. Here’s the short version:

1. You are encouraged to use Conda Python. Miniconda works well, and installs much-more-quickly than full Conda.

2. Create a Conda environment called "r-reticulate".

3. Install reticulate, then suggest to it which Python environment to use. You can do this by putting reticulate::use_condaenv("r-reticulate") into the .First() function in your .Rprofile file.

If you do this, ensure that RETICULATE_PYTHON is not set in your .Renviron file.

As usual, restart R for changes to take effect.

4. install.packages("altair")

5. altair::install_altair()

To verify your installation, use altair::check_altair(); it will tell you which Altair version is installed, and which version is supported by this package.

If you have any SSL-related difficulties, perhaps because you are working in a corporate or institutional environment, please see the Proxies and certificates section of this article.

## Overview

Thanks to the reticulate package, once you have a “standard” Python environment working, each subsequent installation is, in theory, a single command-line call in addition to installing the R package. If you have a working Python (Conda recommended) environment called "r-reticulate", you can skip to the Altair installation section of this article.

## Proxies and certificates

We would recommend using this section only if you are having SSL-related installation difficulties, which may happen if you work at a corporate or institutional environment.

This first step is the most bothersome; you may need to collect some information on certificates (and proxies, if you work behind a firewall), then distribute that information to different places on your computer:

• location of a valid certificate file: </path/to/your/certificate/file.crt>

Additionally, if you work behind a firewall:

• address of your proxy: http://<your.proxy.ip.address>:<port>
• list of addresses for which your proxy is not to be used: 127.0.0.1,localhost,<other.hostnames.go.here>

Please note that the angle-brackets , <>, are a quoting mechanism for demonstration; they should not be a part of your variables.

### Working without a firewall

If you do not work behind a firewall, you need only determine the location of a valid certificate file. If you have the httr package installed, it will use the certificate file associated with the openssl package. You can determine the location of this certificate file by using:

system.file("cacert.pem", package = "openssl")

At this point, you can note this location and move ahead to Managing your settings.

### Working behind a firewall

If you work behind a firewall, it may be a little trickier to find your certificate file. Sylvain Marié has put together a field-guide called develop-behind-proxy, from which we take some inspiration.

It is possible that your IT department requires that your certificate bundle be modified to include a certificate that your IT department can use to monitor your traffic. In this case, Sylvain offers some advice to find this certificate bundle, or you can ask your IT department for its location.

Your proxy is likely set using environment variables, named some combination of:

• http_proxy, https_proxy, no_proxy, HTTP_PROXY, HTTPS_PROXY, NO_PROXY

If you are using Windows, your proxy information may be set using your system’s environment variables, in which case you may not need to do anything more.

It is also possible that you use your .Renviron file to set your proxy and no-proxy variables. If you have the usethis package installed, it can be very easy to find and open: usethis::edit_r_environ().

Once you have noted your proxy and no-proxy settings, as well as the location of a certificate file, you are ready to move on.

Now that you have your information on your certificate (and proxy), the next step is to make this information known to all the programs on your computer that need it. How you make this information known will depend on your operating-system.

Windows

In Windows, the customary way to set or change environment variables is to use Control Panel\All Control Panel Items\System then “Advanced System Settings” and “Environment Variables”. This may vary according to your version of Windows.

Set each of these variables, adapting these lines as needed. The angle-brackets , <>, are a quoting mechanism for demonstration; they should not be a part of your variables.

# Windows environment variables
#
# Varaible : Value

SSL_CERT_FILE : </path/to/your/certificate/file.crt>
REQUESTS_CA_BUNDLE: </path/to/your/certificate/file.crt>

# --------------------------------------
# continue if you work behind a firewall

NO_PROXY : 127.0.0.1,localhost,<other.hostnames.go.here>

HTTPS_PROXY : http://<your.proxy.ip.address>:<port>

By setting these variables here, both your R session and any Python session will have access to the information they will need.

MacOS and Linux (Ubuntu)

On MacOS and Linux, we may need to set this information in two places (we know), so that processes that start from R and processes that start from the shell will both be well-informed.

The customary way to set environment-variables for R is to add variables to your .Renviron file; add and adapt the following lines as needed. The angle-brackets , <>, are a quoting mechanism for demonstration; they should not be a part of your variables.

# .Renviron

# path to a certificate file
SSL_CERT_FILE = "</path/to/your/certificate/file.crt>"
REQUESTS_CA_BUNDLE = "${SSL_CERT_FILE}" # -------------------------------------- # continue if you work behind a firewall # addresses for which proxy is not to be used no_proxy = "127.0.0.1,localhost,<other.hostnames.go.here>" # proxy addresses https_proxy = "http://<your.proxy.ip.address>:<port>" http_proxy = "${https_proxy}"

HTTPS_PROXY = "${https_proxy}" HTTP_PROXY = "${http_proxy}"

On MacOS, your ~/.bash_profile file acts in a similar way as .Renviron, but the syntax is just a little different. On Ubuntu Linux, this file is called ~/.bashrc - you may have to determine this name for your particular flavor of Linux.

Using your favorite text editor, find and edit your .bash_profile (or .bashrc), adding and adapting these lines as needed. The angle-brackets , <>, are a quoting mechanism for demonstration; they should not be a part of your variables.

# MacOS .bash_profile, Ubuntu .bashrc

# path to a certificate file
export SSL_CERT_FILE=</path/to/your/certificate/file.crt>
export REQUESTS_CA_BUNDLE=${SSL_CERT_FILE} # -------------------------------------- # continue if you work behind a firewall # specifies addresses for which proxy is not to be used export NO_PROXY="127.0.0.1,localhost,<other.hostnames.go.here>" # specifies the proxy addresses export https_proxy=http://<your.proxy.ip.address>:<port> export http_proxy=${https_proxy}

export HTTPS_PROXY=${https_proxy} export HTTP_PROXY=${http_proxy}

A new terminal-window will have access to these settings, which you can confirm using the env command.

## Reticulate and Python installation

Reticulate offers a number of ways to manage the installation of Python packages into a Python environment, as described in its Installing Python Packages article. Here, we amplify some opinions offered by RStudio. Because Conda is available for Windows, MacOS, and Linux, we recommend using a Conda Python installation. We have found using that using Conda for Python 3.6 works well.

Follow the Conda installation instructions to suit your particular situation. You will have the choice to install Conda or Miniconda. We have found that both work; the choice depends on how many Python packages you wish to install right away.

If all is well, you will be able to update your Conda installation.

Windows At a new Anaconda prompt:

# Anaconda prompt
conda update conda

MacOS and Linux (Ubuntu) At a new terminal window:

# Terminal window
conda update conda

## Python environment

For use with reticulate, RStudio recommend using a Python environment called "r-reticulate". You can do this for your Conda environment directly from an R command-prompt, and it should “just work”:

reticulate::conda_create("r-reticulate")

To leave a hint for reticulate to use this Python environment by default, you can add this line to the .First() function in your .Rprofile (usethis::edit_r_profile() can be useful):

# .Rprofile

.First <- function() {
<other stuff>
reticulate::use_condaenv("r-reticulate")
}

Of course, you should restart your R session to let your new settings take effect.

## Altair Installation

If you have not already installed this package into your R library, this is a perfect occasion to do so:

install.packages("altair")

Thanks to all the preparatory work you have made, it should be (in theory) relatively straightforward to install the Altair Python package:

altair::install_altair()

You can confirm success by showing your Python configuration:

reticulate::py_config()

And by confirming your Altair installation:

altair::check_altair()