Interface to 'Altair'
Interface to 'Altair' <https://altair-viz.github.io>, which itself
is a 'Python' interface to 'Vega-Lite' <https://vega.github.io/vega-lite/>.
This package uses the 'Reticulate' framework
<https://rstudio.github.io/reticulate/> to manage the interface between R
The goal of altair is to help you build Vega-Lite visualizations. This package uses reticulate to provide an interface to the Altair Python package, and the vegawidget package to render charts as htmlwidgets. To avoid confusion, the capitalized word Altair shall refer to the Python package; the lower-case word altair shall refer to this R package.
This version of the R package supports Python Altair version 4.1.0.
This example is discussed in detail in our getting started article:
library("altair") vega_data <- import_vega_data() chart <- alt$Chart(vega_data$cars())$ mark_point()$ encode( x = "Horsepower:Q", y = "Miles_per_Gallon:Q", color = "Origin:N" ) chart
Some things to keep in mind:
Where you see a
.in the Python examples, use a
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. Alternatively, you can use a double-backslash, e.g.
These and other “gotchas” are compiled along with workarounds in an article: Field Guide to Python Issues.
You can install altair from CRAN with:
The development version of is available from GitHub:
# install.packages("devtools") devtools::install_github("vegawidget/altair")
Because of Python, there may be some additional installation steps, described in greater detail in the Installation article.
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.
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.
Install Altair into your
You may wish to add a line like this to the
.First() function in your
use_condaenv() function is called to provide a hint to
on which Python environment to use.
If you have nodejs installed on your computer, you can use vegawidget’s image-generating functions to convert Altair charts into SVG strings or write SVG files. With the rsvg and png packages installed, you can get a bitmap array, or write PNG files.
When knitting to a non-HTML format, e.g.
github_document, this package
knit_print() function that will intercept the normal
renderer, using instead its own renderer, allowing you to specify
"pdf". Like the image functions, this requires
that nodejs be installed on your system, as well
as rsvg and
png. MacOS users will require
an X11 system, such as XQuartz, to be
The documentation for this package includes some articles:
Getting Started: a walkthrough to get a first chart to work
Installation: some more-detailed instructions
- 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.
Tooltips: shows how Vega-Lite implements tooltips as an encoding within a chart, with formatting options
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 Guide to Python Issues: “gotchas” and their workarounds
Field Guide to Rendering Charts: specify options 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
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 authors:
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.
Functions in altair
|repr_text.altair.vegalite.v4.api.TopLevelMixin||MIME method for text|
|altair_concatenation||Altair plot concatenation|
|vega_embed||Vega embed options|
|vegawidget||Create a Vega/Vega-Lite htmlwidget|
|vegawidgetOutput||Shiny-output for vegawidget|
|vw_as_json||Coerce vegaspec to JSON|
|repr_vegalite4.altair.vegalite.v4.api.TopLevelMixin||MIME method for chart rendering|
|vw_set_base_url||Set base URL|
|renderVegawidget||Render shiny-output for vegawidget|
|install_altair||Install Altair Python package|
|altair||altair: Create and embed Vega-Lite charts using the Altair Python package|
|as_vegaspec.altair.vegalite.v4.api.TopLevelMixin||Coerce to vegaspec|
|check_altair||Check the Altair installation|
|image||Create or write image|
|import_vega_data||Import Vega datasets|
|altair_version||Installed versions of Altair, Vega, etc.|
|as_chart||Create Altair chart from vegaspec|
Last month downloads
|SystemRequirements||Python (>= 3.5.0), (Python) Altair (>= 4.0.0). To use image functions, i.e. suggests: nodejs (> 8), and for MacOS: X11|
|License||MIT + file LICENSE|
|Packaged||2021-01-14 04:02:00 UTC; sesa19001|
|Date/Publication||2021-01-14 13:00:02 UTC|
|imports||assertthat , htmlwidgets , magrittr , repr , reticulate (>= 1.9) , utils , vegawidget (>= 0.3.2)|
|suggests||dplyr , fs , httr , knitr , listviewer (>= 2.0.0) , pkgdown , png , processx , pryr , purrr , readr , rmarkdown , rprojroot , rsvg , stringr , testthat , tibble , tidyr|
|Contributors||Haley Jeppson, Alicia Schep, Altair Developers , Jake Vanderplas, Brian Granger|
Include our badge in your README