Altair: Example Visualizations

[jakevdp]

In preparation for the Altair 2.0 release, we need some good example visualizations for the documentation! These could be everything from simple one-panel scatter and line plots, to more complicated layered or stacked plots, to more advanced interactive features.

Note that the v2 API is not finalized yet, and so another purpose of creating these is to find bugs in the current package as we prepare for release. If you find anything, please report it on the issues tracker!

I've started a folder for these examples in altair/vegalite/v2/examples/. You can treat simple_scatter.py as a template.

Every example should:

• have a descriptive docstring, which will eventually be extracted for the documentation website.
• define a chart variable with the main chart object (This will be used both in the unit tests to confirm that the example executes properly, and also eventually used to display the visualization on the documentation website).
• not make any external calls to download data within the script (i.e. don't use urllib). You can define your data directly within the example file, generate your data using pandas and numpy.random, or you can use data available in the vega_datasets package.

The easiest way to get started would be to adapt examples from the Vega-Lite example gallery. Or you can feel free to be creative and build your own visualizations.

Note that the new display architecture is still being built; for display troubleshooting please see the wiki page: https://github.com/altair-viz/altair/wiki/Display-Troubleshooting

We'll look forward to your pull requests!

[bdore]

I would be glad to contribute to this.

[jakevdp]

Great! Let me know if you need help getting started! And please feel free to use this issue as a forum for any questions you have about example creation, that way other potential contributors will benefit as well.

[kfk]

Hi Jake, this is cool and I also want to help out.

I think some directions on how to setup Altair would help. I cloned the master branch and installed with:

make

Then I tried to run your example and produce an html file

html = chart.to_html()

and I get the below. Maybe I am not supposed to run the latest version of Altair this way though, in that case a bit of direction would help.

Traceback (most recent call last): File "/home/k/env/lib/python3.5/site-packages/altair-2.0.0.dev0-py3.5.egg/altair/utils/schemapi.py", line 81, in __getattr__ return self._kwds[item] KeyError: to_html

During handling of the above exception, another exception occurred: Traceback (most recent call last): File "tmp.py", line 11, in <module> html = chart.to_html() File "/home/k/env/lib/python3.5/site-packages/altair-2.0.0.dev0-py3.5.egg/altair/utils/schemapi.py", line 83, in __getattr__ return super(SchemaBase, self).__getattr__(self, item) AttributeError: 'super' object has no attribute __getattr__'

[kanitw]

If anyone wants to create new "creative" examples that are not on the Vega-Lite gallery, please feel free to submit them to Vega-Lite repo too :)

[jakevdp]

@kfk – the to_html() code is disabled right now, and you should generally ignore all of the documentation at this point.

If you run JupyterLab, then copy the example code I linked to above, you should see the chart. If you're having issues with that, @ellisonbg should be able to help you out: he just revamped the whole display system.

[Dpananos]

I'm having some troubles. When I copy/paste the code, I am returned <VegaLite 2 object>, no chart.

I've also followed the recommended steps for when charts are not showing, found here

[jakevdp]

@Dpananos – hopefully @ellisonbg can help with this: he just updated all the display architecture.

Are you on JupyterLab or on Jupyter notebook?

Also, all the online documentation is all for 1.X and doesn't apply here.

[Dpananos]

@ellisonbg @jakevdp This occurs on both JupyterLab and Jupyter notebook.

[afonit]

@jakevdp , thanks for the invitation for examples.

I want to echo what @Dpananos said and show how I installed it in case that makes a difference.
I installed altair by creating a new conda invironment
then ran:
pip install git+https://github.com/altair-viz/altair/

and I get:

alt.__version__
'2.0.0dev'

So it looks like that is good to go.

When I use the example you provided above:

I also just get this returned:

Note, I am using jupyter notebook - not jupyterlab

[jakevdp]

There is a lab extension that you need to enable, I think. Hopefully @ellisonbg can weigh-in.

[jakevdp]

I think we need some docs on how to display plots within the new system... maybe I put out this invitation prematurely.

[jakevdp]

Can you update Jupyterlab to the latest release? I think it should work if you do that.

[jakevdp]

(Also, @ellisonbg I've been unable to get things working in the notebook myself)

[Dpananos]

@jakevdp Issue persists after updating.

demetri$ conda list jupyterlab
# Name                    Version                   Build  Channel
jupyterlab                0.31.8                   py36_0

I'll wait until @ellisonbg can comment on the issue. Still very eager to contribute

[jakevdp]

One last idea: try running jupyter labextension install @jupyterlab/vega3-extension and then restart JupyterLab.

[Dpananos]

@jakevdp That does it. Works in my env.

[domoritz]

Yeah, the Jupyter renderers package has the Vega 3 extension for Jupyter Lab: https://github.com/jupyterlab/jupyter-renderers/tree/master/packages/vega3-extension. We'll try to move it to Jupyter core soon.

[jakevdp]

OK, I added a wiki page to help people trouble-shoot: https://github.com/altair-viz/altair/wiki/Display-Troubleshooting. As the display mechanisms evolve, we can update the info there. Eventually that info can go into the docs on the website.

[eitanlees]

Do you want examples to end with interactive or are static plots ok?

[jakevdp]

Do you want examples to end with interactive or are static plots ok?

Either is fine

[afonit]

Should we also avoid using jupyter widgets?
When I first built the simple line_percent.py example, I had it running with a dropdown widget so it was easier to go through the different 'job' options.

I then removed it because I assumed that was a dependency that was not wanted in the examples - is that correct?

[domoritz]

@afonit You can bind the selection to get a dropdown in Vega-Lite itself. Then there is no need to use jupyter widgets.

[afonit]

@domoritz thanks, I will look into that.

[domoritz]

Here are the docs: https://vega.github.io/vega-lite/docs/bind.html

[jakevdp]

@afonit yes please avoid jupyter widgets, because these examples will be run via tests and displayed in docs that are outside of Jupyter.

[afonit]

as the api continues to get completed, does one only need to:
pip install git+https://github.com/altair-viz/altair/
to get the latest changes - or does that only install the latest tagged release?

For example, when I do that again it still says:
alt.version
'2.0.0dev'

To put this another way, when things are merged like this:
https://github.com/altair-viz/altair/pull/463#discussion_r170410192

All I have to do is pip install git+https://github.com/altair-viz/altair/ and I get them correct?

Just looking to understand so I can incorporate more into the examples.

[jakevdp]

I think that will work. That said, what I've been doing is just running the examples within the local git clone of the repository, so I can "git pull" and be up to date.

[afonit]

Thanks for the tips. If I could just verify to ensure I am not going about this terribly inefficiently.
(this is for the purpose of building out the examples)

A)
I have a conda environment setup where I have installed the dev version of altair by this command:
pip install git+https://github.com/altair-viz/altair/

B)
I then followed your instructions here:
https://www.youtube.com/watch?v=rgbCcBNZcdQ
to fork altair into my own github repo that I then cloned locally. Doing this I have been successfully adding in examples to the repo through the process shown in the video.

C)
to get copies of the latest examples that others have added, (looking at your last comment), I also need to do a direct clone of the altair repo (not my github fork), and just do "git pull's". I have started doing this.

I just wanted to make sure that this was the correct process and not too cumbersome. Googling around last night and this morning - it seems like Step C, that there is no way to get that github fork to update from the main altair repo - so it will gradually get more and more out of date over time. I guess at some point I would need to delete the fork and re-fork to get a fresher copy. Ultimately - I guess this part does may not matter since I am just doing examples and not touching other parts of the code base.

[jakevdp]

You can have a single clone of the repository that points to both your fork and the main package repository... those pointers to github are called "remotes" . So I would do this in your local clone:

$ git remote add upstream https://github.com/altair-viz/altair.git
$ git checkout master
$ git pull upstream master

And then you'll have all the updates in the master branch of your local fork. Note that git will complain if you've committed changes to your local master branch that are not on upstream (this is one reason it's good practice to never work directly on your master branch). Let me know if that's the case and I can help you trouble-shoot.

[afonit]

@jakevdp I think that gives me good context for where I am at. I will read up more to get a better understanding of what you have shown in your last post. Thanks again for taking the time to explain.

[hydrosquall]

Hi Team,

This question comes from trying to make a box plot (vega-lite )

I was wondering if there are any working example of using the aggregate feature of vega-lite in Altair.

I've seen a few examples of the Chart.transform_data method in the docs, and commented out in the v1 api here ( https://github.com/altair-viz/altair/blob/7724ce1eb10ec00487adf7156633a1c7969c6432/altair/vegalite/v1/api.py#L280 ), but it doesn't seem to be in the v2 api.py file.

edit: I'm reading the docs more carefully, and will try using the methods documented here before revisiting this. Looks like this should be doable without using transform_data.

final update: Ended up overcoming the issue, code is here: https://github.com/altair-viz/altair/pull/502

[Juice178]

Hi, I want to contribute to this project.
I have a similar problem @Dpananos has. Plots show up in JupyterLab, but they don't when running scripts using command line.
What is a source of this problem?

[Juice178]

@afonit Thank you for the info. Examples here are in Python scripts. Does it mean that I can write code in scripts and pull requests if it works in Jupyter Lab? I am really sorry about my little knowledge(I am new to open source)

[jakevdp]

Hi @Juice178, thanks for your interest and sorry that was unclear! The best way to view the visualizations is in JupyterLab. For example, if you type this in a cell (once JupyterLab is properly set up you'll see a chart:

import altair as alt
from vega_datasets import data

cars = data.cars()

chart = alt.Chart(cars).mark_point().encode(
    x='Horsepower',
    y='Miles_per_Gallon',
    color='Origin'
)

chart

JupyterLab displays whatever is on the last line of a cell, so having chart at the end is what makes it display.

The example scripts being created here are for the purpose of auto-generated HTML docs which I will build sometime soon. Notebooks don't play all that well with git version control, so what we're doing here is basically copying and pasting that code from Jupyterlab into a .py file for the sake of storing the example efficiently. From there, the unit test framework can automatically run the example and ensure that everything works, and the documentation generation script I'm working on will embed the code and plot into the docs.

So you'd take the above code and make an example script that looks something like this:

"""
Simple Scatter Plot
-------------------
This is a simple example scatter plot using the cars dataset.
"""
import altair as alt
from vega_datasets import data

cars = data.cars()

chart = alt.Chart(cars).mark_point().encode(
    x='Horsepower',
    y='Miles_per_Gallon',
    color='Origin'
)

Then you can add that file to your branch, and open a pull request. Github has some documentation on that here. If you'd rather see a short video demonstration of a Pull Request, I recorded a demo here.

I hope all that is clear!

[Juice178]

Thank you! I understand now

[jakevdp]

Wow... a week later we have almost 60 new examples! Thanks for the help everyone!

New examples are still welcome, but I'm going to close this issue because we're in pretty good shape at this point.