NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
PyPI · #506 most downloaded on PyPI
Vega-Altair: A declarative statistical visualization library for Python.
Last release 20 days ago
15 Sep 2026
Release timing varies
gaps range from 2 weeks to 3 months
Nearly every release is documented
notes for 35 of 37 stable releases
5 versions withdrawn
withdrawn after publishing
10 years old
68 releases · first in 2016
build: Remove dead doc-build code and deprecated attribute access by @joelostblom in #4122
See below for details on what is new in this release. A special compatibility note is that this release drops support for Python 3.10 (which is reaching end of life in Oct).
alt.datum[xcol_param] in addition to f'datum[{xcol_param.name}]' as in this example in the docs.alt.X("field:Q").scale(["a", "b"], ["#1FC3AA", "#8624F5"])alt.value(alt.expr.scale("x", alt.datum.c1) in addition to alt.value(alt.expr("scale('x', datum.c1)")).Full Changelog: v6.2.2...v6.3.0
One column per quarter.
<!-- Release notes generated using configuration in .github/release.yml at v6.2.2 -->
<!-- Release notes generated using configuration in .github/release.yml at v6.2.2 -->
Full Changelog: https://github.com/vega/altair/compare/v6.2.1...v6.2.2
Full Changelog: v6.2.1...v6.2.2
<!-- Release notes generated using configuration in .github/release.yml at v6.2.1 -->
<!-- Release notes generated using configuration in .github/release.yml at v6.2.1 -->
Full Changelog: https://github.com/vega/altair/compare/v6.2.0...v6.2.1
Full Changelog: v6.2.0...v6.2.1
Nothing published for this version
Nothing published for this version
Nothing published for this version
<!-- Release notes generated using configuration in .github/release.yml at v6.1.0 -->
<!-- Release notes generated using configuration in .github/release.yml at v6.1.0 -->
There are many exciting improvements in this release! Read on for details and a big thanks to everyone who contributed :tada:
duckdb imports by @dangotbanned in https://github.com/vega/altair/pull/3971polars<1.38 pin by @dangotbanned in https://github.com/vega/altair/pull/3973addopts to testpaths by @dangotbanned in https://github.com/vega/altair/pull/3972narwhals>=2.4.0 by @dangotbanned in https://github.com/vega/altair/pull/3970ruff config, fix minor type issues by @alec-bike in https://github.com/vega/altair/pull/3967Full Changelog: https://github.com/vega/altair/compare/v6.0.0...v6.1.0
There are many exciting improvements in this release! Read on for details and a big thanks to everyone who contributed 🎉
duckdb imports by @dangotbanned in #3971polars<1.38 pin by @dangotbanned in #3973addopts to testpaths by @dangotbanned in #3972narwhals>=2.4.0 by @dangotbanned in #3970ruff config, fix minor type issues by @alec-bike in #3967Full Changelog: v6.0.0...v6.1.0
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
chore: Remove deprecated nw.from_native(..., strict=True) by @dangotbanned in https://github.com/vega/altair/pull/3811
<!-- Release notes generated using configuration in .github/release.yml at v6.0.0 -->
The Vega-Altair team is pleased to announce the release of version 6.0.0. Firstly, we are grateful for the many returning contributors (@franzhaas, @dangotbanned, @dsmedia, @joelostblom, @tempdata73, @mattijn, @jonmmease, @eitanlees, @kurtmckee, @MarcoGorelli), and a special shoutout to all the new contributors (@JasonnnW3000, @edmundmiller, @jannisko, @stanmart, @star1327p, @baldwint, @daizutabi, @azjps, @joaopalmeiro, @bobot). You are all awesome!
In short what is included with the version 6 release of Altair.
altair.datasets, lazily access to datasets from https://github.com/vega/vega-datasets.uv as part of the infrastructure modernization and now have automated weekly builds.We test all changes thoroughly, but nevertheless, if you encounter any issue or like to start a discussion. Please feel free!
vega-lite>=6 by @franzhaas in https://github.com/vega/altair/pull/3831ValidationError messages by @dangotbanned in https://github.com/vega/altair/pull/3735vega-lite to 5.21.0 by @dangotbanned in https://github.com/vega/altair/pull/3761user_rows in MaxRowsError message by @dangotbanned in https://github.com/vega/altair/pull/3768ChartType.data by @dangotbanned in https://github.com/vega/altair/pull/3740schemapi.py by @dangotbanned in https://github.com/vega/altair/pull/3751*(Datum|Value) in SchemaValidationError by @dangotbanned in https://github.com/vega/altair/pull/3750sphinx warnings by @dangotbanned in https://github.com/vega/altair/pull/3787eval_block incorrectly showed True as the default for strict by @MarcoGorelli in https://github.com/vega/altair/pull/3855.changed property optional in JupyterChart #3868 by @azjps in https://github.com/vega/altair/pull/3871alt.Chart() from int to float by @joaopalmeiro in https://github.com/vega/altair/pull/3888geopandas.read_file(...) warnings by @dangotbanned in https://github.com/vega/altair/pull/3795pyscript==2025.2.2 by @dangotbanned in https://github.com/vega/altair/pull/3797order and on in the param section by @joelostblom in https://github.com/vega/altair/pull/3629vegafusion by @dangotbanned in https://github.com/vega/altair/pull/3702TC006 fixes by @dangotbanned in https://github.com/vega/altair/pull/3706ruff, mypy warnings by @dangotbanned in https://github.com/vega/altair/pull/3717hatch, pip to uv in GitHub Actions by @dangotbanned in https://github.com/vega/altair/pull/3719pyright.ignore by @dangotbanned in https://github.com/vega/altair/pull/3724mypy>=1.14.0 warnings by @dangotbanned in https://github.com/vega/altair/pull/3739UP006 warnings during codegen by @dangotbanned in https://github.com/vega/altair/pull/3746Vega project versioning by @dangotbanned in https://github.com/vega/altair/pull/3720pillow, allow >=10.0.0 by @dangotbanned in https://github.com/vega/altair/pull/37640.9.0 by @dangotbanned in https://github.com/vega/altair/pull/37660.9.2 lints by @dangotbanned in https://github.com/vega/altair/pull/3771needs-triage to new bug reports by @dangotbanned in https://github.com/vega/altair/pull/3769skip_requires_pyarrow compatible w/ pytest.param by @dangotbanned in https://github.com/vega/altair/pull/3772hatch to uv by @dangotbanned in https://github.com/vega/altair/pull/3723mypy [annotation-unchecked] on examples by @dangotbanned in https://github.com/vega/altair/pull/3775uv.lock by @dangotbanned in https://github.com/vega/altair/pull/3776mypy==1.15.0 by @dangotbanned in https://github.com/vega/altair/pull/3790narwhals>=1.25.1 by @dangotbanned in https://github.com/vega/altair/pull/3792ruff==0.9.5 by @dangotbanned in https://github.com/vega/altair/pull/3799narwhals>=1.26.0 by @dangotbanned in https://github.com/vega/altair/pull/3800narwhals>=1.27.1 by @dangotbanned in https://github.com/vega/altair/pull/3807nw.from_native(..., strict=True) by @dangotbanned in https://github.com/vega/altair/pull/3811_from_array_like by @dangotbanned in https://github.com/vega/altair/pull/3812exclude to extend-exclude by @dangotbanned in https://github.com/vega/altair/pull/3813vega-embed==7 by @franzhaas in https://github.com/vega/altair/pull/3829typos and codespell against the codebase by @kurtmckee in https://github.com/vega/altair/pull/3840ipython[kernel] dependency by @dangotbanned in https://github.com/vega/altair/pull/3861Full Changelog: https://github.com/vega/altair/compare/v5.5.0...v6.0.0
Nothing published for this version
This release deprecates the alt.themes ThemeRegistry object and replaces it with an improved theme API in the new alt.theme module. See the updated Ch…
The Vega-Altair team is pleased to announce the release of version 5.5.0. This version introduces several exciting new features and enhancements including a revamped theme system, a new renderer optimized for screen readers, and numerous type system updates that improve auto-completion and make it easier to integrate Altair into larger typed programs.
This release adds Python 3.13 and removes Python 3.8 support. It also includes a variety of documentation improvements and a range of important bug fixes.
Thanks to our maintainers (@binste, @dangotbanned, @joelostblom, @mattijn, and @jonmmease), returning contributors (@MarcoGorelli, @daylinmorgan, and @dsmedia), and first time contributors (@jpn--, @davidgroves, and @apoorvkh) for these improvements.
This release deprecates the alt.themes ThemeRegistry object and replaces it with an improved theme API in the new alt.theme module.
See the updated Chart Themes documentation for more information.
[!NOTE] Usage of the legacy
alt.themesregistry will be supported until version 6, but will now display a warning on first use.
alt.themes -> alt.theme by @dangotbanned in #3618@alt.theme.register decorator by @dangotbanned in #3526ThemeConfig (TypedDict) by @dangotbanned in #3536import altair as alt
import pandas as pd
data = pd.DataFrame({'x': [5, 3, 6, 7, 2],
'y': ['A', 'B', 'C', 'D', 'E']})
@alt.theme.register("my_little_theme", enable=True)
def custom_theme():
return alt.theme.ThemeConfig(
config={
"bar":{"color":"black"}
}
)
chart = alt.Chart(data).mark_bar().encode(
x='x',
y='y',
)
chart # enable default using `alt.theme.enable("default")`
<img src="https://github.com/user-attachments/assets/9b5e58fd-e89f-42fe-8d5b-32d9b1a3ee40" width="200">
<img src="https://github.com/user-attachments/assets/cc675694-8aa3-4a16-b248-69925e4a06e3" width="450">
This release integrates the Olli project to provide a chart renderer that augments chart visualizations with a keyboard-navigable structure accessible to screen readers.
olli renderer:import altair as alt
from vega_datasets import data
alt.renderers.enable("olli")
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
<img src="https://github.com/user-attachments/assets/49129d89-d077-437f-bfb6-0a9b89d58286" width="555">
Several improvements were made to Altair's expression and selection APIs:
expr method signatures, docs by @dangotbanned in #3600&, |, ~ on all ...Predicate classes by @dangotbanned in #3668datetime.(date|datetime) in Expression(s) by @dangotbanned in #3654datetime.(date|datetime) as a SchemaBase parameter by @dangotbanned in #3653float to IntoExpression alias by @dangotbanned in #3611.transform_filterimport altair as alt
from vega_datasets import data
source = data.population.url
chart = alt.Chart(source).mark_line().encode(
x="age:O",
y="sum(people):Q",
color="year:O"
).transform_filter(
~alt.FieldRangePredicate(field='year', range=[1900, 1960])
& (alt.datum.age <= 70)
)
chart
<img src="https://hackmd.io/_uploads/B1e5TuJQyx.png" width="350">
datetime.date for value in alt.selection_interval()import datetime
import altair as alt
from vega_datasets import data
source = data.unemployment_across_industries.url
dt_values = [datetime.date(2005, 1, 1), datetime.date(2009, 1, 1)]
brush = alt.selection_interval(
encodings=['x'],
value={"x": dt_values}
)
base = alt.Chart(source).mark_area(
color='goldenrod',
opacity=0.3
).encode(
x='yearmonth(date):T',
y='sum(count):Q',
)
background = base.add_params(brush)
selected = base.transform_filter(brush).mark_area(color='goldenrod')
background + selected
<img src="https://github.com/user-attachments/assets/2a44f811-7a57-4820-bb12-a1d0edf3e471" width="350">
predicates and constraints in Chart.transform_filterChart.transform_filter(*predicates, **constraints) by @dangotbanned in #3664constraints to simplify filter compositions:import altair as alt
from vega_datasets import data
source = data.population.url
chart = alt.Chart(source).mark_area().encode(
x="age:O",
y="sum(people):Q",
color="year:O"
).transform_filter(year=2000, sex=1)
chart
<img width="400" alt="image" src="https://github.com/user-attachments/assets/d52fe64b-8da3-4320-b333-f4cd83a98376">
@utils.use_signature issues by @dangotbanned in #3565dict annotations in channels.py by @dangotbanned in #3573locals() manipulation in Chart.encode by @dangotbanned in #3637alt.binding signature/docstring issues by @dangotbanned in #3671@skip_requires_pyarrow(requires_tzdata=True) by @dangotbanned in #3674mypy 1.12.0 errors by @dangotbanned in #3632test_api.py by @dangotbanned in #3592Several new examples were added to the documentation
alt.when().then().otherwise()import altair as alt
from vega_datasets import data
source = data.cars()
brush = alt.selection_interval()
chart = alt.Chart(source).mark_point().encode(
x='Horsepower',
y='Miles_per_Gallon',
color=alt.when(brush).then("Origin").otherwise(alt.value("lightgray"))
).add_params(
brush
)
chart
<img src="https://github.com/user-attachments/assets/c223a4a8-b8be-4ec1-bfb4-a46147b893b7" width="350">
import altair as alt
from vega_datasets import data
source = data.barley()
base = alt.Chart(source).encode(
x=alt.X('sum(yield):Q').stack('zero'),
y=alt.Y('site:O').sort('-x'),
text=alt.Text('sum(yield):Q', format='.0f')
)
bars = base.mark_bar(
tooltip=alt.expr("luminance(scale('color', datum.sum_yield))")
).encode(
color='sum(yield):Q'
)
text = base.mark_text(
align='right',
dx=-3,
color=alt.expr("luminance(scale('color', datum.sum_yield)) > 0.5 ? 'black' : 'white'")
)
bars + text
<img src="https://github.com/user-attachments/assets/e18f0fe8-d666-45df-9a04-90fcdd89353f" width="400">
origin and capitalize version commit by @joelostblom in #3559selection_point by @jpn-- in #3584selection_interval signature by @dangotbanned in #3662selection_point signature by @dangotbanned in #3663when-then-otherwise in User Guide by @dangotbanned in #3544mark_ methods by @dangotbanned in #3675SchemaValidationError traceback length by @dangotbanned in #3530Then annotations, autocompletion, docs by @dangotbanned in #3567SIM910 lint in display.py by @dangotbanned in #3613typings/ to .gitignore by @dangotbanned in #3560test-(slow|fast) options by @dangotbanned in #3555channels parameter in infer_encoding_types by @dangotbanned in #3564pyright by @dangotbanned in #3583pylance>=2024.9.1 by @dangotbanned in #3585typing_extensions python to 3.14 by @dangotbanned in #3593breaking, deprecation labels in changelog by @dangotbanned in #3623vl-convert-python to 1.7.0 by @dangotbanned in #3633vegafusion to mypy overrides by @dangotbanned in #3640schemapi comment by @dangotbanned in #3641Union aliases by @dangotbanned in #3656vl-convert-python to save dependency group by @apoorvkh in #3609channels.py overloads by @dangotbanned in #3659pyright-only warnings by @dangotbanned in #3676pyarrow-stubs to dev dependencies by @dangotbanned in #3679typing_extensions imports by @dangotbanned in #3683expr equivalence by @dangotbanned in #3624Full Changelog: https://github.com/vega/altair/compare/v5.4.1...v5.5.0
test: Fix deprecation warning from ipywidgets by @dangotbanned in https://github.com/vega/altair/pull/3557
<!-- Release notes generated using configuration in .github/release.yml at v5.4.1 -->
Literal aliases in channels overload(s) by @dangotbanned in https://github.com/vega/altair/pull/3535Literal(s) using "const" by @dangotbanned in https://github.com/vega/altair/pull/3538sphinx version constraint by @dangotbanned in https://github.com/vega/altair/pull/3541Then copy TypeError by @dangotbanned in https://github.com/vega/altair/pull/3553frame attribute by @dsmedia in https://github.com/vega/altair/pull/3537ruff>=0.6.0 by @dangotbanned in https://github.com/vega/altair/pull/3539m2r from mypy.overrides by @dangotbanned in https://github.com/vega/altair/pull/3540SchemaBase.copy by @dangotbanned in https://github.com/vega/altair/pull/3543schemapi.py by @dangotbanned in https://github.com/vega/altair/pull/3545chart_error_example__four_errors_hide_fourth by @dangotbanned in https://github.com/vega/altair/pull/3546test_chart_validation_errors test ids by @dangotbanned in https://github.com/vega/altair/pull/3551SchemaBase import by @dangotbanned in https://github.com/vega/altair/pull/3556ipywidgets by @dangotbanned in https://github.com/vega/altair/pull/3557Full Changelog: https://github.com/vega/altair/compare/v5.4.0...v5.4.1
feat(typing): @deprecated versioning, IDE highlighting by @dangotbanned in https://github.com/vega/altair/pull/3455
<!-- Release notes generated using configuration in .github/release.yml at v5.4.0 -->
toolz dependency by @dangotbanned in https://github.com/vega/altair/pull/3426alt.when for examples by @dangotbanned in https://github.com/vega/altair/pull/3427 and https://github.com/vega/altair/pull/3492alt.expr as a class that is understood by IDEs by @dangotbanned in https://github.com/vega/altair/pull/3466np.array, pd.Series, tuples, etc. by @dangotbanned in https://github.com/vega/altair/pull/3501carbon themes, provide autocomplete for themes by @dangotbanned in https://github.com/vega/altair/pull/3516Chart|LayerChart.encode, 1.32x speedup to infer_encoding_types by @dangotbanned in https://github.com/vega/altair/pull/3444Various typing improvements:
altair.typing module by @dangotbanned in https://github.com/vega/altair/pull/3515@deprecated versioning, IDE highlighting by @dangotbanned in https://github.com/vega/altair/pull/3455ChartType type and type guard is_chart_type. Change PurePath to Path type hints by @dangotbanned in https://github.com/vega/altair/pull/3420Map alias for Mapping[str, Any] by @dangotbanned in https://github.com/vega/altair/pull/3458typing.Optional import using ruff by @dangotbanned in https://github.com/vega/altair/pull/3460Literal aliases by @dangotbanned in https://github.com/vega/altair/pull/3469api.py by @dangotbanned in https://github.com/vega/altair/pull/3508mypy==1.11.0 issues in plugin_registry by @dangotbanned in https://github.com/vega/altair/pull/3487ruff rule PLR1701 by @dangotbanned in https://github.com/vega/altair/pull/3453@utils.use_signature formatting by @dangotbanned in https://github.com/vega/altair/pull/3450[arg-type] error in _deduplicate_enum_errors by @dangotbanned in https://github.com/vega/altair/pull/3475sphinx error "Code Execution failed:NameError: name 'format_locale' is not defined" by @dangotbanned in https://github.com/vega/altair/pull/3503sphinx default by @dangotbanned in https://github.com/vega/altair/pull/3512ruff, fix RUF031 by @dangotbanned in https://github.com/vega/altair/pull/3529Vega Theme Test in user guide by @dangotbanned in https://github.com/vega/altair/pull/3528alt.Optional doc by @dangotbanned in https://github.com/vega/altair/pull/3449CONTRIBUTING.md phrasing by @dangotbanned in https://github.com/vega/altair/pull/3477hatch guidance by @dangotbanned in https://github.com/vega/altair/pull/3461empty as a explicit condition kwarg by @dangotbanned in https://github.com/vega/altair/pull/3490altair_saver in save by @dangotbanned in https://github.com/vega/altair/pull/3510numpy 2 by @dangotbanned in https://github.com/vega/altair/pull/3438freq='H' in test_utils.py by @MarcoGorelli in https://github.com/vega/altair/pull/3446ruff rules, improve type annotations, improve ci performance by @dangotbanned in https://github.com/vega/altair/pull/3431Literal aliases in api by @dangotbanned in https://github.com/vega/altair/pull/3464toolz from [[tool.mypy.overrides]] by @dangotbanned in https://github.com/vega/altair/pull/3474SchemaBase repr by @dangotbanned in https://github.com/vega/altair/pull/3472_get_channels_mapping code by @dangotbanned in https://github.com/vega/altair/pull/3467ruff>=0.5.3 for PLW1514 fix by @dangotbanned in https://github.com/vega/altair/pull/3484ibis test on unsupported python version by @dangotbanned in https://github.com/vega/altair/pull/3486api.py by @dangotbanned in https://github.com/vega/altair/pull/3480sphinx theme option 'footer_items' by @dangotbanned in https://github.com/vega/altair/pull/3489is_undefined, OneOrSeq by @dangotbanned in https://github.com/vega/altair/pull/3491pydocstyle rules by @dangotbanned in https://github.com/vega/altair/pull/3493python-version=="3.9" to github action by @dangotbanned in https://github.com/vega/altair/pull/3498docstring-code-format comment by @dangotbanned in https://github.com/vega/altair/pull/3496numpy<=2.0.0 constraint by @dangotbanned in https://github.com/vega/altair/pull/3504m2r with updated mistune by @dangotbanned in https://github.com/vega/altair/pull/3506ipykernel optional dependency to dev group by @dangotbanned in https://github.com/vega/altair/pull/3507I001, TID252) rules by @dangotbanned in https://github.com/vega/altair/pull/3513sphinx, vl-convert-python by @dangotbanned in https://github.com/vega/altair/pull/3527C901 complexity by @dangotbanned in https://github.com/vega/altair/pull/3531vega-themes.json using vl_convert by @dangotbanned in https://github.com/vega/altair/pull/3523Full Changelog: https://github.com/vega/altair/compare/v5.3.0...v5.4.0
Fix anywidget deprecation warning
<!-- Release notes generated using configuration in .github/release.yml at v5.3.0 -->
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
<!-- This comment ends the list above, so that the rest of the list below goes back to normal linespacing -->
"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)https://github.com/altair-viz/altair/assets/4560057/1c2f9b53-b229-4391-bd62-80b1d1c3f5a9
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).<details><summary>Click to view all 44 PRs merged in this release</summary>
Chart.from_dict by @RobinL in https://github.com/altair-viz/altair/pull/3383all dependency group by @jonmmease in https://github.com/altair-viz/altair/pull/3354open_editor method by @joelostblom in https://github.com/altair-viz/altair/pull/3358</details>
Full Changelog: https://github.com/altair-viz/altair/compare/v5.2.0...v5.3.0
Update Vega-Lite from version 5.15.1 to version 5.16.3; see Vega-Lite Release Notes.
Support offline HTML export using vl-convert (#3251)
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.
Support saving charts as PDF files using the vl-convert export engine (#3244)
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.
Support converting charts to sharable Vega editor URLs with chart.to_url() (#3252)
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())
Pass 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!).
Vega-Altair is now a typed package, with type annotations for all public functions and classes and some of the internal code
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.
<details><summary>Click to view all 31 PRs merged in this release</summary>
python-version 3.12 by @mattijn in https://github.com/altair-viz/altair/pull/3235</details>
Full Changelog: https://github.com/altair-viz/altair/compare/v5.1.2...v5.2.0
Remove usage of deprecated Pandas parameter convert_dtypes by @binste in #3191
Update Vega-Lite from version 5.14.1 to version 5.15.1; see Vega-Lite Release Notes.
Use Facet/Trellis/Repeat consistently in the documentation by @NickCrews in #3180
Add tutorial on numpy tooltip images by @joelostblom #3202
https://github.com/altair-viz/altair/assets/4560057/3a9ae5d2-104a-4143-bef6-0d8a551c4393
convert_dtypes by @binste in #3191Full Changelog: https://github.com/altair-viz/altair/compare/v5.1.1...v5.1.2
Fix doctest and run doctests in altair module by @jonmmease in https://github.com/altair-viz/altair/pull/3175
Full Changelog: https://github.com/altair-viz/altair/compare/v5.1.0...v5.1.1
MAINT: Use importlib.metadata and packaging instead of deprecated pkg_resources by @binste in https://github.com/altair-viz/altair/pull/3133
The chart.transformed_data() method was added to extract transformed chart data
For 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.
Introduction of a new data transformer named 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.
A JupyterChart class was added to support accessing params and selections from Python
The 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.
Support for field encoding inference for objects that support the DataFrame Interchange Protocol
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.
A new transform method transform_extent is available
See 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
It is now possible to add configurable pixels-per-inch (ppi) metadata to saved and displayed PNG images
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)<details><summary>Click to view all 52 PRs merged for this release</summary>
</details>
Full Changelog: https://github.com/altair-viz/altair/compare/v5.0.1...v5.1.0
Deprecate .ref() instead of removing it by @mattijn in https://github.com/altair-viz/altair/pull/3063
.ref() instead of removing it by @mattijn in https://github.com/altair-viz/altair/pull/3063Full Changelog: https://github.com/altair-viz/altair/compare/v5.0.0...v5.0.1
Variable parameters are new to Altair, and while selections are not new, much of the old terminology has been deprecated. See Slider Cutoff for an app…
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.<details><summary>Click to view all 203 PRs merged in this release</summary>
iteritems with items by @joelostblom in https://github.com/altair-viz/altair/pull/2683altair_saver in build.yml as Github Actions tests are not passing anymore by @mattijn in https://github.com/altair-viz/altair/pull/2893alt.ExprRef capabilities in alt.expr() by @mattijn in https://github.com/altair-viz/altair/pull/2886type= by @joelostblom in https://github.com/altair-viz/altair/pull/2933stroke option by @joelostblom in https://github.com/altair-viz/altair/pull/2992selection_* docstrings with signatures by @dpoznik in https://github.com/altair-viz/altair/pull/3001ruff 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/3039jsonschema>=3.0 by @mattijn in https://github.com/altair-viz/altair/pull/3044</details>
Full Changelog: https://github.com/altair-viz/altair/compare/v4.2.0...v5.0.0
Nothing published for this version
Nothing published for this version
Nothing published for this version
Fix incompatibility with jsonschema < 4.5 which got introduced in Altair 4.2.1 (#2860).
Full Changelog: https://github.com/altair-viz/altair/compare/v4.2.1...v4.2.2
Replace iteritems with items due to pandas deprecation (#2683).
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).Update Vega-Lite from version 4.8.1 to version 4.17.0; see Vega-Lite Release Notes.
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).Nothing published for this version
Minimum Python version is now 3.6
strokeDash encoding can now be used to control line styles (Example: Multi Series Line Chartchart.save() now relies on altair_saver for more flexibility (#1943).chart.show() method replaces chart.serve(), and relies on altair_viewer to allow offline viewing of charts (#1988).Update Vega-Lite version to 4.0.2
The rangeStep argument to Scale and Chart.configure_scale is deprecated. instead, use chart.properties(width={"step": rangeStep}) or chart.configure_v…
# Altair Version 4.0.0 release
Version 4.0.0 is based on Vega-Lite version 4.0, which you can read about at https://github.com/vega/vega-lite/releases/tag/v4.0.0.
It is the first version of Altair to drop Python 2 compatibility, and is tested on Python 3.5 and newer.
## Enhancements
Support for interactive legends: ([Example](http://altair-viz.github.io/gallery/interactive_legend.html#gallery-interactive-legend)) <img height="200" alt="interactive legend" src="https://user-images.githubusercontent.com/781659/70592444-aec9fb00-1b8e-11ea-8bf7-199a16810e0d.gif">
Responsive chart width and height: ([Example](http://altair-viz.github.io/user_guide/customization.html#customization-chart-size)) <img height="200" alt="dynamic width" src="https://user-images.githubusercontent.com/781659/70593197-f782b380-1b90-11ea-8dcf-29282ea913b0.gif">
Bins responsive to selections: ([Example](http://altair-viz.github.io/gallery/histogram_responsive.html#gallery-histogram-responsive)) <img height="200" alt="responsive bin" src="https://user-images.githubusercontent.com/781659/70596199-19346880-1b9a-11ea-9dec-f9739c2b055a.gif">
New pivot transform: ([Example](http://altair-viz.github.io/user_guide/transform/pivot.html#user-guide-pivot-transform)) <img height="200" alt="pivot" src="https://user-images.githubusercontent.com/781659/70593369-a4f5c700-1b91-11ea-8655-9af0fbb3c149.gif">
New Regression transform: ([Example](http://altair-viz.github.io/user_guide/transform/regression.html#user-guide-regression-transform)) <img height="200" alt="regression" src="https://user-images.githubusercontent.com/781659/70592667-78d94680-1b8f-11ea-999e-4b37725793a8.png">
New LOESS transform: ([Example](http://altair-viz.github.io/user_guide/transform/loess.html#user-guide-loess-transform)) <img height="200" alt="loess" src="https://user-images.githubusercontent.com/781659/70592674-80005480-1b8f-11ea-99bf-9a36d5a50bd3.png">
New density transform: ([Example](http://altair-viz.github.io/user_guide/transform/density.html#user-guide-density-transform)) <img height="200" alt="density" src="https://user-images.githubusercontent.com/781659/70592687-87bff900-1b8f-11ea-842b-0a68f666e26b.png">
Image mark ([Example](http://altair-viz.github.io/user_guide/marks.html#image-mark)) <img height="200" alt="image" src="https://user-images.githubusercontent.com/781659/70592972-4b40cd00-1b90-11ea-93ca-81d49c196053.png">
New default html renderer, directly compatible with Jupyter Notebook and JupyterLab without the need for frontend extensions, as well as tools like nbviewer and nbconvert, and related notebook environments such as Zeppelin, Colab, Kaggle Kernels, and DataBricks. To enable the old default renderer, use: ` alt.renderers.enable('mimetype') `
Support per-corner radius for bar marks: ([Example](http://altair-viz.github.io/gallery/bar_rounded.html#gallery-bar-rounded)) <img height="300" alt="round-bar" src="https://user-images.githubusercontent.com/781659/70592714-99090580-1b8f-11ea-9304-03d3967d600c.png">
## Grammar Changes - Sort-by-field can now use the encoding name directly. So instead of
` alt.Y('y:Q', sort=alt.EncodingSortField('x_field', order='descending')) ` you can now use:: ` alt.Y('y:Q', sort="-x") `
The rangeStep argument to Scale and Chart.configure_scale is deprecated. instead, use chart.properties(width={"step": rangeStep}) or chart.configure_view(step=rangeStep).
align, center, spacing, and columns are no longer valid chart properties, but are moved to the encoding classes to which they refer.
Last release to support Python 2
released Nov 27, 2019
Last release to support Python 2
html renderer which works across frontends (#1793):G shorthand for geojson type (#1714)alt.sequence, alt.graticule,
alt.sphere() (#1667, #1687)__geo_interface__ (#1664)pickle and copy.deepcopy for chart objects (#1805)count() within transform_joinaggregate() (#1751)LayerChart.add_selection (#1794)project() method (#1717)Upgraded to Vega-Lite version 3.4 (See Vega-Lite 3.4 Release Notes).
Upgraded to Vega-Lite version 3.4 (See Vega-Lite 3.4 Release Notes).
Following are changes to Altair in addition to those that came with VL 3.4:
add_selection methods now delegate to sub-charts. Previously
they produced invalid charts (#1607)mark_*() methods removed from LayerChart (#1607)alt.LayerChart no longer has mark_*() methods, because they never
produced valid chart specifications) (#1607)Update includes full compatibility with version 3.3 of Vega-Lite.
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
Fix version info bug for HTML output and Colab & Kaggle renderers.
Fix version info bug for HTML output and Colab & Kaggle renderers.
Update to Vega-Lite 3.2 and Vega 5.3 & support all new features. See https://github.com/vega/vega-lite/releases/tag/v3.0.0 for Vega-Lite feature lists
Update to Vega-Lite 3.2 and Vega 5.3 & support all new features. See https://github.com/vega/vega-lite/releases/tag/v3.0.0 for Vega-Lite feature lists.
mark_boxplot(), mark_errorband(), mark_errorbar()transform_impute(), transform_joinaggregate(), transform_flatten() transform_fold(), transform_sample(), transform_stack()facet encoding that is similar to the row and column encoding, but allows for wrapped facetsalt.concat() function that is similar to alt.hconcat and alt.vconcat, but allows for more general wrapped concatenationcolumns keyword that allows wrapped faceting, repeating, and concatenation.tooltip mark configuration.Nothing published for this version
Several documentation cleanups & new examples
Includes many reworked examples in the example gallery.
Includes many reworked examples in the example gallery.
pandas.RangeIndex columns to strings (#1107)set_embed_options() method (#1203)chart.save() (#1134)fix missing JSON resource in altair.vega.v4
altair.vega.v4 (#1097)appropriate handling of InlineData in dataset consolidation
appropriate handling of InlineData in dataset consolidation (#1092)
fix admonition formatting in documentation page (#1094)
better handling of datetimes and timezones
better handling of datetimes and timezones (#1053)
all inline datasets are now converted to named datasets and stored at the
top level of the chart. This behavior can be disabled by setting
alt.data_transformers.consolidate_datasets = False (#951 & #1046)
more streamlined shorthand syntax for window transforms (#957)
alt.SortField renamed to alt.EncodingSortField and
alt.WindowSortField renamed to alt.SortField (#923)Fixed serialization of logical operands on selections within
transform_filter(): (#1075)
Fixed sphinx issue which embedded chart specs twice (#1088)
Avoid Selenium import until it is actually needed (#982)
add a scale_factor argument to chart.save() to allow the size/resolution of saved figures to be adjusted.
add a scale_factor argument to chart.save() to allow the
size/resolution of saved figures to be adjusted. (#918)
add an add_selection() method to add selections to charts (#832)
add chart.serve() and chart.display() methods for more flexiblity
in displaying charts (#831)
allow multiple fields to be passed to encodings such as tooltip
and detail (#830)
make timeUnit specifications more succinct, by parsing them in a manner
similar to aggregates (#866)
make to_json() and to_csv() have deterministic filenames, so in json
mode a single datasets will lead to a single on-disk serialization (#862)
make data the first argument for all compound chart types to match the
semantics of alt.Chart (this includes alt.FacetChart,
alt.LayerChart, alt.RepeatChart, alt.VConcatChart, and
alt.HConcatChart) (#895).
update vega-lite to version 2.4.3 (#836)
alt.MarkProperties is now alt.MarkConfigNothing published for this version
Complete rewrite of Altair, focused on supporting Vega-Lite 2.X
Complete rewrite of Altair, focused on supporting Vega-Lite 2.X
Nothing published for this version
Your coding agent can read these notes before it upgrades. Set up the MCP server →