Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/vegawidget/altair

R interface to 'Altair'
https://github.com/vegawidget/altair

altair interactive r reticulate vega-lite visualization

Last synced: 3 months ago
JSON representation

R interface to 'Altair'

Awesome Lists containing this project

README 

        
---

output: github_document

editor_options: 

  chunk_output_type: console

---



```{r setup, include = FALSE}

knitr::opts_chunk$set(

  collapse = TRUE,

  comment = "#>",

  fig.path = "man/figures/README-",

  dev = "svg"

)



url_local <- function(x) {

  file.path("https://vegawidget.github.io/altair", x)

}

```



[![CRAN status](https://www.r-pkg.org/badges/version/altair)](https://cran.r-project.org/package=altair)

[![R-CMD-check](https://github.com/vegawidget/altair/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/vegawidget/altair/actions/workflows/R-CMD-check.yaml)



# altair



The goal of altair is to help you build [**Vega-Lite**](https://vega.github.io/vega-lite/) visualizations. 

This package uses [**reticulate**](https://rstudio.github.io/reticulate/) to provide an interface to the [**Altair**](https://altair-viz.github.io) Python package, and the [**vegawidget**](https://vegawidget.github.io/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 `r altair::altair_version()$altair`.



## Example



This example is discussed in detail in our [Getting Started article](https://vegawidget.github.io/altair/articles/altair.html):



```{r example}

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 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. `Sepal\\.Width`.

  

These and other "gotchas" are compiled along with workarounds in an article: [Field Guide to Python Issues](https://vegawidget.github.io/altair/articles/field-guide-python.html).   



## Installation



You can install altair from CRAN with:



```{r cran-installation, eval=FALSE}

install.packages("altair")

```



The development version of is available from [GitHub](https://github.com/vegawidget/altair/):



``` r

# 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](https://vegawidget.github.io/altair/articles/installation.html).



1. Python must be installed on your system. 

   We have had success using [Conda](https://conda.io/docs): in particular, [Miniconda](https://conda.io/projects/conda/en/latest/user-guide/install/index.html#anaconda-or-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](https://vegawidget.github.io/altair/articles/installation.html#proxies) on this. 

   

1. Create a Conda environment called `"r-reticulate"`. 

The reticulate folks [recommend](https://rstudio.github.io/reticulate/articles/python_packages.html) standardizing on a common name for all packages that use reticulate. 

For more information, there is a [section](https://vegawidget.github.io/altair/articles/installation.html#python-env) in the installation article. 



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



1. **Important**: (Python) Altair 4.2.0 does note work with 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 release of (R) altair.



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



```r

reticulate::use_condaenv("r-reticulate")

```



The `use_condaenv()` function is called to provide a [hint to reticulate](https://rstudio.github.io/reticulate/articles/versions.html#order-of-discovery) on which Python environment to use.



### Optional installations



If you have the **[V8](https://CRAN.R-project.org/package=V8)** installed, you can use [vegawidget's image-generating functions](https://vegawidget.github.io/vegawidget/reference/image.html) to convert Altair charts into SVG strings or write SVG files. 

With the **[rsvg](https://CRAN.R-project.org/package=rsvg)** and **[png](https://CRAN.R-project.org/package=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 provides a `knit_print()` function that will intercept the normal renderer, using instead its own renderer, allowing you to specify `"png"` , `"svg"` or `"pdf"`. 

Like the image functions, this requires that the V8 package be installed, as well as  [rsvg](https://cran.r-project.org/package=rsvg) and [png](https://cran.r-project.org/package=png). 

MacOS users will require an X11 system, such as [XQuartz](https://www.xquartz.org), to be installed.



## Articles



The documentation for this package includes some [articles](https://vegawidget.github.io/altair/articles/index.html):



- [Getting Started](https://vegawidget.github.io/altair/articles/altair.html): a walkthrough to get a first chart to work



- [Installation](https://vegawidget.github.io/altair/articles/installation.html): some more-detailed instructions



Gallery:



- An adaptation to R of the [Altair Example Gallery](https://altair-viz.github.io/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](https://vegawidget.github.io/altair/articles/example-gallery-08-interactive-charts.html) examples.  



Examples:



- [Tooltips](https://vegawidget.github.io/altair/articles/tooltips.html): shows how Vega-Lite implements tooltips as an encoding within a chart, with formatting options



- [Vega Datasets](https://vegawidget.github.io/altair/articles/vega-datasets.html): work with [Vega datasets](https://github.com/altair-viz/vega_datasets) using `import_vega_data()`



- [View Composition](https://vegawidget.github.io/altair/articles/view-composition.html): how to facet, add layers to, repeat, and concatenate charts



- [Interactive Examples](https://vegawidget.github.io/altair/articles/interactive.html): a set of examples that work towards linked-brushing of two scatterplots



Field Guides:



- [Field Guide to Python Issues](https://vegawidget.github.io/altair/articles/field-guide-python.html): "gotchas" and their workarounds



- [Field Guide to Rendering Charts](https://vegawidget.github.io/altair/articles/field-guide-rendering.html): specify options to render charts as HTML



## Acknowledgements



This package rests on these foundations:



- [Altair](https://altair-viz.github.io): Python interface to Vega-Lite



- [reticulate](https://rstudio.github.io/reticulate/): R framework to work with Python



- [Vega-Lite](https://vega.github.io/vega-lite/): a grammar of interactive graphics



- [vegawidget](https://vegawidget.github.io/vegawidget/): R package to render Vega(-Lite) visualizations



- [htmlwidgets](https://www.htmlwidgets.org/): R framework to work with JavaScript visualizations



As well, a particular debt is owed to the folks behind the [vegalite](https://github.com/hrbrmstr/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:



- [Alicia Schep](https://github.com/AliciaSchep) has contributed the concatenation functions, as well as sorted out many of the Python, JavaScript, and package-API issues.



- [Heike Hofmann](https://github.com/heike) has been an invaluable advisor, providing incisive feedback, and insight into the fundamentals of interactive graphics.



## Contributing



Please note that this project is released with a [Contributor Code of Conduct](`r url_local("CODE_OF_CONDUCT.html")`).

By participating in this project you agree to abide by its terms. 



This project also has a [Contributing Guide](`r url_local("CONTRIBUTING.html")`).