Declarative statistical visualization library for Python
BSD-3-CLAUSE License
Bot releases are hidden (Show)
The Vega Project is happy to announce the release of version 5.3.0 of the Vega-Altair Python visualization library. This release has been 4 months in the making and includes enhancements, fixes, and documentation improvements from 11 contributors.
Add integration of VegaFusion and JupyterChart to enable scaling many interactive Vega-Altair charts to millions of rows. See VegaFusion Data Transformer for more information. Here is an example of histogram cross filtering with a 1 million row dataset.
https://github.com/altair-viz/altair/assets/15064365/ddca2a1e-6e6b-4d9f-9949-97e0c51b47d9
Add "browser"
renderer to support displaying Vega-Altair charts in an external web browser. See Browser Renderer for more information (#3379).
https://github.com/altair-viz/altair/assets/15064365/30d4f2e2-7a30-4c8a-97ae-085d7580c5e4
Support opening charts in the Vega editor with chart.open_editor()
(#3358)
https://github.com/altair-viz/altair/assets/15064365/9233b290-421d-4fa7-80b2-945423bbc3fc
"jupyter"
renderer which uses JupyterChart for rendering (#3283). See Displaying Altair Charts for more information.embed_options
argument to JupyterChart to allow customization of Vega Embed options (#3304)"jupyter"
renderer. See JupyterChart - Offline Usage for more information.python -m pip install altair[all]
and conda install altair-all -c conda-forge
(#3354)embed_options
are None
(#3376)md5
to a truncated sha256
non-cryptograhic hash (#3291)chart.show()
method to invoke the active renderer rather than depend on altair_saver
(Which was never updated for use with Altair 5) (#3379).Chart.from_dict
by @RobinL in https://github.com/altair-viz/altair/pull/3383
all
dependency group by @jonmmease in https://github.com/altair-viz/altair/pull/3354
open_editor
method by @joelostblom in https://github.com/altair-viz/altair/pull/3358
Full Changelog: https://github.com/altair-viz/altair/compare/v5.2.0...v5.3.0
Published by binste 7 months ago
Published by binste 7 months ago
Update includes full compatibility with version 3.3 of Vega-Lite.
Added support for vega themes via alt.themes.enable(theme_name)
(#1539)
Added an alt.renderers.disable_max_rows()
method for disabling the maximum rows check (#1538)
Improved user-facing warnings/errors around layering and faceting (#1535).
data
argument is now properly handled by Chart.properties
(#1525)
Compound charts (layer, concat, hconcat, vconcat) now move data to the top level by default. In particular, this means that the facet()
method can now be called directly on a layered chart without having to change how data is specified. (#1521)
alt.LayerChart
now supports mark_*()
methods. If a layer specifies a mark at the top level, all child charts will inherit it (unless they override it explicitly).
alt.Chart.facet()
now handles wrapped facets; for example: chart.facet('column_name', columns=5)
See altair/examples/us_population_over_time_facet.py
for a more complete example.
Make chart.serve()
and chart.save()
respect the data transformer setting (#1538)
Fixed a deserialization bug for certain chart specs in schemapi (#1543)
alt.Chart.facet()
now accepts a wrapped facet encoding as a first positional argument, rather than a row encoding. The following are examples of old invocations, and the equivalent new invocations:
chart.facet(row='col1', column='col2')
: unchanged
chart.facet('col1', 'col2')
: change to chart.facet(row='col1', column='col2')
chart.facet('col1')
: change to chart.facet(row='col1')
In each case, the new invocations are compatible back to Altair 2.X.
Several of the encoding channels added in 3.0 have had their capitalization corrected to better match the names used in the schema:
alt.Fillopacity
-> alt.FillOpacity
alt.Strokeopacity
-> alt.StrokeOpacity
alt.Strokewidth
-> alt.StrokeWidth
alt.Xerror
-> alt.XError
alt.Xerror2
-> alt.XError2
alt.Yerror
-> alt.YError
alt.Yerror2
-> alt.YError2
Published by binste 7 months ago
Fix version info bug for HTML output and Colab & Kaggle renderers.
Published by binste 7 months ago
Published by binste 7 months ago
Includes many reworked examples in the example gallery.
pandas.RangeIndex
columns to strings (#1107)set_embed_options()
method (#1203)chart.save()
(#1134)Published by binste 7 months ago
altair.vega.v4
(#1097)Published by binste 7 months ago
appropriate handling of InlineData in dataset consolidation (#1092)
fix admonition formatting in documentation page (#1094)
Published by binste 7 months ago
Complete rewrite of Altair, focused on supporting Vega-Lite 2.X
Published by binste 7 months ago
This version of Altair is based on Vega-Lite 1.2.1.
Support for JupyterLab/nteract through MIME based rendering. Enable this by calling enable_mime_rendering()
before rendering visualizations (#216).
Change default import in all code and docs to import altair as alt
Check for missing and misspelled column names upon exporting or rendering, and raise FieldError
(#399) if any problems are found. This can be disabled by setting Chart.validated_columns=False
.
Raise MaxRowsExceeded
if the number of rows in the dataset is larger than Chart.max_rows
to guard against sending large datasets to the browser.
Move the Vega-Lite 1.x api into altair.v1
to make it easier for us to migrate to Vega-Lite 2.x and continue to support 1.x. No import change are needed as altair.v1
is aliased to altair
in this release (#377).
Moved the example notebooks into a separate repository (https://github.com/altair-viz/altair_notebooks) that has Binder support (#391).
Add $schema
to top-level JSON spec (#370).
Minor documentation revisions.
Published by binste 7 months ago
Initial release of Altair
Published by mattijn 11 months ago
You now can use:
chart.save('chart.html', inline=True)
To create an HTML file with inline JavaScript dependencies. This enhancements takes advantage of HTML bundling support in vl-convert
to replace the dependency on altair_viewer
. Vega-Altair 5.2.0 expects vl-convert-python
version 1.1.0 or higher for this enhancement.
You now can use:
chart.save('chart.pdf')
To create an PDF representation of your chart. This enhancements takes advantage of PDF support in vl-convert
to replace the dependency on altair_saver
. Vega-Altair 5.2.0 expects vl-convert-python
version 1.1.0 or higher for this enhancement.
You now can use:
chart.to_url()
To generate a Vega editor URL that opens the chart's specification in the online Vega editor. This enhancements takes advantage of lz-string URL-compatible compression in vl-convert
. Vega-Altair 5.2.0 expects vl-convert-python
version 1.1.0 or higher for this enhancement.
Example:
import altair as alt
from vega_datasets import data
chart = alt.Chart(data.cars.url).mark_point().encode(
x='Horsepower:Q',
y='Miles_per_Gallon:Q',
color='Origin:N'
)
print(chart.to_url())
format_locale
and time_format_locale
through to vl-convert to support locales in static image export (#3274)The preferred format of numbers, dates, and currencies varies by language and locale. Vega-Altair takes advantage of D3’s localization support to make it easy to configure the locale for your chart using the global alt.renderers.set_embed_options
function. Vega-Altair 5.2.0 expects vl-convert-python
version 1.1.0 or higher for this enhancement.
See https://altair-viz.github.io/user_guide/customization.html#localization for more info (including the note with a caveat!).
See https://github.com/altair-viz/altair/issues/2951 for a full summary how we have implemented these. Type hints can help IDEs to provide a better development experience as well as static type checkers to catch potential errors before they appear at runtime.
python-version
3.12 by @mattijn in https://github.com/altair-viz/altair/pull/3235
Full Changelog: https://github.com/altair-viz/altair/compare/v5.1.2...v5.2.0
Published by joelostblom about 1 year ago
convert_dtypes
by @binste in #3191Full Changelog: https://github.com/altair-viz/altair/compare/v5.1.1...v5.1.2
Published by mattijn about 1 year ago
Full Changelog: https://github.com/altair-viz/altair/compare/v5.1.0...v5.1.1
Published by mattijn about 1 year ago
chart.transformed_data()
method was added to extract transformed chart dataFor example when having an Altair chart including aggregations:
import altair as alt
from vega_datasets import data
cars = data.cars.url
chart = alt.Chart(cars).mark_bar().encode(
y='Cylinders:O',
x='mean_acc:Q'
).transform_aggregate(
mean_acc='mean(Acceleration)',
groupby=["Cylinders"]
)
chart
Its now possible to call the chart.transformed_data
method to extract a pandas DataFrame containing the transformed data.
chart.transformed_data()
This method is dependent on VegaFusion with the embed extras enabled.
vegafusion
VegaFusion is an external project that provides efficient Rust implementations of most of Altair's data transformations. Using VegaFusion as Data Transformer it can overcome the Altair MaxRowsError by performing data-intensive aggregations in Python and pruning unused columns from the source dataset.
The data transformer can be enabled as such:
import altair as alt
alt.data_transformers.enable("vegafusion") # default is "default"
DataTransformerRegistry.enable('vegafusion')
And one can now visualize a very large DataFrame as histogram where the binning is done within VegaFusion:
import pandas as pd
import altair as alt
# prepare dataframe with 1 million rows
flights = pd.read_parquet(
"https://vegafusion-datasets.s3.amazonaws.com/vega/flights_1m.parquet"
)
delay_hist = alt.Chart(flights).mark_bar(tooltip=True).encode(
alt.X("delay", bin=alt.Bin(maxbins=30)),
alt.Y("count()")
)
delay_hist
When the vegafusion
data transformer is active, data transformations will be pre-evaluated when displaying, saving and converting charts as dictionary or JSON.
See a detailed overview on the VegaFusion Data Transformer in the documentation.
JupyterChart
class was added to support accessing params and selections from PythonThe JupyterChart
class makes it possible to update charts after they have been displayed and access the state of interactions from Python.
For example when having an Altair chart including a selection interval as brush:
import altair as alt
from vega_datasets import data
source = data.cars()
brush = alt.selection_interval(name="interval", value={"x": [80, 160], "y": [15, 30]})
chart = alt.Chart(source).mark_point().encode(
x='Horsepower:Q',
y='Miles_per_Gallon:Q',
color=alt.condition(brush, 'Cylinders:O', alt.value('grey')),
).add_params(brush)
jchart = alt.JupyterChart(chart)
jchart
It is now possible to return the defined interval selection within Python using the JupyterChart
jchart.selections.interval.value
{'Horsepower': [80, 160], 'Miles_per_Gallon': [15, 30]}
The selection dictionary may be converted into a pandas query to filter the source DataFrame:
filter = " and ".join([
f"{v[0]} <= `{k}` <= {v[1]}"
for k, v in jchart.selections.interval.value.items()
])
source.query(filter)
Another possibility of the new JupyerChart
class is to use IPyWidgets
to control parameters in Altair. Here we use an ipywidget IntSlider
to control the Altair parameter named cutoff
.
import pandas as pd
import numpy as np
from ipywidgets import IntSlider, link, VBox
rand = np.random.RandomState(42)
df = pd.DataFrame({
'xval': range(100),
'yval': rand.randn(100).cumsum()
})
cutoff = alt.param(name="cutoff", value=23)
chart = alt.Chart(df).mark_point().encode(
x='xval',
y='yval',
color=alt.condition(
alt.datum.xval < cutoff,
alt.value('red'), alt.value('blue')
)
).add_params(
cutoff
)
jchart = alt.JupyterChart(chart)
slider = IntSlider(min=0, max=100, description='ipywidget')
link((slider, "value"), (jchart.params, "cutoff"))
VBox([slider, jchart])
The JupyterChart
class is dependent on AnyWidget. See a detailed overview in the new documentation page on JupyterChart Interactivity.
We are maturing support for objects build upon the DataFrame Interchange Protocol in Altair.
Given the following pandas DataFrame with an ordered categorical column-type:
import altair as alt
from vega_datasets import data
# Clean Title column
movies = data.movies()
movies["Title"] = movies["Title"].astype(str)
# Convert MPAA rating to an ordered categorical
rating = movies["MPAA_Rating"].astype("category")
rating = rating.cat.reorder_categories(
['Open', 'G', 'PG', 'PG-13', 'R', 'NC-17', 'Not Rated']
).cat.as_ordered()
movies["MPAA_Rating"] = rating
# Build chart using pandas
chart = alt.Chart(movies).mark_bar().encode(
alt.X("MPAA_Rating"),
alt.Y("count()")
)
chart
We can convert the DataFrame to a PyArrow Table and observe that the types are now equally infered when rendering the chart.
import pyarrow as pa
# Build chart using PyArrow
chart = alt.Chart(pa.Table.from_pandas(movies)).mark_bar().encode(
alt.X("MPAA_Rating"),
alt.Y("count()")
)
chart
Vega-Altair support of the DataFrame Interchange Protocol is dependent on PyArrow.
transform_extent
is availableSee the following example how this transform can be used:
import pandas as pd
import altair as alt
df = pd.DataFrame(
[
{"a": "A", "b": 28},
{"a": "B", "b": 55},
{"a": "C", "b": 43},
{"a": "D", "b": 91},
{"a": "E", "b": 81},
{"a": "F", "b": 53},
{"a": "G", "b": 19},
{"a": "H", "b": 87},
{"a": "I", "b": 52},
]
)
base = alt.Chart(df, title="A Simple Bar Chart with Lines at Extents").transform_extent(
extent="b", param="b_extent"
)
bars = base.mark_bar().encode(x="b", y="a")
lower_extent_rule = base.mark_rule(stroke="firebrick").encode(
x=alt.value(alt.expr("scale('x', b_extent[0])"))
)
upper_extent_rule = base.mark_rule(stroke="firebrick").encode(
x=alt.value(alt.expr("scale('x', b_extent[1])"))
)
bars + lower_extent_rule + upper_extent_rule
import altair as alt
from vega_datasets import data
source = data.cars()
chart = alt.Chart(source).mark_boxplot(extent="min-max").encode(
alt.X("Miles_per_Gallon:Q").scale(zero=False),
alt.Y("Origin:N"),
)
chart.save("box.png", ppi=300)
alt.renderers.enable("png", ppi=144) # default ppi is 72
chart
len
on DataFrame Interchange Protocol objects (#3111)Full Changelog: https://github.com/altair-viz/altair/compare/v5.0.1...v5.1.0
Published by mattijn over 1 year ago
.ref()
instead of removing it by @mattijn in https://github.com/altair-viz/altair/pull/3063
Full Changelog: https://github.com/altair-viz/altair/compare/v5.0.0...v5.0.1
Published by mattijn over 1 year ago
vl-convert
is now used as the default backend for saving Altair charts as svg and png files, which simplifies saving chart as it does not require external dependencies like altair_saver
does (#2701). Currently, altair_saver
does not support Altair 5 and it is recommended to switch to vl-convert
. See PNG, SVG, and PDF format for more details.altair_saver
installed (#2807).400
to 300
(#2785).Title
and Impute
aliases were added for TitleParams
and ImputeParams
, respectively (#2732).__dataframe__
attribute). This requires pyarrow>=11.0.0
(#2888).width="container"
when saving charts to html or displaying them with the default html
renderer (#2867).alt.X(..., bin=alt.Bin(...))
it is now recommend to use alt.X(...).bin(...)
) (#2795). See Method-Based Syntax for details.selection_single
and selection_multi
are now deprecated; use selection_point
instead. Similarly, type=point
should be used instead of type=single
and type=multi
.add_selection
is deprecated; use add_params
instead.selection
keyword argument must in many cases be replaced by param
(e.g., when specifying a filter transform).empty
keyword argument for a selection parameter should be specified as True
or False
instead of all
or none
, respectively.init
keyword argument for a parameter is deprecated; use value
instead.disable_debug_mode
(#2851)."column\:name"
instead of "column:name"
(#2824).param
are used in dictionaries to specify axis domains. Those used to be selection
, but that usage is not compatible with the current Vega-Lite schema.altair.sphinxext
module (#2792). The altair-plot
Sphinx directive is now part of the sphinxext-altair package.hatch
for package management.ruff
for linting.iteritems
with items
by @joelostblom in https://github.com/altair-viz/altair/pull/2683
altair_saver
in build.yml
as Github Actions tests are not passing anymore by @mattijn in https://github.com/altair-viz/altair/pull/2893
alt.ExprRef
capabilities in alt.expr()
by @mattijn in https://github.com/altair-viz/altair/pull/2886
type=
by @joelostblom in https://github.com/altair-viz/altair/pull/2933
stroke
option by @joelostblom in https://github.com/altair-viz/altair/pull/2992
selection_*
docstrings with signatures by @dpoznik in https://github.com/altair-viz/altair/pull/3001
ruff
as linter by @mattijn in https://github.com/altair-viz/altair/pull/3008
>=4.0.01
) by @mattijn in https://github.com/altair-viz/altair/pull/3039
jsonschema>=3.0
by @mattijn in https://github.com/altair-viz/altair/pull/3044
Full Changelog: https://github.com/altair-viz/altair/compare/v4.2.0...v5.0.0
Published by mattijn over 1 year ago
Full Changelog: https://github.com/altair-viz/altair/compare/v4.2.1...v4.2.2
Published by mattijn over 1 year ago
Note: This version requires jsonschema>=4.5.0
see (https://github.com/altair-viz/altair/issues/2857).
iteritems
with items
due to pandas deprecation (#2683).Published by jakevdp almost 3 years ago
mark_arc
. (Examples: eg. Pie Chart and Radial Chart)datum
encoding specifications from Vega-Lite; see Vega-Lite Datum Definition. (Examples: Line Chart with datum and Line Chart with datum for color.)angle
encoding can now be used to control point styles (Example: Wind Vector Map)Chart
is called without a data parameter (#2515).to_dict()
for nested selections (#2120).