Package 'altair' reference manual

Title:	Interface to 'Altair'
Description:	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 and 'Python'.
Authors:	Ian Lyttle [aut, cre] , Haley Jeppson [aut], Altair Developers [aut], Alicia Schep [ctb] , Jake Vanderplas [ctb] (Altair library), Brian Granger [ctb] (Altair library)
Maintainer:	Ian Lyttle <[email protected]>
License:	MIT + file LICENSE
Version:	5.2.0.9002
Built:	2024-09-11 02:37:50 UTC
Source:	https://github.com/vegawidget/altair

Altair object

Description

Uses the reticulate framework to access the Altair API.

Usage

alt
alt

Format

An object of class python.builtin.module (inherits from python.builtin.object) of length 0.

Details

The Altair Python package is exposed through the alt object. You can create and add to chart using its methods and classes, as outlined in the Altair Python documentation.

In this package, use the $ operator wherever you see the . operator used in Python.

Examples

if (interactive()) {
  vega_data <- import_vega_data()

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

   plot_basic
}

if (interactive()) {
  vega_data <- import_vega_data()

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

   plot_basic
}

Altair plot concatenation

Description

Altair plots can be concatenated using the following operators: +, |, and &

Usage

## S3 method for class 'altair.vegalite.v4.api.TopLevelMixin'
e1 | e2

## S3 method for class 'altair.vegalite.v4.api.TopLevelMixin'
e1 + e2

## S3 method for class 'altair.vegalite.v4.api.TopLevelMixin'
e1 & e2
## S3 method for class 'altair.vegalite.v4.api.TopLevelMixin'
e1 | e2

## S3 method for class 'altair.vegalite.v4.api.TopLevelMixin'
e1 + e2

## S3 method for class 'altair.vegalite.v4.api.TopLevelMixin'
e1 & e2

Arguments

`e1`	Altair chart object
`e2`	Altair chart object

Value

Compound Altair chart object

Examples


if (interactive()){

  # Examples using the beaver1 and beaver2 body temperature data sets
  # Layering Charts
  base <- alt$Chart(beaver1)$encode(
    x = alt$X('time'),
    y = alt$Y('temp', scale = alt$Scale(zero = FALSE))
  )

  scatter_plot <- base$mark_point()
  line_plot <- base$mark_line()

  combined_plot <- scatter_plot + line_plot

  # Horizontal Concatenation
  base2 <- alt$Chart(beaver2)$
    encode(
      x = alt$X("time"),
      y = alt$Y("temp", scale = alt$Scale(zero = FALSE))
    )

  scatter_plot2 <- base2$mark_point()
  line_plot2 <- base2$mark_line()

  combined_plot <-
    (scatter_plot + line_plot)$
    properties(title = "Beaver 1", width = 200)

  combined_plot2 <-
    (scatter_plot2 + line_plot2)$
    properties(title = "Beaver 2", width = 200)

  hconcat_plot <- combined_plot | combined_plot2

  # Vertical Concatenation
  vconcat_plot <- combined_plot & combined_plot2

}

if (interactive()){

  # Examples using the beaver1 and beaver2 body temperature data sets
  # Layering Charts
  base <- alt$Chart(beaver1)$encode(
    x = alt$X('time'),
    y = alt$Y('temp', scale = alt$Scale(zero = FALSE))
  )

  scatter_plot <- base$mark_point()
  line_plot <- base$mark_line()

  combined_plot <- scatter_plot + line_plot

  # Horizontal Concatenation
  base2 <- alt$Chart(beaver2)$
    encode(
      x = alt$X("time"),
      y = alt$Y("temp", scale = alt$Scale(zero = FALSE))
    )

  scatter_plot2 <- base2$mark_point()
  line_plot2 <- base2$mark_line()

  combined_plot <-
    (scatter_plot + line_plot)$
    properties(title = "Beaver 1", width = 200)

  combined_plot2 <-
    (scatter_plot2 + line_plot2)$
    properties(title = "Beaver 2", width = 200)

  hconcat_plot <- combined_plot | combined_plot2

  # Vertical Concatenation
  vconcat_plot <- combined_plot & combined_plot2

}

Installed versions of Altair, Vega, etc.

Description

Returns a named list of version tags for Altair, Vega, Vega-Lite, and Vega-Embed

Usage

altair_version()
altair_version()

Value

named list of version tags

Examples

if (interactive()) {
  altair_version()
}

if (interactive()) {
  altair_version()
}

Create Altair chart from vegaspec

Description

Create Altair chart from vegaspec

Usage

as_chart(spec)
as_chart(spec)

Arguments

spec

An object to be coerced to vegaspec, a Vega/Vega-Lite specification

Value

altair object

Examples

  if (interactive()) {
    as_chart(vegawidget::spec_mtcars)
  }
if (interactive()) {
    as_chart(vegawidget::spec_mtcars)
  }

Coerce to vegaspec

Description

See vegawidget::as_vegaspec for details.

Usage

## S3 method for class 'altair.vegalite.v5.api.TopLevelMixin'
as_vegaspec(spec, ...)
## S3 method for class 'altair.vegalite.v5.api.TopLevelMixin'
as_vegaspec(spec, ...)

Arguments

`spec`	An object to be coerced to `vegaspec`, a Vega/Vega-Lite specification
`...`	Other arguments (attempt to future-proof)

Check the Altair installation

Description

Provides feedback on any differences between your installed version of Altair and the version this package supports.

Usage

check_altair(quiet = FALSE)
check_altair(quiet = FALSE)

Arguments

quiet

logical, if TRUE, suppresses message upon successful check

Details

If the supported Altair version is different from your installed version, this function will act according to where the difference in the version numbers:

major version leads to an error
minor version leads to a warning
patch version leads to a message

If there is no difference:

quiet = FALSE, success message showing version-numbers
quiet = TRUE, no message

To install the supported version into a Python environment called "r-reticulate", use install_altair().

Value

invisible NULL, called for side-effects

Examples

## Not run: 
  # not run because it requires Python
  check_altair()

## End(Not run)
## Not run: 
  # not run because it requires Python
  check_altair()

## End(Not run)

Import Vega datasets

Description

Lets you access Vega datasets.

Usage

import_vega_data()
import_vega_data()

Details

Returns the data object in the Python package vega-datasets. In the documentation for this package, the convention is to assign this object to the name vega_data.

Value

An S3 object of class vega_datasets.core.DataLoader

Examples

if (interactive()) {
  vega_data <- import_vega_data()

  # To list available datasets
  print(vega_data$list_datasets())

  # When accessing a dataset, substitute any "-" in the name with a "_"
  print(head(vega_data$sf_temps()))

  # Metadata are available for each dataset:
  print(vega_data$anscombe$references)
  print(vega_data$anscombe$description)
  print(vega_data$anscombe$url)

  # For local datasets, local path is available
  print(vega_data$sf_temps$filepath)
}
if (interactive()) {
  vega_data <- import_vega_data()

  # To list available datasets
  print(vega_data$list_datasets())

  # When accessing a dataset, substitute any "-" in the name with a "_"
  print(head(vega_data$sf_temps()))

  # Metadata are available for each dataset:
  print(vega_data$anscombe$references)
  print(vega_data$anscombe$description)
  print(vega_data$anscombe$url)

  # For local datasets, local path is available
  print(vega_data$sf_temps$filepath)
}

Install Altair Python package

Description

This function wraps installation functions from reticulate to install the Python packages altair and vega_datasets.

Usage

install_altair(
  method = c("conda", "virtualenv"),
  envname = "r-reticulate",
  version = getOption("altair.python.version"),
  ...
)
install_altair(
  method = c("conda", "virtualenv"),
  envname = "r-reticulate",
  version = getOption("altair.python.version"),
  ...
)

Arguments

`method`	`character`, indicates to use `"conda"` or `"virtualenv"`
`envname`	`character`, name of environment into which to install
`version`	`character`, version of Altair to install. For general use of this package, this is set automatically, so you should not need to specify this.
`...`	other arguments sent to `reticulate::py_install()`

Details

This package uses the reticulate package to make an interface with the Altair Python package. To promote consistency in usage of reticulate among different R packages, it is recommended to use a common Python environment, called "r-reticulate".

Depending on your setup, you can create this environment using reticulate::conda_create() or reticulate::virtualenv_create(), as described in this reticulate article, or in this package's Installation article.

Value

invisible NULL, called for side-effects

Examples

## Not run: 
  # not run because it requires Python
  install_altair()

## End(Not run)
## Not run: 
  # not run because it requires Python
  install_altair()

## End(Not run)

Knit-print method

Description

See vegawidget::knit_print.vegaspec for details, particularly on additional packages that may have to be installed.

Usage

knit_print.altair.vegalite.v5.api.TopLevelMixin(spec, ..., options = NULL)
knit_print.altair.vegalite.v5.api.TopLevelMixin(spec, ..., options = NULL)

Arguments

`spec`	An object to be coerced to `vegaspec`, a Vega/Vega-Lite specification
`...`	other arguments
`options`	`list`, knitr options

Render shiny-output for vegawidget

Description

Deprecated, please use vegawidget::renderVegawidget.

Usage

renderVegawidget(expr, env = parent.frame(), quoted = FALSE)
renderVegawidget(expr, env = parent.frame(), quoted = FALSE)

Arguments

`expr`	expression that generates a vegawidget. This can be a `vegawidget` or a `vegaspec`.
`env`	The environment in which to evaluate `expr`.
`quoted`	Is `expr` a quoted expression (with `quote()`)? This is useful if you want to save an expression in a variable.

Vega embed options

Description

See vegawidget::vega_embed for details.

Create a Vega/Vega-Lite htmlwidget

Description

See vegawidget::vegawidget for details.

Shiny-output for vegawidget

Description

Deprecated, please use vegawidget::vegawidgetOutput.

Usage

vegawidgetOutput(outputId, width = "auto", height = "auto")
vegawidgetOutput(outputId, width = "auto", height = "auto")

Arguments

`outputId`	output variable to read from
`width`, `height`	Must be a valid CSS unit (like `"100%"`, `"400px"`, `"auto"`) or a number, which will be coerced to a string and have `"px"` appended. For vegawidgets, `"auto"` is useful because, as of now, the spec determines the size of the widget, then the widget determines the size of the container.

Coerce vegaspec to JSON

Description

Deprecated, please use vegawidget::vw_as_json.

Usage

vw_as_json(spec, pretty = TRUE)
vw_as_json(spec, pretty = TRUE)

Arguments

`spec`	An object to be coerced to `vegaspec`, a Vega/Vega-Lite specification
`pretty`	`logical` indicates to use pretty (vs. minified) formatting

Value

jsonlite::json object

Set base URL

Description

See vegawidget::vw_set_base_url for details.

Package 'altair'

Help Index

Altair object

Description

Usage

Format

Details

See Also

Examples

Altair plot concatenation

Description

Usage

Arguments

Value

Examples

Installed versions of Altair, Vega, etc.

Description

Usage

Value

Examples

Create Altair chart from vegaspec

Description

Usage

Arguments

Value

Examples

Coerce to vegaspec

Description

Usage

Arguments

Check the Altair installation

Description

Usage

Arguments

Details

Value

See Also

Examples

Create or write image

Description

Import Vega datasets

Description

Usage

Details

Value

See Also

Examples

Install Altair Python package

Description

Usage

Arguments

Details

Value

See Also

Examples

Knit-print method

Description

Usage

Arguments

Render shiny-output for vegawidget

Description

Usage

Arguments

Vega embed options

Description

Create a Vega/Vega-Lite htmlwidget

Description

Shiny-output for vegawidget

Description

Usage

Arguments

Coerce vegaspec to JSON

Description

Usage

Arguments

Value

Set base URL

Description