Skip to content

Commit

Permalink
Update and simplify README (#2774)
Browse files Browse the repository at this point in the history 
* Clarify in Getting Help that GH issues are for bugs and feature requests, not questions

* Remove section 'A Python API for statistical visualizations' as outdated regarding frontends and fully contained in documentation

* Remove mentions of traitlets package as no longer used. Update development sections and refer to documentation as readme gets stale quickly

* Deduplicate mentioning of tutorial notebooks. Some smaller improvements

* Deduplicate mentioning of tutorial notebooks. Some smaller improvements

* How to contribute to the documentation taken over from #1122

* Switch to recommending vl-convert-python for thumbnails. Minor language improvements

* Clarify that vl-convert-python is easier to build docs but altair_saver is required for deployment as one thumbnail cannot be generated otherwise

* Mention google group

* Apply suggestions from code review

Co-authored-by: Mattijn van Hoek <[email protected]>

* Update RELEASING.md

Co-authored-by: Mattijn van Hoek <[email protected]>

* Further clarify when to uninstall vl-convert-python

* Install vl-convert-python by default for documentation and clarify when it needs to be uninstalled in favor of altair_saver

* Apply suggestions from code review

Co-authored-by: Mattijn van Hoek <[email protected]>

* Update RELEASING.md

Co-authored-by: Mattijn van Hoek <[email protected]>

* Update black command to show diff

* Apply suggestions from code review

Co-authored-by: Joel Ostblom <[email protected]>

* Remove mention of google group

* Mention stackoverflow answer re Plotly vs. Altair

Co-authored-by: Luke Shulman <[email protected]>
Co-authored-by: Mattijn van Hoek <[email protected]>
Co-authored-by: Joel Ostblom <[email protected]>
  • Loading branch information
@binste @kindofluke
@mattijn @joelostblom
4 people authored Jan 5, 2023
1 parent 4932929 commit 8a71d2e
Show file tree
Hide file tree
Showing 8 changed files with 186 additions and 194 deletions.
1 change: 1 addition & 0 deletions .github/workflows/docbuild.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@ jobs:
pip install "selenium<4.3.0"
pip install altair_saver
pip install -r doc/requirements.txt
pip uninstall vl-convert-python --yes
pip install git+https://github.com/altair-viz/altair_viewer.git
- name: Run docbuild
run: |
Expand Down
79 changes: 53 additions & 26 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,23 +11,18 @@ visualization.
We are also seeking contributions of additional Jupyter notebook-based examples
in our separate GitHub repository: https://github.com/altair-viz/altair_notebooks.

The altair users mailing list can be found at
https://groups.google.com/forum/#!forum/altair-viz. If you are working on
Altair, you can talk to other developers in the `#altair` channel of the [Vega
slack](https://bit.ly/join-vega-slack).

## How To Contribute Code to Altair

### Setting Up Your Environment

Fork the Altair repository on GitHub and clone the fork to you local
Fork the Altair repository on GitHub and then clone the fork to you local
machine. For more details on forking see the [GitHub
Documentation](https://help.github.com/en/articles/fork-a-repo).
```
$ git clone https://github.com/YOUR-USERNAME/altair.git
```

To keep your fork up to date with changes in the this repo,
To keep your fork up to date with changes in this repo,
you can [use the fetch upstream button on GitHub](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork).

Now you can install the latest version of Altair locally using `pip`.
Expand All @@ -36,14 +31,11 @@ every time you open a new Python interpreter
(instead of having to reinstall the package each time).
```
$ cd altair/
$ python -m pip install -e .
```

You can now install the development requirements using
```
$ python -m pip install -r requirements_dev.txt
$ python -m pip install -e '.[dev]'
```

'[dev]' indicates that pip should also install the development requirements
which you can find in `requirements_dev.txt`

### Creating a Branch

Expand All @@ -55,14 +47,6 @@ $ git switch -c <branch-name>
```
With this branch checked-out, make the desired changes to the package.

Note that Altair code uses the [black](https://black.readthedocs.io/)
code formatter and [flake8](https://flake8.pycqa.org/en/latest/) linter
which you can apply to your modifications by running:
```
$ black --diff . # View changes
$ black . # Apply changes
$ flake8 . --statistics # View changes (fix manually)
```

### Testing your Changes

Expand All @@ -74,6 +58,9 @@ which includes a number of tests to validate the correctness of your code:
$ make test
```

This also runs the [black](https://black.readthedocs.io/)
code formatter and [flake8](https://flake8.pycqa.org/en/latest/) linter.

Study the output of any failed tests and try to fix the issues
before proceeding to the next section.

Expand All @@ -98,7 +85,18 @@ automatically shown in the PR.
Hopefully your PR will be answered in a timely manner and your contribution will
help others in the future.

## Adding Examples
## Documentation
Altair documentation is written in [reStructuredText](http://docutils.sourceforge.net/rst.html)
and compiled into html pages using [Sphinx](http://www.sphinx-doc.org/en/master/).
Contributing to the documentation requires some extra dependencies and
we have some conventions and plugins that are used to help navigate the docs and
generate great Altair visualizations.

Note that the [Altair website](https://altair-viz.github.io/)
is only updated when a new version is released so your contribution might not show
up for a while.

### Adding Examples

We are always interested in new examples contributed from the community. These
could be everything from simple one-panel scatter and line plots, to more
Expand Down Expand Up @@ -154,7 +152,36 @@ Some additional notes:
included then it should be referenced by URL, such as `source =
data.movies.url`. This is to ensure that Altair's automated test suite does
not depend on availability of external HTTP resources.

Note that examples shown on the [Altair website](https://altair-viz.github.io/)
are only updated when a new version is released so your new example might not show
up there for a while.

### Building the Documentation Locally
In addition to the development dependencies mentioned further above,
you will also need to install the dependencies for the documentation
listed in `docs/requirements.txt`. Note that `geopandas` might require you to first
install some other dependencies, see [their installation page](https://geopandas.org/en/stable/getting_started/install.html#installation)
for details.

```
pip install -r doc/requirements.txt
```

If you want to build the documentation so it can be published on the [official Altair website](https://altair-viz.github.io), you need to
additionally install [altair_saver](https://github.com/altair-viz/altair_saver/) and uninstall [vl-convert-python](https://github.com/vega/vl-convert/tree/main/vl-convert-python).
These packages are used to generate PNG thumbnails for the example gallery. If both are installed, `vl-convert-python` is used by default.
The reason for this is that `vl-convert-python` cannot create a thumbnail for the `isotype_emoji.py` example,
which is fine for normal contributions but not when creating a new version of the official documentation.

Once you have all the dependencies, you can build the documentation
using various commands defined in the Makefile.
From the `doc` folder, you can use `make help` to see all of the available commands
which control the type of documentation you want to generate.

Usually, you will want to run `make html` which will generate the documentation
in a sub folder `_build/html`. You can then view the documentation by running:

```
cd _build/html
python -m http.server
```

and then opening `http://localhost:8000` in your browser.

2 changes: 1 addition & 1 deletion Makefile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ install:
python setup.py install

test :
black . --check
black --diff --color .
flake8 . --statistics
python -m pytest --pyargs --doctest-modules tests

Expand Down
176 changes: 29 additions & 147 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,10 +7,6 @@
[![code style black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![JOSS Paper](https://joss.theoj.org/papers/10.21105/joss.01057/status.svg)](https://joss.theoj.org/papers/10.21105/joss.01057)
[![PyPI - Downloads](https://img.shields.io/pypi/dm/altair)](https://pypi.org/project/altair)
[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/altair-viz/altair_notebooks/master?urlpath=lab/tree/notebooks/Index.ipynb)
[![Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/altair-viz/altair_notebooks/blob/master/notebooks/Index.ipynb)

[https://altair-viz.github.io](https://altair-viz.github.io)

**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
Expand All @@ -19,10 +15,13 @@ simplicity produces beautiful and effective visualizations with a minimal amount
Granger](https://github.com/ellisonbg) in close collaboration with the [UW
Interactive Data Lab](https://idl.cs.washington.edu/).*

## Vega-Altair Documentation
## 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:

See [Vega-Altair's Documentation Site](https://altair-viz.github.io),
as well as Vega-Altair's [Tutorial Notebooks](https://github.com/altair-viz/altair_notebooks).
[![Binder](https://beta.mybinder.org/badge.svg)](https://beta.mybinder.org/v2/gh/altair-viz/altair_notebooks/master)
[![Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/altair-viz/altair_notebooks/blob/master/notebooks/Index.ipynb)

## Example

Expand Down Expand Up @@ -76,160 +75,47 @@ points & bars

![Vega-Altair Visualization Gif](https://raw.githubusercontent.com/altair-viz/altair/master/images/cars_scatter_bar.gif)


## Getting your Questions Answered

If you have a question that is not addressed in the documentation, there are several ways to ask:

- open a [Github Issue](https://github.com/altair-viz/altair/issues)
- post a [StackOverflow Question](https://stackoverflow.com/questions/tagged/altair) (be sure to use the `altair` tag)
- ask on the [Vega-Altair Google Group](https://groups.google.com/forum/#!forum/altair-viz)

We'll do our best to get your question answered

## A Python API for statistical visualizations

Vega-Altair provides a Python API for building statistical visualizations in a declarative
manner. By statistical visualization we mean:

* The **data source** is a `DataFrame` that consists of columns of different data types (quantitative, ordinal, nominal and date/time).
* The `DataFrame` is in a [tidy format](https://vita.had.co.nz/papers/tidy-data.pdf)
where the rows correspond to samples and the columns correspond to the observed variables.
* The data is mapped to the **visual properties** (position, color, size, shape,
faceting, etc.) using the group-by data transformation.

The Vega-Altair API contains no actual visualization rendering code but instead
emits JSON data structures following the
[Vega-Lite](https://github.com/vega/vega-lite) specification. The resulting
Vega-Lite JSON data can be rendered in the following user-interfaces:

* [Jupyter Notebook](https://github.com/jupyter/notebook) (by installing [ipyvega](https://github.com/vega/ipyvega)).
* [JupyterLab](https://github.com/jupyterlab/jupyterlab) (no additional dependencies needed).
* [nteract](https://github.com/nteract/nteract) (no additional dependencies needed).

## Features

* Carefully-designed, declarative Python API based on
[traitlets](https://github.com/ipython/traitlets).
* 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 the live Jupyter Notebook, JupyterLab, nteract, on GitHub and
[nbviewer](https://nbviewer.jupyter.org/).
* Export visualizations to PNG/SVG images, stand-alone HTML pages and the
* 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.
* Explore Vega-Altair with dozens of examples in the [Example Gallery](https://altair-viz.github.io/gallery/index.html)

## Installation
Vega-Altair can be installed with:
```bash
pip install altair
```

To use Vega-Altair for visualization, you need to install two sets of tools

1. The core Vega-Altair Package and its dependencies

2. The renderer for the frontend you wish to use (i.e. `Jupyter Notebook`,
`JupyterLab`, or `nteract`)

Vega-Altair can be installed with either ``pip`` or with ``conda``.
For full installation instructions, please see
https://altair-viz.github.io/getting_started/installation.html

## Example and tutorial notebooks

We maintain a separate Github repository of Jupyter Notebooks that contain an
interactive tutorial and examples:

https://github.com/altair-viz/altair_notebooks

To launch a live notebook server with those notebook using [binder](https://mybinder.org/) or
[Colab](https://colab.research.google.com), click on one of the following badges:

[![Binder](https://beta.mybinder.org/badge.svg)](https://beta.mybinder.org/v2/gh/altair-viz/altair_notebooks/master)
[![Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/altair-viz/altair_notebooks/blob/master/notebooks/Index.ipynb)

## Project philosophy

Many excellent plotting libraries exist in Python, including the main ones:

* [Matplotlib](https://matplotlib.org/)
* [Bokeh](https://bokeh.pydata.org/en/latest/)
* [Seaborn](https://seaborn.pydata.org/)
* [Lightning](https://github.com/lightning-viz/lightning)
* [Plotly](https://plot.ly/)
* [Pandas built-in plotting](https://pandas.pydata.org/pandas-docs/stable/visualization.html)
* [HoloViews](https://holoviews.org)
* [VisPy](https://vispy.org/)
* [pygg](https://www.github.com/sirrice/pygg)

Each library does a particular set of things well.

### User challenges

However, such a proliferation of options creates great difficulty for users
as they have to wade through all of these APIs to find which of them is the
best for the task at hand. None of these libraries are optimized for
high-level statistical visualization, so users have to assemble their own
using a mishmash of APIs. For individuals just learning data science, this
forces them to focus on learning APIs rather than exploring their data.

Another challenge is current plotting APIs require the user to write code,
even for incidental details of a visualization. This results in an unfortunate
and unnecessary cognitive burden as the visualization type (histogram,
scatterplot, etc.) can often be inferred using basic information such as the
columns of interest and the data types of those columns.

For example, if you are interested in the visualization of two numerical
columns, a scatterplot is almost certainly a good starting point. If you add
a categorical column to that, you probably want to encode that column using
colors or facets. If inferring the visualization proves difficult at times, a
simple user interface can construct a visualization without any coding.
[Tableau](https://www.tableau.com/) and the [Interactive Data
Lab's](https://idl.cs.washington.edu/)
[Polestar](https://github.com/vega/polestar) and
[Voyager](https://github.com/vega/voyager) are excellent examples of such UIs.

### Design approach and solution

We believe that these challenges can be addressed without the creation of yet
another visualization library that has a programmatic API and built-in
rendering. Vega-Altair's approach to building visualizations uses a layered design
that leverages the full capabilities of existing visualization libraries:

1. Create a constrained, simple Python API (Vega-Altair) that is purely declarative
2. Use the API (Vega-Altair) to emit JSON output that follows the Vega-Lite spec
3. Render that spec using existing visualization libraries

This approach enables users to perform exploratory visualizations with a much
simpler API initially, pick an appropriate renderer for their usage case, and
then leverage the full capabilities of that renderer for more advanced plot
customization.

We realize that a declarative API will necessarily be limited compared to the
full programmatic APIs of Matplotlib, Bokeh, etc. That is a deliberate design
choice we feel is needed to simplify the user experience of exploratory
visualization.
If you are using the conda package manager, the equivalent is:
```bash
conda install altair -c conda-forge
```

## Development install
For full installation instructions, please see [the documentation](https://altair-viz.github.io/getting_started/installation.html).

Instructions on how to install Vega-Altair for development can be found in
[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/altair-viz/altair/issues).

## Testing
## Development
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 test suite you must have [py.test](https://pytest.org/latest/) installed.
To run the tests, use

```
py.test --pyargs altair
pytest --doctest-modules altair
```
(you can omit the `--pyargs` flag if you are running the tests from a source checkout).

## Feedback and Contribution

See [`CONTRIBUTING.md`](https://github.com/altair-viz/altair/blob/master/CONTRIBUTING.md)
For information on how to contribute your developments back to the Vega-Altair repository, see
[`CONTRIBUTING.md`](https://github.com/altair-viz/altair/blob/master/CONTRIBUTING.md)

## Citing Vega-Altair

[![JOSS Paper](https://joss.theoj.org/papers/10.21105/joss.01057/status.svg)](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
Expand All @@ -248,7 +134,7 @@ If you use Vega-Altair in academic work, please consider citing https://joss.the
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
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},
Expand All @@ -261,7 +147,3 @@ Please additionally consider citing the [vega-lite](https://vega.github.io/vega-
publisher={IEEE}
}
```

## Whence Vega-Altair?

The Vega project was named after the brightest star in the constellation Lyra; nearby Altair is the [brightest star](https://en.wikipedia.org/wiki/Altair) in the constellation Aquila, and along with Deneb and Vega forms the northern-hemisphere asterism known as the [Summer Triangle](https://en.wikipedia.org/wiki/Summer_Triangle).
Loading

0 comments on commit 8a71d2e

Please sign in to comment.