altair

R interface to 'Altair'

https://github.com/vegawidget/altair

Keywords

Keywords from Contributors

Repository

R interface to 'Altair'

README.Rmd

---
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")`).

Owner

GitHub Events

Committers

Last synced: over 2 years ago

Issues and Pull Requests

Last synced: 6 months ago

Packages