Vega-Altair Documentation

Altair is a declarative statistical visualization library for Python. It is designed for scientists and data scientists performing exploratory data analysis.

Key characteristics:

• Declarative API: Visualizations are specified by describing how data is mapped to visual properties (position, color, size, etc.) rather than by manual drawing commands.
• Vega-Lite Based: Altair is built on top of the Vega-Lite visualization grammar, providing a wide range of statistical visualizations through a small set of grammar primitives.
• Interactivity: Supports complex interactions (like interval selections and multi-selections) that can drive filters and transformations across multiple plots.
• Rendering: The Python API emits Vega-Lite JSON data, which is rendered in environments like Jupyter Notebook, JupyterLab, or nteract using the Vega-Lite JavaScript library.

Vega-Altair is designed to simplify exploratory data visualization by providing a constrained, declarative Python API. Instead of being a standalone rendering engine, it follows a layered design pattern:

1. Declarative API: You use the Vega-Altair Python API to describe what you want to see, rather than how to draw it.
2. JSON Specification: The API emits JSON output that adheres to the Vega-Lite specification.
3. Rendering: The resulting Vega-Lite specification is rendered using existing visualization libraries (like Vega).

This approach allows users to start with simple, high-level commands for statistical visualization and transition to advanced customization by leveraging the underlying renderer's capabilities.

Altair's data transformation API manages how pandas DataFrames are sanitized and serialized before being passed to a Vega-Lite or Vega renderer. This includes tasks like converting DataFrames to JSON, sampling rows, or limiting the number of rows for performance.

Note: The Altair data transformation API is distinct from the transform API within Vega and Vega-Lite.

Altair is compatible with several Python dashboarding packages. Some packages support reading out parameters from the chart, allowing for interactive dashboards where selections update other components (like tables).

For use cases where full server-side interactivity isn't required, tools like Quarto or Jupyter Book can generate HTML pages containing Altair charts without needing a web server.

Altair uses a declarative grammar for interaction based on three core concepts:

1. Parameters: The basic building blocks. These can be simple variables or complex selections that map user input (like mouse clicks or drags) to data queries.
2. Conditions and Filters: These respond to changes in parameter values to update chart elements dynamically.
3. Widgets and Bindings: Chart input elements (like drop-down menus, radio buttons, or sliders) can be bound to parameters to allow users to manipulate charts.

Additionally, you can use Expressions for custom calculations via formulas and JupyterCharts to access parameter values directly from Python.

Use alt.value to map an encoding channel to an absolute visual constant, such as a specific pixel position, an RGB color name, or a shape name. Unlike alt.datum, alt.value ignores the data scale and uses absolute units (e.g., alt.value(300) positions an element 300 pixels from the chart border).

import altair as alt
from altair.datasets import data

source = data.stocks()
base = alt.Chart(source)
lines = base.mark_line().encode(
    x="date:T",
    y="price:Q",
    color="symbol:N"
)
# Position the rule 300 pixels from the top border
rule = base.mark_rule(strokeDash=[2, 2]).encode(
    y=alt.value(300)
)

lines + rule

Instead of embedding data directly, you can store it in a separate file and pass the URL to the chart. This improves notebook performance and interactivity.

Local Filesystem: You can save data to a JSON file and pass the path to alt.Chart().

url = 'data.json'
data.to_json(url, orient='records')
chart = alt.Chart(url).mark_line().encode(x='x:Q', y='y:Q')

Automatic JSON/CSV Transformers: Altair provides transformers that handle this process transparently:

alt.data_transformers.enable('json')
# Note: 'csv' is also available but does not preserve data types as well as JSON

Vega Datasets: For built-in Vega datasets, use the url attribute:

from altair.datasets import data
source = data.cars.url
alt.Chart(source).mark_point()