{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "# Chart Configuration\n", "\n", "Altair provides a number of hooks to configure the look of your chart; we don't have time to go into all the available options here, but it is useful to know where and how such configuration settings can be accessed and explored.\n", "\n", "In general, there are two or three places where the look of a chart can be controlled, each with a greater priority than the last.\n", "\n", "1. **Top Level Chart Config**. At the top level of an Altair chart, you can specify configuration settings that will apply to every panel or layer in the chart.\n", "\n", "2. **Local Configuration Settings**. The top-level settings can be over-ridden locally, by specifying local configuration\n", "\n", "3. **Encoding Values**. If an encoding value is specified, it will take highest precedance, and override the other options.\n", "\n", "Let's see an example." ] }, { "cell_type": "code", "execution_count": 1, "metadata": {}, "outputs": [], "source": [ "import altair as alt" ] }, { "cell_type": "code", "execution_count": 2, "metadata": {}, "outputs": [], "source": [ "import numpy as np\n", "import pandas as pd\n", "np.random.seed(42)\n", "\n", "data = pd.DataFrame(np.random.randn(100, 2), columns=['x', 'y'])" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Example 1: Controlling Marker Properties\n", "\n", "Suppose you would like to control the color of the markers in a scatter plot: let's see each of the three options for doing this. We'll use a simple datasets of normally-distributed points:" ] }, { "cell_type": "code", "execution_count": 3, "metadata": {}, "outputs": [ { "data": { "text/html": [ "\n", "
\n", "" ], "text/plain": [ "alt.Chart(...)" ] }, "execution_count": 3, "metadata": {}, "output_type": "execute_result" } ], "source": [ "alt.Chart(data).mark_point().encode(\n", " x='x:Q',\n", " y='y:Q'\n", ")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Top-level configuration\n", "\n", "At the top level, Altair has a ``configure_mark()`` method that allows you to adjust a large number of configuration settings for marks in general, as well as a ``configure_point()`` property that specifically adjusts the properties of points.\n", "\n", "You can see the availale options in Jupyter in the documentation string, accessed with a question mark:" ] }, { "cell_type": "code", "execution_count": 4, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "\u001b[0;31mSignature:\u001b[0m\n", "\u001b[0malt\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0mChart\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0mconfigure_point\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0;34m\u001b[0m\n", "\u001b[0;34m\u001b[0m \u001b[0mself\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m\u001b[0m\n", "\u001b[0;34m\u001b[0m \u001b[0malign\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0mUndefined\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m\u001b[0m\n", "\u001b[0;34m\u001b[0m \u001b[0mangle\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0mUndefined\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m\u001b[0m\n", "\u001b[0;34m\u001b[0m \u001b[0maspect\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0mUndefined\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m\u001b[0m\n", "\u001b[0;34m\u001b[0m \u001b[0mbaseline\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0mUndefined\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m\u001b[0m\n", "\u001b[0;34m\u001b[0m \u001b[0mcolor\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0mUndefined\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m\u001b[0m\n", "\u001b[0;34m\u001b[0m \u001b[0mcornerRadius\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0mUndefined\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m\u001b[0m\n", "\u001b[0;34m\u001b[0m \u001b[0mcornerRadiusBottomLeft\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0mUndefined\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m\u001b[0m\n", "\u001b[0;34m\u001b[0m \u001b[0mcornerRadiusBottomRight\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0mUndefined\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m\u001b[0m\n", "\u001b[0;34m\u001b[0m \u001b[0mcornerRadiusTopLeft\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0mUndefined\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m\u001b[0m\n", "\u001b[0;34m\u001b[0m \u001b[0mcornerRadiusTopRight\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0mUndefined\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m\u001b[0m\n", "\u001b[0;34m\u001b[0m \u001b[0mcursor\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0mUndefined\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m\u001b[0m\n", "\u001b[0;34m\u001b[0m \u001b[0mdir\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0mUndefined\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m\u001b[0m\n", "\u001b[0;34m\u001b[0m \u001b[0mdx\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0mUndefined\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m\u001b[0m\n", "\u001b[0;34m\u001b[0m \u001b[0mdy\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0mUndefined\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m\u001b[0m\n", "\u001b[0;34m\u001b[0m \u001b[0mellipsis\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0mUndefined\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m\u001b[0m\n", "\u001b[0;34m\u001b[0m \u001b[0mfill\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0mUndefined\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m\u001b[0m\n", "\u001b[0;34m\u001b[0m \u001b[0mfillOpacity\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0mUndefined\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m\u001b[0m\n", "\u001b[0;34m\u001b[0m \u001b[0mfilled\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0mUndefined\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m\u001b[0m\n", "\u001b[0;34m\u001b[0m \u001b[0mfont\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0mUndefined\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m\u001b[0m\n", "\u001b[0;34m\u001b[0m \u001b[0mfontSize\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0mUndefined\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m\u001b[0m\n", "\u001b[0;34m\u001b[0m \u001b[0mfontStyle\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0mUndefined\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m\u001b[0m\n", "\u001b[0;34m\u001b[0m \u001b[0mfontWeight\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0mUndefined\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m\u001b[0m\n", "\u001b[0;34m\u001b[0m \u001b[0mheight\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0mUndefined\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m\u001b[0m\n", "\u001b[0;34m\u001b[0m \u001b[0mhref\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0mUndefined\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m\u001b[0m\n", "\u001b[0;34m\u001b[0m \u001b[0minterpolate\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0mUndefined\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m\u001b[0m\n", "\u001b[0;34m\u001b[0m \u001b[0minvalid\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0mUndefined\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m\u001b[0m\n", "\u001b[0;34m\u001b[0m \u001b[0mlimit\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0mUndefined\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m\u001b[0m\n", "\u001b[0;34m\u001b[0m \u001b[0mlineBreak\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0mUndefined\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m\u001b[0m\n", "\u001b[0;34m\u001b[0m \u001b[0mlineHeight\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0mUndefined\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m\u001b[0m\n", "\u001b[0;34m\u001b[0m \u001b[0mopacity\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0mUndefined\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m\u001b[0m\n", "\u001b[0;34m\u001b[0m \u001b[0morder\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0mUndefined\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m\u001b[0m\n", "\u001b[0;34m\u001b[0m \u001b[0morient\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0mUndefined\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m\u001b[0m\n", "\u001b[0;34m\u001b[0m \u001b[0mradius\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0mUndefined\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m\u001b[0m\n", "\u001b[0;34m\u001b[0m \u001b[0mshape\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0mUndefined\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m\u001b[0m\n", "\u001b[0;34m\u001b[0m \u001b[0msize\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0mUndefined\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m\u001b[0m\n", "\u001b[0;34m\u001b[0m \u001b[0mstroke\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0mUndefined\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m\u001b[0m\n", "\u001b[0;34m\u001b[0m \u001b[0mstrokeCap\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0mUndefined\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m\u001b[0m\n", "\u001b[0;34m\u001b[0m \u001b[0mstrokeDash\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0mUndefined\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m\u001b[0m\n", "\u001b[0;34m\u001b[0m \u001b[0mstrokeDashOffset\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0mUndefined\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m\u001b[0m\n", "\u001b[0;34m\u001b[0m \u001b[0mstrokeJoin\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0mUndefined\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m\u001b[0m\n", "\u001b[0;34m\u001b[0m \u001b[0mstrokeMiterLimit\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0mUndefined\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m\u001b[0m\n", "\u001b[0;34m\u001b[0m \u001b[0mstrokeOpacity\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0mUndefined\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m\u001b[0m\n", "\u001b[0;34m\u001b[0m \u001b[0mstrokeWidth\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0mUndefined\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m\u001b[0m\n", "\u001b[0;34m\u001b[0m \u001b[0mtension\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0mUndefined\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m\u001b[0m\n", "\u001b[0;34m\u001b[0m \u001b[0mtext\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0mUndefined\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m\u001b[0m\n", "\u001b[0;34m\u001b[0m \u001b[0mtheta\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0mUndefined\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m\u001b[0m\n", "\u001b[0;34m\u001b[0m \u001b[0mtimeUnitBand\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0mUndefined\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m\u001b[0m\n", "\u001b[0;34m\u001b[0m \u001b[0mtimeUnitBandPosition\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0mUndefined\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m\u001b[0m\n", "\u001b[0;34m\u001b[0m \u001b[0mtooltip\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0mUndefined\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m\u001b[0m\n", "\u001b[0;34m\u001b[0m \u001b[0mwidth\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0mUndefined\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m\u001b[0m\n", "\u001b[0;34m\u001b[0m \u001b[0mx\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0mUndefined\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m\u001b[0m\n", "\u001b[0;34m\u001b[0m \u001b[0mx2\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0mUndefined\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m\u001b[0m\n", "\u001b[0;34m\u001b[0m \u001b[0my\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0mUndefined\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m\u001b[0m\n", "\u001b[0;34m\u001b[0m \u001b[0my2\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0mUndefined\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m\u001b[0m\n", "\u001b[0;34m\u001b[0m \u001b[0;34m**\u001b[0m\u001b[0mkwds\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m\u001b[0m\n", "\u001b[0;34m\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n", "\u001b[0;31mDocstring:\u001b[0m\n", "MarkConfig schema wrapper\n", "\n", "Mapping(required=[])\n", "\n", "Attributes\n", "----------\n", "\n", "align : :class:`Align`\n", " The horizontal alignment of the text or ranged marks (area, bar, image, rect, rule).\n", " One of ``\"left\"``, ``\"right\"``, ``\"center\"``.\n", "angle : float\n", " The rotation angle of the text, in degrees.\n", "aspect : boolean\n", " Whether to keep aspect ratio of image marks.\n", "baseline : :class:`TextBaseline`\n", " The vertical alignment of the text or ranged marks (area, bar, image, rect, rule).\n", " One of ``\"top\"``, ``\"middle\"``, ``\"bottom\"``.\n", "\n", " **Default value:** ``\"middle\"``\n", "color : anyOf(:class:`Color`, :class:`Gradient`)\n", " Default color.\n", "\n", " **Default value:** :raw-html:`■`\n", " ``\"#4682b4\"``\n", "\n", " **Note:**\n", "\n", "\n", " * This property cannot be used in a `style config\n", " `__.\n", " * The ``fill`` and ``stroke`` properties have higher precedence than ``color`` and\n", " will override ``color``.\n", "cornerRadius : float\n", " The radius in pixels of rounded rectangle corners.\n", "\n", " **Default value:** ``0``\n", "cornerRadiusBottomLeft : float\n", " The radius in pixels of rounded rectangle bottom left corner.\n", "\n", " **Default value:** ``0``\n", "cornerRadiusBottomRight : float\n", " The radius in pixels of rounded rectangle bottom right corner.\n", "\n", " **Default value:** ``0``\n", "cornerRadiusTopLeft : float\n", " The radius in pixels of rounded rectangle top right corner.\n", "\n", " **Default value:** ``0``\n", "cornerRadiusTopRight : float\n", " The radius in pixels of rounded rectangle top left corner.\n", "\n", " **Default value:** ``0``\n", "cursor : :class:`Cursor`\n", " The mouse cursor used over the mark. Any valid `CSS cursor type\n", " `__ can be used.\n", "dir : :class:`Dir`\n", " The direction of the text. One of ``\"ltr\"`` (left-to-right) or ``\"rtl\"``\n", " (right-to-left). This property determines on which side is truncated in response to\n", " the limit parameter.\n", "\n", " **Default value:** ``\"ltr\"``\n", "dx : float\n", " The horizontal offset, in pixels, between the text label and its anchor point. The\n", " offset is applied after rotation by the *angle* property.\n", "dy : float\n", " The vertical offset, in pixels, between the text label and its anchor point. The\n", " offset is applied after rotation by the *angle* property.\n", "ellipsis : string\n", " The ellipsis string for text truncated in response to the limit parameter.\n", "\n", " **Default value:** ``\"…\"``\n", "fill : anyOf(:class:`Color`, :class:`Gradient`, None)\n", " Default Fill Color. This has higher precedence than ``config.color``.\n", "\n", " **Default value:** (None)\n", "fillOpacity : float\n", " The fill opacity (value between [0,1]).\n", "\n", " **Default value:** ``1``\n", "filled : boolean\n", " Whether the mark's color should be used as fill color instead of stroke color.\n", "\n", " **Default value:** ``false`` for all ``point``, ``line``, and ``rule`` marks as well\n", " as ``geoshape`` marks for `graticule\n", " `__ data sources;\n", " otherwise, ``true``.\n", "\n", " **Note:** This property cannot be used in a `style config\n", " `__.\n", "font : string\n", " The typeface to set the text in (e.g., ``\"Helvetica Neue\"`` ).\n", "fontSize : float\n", " The font size, in pixels.\n", "fontStyle : :class:`FontStyle`\n", " The font style (e.g., ``\"italic\"`` ).\n", "fontWeight : :class:`FontWeight`\n", " The font weight.\n", " This can be either a string (e.g ``\"bold\"``, ``\"normal\"`` ) or a number ( ``100``,\n", " ``200``, ``300``, ..., ``900`` where ``\"normal\"`` = ``400`` and ``\"bold\"`` = ``700``\n", " ).\n", "height : float\n", " Height of the marks.\n", "href : string\n", " A URL to load upon mouse click. If defined, the mark acts as a hyperlink.\n", "interpolate : :class:`Interpolate`\n", " The line interpolation method to use for line and area marks. One of the following:\n", "\n", "\n", " * ``\"linear\"`` : piecewise linear segments, as in a polyline.\n", " * ``\"linear-closed\"`` : close the linear segments to form a polygon.\n", " * ``\"step\"`` : alternate between horizontal and vertical segments, as in a step\n", " function.\n", " * ``\"step-before\"`` : alternate between vertical and horizontal segments, as in a\n", " step function.\n", " * ``\"step-after\"`` : alternate between horizontal and vertical segments, as in a\n", " step function.\n", " * ``\"basis\"`` : a B-spline, with control point duplication on the ends.\n", " * ``\"basis-open\"`` : an open B-spline; may not intersect the start or end.\n", " * ``\"basis-closed\"`` : a closed B-spline, as in a loop.\n", " * ``\"cardinal\"`` : a Cardinal spline, with control point duplication on the ends.\n", " * ``\"cardinal-open\"`` : an open Cardinal spline; may not intersect the start or end,\n", " but will intersect other control points.\n", " * ``\"cardinal-closed\"`` : a closed Cardinal spline, as in a loop.\n", " * ``\"bundle\"`` : equivalent to basis, except the tension parameter is used to\n", " straighten the spline.\n", " * ``\"monotone\"`` : cubic interpolation that preserves monotonicity in y.\n", "invalid : enum('filter', None)\n", " Defines how Vega-Lite should handle marks for invalid values ( ``null`` and ``NaN``\n", " ).\n", "\n", "\n", " * If set to ``\"filter\"`` (default), all data items with null values will be skipped\n", " (for line, trail, and area marks) or filtered (for other marks).\n", " * If ``null``, all data items are included. In this case, invalid values will be\n", " interpreted as zeroes.\n", "limit : float\n", " The maximum length of the text mark in pixels. The text value will be automatically\n", " truncated if the rendered size exceeds the limit.\n", "\n", " **Default value:** ``0``, indicating no limit\n", "lineBreak : string\n", " A delimiter, such as a newline character, upon which to break text strings into\n", " multiple lines. This property will be ignored if the text property is array-valued.\n", "lineHeight : float\n", " The height, in pixels, of each line of text in a multi-line text mark.\n", "opacity : float\n", " The overall opacity (value between [0,1]).\n", "\n", " **Default value:** ``0.7`` for non-aggregate plots with ``point``, ``tick``,\n", " ``circle``, or ``square`` marks or layered ``bar`` charts and ``1`` otherwise.\n", "order : anyOf(None, boolean)\n", " For line and trail marks, this ``order`` property can be set to ``null`` or\n", " ``false`` to make the lines use the original order in the data sources.\n", "orient : :class:`Orientation`\n", " The orientation of a non-stacked bar, tick, area, and line charts.\n", " The value is either horizontal (default) or vertical.\n", "\n", "\n", " * For bar, rule and tick, this determines whether the size of the bar and tick\n", " should be applied to x or y dimension.\n", " * For area, this property determines the orient property of the Vega output.\n", " * For line and trail marks, this property determines the sort order of the points in\n", " the line\n", " if ``config.sortLineBy`` is not specified.\n", " For stacked charts, this is always determined by the orientation of the stack;\n", " therefore explicitly specified value will be ignored.\n", "radius : float\n", " Polar coordinate radial offset, in pixels, of the text label from the origin\n", " determined by the ``x`` and ``y`` properties.\n", "shape : string\n", " Shape of the point marks. Supported values include:\n", "\n", "\n", " * plotting shapes: ``\"circle\"``, ``\"square\"``, ``\"cross\"``, ``\"diamond\"``,\n", " ``\"triangle-up\"``, ``\"triangle-down\"``, ``\"triangle-right\"``, or\n", " ``\"triangle-left\"``.\n", " * the line symbol ``\"stroke\"``\n", " * centered directional shapes ``\"arrow\"``, ``\"wedge\"``, or ``\"triangle\"``\n", " * a custom `SVG path string\n", " `__ (For correct\n", " sizing, custom shape paths should be defined within a square bounding box with\n", " coordinates ranging from -1 to 1 along both the x and y dimensions.)\n", "\n", " **Default value:** ``\"circle\"``\n", "size : float\n", " Default size for marks.\n", "\n", "\n", " * For ``point`` / ``circle`` / ``square``, this represents the pixel area of the\n", " marks. For example: in the case of circles, the radius is determined in part by\n", " the square root of the size value.\n", " * For ``bar``, this represents the band size of the bar, in pixels.\n", " * For ``text``, this represents the font size, in pixels.\n", "\n", " **Default value:**\n", "\n", "\n", " * ``30`` for point, circle, square marks; width/height's ``step``\n", " * ``2`` for bar marks with discrete dimensions;\n", " * ``5`` for bar marks with continuous dimensions;\n", " * ``11`` for text marks.\n", "stroke : anyOf(:class:`Color`, :class:`Gradient`, None)\n", " Default Stroke Color. This has higher precedence than ``config.color``.\n", "\n", " **Default value:** (None)\n", "strokeCap : :class:`StrokeCap`\n", " The stroke cap for line ending style. One of ``\"butt\"``, ``\"round\"``, or\n", " ``\"square\"``.\n", "\n", " **Default value:** ``\"square\"``\n", "strokeDash : List(float)\n", " An array of alternating stroke, space lengths for creating dashed or dotted lines.\n", "strokeDashOffset : float\n", " The offset (in pixels) into which to begin drawing with the stroke dash array.\n", "strokeJoin : :class:`StrokeJoin`\n", " The stroke line join method. One of ``\"miter\"``, ``\"round\"`` or ``\"bevel\"``.\n", "\n", " **Default value:** ``\"miter\"``\n", "strokeMiterLimit : float\n", " The miter limit at which to bevel a line join.\n", "strokeOpacity : float\n", " The stroke opacity (value between [0,1]).\n", "\n", " **Default value:** ``1``\n", "strokeWidth : float\n", " The stroke width, in pixels.\n", "tension : float\n", " Depending on the interpolation type, sets the tension parameter (for line and area\n", " marks).\n", "text : :class:`Text`\n", " Placeholder text if the ``text`` channel is not specified\n", "theta : float\n", " Polar coordinate angle, in radians, of the text label from the origin determined by\n", " the ``x`` and ``y`` properties. Values for ``theta`` follow the same convention of\n", " ``arc`` mark ``startAngle`` and ``endAngle`` properties: angles are measured in\n", " radians, with ``0`` indicating \"north\".\n", "timeUnitBand : float\n", " Default relative band size for a time unit. If set to ``1``, the bandwidth of the\n", " marks will be equal to the time unit band step.\n", " If set to ``0.5``, bandwidth of the marks will be half of the time unit band step.\n", "timeUnitBandPosition : float\n", " Default relative band position for a time unit. If set to ``0``, the marks will be\n", " positioned at the beginning of the time unit band step.\n", " If set to ``0.5``, the marks will be positioned in the middle of the time unit band\n", " step.\n", "tooltip : anyOf(:class:`Value`, :class:`TooltipContent`, None)\n", " The tooltip text string to show upon mouse hover or an object defining which fields\n", " should the tooltip be derived from.\n", "\n", "\n", " * If ``tooltip`` is ``true`` or ``{\"content\": \"encoding\"}``, then all fields from\n", " ``encoding`` will be used.\n", " * If ``tooltip`` is ``{\"content\": \"data\"}``, then all fields that appear in the\n", " highlighted data point will be used.\n", " * If set to ``null`` or ``false``, then no tooltip will be used.\n", "\n", " See the `tooltip `__\n", " documentation for a detailed discussion about tooltip in Vega-Lite.\n", "\n", " **Default value:** ``null``\n", "width : float\n", " Width of the marks.\n", "x : anyOf(float, enum('width'))\n", " X coordinates of the marks, or width of horizontal ``\"bar\"`` and ``\"area\"`` without\n", " specified ``x2`` or ``width``.\n", "\n", " The ``value`` of this channel can be a number or a string ``\"width\"`` for the width\n", " of the plot.\n", "x2 : anyOf(float, enum('width'))\n", " X2 coordinates for ranged ``\"area\"``, ``\"bar\"``, ``\"rect\"``, and ``\"rule\"``.\n", "\n", " The ``value`` of this channel can be a number or a string ``\"width\"`` for the width\n", " of the plot.\n", "y : anyOf(float, enum('height'))\n", " Y coordinates of the marks, or height of vertical ``\"bar\"`` and ``\"area\"`` without\n", " specified ``y2`` or ``height``.\n", "\n", " The ``value`` of this channel can be a number or a string ``\"height\"`` for the\n", " height of the plot.\n", "y2 : anyOf(float, enum('height'))\n", " Y2 coordinates for ranged ``\"area\"``, ``\"bar\"``, ``\"rect\"``, and ``\"rule\"``.\n", "\n", " The ``value`` of this channel can be a number or a string ``\"height\"`` for the\n", " height of the plot.\n", "\u001b[0;31mFile:\u001b[0m ~/miniconda3/lib/python3.7/site-packages/altair/vegalite/v4/schema/core.py\n", "\u001b[0;31mType:\u001b[0m function\n" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "alt.Chart.configure_point?" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "This top-level configuration should be thought of as a chart theme: they are the default settings for the aesthetics of all chart elements.\n", "Let's use ``configure_point`` to set some properties of points:" ] }, { "cell_type": "code", "execution_count": 5, "metadata": {}, "outputs": [ { "data": { "text/html": [ "\n", "
\n", "" ], "text/plain": [ "alt.Chart(...)" ] }, "execution_count": 5, "metadata": {}, "output_type": "execute_result" } ], "source": [ "alt.Chart(data).mark_point().encode(\n", " x='x:Q',\n", " y='y:Q'\n", ").configure_point(\n", " size=200,\n", " color='red',\n", " filled=True\n", ")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Many local configurations are available; you can use Jupyter's tab-completion and help features to explore them\n", "\n", "```python\n", " alt.Chart.configure_ # then the TAB key to see available configurations\n", "```" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Local Mark Configuration\n", "\n", "Within the ``mark_point()`` method, you can pass local configurations that will override the top-level configuration settings.\n", "The arguments are the same as that of ``configure_mark``." ] }, { "cell_type": "code", "execution_count": 6, "metadata": {}, "outputs": [ { "data": { "text/html": [ "\n", "
\n", "" ], "text/plain": [ "alt.Chart(...)" ] }, "execution_count": 6, "metadata": {}, "output_type": "execute_result" } ], "source": [ "alt.Chart(data).mark_point(color='green', filled=False).encode(\n", " x='x:Q',\n", " y='y:Q'\n", ").configure_point(\n", " size=200,\n", " color='red',\n", " filled=True\n", ")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Notice here that the \"color\" and \"fill\" configurations are overridden by the local configurations, but the \"size\" remains the same as before." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Encoding Configuration\n", "\n", "Finally, the highest precedence setting is the \"encoding\" setting. Here let's set the color to \"steelblue\" within the encoding:" ] }, { "cell_type": "code", "execution_count": 7, "metadata": {}, "outputs": [ { "data": { "text/html": [ "\n", "
\n", "" ], "text/plain": [ "alt.Chart(...)" ] }, "execution_count": 7, "metadata": {}, "output_type": "execute_result" } ], "source": [ "alt.Chart(data).mark_point(color='green', filled=False).encode(\n", " x='x:Q',\n", " y='y:Q',\n", " color=alt.value('steelblue')\n", ").configure_point(\n", " size=200,\n", " color='red',\n", " filled=True\n", ")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Now this is a bit of a contrived example, but it's useful to help grasp the various places that properties of marks can be set." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Example 2: Chart and Axis Titles\n", "\n", "Chart and axis titles are set automatically based on the data source, but sometimes it is useful to change them.\n", "For example, here is a histogram of the above data:" ] }, { "cell_type": "code", "execution_count": 8, "metadata": {}, "outputs": [ { "data": { "text/html": [ "\n", "
\n", "" ], "text/plain": [ "alt.Chart(...)" ] }, "execution_count": 8, "metadata": {}, "output_type": "execute_result" } ], "source": [ "alt.Chart(data).mark_bar().encode(\n", " x=alt.X('x', bin=True),\n", " y=alt.Y('count()')\n", ")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "We can explicitly set the axis titles using the ``title`` argument to the encoding:" ] }, { "cell_type": "code", "execution_count": 9, "metadata": {}, "outputs": [ { "data": { "text/html": [ "\n", "
\n", "" ], "text/plain": [ "alt.Chart(...)" ] }, "execution_count": 9, "metadata": {}, "output_type": "execute_result" } ], "source": [ "alt.Chart(data).mark_bar().encode(\n", " x=alt.X('x', bin=True, title='binned x values'),\n", " y=alt.Y('count()', title='counts in x')\n", ")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Likewise, we can set the ``title`` property of the chart within the chart properties:" ] }, { "cell_type": "code", "execution_count": 10, "metadata": {}, "outputs": [ { "data": { "text/html": [ "\n", "
\n", "" ], "text/plain": [ "alt.Chart(...)" ] }, "execution_count": 10, "metadata": {}, "output_type": "execute_result" } ], "source": [ "alt.Chart(data).mark_bar().encode(\n", " x=alt.X('x', bin=True, title='binned x values'),\n", " y=alt.Y('count()', title='counts in x')\n", ").properties(\n", " title='A histogram'\n", ")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Example 3: Axis Properties\n", "\n", "If you would like to set the properties of the axes, including grid lines, you can use the encodings'``axis`` argument." ] }, { "cell_type": "code", "execution_count": 11, "metadata": {}, "outputs": [ { "data": { "text/html": [ "\n", "
\n", "" ], "text/plain": [ "alt.Chart(...)" ] }, "execution_count": 11, "metadata": {}, "output_type": "execute_result" } ], "source": [ "alt.Chart(data).mark_bar().encode(\n", " x=alt.X('x', bin=True, axis=alt.Axis(labelAngle=45)),\n", " y=alt.Y('count()', axis=alt.Axis(labels=False, ticks=False, title=None))\n", ")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Note that some of these values can be adjusted at the top-level configuration as well, if you want them to apply to the chart as a whole. For example:" ] }, { "cell_type": "code", "execution_count": 12, "metadata": {}, "outputs": [ { "data": { "text/html": [ "\n", "
\n", "" ], "text/plain": [ "alt.Chart(...)" ] }, "execution_count": 12, "metadata": {}, "output_type": "execute_result" } ], "source": [ "alt.Chart(data).mark_bar().encode(\n", " x=alt.X('x', bin=True),\n", " y=alt.Y('count()', axis=alt.Axis(labels=False, ticks=False, title=None))\n", ").configure_axisX(\n", " labelAngle=45\n", ")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Example 4: Scale properties & axis limits\n", "\n", "Each encoding also has a ``scale`` that allows you to adjust things like axis limits and other scale properties." ] }, { "cell_type": "code", "execution_count": 13, "metadata": {}, "outputs": [ { "data": { "text/html": [ "\n", "
\n", "" ], "text/plain": [ "alt.Chart(...)" ] }, "execution_count": 13, "metadata": {}, "output_type": "execute_result" } ], "source": [ "alt.Chart(data).mark_point().encode(\n", " x=alt.X('x:Q', scale=alt.Scale(domain=[-5, 5])),\n", " y=alt.Y('y:Q', scale=alt.Scale(domain=[-5, 5])),\n", ")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Note that if you shrink the scale to smaller than the range of the data, the data will extend beyond the scale by default:" ] }, { "cell_type": "code", "execution_count": 14, "metadata": {}, "outputs": [ { "data": { "text/html": [ "\n", "
\n", "" ], "text/plain": [ "alt.Chart(...)" ] }, "execution_count": 14, "metadata": {}, "output_type": "execute_result" } ], "source": [ "alt.Chart(data).mark_point().encode(\n", " x=alt.X('x:Q', scale=alt.Scale(domain=[-3, 1])),\n", " y=alt.Y('y:Q', scale=alt.Scale(domain=[-3, 1])),\n", ")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Not hiding data is a useful default in exploratory visualization, because it prevents you from inadvertently missing data points.\n", "\n", "If you would like the markers to be clipped beyond the range of the scales, you can set the ``clip`` property of marks:" ] }, { "cell_type": "code", "execution_count": 15, "metadata": {}, "outputs": [ { "data": { "text/html": [ "\n", "
\n", "" ], "text/plain": [ "alt.Chart(...)" ] }, "execution_count": 15, "metadata": {}, "output_type": "execute_result" } ], "source": [ "alt.Chart(data).mark_point(clip=True).encode(\n", " x=alt.X('x:Q', scale=alt.Scale(domain=[-3, 1])),\n", " y=alt.Y('y:Q', scale=alt.Scale(domain=[-3, 1])),\n", ")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Another useful approach is to instead \"clamp\" the data to the extremes of the scale, keeping it visible even when it is out of range:" ] }, { "cell_type": "code", "execution_count": 16, "metadata": {}, "outputs": [ { "data": { "text/html": [ "\n", "
\n", "" ], "text/plain": [ "alt.Chart(...)" ] }, "execution_count": 16, "metadata": {}, "output_type": "execute_result" } ], "source": [ "alt.Chart(data).mark_point().encode(\n", " x=alt.X('x:Q', scale=alt.Scale(domain=[-3, 1], clamp=True)),\n", " y=alt.Y('y:Q', scale=alt.Scale(domain=[-3, 1], clamp=True)),\n", ").interactive()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Example 5: Color Scales\n", "\n", "Sometimes it's useful to manually adjust a color scale used" ] }, { "cell_type": "code", "execution_count": 17, "metadata": {}, "outputs": [ { "data": { "text/html": [ "
\n", "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "
dateprecipitationtemp_maxtemp_minwindweather
02012-01-010.012.85.04.7drizzle
12012-01-0210.910.62.84.5rain
22012-01-030.811.77.22.3rain
32012-01-0420.312.25.64.7rain
42012-01-051.38.92.86.1rain
\n", "
" ], "text/plain": [ " date precipitation temp_max temp_min wind weather\n", "0 2012-01-01 0.0 12.8 5.0 4.7 drizzle\n", "1 2012-01-02 10.9 10.6 2.8 4.5 rain\n", "2 2012-01-03 0.8 11.7 7.2 2.3 rain\n", "3 2012-01-04 20.3 12.2 5.6 4.7 rain\n", "4 2012-01-05 1.3 8.9 2.8 6.1 rain" ] }, "execution_count": 17, "metadata": {}, "output_type": "execute_result" } ], "source": [ "from vega_datasets import data\n", "weather = data.seattle_weather()\n", "weather.head()" ] }, { "cell_type": "code", "execution_count": 18, "metadata": {}, "outputs": [ { "data": { "text/html": [ "\n", "
\n", "" ], "text/plain": [ "alt.Chart(...)" ] }, "execution_count": 18, "metadata": {}, "output_type": "execute_result" } ], "source": [ "alt.Chart(weather).mark_point().encode(\n", " x='date:T',\n", " y='temp_max:Q',\n", " color='weather:N'\n", ")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "You can change the color scheme by using the color scale property, and by referencing any of [Vega's named color schemes](https://vega.github.io/vega/docs/schemes/#reference):" ] }, { "cell_type": "code", "execution_count": 19, "metadata": {}, "outputs": [ { "data": { "text/html": [ "\n", "
\n", "" ], "text/plain": [ "alt.Chart(...)" ] }, "execution_count": 19, "metadata": {}, "output_type": "execute_result" } ], "source": [ "alt.Chart(weather).mark_point().encode(\n", " x='date:T',\n", " y='temp_max:Q',\n", " color=alt.Color('weather:N', scale=alt.Scale(scheme=\"dark2\"))\n", ")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Alternatively, you can create your own color scheme by specifying a color domain and range:" ] }, { "cell_type": "code", "execution_count": 20, "metadata": {}, "outputs": [ { "data": { "text/html": [ "\n", "
\n", "" ], "text/plain": [ "alt.Chart(...)" ] }, "execution_count": 20, "metadata": {}, "output_type": "execute_result" } ], "source": [ "colorscale = alt.Scale(domain=['sun', 'fog', 'drizzle', 'rain', 'snow'],\n", " range=['goldenrod', 'gray', 'lightblue', 'steelblue', 'midnightblue'])\n", "\n", "alt.Chart(weather).mark_point().encode(\n", " x='date:T',\n", " y='temp_max:Q',\n", " color=alt.Color('weather:N', scale=colorscale)\n", ")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Exercise: Adjusting Plots\n", "\n", "Take about 10 minutes now and practice adjusting the aesthetics of your plots.\n", "\n", "Use your favorite visualization from the previous exercise, and adjust the aesthetics of the plot:\n", "\n", "- customize the look of the marks (size, strokewidth, etc.)\n", "- change axes and plot titles\n", "- change the x and y limits\n", "\n", "Use tab-completion on ``alt.Chart.configure_`` to see the various configuration options, then use ``?`` to see the documentation on what the options do." ] } ], "metadata": { "kernelspec": { "display_name": "Python 3", "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.7.6" } }, "nbformat": 4, "nbformat_minor": 4 }