256 lines
11 KiB
Text
256 lines
11 KiB
Text
![]() |
Metadata-Version: 2.3
|
||
|
Name: altair
|
||
|
Version: 5.5.0
|
||
|
Summary: Vega-Altair: A declarative statistical visualization library for Python.
|
||
|
Project-URL: Documentation, https://altair-viz.github.io
|
||
|
Project-URL: Source, https://github.com/vega/altair
|
||
|
Author: Vega-Altair Contributors
|
||
|
License: Copyright (c) 2015-2023, Vega-Altair Developers
|
||
|
All rights reserved.
|
||
|
|
||
|
Redistribution and use in source and binary forms, with or without
|
||
|
modification, are permitted provided that the following conditions are met:
|
||
|
|
||
|
* Redistributions of source code must retain the above copyright notice, this
|
||
|
list of conditions and the following disclaimer.
|
||
|
|
||
|
* Redistributions in binary form must reproduce the above copyright notice,
|
||
|
this list of conditions and the following disclaimer in the documentation
|
||
|
and/or other materials provided with the distribution.
|
||
|
|
||
|
* Neither the name of vega-altair nor the names of its
|
||
|
contributors may be used to endorse or promote products derived from
|
||
|
this software without specific prior written permission.
|
||
|
|
||
|
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
|
||
|
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
||
|
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
||
|
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
|
||
|
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
||
|
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
|
||
|
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
|
||
|
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
|
||
|
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
|
||
|
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
||
|
|
||
|
Keywords: declarative,interactive,json,statistics,vega-lite,visualization
|
||
|
Classifier: Development Status :: 5 - Production/Stable
|
||
|
Classifier: Environment :: Console
|
||
|
Classifier: Intended Audience :: Science/Research
|
||
|
Classifier: License :: OSI Approved :: BSD License
|
||
|
Classifier: Natural Language :: English
|
||
|
Classifier: Programming Language :: Python :: 3.9
|
||
|
Classifier: Programming Language :: Python :: 3.10
|
||
|
Classifier: Programming Language :: Python :: 3.11
|
||
|
Classifier: Programming Language :: Python :: 3.12
|
||
|
Classifier: Programming Language :: Python :: 3.13
|
||
|
Classifier: Typing :: Typed
|
||
|
Requires-Python: >=3.9
|
||
|
Requires-Dist: jinja2
|
||
|
Requires-Dist: jsonschema>=3.0
|
||
|
Requires-Dist: narwhals>=1.14.2
|
||
|
Requires-Dist: packaging
|
||
|
Requires-Dist: typing-extensions>=4.10.0; python_version < '3.14'
|
||
|
Provides-Extra: all
|
||
|
Requires-Dist: altair-tiles>=0.3.0; extra == 'all'
|
||
|
Requires-Dist: anywidget>=0.9.0; extra == 'all'
|
||
|
Requires-Dist: numpy; extra == 'all'
|
||
|
Requires-Dist: pandas>=1.1.3; extra == 'all'
|
||
|
Requires-Dist: pyarrow>=11; extra == 'all'
|
||
|
Requires-Dist: vega-datasets>=0.9.0; extra == 'all'
|
||
|
Requires-Dist: vegafusion[embed]>=1.6.6; extra == 'all'
|
||
|
Requires-Dist: vl-convert-python>=1.7.0; extra == 'all'
|
||
|
Provides-Extra: dev
|
||
|
Requires-Dist: duckdb>=1.0; extra == 'dev'
|
||
|
Requires-Dist: geopandas; extra == 'dev'
|
||
|
Requires-Dist: hatch>=1.13.0; extra == 'dev'
|
||
|
Requires-Dist: ipython[kernel]; extra == 'dev'
|
||
|
Requires-Dist: mistune; extra == 'dev'
|
||
|
Requires-Dist: mypy; extra == 'dev'
|
||
|
Requires-Dist: pandas-stubs; extra == 'dev'
|
||
|
Requires-Dist: pandas>=1.1.3; extra == 'dev'
|
||
|
Requires-Dist: polars>=0.20.3; extra == 'dev'
|
||
|
Requires-Dist: pyarrow-stubs; extra == 'dev'
|
||
|
Requires-Dist: pytest; extra == 'dev'
|
||
|
Requires-Dist: pytest-cov; extra == 'dev'
|
||
|
Requires-Dist: pytest-xdist[psutil]~=3.5; extra == 'dev'
|
||
|
Requires-Dist: ruff>=0.6.0; extra == 'dev'
|
||
|
Requires-Dist: types-jsonschema; extra == 'dev'
|
||
|
Requires-Dist: types-setuptools; extra == 'dev'
|
||
|
Provides-Extra: doc
|
||
|
Requires-Dist: docutils; extra == 'doc'
|
||
|
Requires-Dist: jinja2; extra == 'doc'
|
||
|
Requires-Dist: myst-parser; extra == 'doc'
|
||
|
Requires-Dist: numpydoc; extra == 'doc'
|
||
|
Requires-Dist: pillow<10,>=9; extra == 'doc'
|
||
|
Requires-Dist: pydata-sphinx-theme>=0.14.1; extra == 'doc'
|
||
|
Requires-Dist: scipy; extra == 'doc'
|
||
|
Requires-Dist: sphinx; extra == 'doc'
|
||
|
Requires-Dist: sphinx-copybutton; extra == 'doc'
|
||
|
Requires-Dist: sphinx-design; extra == 'doc'
|
||
|
Requires-Dist: sphinxext-altair; extra == 'doc'
|
||
|
Provides-Extra: save
|
||
|
Requires-Dist: vl-convert-python>=1.7.0; extra == 'save'
|
||
|
Description-Content-Type: text/markdown
|
||
|
|
||
|
# Vega-Altair <a href="https://altair-viz.github.io/"><img align="right" src="https://altair-viz.github.io/_static/altair-logo-light.png" height="50"></img></a>
|
||
|
|
||
|
[](https://github.com/vega/altair/actions?query=workflow%3Abuild)
|
||
|
[](https://www.mypy-lang.org)
|
||
|
[](https://joss.theoj.org/papers/10.21105/joss.01057)
|
||
|
[](https://pypi.org/project/altair)
|
||
|
|
||
|
**Vega-Altair** is a declarative statistical visualization library for Python. With Vega-Altair, you can spend more time understanding your data and its meaning. Vega-Altair's
|
||
|
API is simple, friendly and consistent and built on top of the powerful
|
||
|
[Vega-Lite](https://github.com/vega/vega-lite) JSON specification. This elegant
|
||
|
simplicity produces beautiful and effective visualizations with a minimal amount of code.
|
||
|
|
||
|
*Vega-Altair was originally developed by [Jake Vanderplas](https://github.com/jakevdp) and [Brian
|
||
|
Granger](https://github.com/ellisonbg) in close collaboration with the [UW
|
||
|
Interactive Data Lab](https://idl.cs.washington.edu/).*
|
||
|
*The Vega-Altair open source project is not affiliated with Altair Engineering, Inc.*
|
||
|
|
||
|
## Documentation
|
||
|
|
||
|
See [Vega-Altair's Documentation Site](https://altair-viz.github.io) as well as the [Tutorial Notebooks](https://github.com/altair-viz/altair_notebooks). You can
|
||
|
run the notebooks directly in your browser by clicking on one of the following badges:
|
||
|
|
||
|
[](https://beta.mybinder.org/v2/gh/altair-viz/altair_notebooks/master)
|
||
|
[](https://colab.research.google.com/github/altair-viz/altair_notebooks/blob/master/notebooks/Index.ipynb)
|
||
|
|
||
|
## Example
|
||
|
|
||
|
Here is an example using Vega-Altair to quickly visualize and display a dataset with the native Vega-Lite renderer in the JupyterLab:
|
||
|
|
||
|
```python
|
||
|
import altair as alt
|
||
|
|
||
|
# load a simple dataset as a pandas DataFrame
|
||
|
from vega_datasets import data
|
||
|
cars = data.cars()
|
||
|
|
||
|
alt.Chart(cars).mark_point().encode(
|
||
|
x='Horsepower',
|
||
|
y='Miles_per_Gallon',
|
||
|
color='Origin',
|
||
|
)
|
||
|
```
|
||
|
|
||
|

|
||
|
|
||
|
One of the unique features of Vega-Altair, inherited from Vega-Lite, is a declarative grammar of not just visualization, but _interaction_.
|
||
|
With a few modifications to the example above we can create a linked histogram that is filtered based on a selection of the scatter plot.
|
||
|
|
||
|
```python
|
||
|
import altair as alt
|
||
|
from vega_datasets import data
|
||
|
|
||
|
source = data.cars()
|
||
|
|
||
|
brush = alt.selection_interval()
|
||
|
|
||
|
points = 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
|
||
|
)
|
||
|
|
||
|
bars = alt.Chart(source).mark_bar().encode(
|
||
|
y='Origin',
|
||
|
color='Origin',
|
||
|
x='count(Origin)'
|
||
|
).transform_filter(
|
||
|
brush
|
||
|
)
|
||
|
|
||
|
points & bars
|
||
|
```
|
||
|
|
||
|

|
||
|
|
||
|
## Features
|
||
|
|
||
|
* Carefully-designed, declarative Python API.
|
||
|
* Auto-generated internal Python API that guarantees visualizations are type-checked and
|
||
|
in full conformance with the [Vega-Lite](https://github.com/vega/vega-lite)
|
||
|
specification.
|
||
|
* Display visualizations in JupyterLab, Jupyter Notebook, Visual Studio Code, on GitHub and
|
||
|
[nbviewer](https://nbviewer.jupyter.org/), and many more.
|
||
|
* Export visualizations to various formats such as PNG/SVG images, stand-alone HTML pages and the
|
||
|
[Online Vega-Lite Editor](https://vega.github.io/editor/#/).
|
||
|
* Serialize visualizations as JSON files.
|
||
|
|
||
|
## Installation
|
||
|
|
||
|
Vega-Altair can be installed with:
|
||
|
```bash
|
||
|
pip install altair
|
||
|
```
|
||
|
|
||
|
If you are using the conda package manager, the equivalent is:
|
||
|
```bash
|
||
|
conda install altair -c conda-forge
|
||
|
```
|
||
|
|
||
|
For full installation instructions, please see [the documentation](https://altair-viz.github.io/getting_started/installation.html).
|
||
|
|
||
|
## Getting Help
|
||
|
|
||
|
If you have a question that is not addressed in the documentation,
|
||
|
you can post it on [StackOverflow](https://stackoverflow.com/questions/tagged/altair) using the `altair` tag.
|
||
|
For bugs and feature requests, please open a [Github Issue](https://github.com/vega/altair/issues).
|
||
|
|
||
|
## Development
|
||
|
|
||
|
[](https://github.com/pypa/hatch)
|
||
|
[](https://github.com/astral-sh/ruff)
|
||
|
[](https://github.com/pytest-dev/pytest)
|
||
|
|
||
|
You can find the instructions on how to install the package for development in [the documentation](https://altair-viz.github.io/getting_started/installation.html).
|
||
|
|
||
|
To run the tests and linters, use
|
||
|
|
||
|
```bash
|
||
|
hatch test
|
||
|
```
|
||
|
|
||
|
For information on how to contribute your developments back to the Vega-Altair repository, see
|
||
|
[`CONTRIBUTING.md`](https://github.com/vega/altair/blob/main/CONTRIBUTING.md)
|
||
|
|
||
|
## Citing Vega-Altair
|
||
|
|
||
|
[](https://joss.theoj.org/papers/10.21105/joss.01057)
|
||
|
|
||
|
If you use Vega-Altair in academic work, please consider citing https://joss.theoj.org/papers/10.21105/joss.01057 as
|
||
|
|
||
|
```bib
|
||
|
@article{VanderPlas2018,
|
||
|
doi = {10.21105/joss.01057},
|
||
|
url = {https://doi.org/10.21105/joss.01057},
|
||
|
year = {2018},
|
||
|
publisher = {The Open Journal},
|
||
|
volume = {3},
|
||
|
number = {32},
|
||
|
pages = {1057},
|
||
|
author = {Jacob VanderPlas and Brian Granger and Jeffrey Heer and Dominik Moritz and Kanit Wongsuphasawat and Arvind Satyanarayan and Eitan Lees and Ilia Timofeev and Ben Welsh and Scott Sievert},
|
||
|
title = {Altair: Interactive Statistical Visualizations for Python},
|
||
|
journal = {Journal of Open Source Software}
|
||
|
}
|
||
|
```
|
||
|
Please additionally consider citing the [Vega-Lite](https://vega.github.io/vega-lite/) project, which Vega-Altair is based on: https://dl.acm.org/doi/10.1109/TVCG.2016.2599030
|
||
|
|
||
|
```bib
|
||
|
@article{Satyanarayan2017,
|
||
|
author={Satyanarayan, Arvind and Moritz, Dominik and Wongsuphasawat, Kanit and Heer, Jeffrey},
|
||
|
title={Vega-Lite: A Grammar of Interactive Graphics},
|
||
|
journal={IEEE transactions on visualization and computer graphics},
|
||
|
year={2017},
|
||
|
volume={23},
|
||
|
number={1},
|
||
|
pages={341-350},
|
||
|
publisher={IEEE}
|
||
|
}
|
||
|
```
|