The goal of altair is to help you buildVega-Litevisualizations. This package usesreticulateto provide an interface to theAltair Pythonpackage, and thevegawidgetpackage to render charts as htmlwidgets. To avoid confusion, thecapitalized wordAltair shall refer to the Pythonpackage; the lower-case wordaltair shall refer to thisR package.
This version of the R package supports Python Altair version4.2.0.
This example is discussed in detail in ourGettingStarted 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$ instead.
In your data, columns that contain dots can be wrapped in squarebrackets in Altair specifications, e.g. [Sepal.Width], tokeep Altair from throwing an error. Alternatively, you can use adouble-backslash, e.g. Sepal\\.Width.
These and other “gotchas” are compiled along with workarounds in anarticle:FieldGuide to Python Issues.
You can install altair from CRAN with:
install.packages("altair")The development version of is available fromGitHub:
# install.packages("devtools")devtools::install_github("vegawidget/altair")Because of Python, there may be some additional installation steps,described in greater detail in theInstallationarticle.
Python must be installed on your system. We have had successusingConda: in particular,Minicondaworks well and installs more-quickly than Anaconda.
If you work in a corporate or institutional environment, you may haveto specify the location of your SSL certificate, or deal with a proxy.The installation article has asectionon this.
Create a Conda environment called"r-reticulate".The reticulate folksrecommendstandardizing on a common name for all packages that use reticulate. Formore information, there is asectionin the installation article.
Install Altair into your"r-reticulate" environmentusingaltair::install_altair().
Important: (Python) Altair 4.2.0 does note workwith Pandas 2.0; use Pandas 1.5.3 (for example). This is fixed for(Python) Altair 5, which will be made available in an upcoming releaseof (R) altair.
You may wish to add a line like this to the.First()function in your.Rprofile:
reticulate::use_condaenv("r-reticulate")Theuse_condaenv() function is called to provide ahintto reticulate on which Python environment to use.
If you have theV8 installed,you can usevegawidget’simage-generating functions to convert Altair charts into SVG stringsor write SVG files. With thersvg andpng packagesinstalled, you can get a bitmap array, or write PNG files.
When knitting to a non-HTML format,e.g. github_document, this package provides aknit_print() function that will intercept the normalrenderer, using instead its own renderer, allowing you to specify"png" ,"svg" or"pdf". Like theimage functions, this requires that the V8 package be installed, as wellasrsvg andpng. MacOS users willrequire an X11 system, such asXQuartz, to be installed.
The documentation for this package includes somearticles:
GettingStarted: a walkthrough to get a first chart to work
Installation:some more-detailed instructions
Gallery:
Examples:
Tooltips:shows how Vega-Lite implements tooltips as an encoding within a chart,with formatting options
VegaDatasets: work withVega datasetsusingimport_vega_data()
ViewComposition: how to facet, add layers to, repeat, and concatenatecharts
InteractiveExamples: a set of examples that work towards linked-brushing of twoscatterplots
Field Guides:
FieldGuide to Python Issues: “gotchas” and their workarounds
FieldGuide to Rendering Charts: specify options to render charts asHTML
This package rests on these foundations:
Altair: Pythoninterface to Vega-Lite
reticulate: Rframework to work with Python
Vega-Lite: agrammar of interactive graphics
vegawidget: Rpackage to render Vega(-Lite) visualizations
htmlwidgets: Rframework to work with JavaScript visualizations
As well, a particular debt is owed to the folks behind thevegalite package, as itprovided a lot of the inspiration for these efforts.
This project is a collaborative effort. In addition to the principalauthors:
Alicia Schep hascontributed the concatenation functions, as well as sorted out many ofthe Python, JavaScript, and package-API issues.
Heike Hofmann has been aninvaluable advisor, providing incisive feedback, and insight into thefundamentals of interactive graphics.
Please note that this project is released with aContributorCode of Conduct. By participating in this project you agree to abideby its terms.
This project also has aContributingGuide.