altair

Declarative statistical visualization library for Python

BSD-3-CLAUSE License

Downloads
22.7M
Stars
9K
Committers
169

Bot releases are hidden (Show)

altair - Version 5.3.0 Latest Release

Published by binste 7 months ago

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.

What's Changed

Enhancements

  • Add "jupyter" renderer which uses JupyterChart for rendering (#3283). See Displaying Altair Charts for more information.
  • Add embed_options argument to JupyterChart to allow customization of Vega Embed options (#3304)
  • Add offline support for JupyterChart and the new "jupyter" renderer. See JupyterChart - Offline Usage for more information.
  • Add a new section to documentation on dashboards which have support for Altair (#3299)
  • Support restrictive FIPS-compliant environment (#3291)
  • Simplify type-hints to improve the readability of the function signature and docstring (#3307)
  • Support installation of all optional dependencies via python -m pip install altair[all] and conda install altair-all -c conda-forge (#3354)
  • Add privacy friendly web-analytics for the documentation (#3350)
  • Additional gallery examples and documentation clarifications (#3233, #3266, #3276, #3282, #3298, #3299, #3323, #3334, #3324, #3340, #3350, #3353, #3357, #3362, #3363)

Bug Fixes

  • Fix error when embed_options are None (#3376)
  • Fix type hints for libraries such as Polars where Altair uses the dataframe interchange protocol (#3297)
  • Fix anywidget deprecation warning (#3364)
  • Fix handling of Date32 columns in arrow tables and Polars DataFrames (#3377)

Backward-Incompatible Changes

  • Changed hash function from md5 to a truncated sha256 non-cryptograhic hash (#3291)
  • Updated chart.show() method to invoke the active renderer rather than depend on altair_saver (Which was never updated for use with Altair 5) (#3379).

New Contributors

Release notes by pull requests

Full Changelog: https://github.com/altair-viz/altair/compare/v5.2.0...v5.3.0

altair - Version 4.0.1

Published by binste 7 months ago

Bug fixes

  • Update Vega-Lite version to 4.0.2
  • Fix issue with duplicate chart divs in HTML renderer (#1888)
altair - Version 3.1.0

Published by binste 7 months ago

Update includes full compatibility with version 3.3 of Vega-Lite.

Enhancements

  • 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.

Bug fixes

  • Make chart.serve() and chart.save() respect the data transformer setting (#1538)

  • Fixed a deserialization bug for certain chart specs in schemapi (#1543)

Backward-Incompatible Changes

  • 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

altair - Version 3.0.1

Published by binste 7 months ago

Fix version info bug for HTML output and Colab & Kaggle renderers.

altair - Version 2.4.1

Published by binste 7 months ago

Enhancements

  • Several documentation cleanups & new examples

Bug Fixes

  • Fix incompatibility with pandas version 0.24 (#1315)
altair - Version 2.3.0

Published by binste 7 months ago

Includes many reworked examples in the example gallery.

Enhancements

  • Better errors for non-string column names, as well as automatic conversion of pandas.RangeIndex columns to strings (#1107)
  • Renderers now have set_embed_options() method (#1203)
  • Added kaggle renderer & more HTML output options (#1123)

Maintenance

  • fix typing requirement in Python 3.6+ (#1185)
  • Added support & CI testing for Python 3.7 (#1008)

Bug fixes

  • Selection predicates now recognize all valid entries (#1143)
  • Python 2 support for chart.save() (#1134)
altair - Version 2.2.2

Published by binste 7 months ago

Bug Fixes

  • fix missing JSON resource in altair.vega.v4 (#1097)
altair - Version 2.2.1

Published by binste 7 months ago

Bug Fixes

  • appropriate handling of InlineData in dataset consolidation (#1092)

  • fix admonition formatting in documentation page (#1094)

altair - Version 2.0.0

Published by binste 7 months ago

Complete rewrite of Altair, focused on supporting Vega-Lite 2.X

altair - Version 1.2.1

Published by binste 7 months ago

This version of Altair is based on Vega-Lite 1.2.1.

Major additions

  • 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.

Bug fixes

  • Make sure default mark is a point (#344).
altair - Version 1.0.0

Published by binste 7 months ago

Initial release of Altair

altair - Version 5.2.0

Published by mattijn 11 months ago

What's Changed

Enhancements

  1. 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.


  1. 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.


  1. 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())

https://vega.github.io/editor/#/url/vega-lite/N4Igxg9gdgZglgcxALlANzgUwO4tJKAFzigFcJSBnAdTgBNCALFAZgAY2AacaYsiygAlMiRoVYcAvpO50AhoTl4QpAE4AbFCDGEADpWQB6Q2DpQAdACtKdTOrhpV5qJkKGougLaG0mBHIBaeUVKV0oAATQARnMAJgBOczZDYLkTOVVKK0poEBkQTwyAa2VCAE9dTC1dCBJxfMwoSDoSJFQedQhVZXg7Oi0AeVVEEhBucsqtKAhPEjlNfIAPHqx1fuQQQS7QmuxMbvGKqo2AR1I5IjhFYl887jKVvq0AWTh1TEoAfUrVT4BxeadKBjEATY4gM4XYjXBxVaTcAAklDAjEwhS0On0Rh8fjk5gQV0YpAARuY4BBDMjUYUcf4AvZCJgfABWcxRABs5hY2VykiAA


  1. 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!).


  1. 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.

Maintenance

  • Vega-Altair now uses ruff for maintaining code quality & consistency (#3243)
  • Vega-Altair is tested against Python 3.12 (#3235)

Bug Fixes

  • None

Backward-Incompatible Changes

  • None

Release Notes by Pull Request

New Contributors

Full Changelog: https://github.com/altair-viz/altair/compare/v5.1.2...v5.2.0

altair - Version 5.1.2

Published by joelostblom about 1 year ago

What's changed

  • 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

Bug Fixes

  • Remove usage of deprecated Pandas parameter convert_dtypes by @binste in #3191
  • Fix encoding type inference for boolean columns when pyarrow is installed by @jonmmease in #3210

Full Changelog: https://github.com/altair-viz/altair/compare/v5.1.1...v5.1.2

altair - Version 5.1.1

Published by mattijn about 1 year ago

What's Changed

Full Changelog: https://github.com/altair-viz/altair/compare/v5.1.0...v5.1.1

altair - Version 5.1.0

Published by mattijn about 1 year ago

What's Changed

Enhancements

  1. 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

image
Its now possible to call the chart.transformed_data method to extract a pandas DataFrame containing the transformed data.

chart.transformed_data()

image
This method is dependent on VegaFusion with the embed extras enabled.


  1. 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

image
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.


  1. 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

image
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)

image
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])

image
The JupyterChart class is dependent on AnyWidget. See a detailed overview in the new documentation page on JupyterChart Interactivity.


  1. 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

image
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

image
Vega-Altair support of the DataFrame Interchange Protocol is dependent on PyArrow.


  1. 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

image


  1. 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)

image

alt.renderers.enable("png", ppi=144) # default ppi is 72
chart

image

Bug Fixes

  • Don't call len on DataFrame Interchange Protocol objects (#3111)

Maintenance

  • Add support for new referencing logic in version 4.18 of the jsonschema package

Backward-Incompatible Changes

  • Drop support for Python 3.7 which is end-of-life (#3100)
  • Hard dependencies: Increase minimum required pandas version to 0.25 (#3130)
  • Soft dependencies: Increase minimum required vl-convert-python version to 0.13.0 and increase minimum required vegafusion version to 1.4.0 (#3163, #3160)

Release Notes by Pull Request

New Contributors

Full Changelog: https://github.com/altair-viz/altair/compare/v5.0.1...v5.1.0

altair - Version 5.0.1

Published by mattijn over 1 year ago

What's Changed

Full Changelog: https://github.com/altair-viz/altair/compare/v5.0.0...v5.0.1

altair - Version 5.0.0

Published by mattijn over 1 year ago

What's Changed

Enhancements

  • As described in the release notes for Vega-Lite 5.0.0, the primary change in this release of Altair is the introduction of parameters. There are two types of parameters, selection parameters and variable parameters. 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 application of variable parameters (#2528).
  • Grouped bar charts and jitter are now supported using offset channels, see Grouped Bar Chart with xOffset and Strip Plot Jitter.
  • 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.
  • Saving charts with HTML inline is now supported without having altair_saver installed (#2807).
  • The default chart width was changed from 400 to 300 (#2785).
  • Ordered pandas categorical data are now automatically encoded as sorted ordinal data (#2522)
  • The Title and Impute aliases were added for TitleParams and ImputeParams, respectively (#2732).
  • The documentation page has been revamped, both in terms of appearance and content.
  • More informative autocompletion by removing deprecated methods (#2814) and for editors that rely on type hints (e.g. VS Code) we added support for completion in method chains (#2846) and extended keyword completion to cover additional methods (#2920).
  • Substantially improved error handling. Both in terms of finding the more relevant error (#2842), and in terms of improving the formatting and clarity of the error messages (#2824, #2568, #2979, #3009).
  • Include experimental support for the DataFrame Interchange Protocol (through __dataframe__ attribute). This requires pyarrow>=11.0.0 (#2888).
  • Support data type inference for columns with special characters (#2905).
  • Responsive width support using width="container" when saving charts to html or displaying them with the default html renderer (#2867).

Grammar Changes

  • Channel options can now be set via a more convenient method-based syntax in addition to the previous attribute-based syntax. For example, instead of 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.
  • The selection keyword argument must in many cases be replaced by param (e.g., when specifying a filter transform).
  • The empty keyword argument for a selection parameter should be specified as True or False instead of all or none, respectively.
  • The init keyword argument for a parameter is deprecated; use value instead.

Bug Fixes

  • Displaying a chart not longer changes the shorthand syntax of the stored spec (#2813).
  • Fixed disable_debug_mode (#2851).
  • Fixed issue where the webdriver was not working with Firefox's geckodriver (#2466).
  • Dynamically determine the jsonschema validator to avoid issues with recent jsonschema versions (#2812).

Backward-Incompatible Changes

  • Colons in column names must now be escaped to remove any ambiguity with encoding types. You now need to write "column\:name" instead of "column:name" (#2824).
  • Removed the Vega (v5) wrappers and deprecate rendering in Vega mode (save Chart as Vega format is still allowed) (#2829).
  • Removed the Vega-Lite 3 and 4 wrappers (#2847).
  • Removed the deprecated datasets.py (#3010).
  • In regards to the grammar changes listed above, the old terminology will still work in many basic cases. On the other hand, if that old terminology gets used at a lower level, then it most likely will not work. For example, in the current version of Scatter Plot with Minimap, two instances of the key 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.
  • Removed the altair.sphinxext module (#2792). The altair-plot Sphinx directive is now part of the sphinxext-altair package.

Maintenance

  • Vega-Altair now uses hatch for package management.
  • Vega-Altair now uses ruff for linting.

Release Notes by Pull Request

New Contributors

Full Changelog: https://github.com/altair-viz/altair/compare/v4.2.0...v5.0.0

altair - Version 4.2.2

Published by mattijn over 1 year ago

Bug Fixes

  • 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

altair - Version 4.2.1

Published by mattijn over 1 year ago

Note: This version requires jsonschema>=4.5.0 see (https://github.com/altair-viz/altair/issues/2857).

Bug Fixes

  • Disable uri-reference format check in jsonsschema (#2771).
  • Replace iteritems with items due to pandas deprecation (#2683).

Maintenance

  • Add deprecation and removal warnings for Vega-Lite v3 wrappers and Vega v5 wrappers (#2843).
altair - Version 4.2.0

Published by jakevdp almost 3 years ago

Enhancements

  • Pie charts are now supported through the use of mark_arc. (Examples: eg. Pie Chart and Radial Chart)
  • Support for the 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)
  • Support for serialising pandas nullable data types for float data (#2399).
  • Automatically create an empty data object when Chart is called without a data parameter (#2515).
  • Allow the use of pathlib Paths when saving charts (#2355).
  • Support deepcopy for charts (#2403).

Bug Fixes

  • Fix to_dict() for nested selections (#2120).
  • Fix item access for expressions (#2099).