The goal of altair is to help you build Vega-Lite visualizations. Using the reticulate package, it provides an interface to the Altair Python package. This approach is distinct from efforts to build a native R interface to Vega-Lite, by Bob Rudis and coworkers: the vegalite package, which has inspired this effort.

In this documentation, the capitalized word Altair shall refer to the Python package; the lower-case word altair shall refer to this R package.

A development version is available from GitHub:

# install.packages("devtools")
devtools::install_github("vegawidget/altair") 

Because you are using a Python package, you may have some additional installation steps. These steps are described in greater detail in the Installation article.

1. Python must be installed on your system. I recommend using a Conda installation; Miniconda works well and installs more-quickly than Anaconda.

   If you work in a corporate or institutional environment, you may have to specify the location of your SSL certificate, or deal with a proxy. The installation article has a section on this.

2. Create a Conda environment called "r-reticulate". The reticulate folks recommend standardizing on a common name for all packages that use reticulate. For more information, there is a section in the installation article.

3. Install Altair into your "r-reticulate" environment using altair::install_altair().

You may wish to add a line like this to the .First() function in your .Rprofile:

reticulate::use_condaenv("r-reticulate")

The use_condaenv() function is called to provide a hint to reticulate on which Python environment to use.

library("altair")

vega_data <- import_vega_data()

chart <- 
  alt$Chart(r_to_py(vega_data$cars()))$
  encode(
    x = "Horsepower:Q",
    y = "Miles_per_Gallon:Q",
    color = "Origin:N"
  )$
  mark_point()

chart

Some things to keep in mind:

• Where you see a . in the Python examples, use a $ instead.

• Any data frames you provide as data arguments need to wrapped by r_to_py().

• In your data, columns that contain dots can be wrapped in square brackets in Altair specifications, e.g. [Sepal.Width], to keep Altair from throwing an error.

These and other “gotchas” are compiled, along with workarounds, in an article: Field Guide to Python Issues.

The documentation for this package includes some articles:

• Installation: some more-detailed instructions

• Manifesto: an outline of some high-level development ideas, which may change from time to time

Gallery:

• An adaptation to R of the Altair Example Gallery, to demonstrate (not least to ourselves) that we are not missing any of the expressiveness of the Python API. You may be interested in the Interactive Charts examples.

Examples:

• First Example: a walkthrough to get a first chart to work

• Tooltips: shows how Vega-Lite implements tooltips as an encoding within a chart, with formatting options

• Vega Datasets: work with Vega datasets using import_vega_data()

• View Composition: how to facet, add layers to, repeat, and concatenate charts

• Interactive Examples: a set of examples that work towards linked-brushing of two scatterplots

Field Guides:

• Field Guide to Python Issues: A place for “gotchas” and their workarounds

• Field Guide to Rendering Charts: How to use the vegawidget() function to render charts as HTML

This package rests on these foundations:

• Altair: Python interface to Vega-Lite

• reticulate: R framework to work with Python

• Vega-Lite: a grammar of interactive graphics

• htmlwidgets: R framework to work with JavaScript visualizations

As well, a particular debt is owed to the folks behind the vegalite package, as it provided a lot of the inspiration for these efforts.

This project is a collaborative effort. In addition to the principal author:

• Alicia Schep has contributed the concatenation functions, as well as sorted out many of the Python, JavaScript, and package-API issues.

• Haley Jeppson has adapted the Altair Example Gallery to R.

• Heike Hofmann has been an invaluable advisor, providing incisive feedback, and insight into the fundamentals of interactive graphics.

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

This project also has a Contributing Guide.