{ "cells": [ { "cell_type": "markdown", "id": "b30269d6-9c9d-4a1f-a5e2-95c94a4877d6", "metadata": {}, "source": [ "# Introduction to Altair\n", "\n", "## Before we start: Jupyter Notebooks\n", "\n", "- Made up of \"cells\" which can be Python, markdown, or with extensions, any language.\n", "- Cells execute individually, and can execute out of order. Always re-order cells to be logical and make use of comments and/or markdown cells to make your notebook a narrative.\n", "- Tip: Before submitting a notebook, restart the kernel and run all cells in order. (See Kernel menu for options.) Ensure that you didn't inadvertently break things.\n", "- Not particularly Git friendly as the contents of the notebook are stored in JSON. (Still keep them in Git! even if suboptimal better than losing work!)\n", "- An alternative is `marimo` notebooks, which fix a few of the above issues. Still new & there are some rough edges still so I'll be sticking with Jupyter.\n", "\n", "`uv run jupyter lab` or `uv run jupyter notebook` will start the local notebook server (Lab is a newer UI, Notebook is the traditional one). You may opt to use VS Code, but I personallyh find their interface for notebooks more confusing than helpful.\n", "\n", "### Style Addendum (for all assignments in this course)\n", "\n", "- Notebook style imports allowed/preferred.\n", "- Limited use of global variables permitted with useful names and comments.\n", "- Notebooks must execute sequentially!" ] }, { "cell_type": "markdown", "id": "MJUe", "metadata": {}, "source": [ "## Altair expects \"tidy\" data\n", "\n", "Altair expects our data to be [tidy](http://vita.had.co.nz/papers/tidy-data.html).\n", "\n", "- Each variable is a column.\n", "- Each observation is a row.\n", "- Each type of observational unit is a table.\n", "\n", "You may use `pandas` or `polars` DataFrames. \n", "Class examples will focus on pre-cleaned data, and I will use polars in examples, though rarely will what I show differ significantly in pandas." ] }, { "cell_type": "code", "execution_count": 18, "id": "Hbol", "metadata": {}, "outputs": [], "source": [ "# best to follow convention, \"notebook\" style imports are allowed/preferred\n", "import marimo as mo\n", "import altair as alt\n", "import polars as pl\n", "from pathlib import Path" ] }, { "cell_type": "code", "execution_count": 22, "id": "vblA", "metadata": {}, "outputs": [ { "data": { "text/html": [ "
\n", "shape: (12, 3)
statesession_start_yearnum_bills
stri64i64
"IL"201713616
"IL"201912760
"IL"202112847
"IL"202311951
"MI"20174818
………
"MI"20233424
"WI"20171820
"WI"20192264
"WI"20212618
"WI"20232656
" ], "text/plain": [ "shape: (12, 3)\n", "┌───────┬────────────────────┬───────────┐\n", "│ state ┆ session_start_year ┆ num_bills │\n", "│ --- ┆ --- ┆ --- │\n", "│ str ┆ i64 ┆ i64 │\n", "╞═══════╪════════════════════╪═══════════╡\n", "│ IL ┆ 2017 ┆ 13616 │\n", "│ IL ┆ 2019 ┆ 12760 │\n", "│ IL ┆ 2021 ┆ 12847 │\n", "│ IL ┆ 2023 ┆ 11951 │\n", "│ MI ┆ 2017 ┆ 4818 │\n", "│ … ┆ … ┆ … │\n", "│ MI ┆ 2023 ┆ 3424 │\n", "│ WI ┆ 2017 ┆ 1820 │\n", "│ WI ┆ 2019 ┆ 2264 │\n", "│ WI ┆ 2021 ┆ 2618 │\n", "│ WI ┆ 2023 ┆ 2656 │\n", "└───────┴────────────────────┴───────────┘" ] }, "execution_count": 22, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# Also OK, limited use of global variables.\n", "#\n", "# Avoid `df` though because that is a common parameter name and not helpful in a global context.\n", "# Also to avoid: `df2`, `df_pure`, `df_final_final_final_final_v4_v9`.\n", "\n", "# first let's load and look at a dataframe with three columns\n", "# there is an observation for each state legislature, showing how many bills they introduced in a given year\n", "bills = pl.read_csv(\"midwest_bills.csv\")\n", "\n", "# Having a dataframe or chart variable as the last line in a notebook cell will automatically display it.\n", "# Use sparingly, and typically only for final chart in your own work, but in tutorials I will show intermediate steps.\n", "bills" ] }, { "cell_type": "code", "execution_count": 4, "id": "bkHC", "metadata": {}, "outputs": [], "source": [ "# Let's make our own charts of this data, first we bind the data to a new chart object\n", "chart = alt.Chart(df)" ] }, { "cell_type": "code", "execution_count": 8, "id": "lEQa", "metadata": {}, "outputs": [ { "data": { "text/html": [ "\n", "\n", "
\n", "" ], "text/plain": [ "alt.Chart(...)" ] }, "execution_count": 8, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# we add a geometry, we'll start with a point (at this point *something* can be displayed, but it won't be useful)\n", "chart.mark_point()" ] }, { "cell_type": "code", "execution_count": 29, "id": "PKri", "metadata": {}, "outputs": [ { "data": { "text/html": [ "\n", "\n", "
\n", "" ], "text/plain": [ "alt.Chart(...)" ] }, "execution_count": 29, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# Example 1\n", "# We use encodings to map our data to particular dimensions.\n", "# Altair will make then make appropriate choices based upon the type of data.\n", "\n", "chart.mark_point().encode(\n", " y=\"state\",\n", " x=\"num_bills\"\n", ")" ] }, { "cell_type": "code", "execution_count": 10, "id": "SFPL", "metadata": {}, "outputs": [ { "data": { "text/html": [ "\n", "\n", "
\n", "" ], "text/plain": [ "alt.Chart(...)" ] }, "execution_count": 10, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# Example 2 - what happens when we try to add color?\n", "chart.mark_point().encode(\n", " alt.Y(\"state\"),\n", " alt.X(\"num_bills\"),\n", " alt.Color(\"session_start_year\"),\n", ")" ] }, { "cell_type": "code", "execution_count": 32, "id": "BYtC", "metadata": {}, "outputs": [ { "data": { "text/html": [ "\n", "\n", "
\n", "" ], "text/plain": [ "alt.Chart(...)" ] }, "execution_count": 32, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# Example 3\n", "# The prior example treated year as an Ordinal because it was numeric,\n", "# instead we would treat it as Nominal for this data.\n", "# We can use :Q, :O, :N, :T to mark the type that should be used.\n", "\n", "by_year = chart.mark_point().encode(\n", " alt.Y(\"state:N\"),\n", " alt.X(\"num_bills:Q\"),\n", " alt.Color(\"session_start_year:N\"),\n", ")\n", "\n", "# we're saving this one for later, so repeat the variable name to see it\n", "by_year" ] }, { "cell_type": "code", "execution_count": 34, "id": "RGSE", "metadata": {}, "outputs": [ { "data": { "text/html": [ "\n", "\n", "
\n", "" ], "text/plain": [ "alt.Chart(...)" ] }, "execution_count": 34, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# Example 4\n", "# Here we make a different chart from the same base data \n", "# by re-using our `chart` variable.\n", "#\n", "# We choose a different shape (parameters that don't need to vary can be passed into the mark_* functions)\n", "# We also use an aggregate function average(num_bills)\n", "\n", "avgs = chart.mark_point(shape=\"wedge\").encode(\n", " alt.Y(\"state:N\"),\n", " alt.X(\"average(num_bills)\"),\n", ")\n", "avgs" ] }, { "cell_type": "code", "execution_count": 36, "id": "Kclp", "metadata": {}, "outputs": [ { "data": { "text/html": [ "\n", "\n", "
\n", "" ], "text/plain": [ "alt.LayerChart(...)" ] }, "execution_count": 36, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# Example 5\n", "# We can combine compatible charts by using `+` to layer them.\n", "# There are other operators you'll encounter that allow placing charts side by side.\n", "by_year + avgs" ] }, { "cell_type": "code", "execution_count": 41, "id": "Hstk", "metadata": {}, "outputs": [ { "data": { "text/html": [ "\n", "\n", "
\n", "" ], "text/plain": [ "alt.LayerChart(...)" ] }, "execution_count": 41, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# Example 6\n", "# perhaps we don't want to use mark_point anymore, maybe a bar?\n", "bar_avgs = chart.mark_bar(color=\"#ccc\").encode(\n", " alt.Y(\"state\"),\n", " alt.X(\"average(num_bills)\"),\n", ")\n", "bar_avgs + by_year" ] }, { "cell_type": "code", "execution_count": 42, "id": "nWHF", "metadata": {}, "outputs": [ { "data": { "text/html": [ "\n", "\n", "
\n", "" ], "text/plain": [ "alt.LayerChart(...)" ] }, "execution_count": 42, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# Example 7\n", "# We can customize titles and other details by using `.title` and `.properties`\n", "# the latter sets chart-wide properties.\n", "\n", "final = chart.mark_point(shape=\"diamond\").encode(\n", " alt.Y(\"state:N\"),\n", " alt.X(\"num_bills:Q\"),\n", " alt.Color(\"session_start_year:N\").title(\"Session Year\"),\n", ") + chart.mark_bar(color=\"#70905050\").encode(\n", " alt.Y(\"state\"),\n", " alt.X(\"average(num_bills)\").title(\"Number of Bills Introduced\"),\n", ")\n", "final.properties(\n", " title='Midwest Bills by State',\n", " background='#f5f5dc'\n", ")" ] }, { "cell_type": "markdown", "id": "93b3a8bc-be56-452d-a443-7b4711e339cb", "metadata": {}, "source": [ "## Exercise\n", "\n", "Let's say we instead want to see if there are trends by year.\n", "Try and create a new chart that:\n", "- has year on X axis, and bills on Y\n", "- is print & colorblind friendly (using multiple channels for encoding state)\n", "- uses a custom color scale, not the default (to avoid confusion with the colors used in our earlier chart)\n", "\n", "Try completing this below, before continuing on to look at my version." ] }, { "cell_type": "code", "execution_count": 43, "id": "3506dd11-76ba-40b0-8e1f-2210dcd3defd", "metadata": {}, "outputs": [], "source": [ "# YOUR SOLUTION HERE" ] }, { "cell_type": "markdown", "id": "ZHCJ", "metadata": {}, "source": [ "### Altair User Guide / Next Steps\n", "\n", "See for details.\n", "\n", "You'll want to work your way through the recommended material at your own pace, which will help you learn the material much better than me reading library documentation to you would. :)\n", "\n", "**You aren't on your own**, we're here to help -- start with documentation and ask questions on Ed, in class, and in office hours.\n", "\n", "Once you've read the guide and worked through the assignment you will have the core ideas of Altair.\n", "\n", "The next steps towards mastery are using it a lot and asking questions to deepen understanding, *not leaning on GenAI too much*.\n", "\n", "You're reading a fairly small subset of the library's documentation. \n", "The remaining sections are useful as reference, and as you use Altair you will find your way to them as you ask yourself questions like \"how do I work with geospatial data\" or \"how can I combine these axes\"?\n", "\n", "It's likely the most common thing you will use the documentation for is \"what arguments can I pass to this?\"\n", "\n", "For that, use the [API Reference](https://altair-viz.github.io/user_guide/api.html) and find the class you're working with.\n", "\n", "Example:\n", "\n", "- Let's say we want to adjust the color scheme, start with \n", "- Note that it can take a scale, and click to \n", "- We find ourselves on Vega documentation, here before long. Vega documentation can be very helpful for understanding the options that are available, since Altair is an interface to those." ] }, { "cell_type": "code", "execution_count": 54, "id": "iLit", "metadata": {}, "outputs": [ { "data": { "text/html": [ "\n", "\n", "
\n", "" ], "text/plain": [ "alt.LayerChart(...)" ] }, "execution_count": 54, "metadata": {}, "output_type": "execute_result" } ], "source": [ "\n", "# one possible solution to the exercise\n", "\n", "color_scheme = alt.Scale(scheme=\"set2\")\n", "chart.mark_line().encode(\n", " alt.Y(\"num_bills\"),\n", " alt.X(\"session_start_year:N\"),\n", " alt.Color(\"state\", scale=color_scheme),\n", ") + chart.mark_point().encode(\n", " alt.Y(\"num_bills\").title(\"Bills Introduced\"),\n", " alt.X(\"session_start_year:N\").title(\"Session Year\"),\n", " alt.Color(\"state\", scale=color_scheme),\n", " alt.Shape(\"state\"),\n", ").properties(\n", " title='Midwest Bills by Session',\n", ")" ] }, { "cell_type": "code", "execution_count": null, "id": "b4a63b04-c8b0-4406-933e-973708c151f6", "metadata": {}, "outputs": [], "source": [] }, { "cell_type": "code", "execution_count": null, "id": "e6ca4883-fea8-49ac-ad7c-23168c69a118", "metadata": {}, "outputs": [], "source": [] } ], "metadata": { "kernelspec": { "display_name": "Python 3 (ipykernel)", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.10.15" } }, "nbformat": 4, "nbformat_minor": 5 }