diff --git a/.github/workflows/docbuild.yml b/.github/workflows/docbuild.yml index 914d2a111..788deac15 100644 --- a/.github/workflows/docbuild.yml +++ b/.github/workflows/docbuild.yml @@ -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: | diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cb89d42d5..59de7e4f7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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`. @@ -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 @@ -55,14 +47,6 @@ $ git switch -c ``` 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 @@ -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. @@ -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 @@ -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. + diff --git a/Makefile b/Makefile index 92669bbac..bacc76e32 100644 --- a/Makefile +++ b/Makefile @@ -4,7 +4,7 @@ install: python setup.py install test : - black . --check + black --diff --color . flake8 . --statistics python -m pytest --pyargs --doctest-modules tests diff --git a/README.md b/README.md index 3ca11f1a3..d4d70cfe0 100644 --- a/README.md +++ b/README.md @@ -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 @@ -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 @@ -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 @@ -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}, @@ -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). diff --git a/RELEASING.md b/RELEASING.md index 5c9d7cac5..c4b7626a0 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -1,8 +1,12 @@ -1. Make certain your branch is in sync with head +1. Create a new virtual environment following the instructions in `CONTRIBUTING.md`. + Make sure to also install all dependencies for the documentation including `altair_saver` + and uninstall `vl-convert-python` (this is not needed for normal contributions to the repo, see `CONTRIBUTING.md` for details). + +2. Make certain your branch is in sync with head $ git pull upstream master -2. Do a clean doc build: +3. Do a clean doc build: $ cd doc $ make clean-all @@ -12,55 +16,55 @@ Navigate to http://localhost:8000 and ensure it looks OK (particularly do a visual scan of the gallery thumbnails). -3. Make sure changes.rst is up to date for the release: compare against PRs +4. Make sure changes.rst is up to date for the release: compare against PRs merged since the last release & update top heading with release date. -4. Update version to, e.g. 2.0.0 +5. Update version to, e.g. 5.0.0 - in ``altair/__init__.py`` - in ``doc/conf.py`` (two places) -5. Double-check that all vega-lite/vega/vega-embed versions are up-to-date: +6. Double-check that all vega-lite/vega/vega-embed versions are up-to-date: - URLs in ``doc/conf.py`` - versions in ``altair/vegalite/v5/display.py`` -6. Commit change and push to master +7. Commit change and push to master: git add . -u - git commit -m "MAINT: bump version to 2.0.0" + git commit -m "MAINT: bump version to 5.0.0" git push upstream master -7. Tag the release: +8. Tag the release: - git tag -a v2.0.0 -m "version 2.0.0 release" + git tag -a v5.0.0 -m "version 5.0.0 release" git push upstream v2.0.0 -8. Build source & wheel distributions +9. Build source & wheel distributions: rm -r dist build # clean old builds & distributions python setup.py sdist # create a source distribution python setup.py bdist_wheel # create a universal wheel -9. publish to PyPI (Requires correct PyPI owner permissions) +10. publish to PyPI (Requires correct PyPI owner permissions): twine upload dist/* -10. build and publish docs (Requires write-access to altair-viz/altair-viz.github.io) +11. build and publish docs (Requires write-access to altair-viz/altair-viz.github.io): cd doc make clean-all make html bash sync_website.sh -11. update version to, e.g. 2.1.0dev +12. update version to, e.g. 5.1.0dev: - in ``altair/__init__.py`` - in ``doc/conf.py`` (two places) -12. add a new changelog entry for the unreleased version: +13. add a new changelog entry for the unreleased version: - Version 2.1.0 (unreleased) + Version 5.1.0 (unreleased) -------------------------- Enhancements @@ -70,15 +74,15 @@ Backward-Incompatible Changes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -13. Commit change and push to master +14. Commit change and push to master git add . -u - git commit -m "MAINT: bump version to 2.1.0dev" + git commit -m "MAINT: bump version to 5.1.0dev" git push upstream master -14. Double-check that a conda-forge pull request is generated from the updated +15. Double-check that a conda-forge pull request is generated from the updated pip package by the conda-forge bot (may take up to ~an hour): https://github.com/conda-forge/altair-feedstock/pulls -15. Copy changes.rst section into release notes within +16. Copy changes.rst section into release notes within https://github.com/altair-viz/altair/releases/, and publish the release. diff --git a/doc/getting_started/overview.rst b/doc/getting_started/overview.rst index 65bab900f..90f4ebb4f 100644 --- a/doc/getting_started/overview.rst +++ b/doc/getting_started/overview.rst @@ -44,3 +44,4 @@ concise grammar. installation starting getting_help + project_philosophy diff --git a/doc/getting_started/project_philosophy.rst b/doc/getting_started/project_philosophy.rst new file mode 100644 index 000000000..721cd5085 --- /dev/null +++ b/doc/getting_started/project_philosophy.rst @@ -0,0 +1,76 @@ +Project Philosophy +================== + +Many excellent plotting libraries exist in Python, including: + +* `Matplotlib `_ +* `Bokeh `_ +* `Seaborn `_ +* `Lightning `_ +* `Plotly `_ +* `Pandas built-in plotting `_ +* `HoloViews `_ +* `VisPy `_ +* `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 to work with data, 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 `_ and the `Interactive Data +Lab's `_ +`Polestar `_ and +`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. + +You can find a more detailed comparison between Plotly and Altair in +`this StackOverflow answer `. + +Whence Vega-Altair? +------------------- + +The Vega project was named after the brightest star in the constellation Lyra; +nearby Altair is the `brightest star `_ +in the constellation Aquila, and along with Deneb and Vega forms +the northern-hemisphere asterism known as +the `Summer Triangle `_. \ No newline at end of file diff --git a/doc/requirements.txt b/doc/requirements.txt index efefc068c..97310dcbe 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -4,4 +4,5 @@ numpydoc pillow mistune<=0.8.4 pydata-sphinx-theme -geopandas \ No newline at end of file +geopandas +vl-convert-python \ No newline at end of file