{
"cells": [
{
"cell_type": "raw",
"metadata": {
"raw_mimetype": "text/restructuredtext"
},
"source": [
".. _color-mapping:\n",
"\n",
"Color Mapping\n",
"=============\n",
"\n",
"Color mapping is the process of mapping values in your data to colors in a plot. It allows you to increase the dimensionality of a graphic - for example, adding a third dimension to the two-dimensional x, y coordinates in a scatterplot. Good color mapping choices can reveal or emphasize patterns in your data while poor choices will obscure them, making color mapping an essential part of the Toyplot API.\n",
"\n",
"If you haven't already, see :ref:`colors` for information on basic color management in Toyplot for creating and manipulating color values, color palettes, and color maps.\n",
"\n",
"Mapping Data to Color\n",
"---------------------\n",
"\n",
"There are a few decisions to make whenever you map colors in Toyplot:\n",
"\n",
"First, what is the cardinality of your data? Will you be specifying:\n",
"\n",
"* A constant color?\n",
"* Per-series colors?\n",
"* Per-datum colors?\n",
"\n",
"Second, for per-series or per-datum colors, will you specify:\n",
"\n",
"* A custom palette?\n",
"* Explicit colors?\n",
"* Scalar values that are mapped to colors?\n",
"\n",
"Third, if you choose to map scalars, will you provide:\n",
"\n",
"* Just scalar values?\n",
"* Just a color map?\n",
"* Both scalar values and a color map?\n",
"\n",
"We will examine all of these options in the examples that follow. To begin, let's create some random data series to use in our sample figures:"
]
},
{
"cell_type": "code",
"execution_count": 1,
"metadata": {
"collapsed": true
},
"outputs": [],
"source": [
"import numpy\n",
"numpy.random.seed(1234)\n",
"\n",
"samples = numpy.linspace(0, 4 * numpy.pi, 100)\n",
"frequency = lambda: numpy.random.normal()\n",
"phase = lambda: numpy.random.normal()\n",
"amplitude = lambda: numpy.random.uniform(0.1, 1)\n",
"wave = lambda: numpy.sin(phase() + (frequency() * samples))\n",
"signal = lambda: amplitude() * (2 + wave())\n",
"\n",
"series = numpy.column_stack([signal() for i in range(10)])\n",
"single_series = series[:, 1]"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Next, we'll display the data without specifying any color information. Here is a plot with a single series:"
]
},
{
"cell_type": "code",
"execution_count": 2,
"metadata": {},
"outputs": [
{
"data": {
"text/html": [
"
"
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"toyplot.fill(series, baseline=\"stacked\", width=600, height=300);"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"These examples allow us to see the answers to the questions posed above: by default, Toyplot generates per-series colors, using the default palette:"
]
},
{
"cell_type": "code",
"execution_count": 4,
"metadata": {},
"outputs": [
{
"data": {
"text/html": [
"
"
],
"text/plain": [
""
]
},
"execution_count": 4,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"toyplot.color.Palette()"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"In the examples that follow, we will explore how to override these defaults."
]
},
{
"cell_type": "raw",
"metadata": {
"raw_mimetype": "text/restructuredtext"
},
"source": [
"Default Palettes\n",
"----------------\n",
"\n",
"First, let's specify an alternate palette to be used when assigning default per-series colors. The default color palette is a property of a coordinate system, so to change it we have to specify the palette when the coordinate system is created:"
]
},
{
"cell_type": "code",
"execution_count": 5,
"metadata": {},
"outputs": [
{
"data": {
"text/html": [
"
"
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"canvas = toyplot.Canvas(width=600, height=300)\n",
"axes = canvas.cartesian(palette=palette)\n",
"axes.fill(series, baseline=\"stacked\");"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Because the palette is a part of a coordinate system, it affects only those marks that you add to that system - if your plot contained multiple sets of axes, they can have any combination of default palettes that you like (although we always recommend that you find ways to use consistent color schemes in your plots!)\n",
"\n",
"In the examples that follow, we will begin to override the colors provided by the axes palettes on a per-mark basis."
]
},
{
"cell_type": "raw",
"metadata": {
"raw_mimetype": "text/restructuredtext"
},
"source": [
"Constant Colors\n",
"---------------\n",
"\n",
"Next, you can specify a single color value, which overrides the default palette and will be applied to all your data:"
]
},
{
"cell_type": "code",
"execution_count": 7,
"metadata": {},
"outputs": [
{
"data": {
"text/html": [
"
"
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"toyplot.fill(series, color=\"steelblue\", baseline=\"stacked\", width=600, height=300);"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"As you can see above, combining constant color and multiple series can obscure the series boundaries. In this case, you might use additional styling to make the boundaries visible again:"
]
},
{
"cell_type": "code",
"execution_count": 9,
"metadata": {},
"outputs": [
{
"data": {
"text/html": [
"
"
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"style = {\"stroke\": \"white\"}\n",
"toyplot.fill(series, color=\"steelblue\", style=style, baseline=\"stacked\", width=600, height=300);"
]
},
{
"cell_type": "raw",
"metadata": {
"raw_mimetype": "text/restructuredtext"
},
"source": [
"Of course, there are many ways that you could specify a constant color value. See :ref:`colors` for details.\n",
"\n",
"Per-Series Colors\n",
"-----------------\n",
"\n",
"More often than not, you will want to specify per-series colors to make the series in your data easy to differentiate - which is why Toyplot defaults to per-series colors. To specify per-series colors for any plot that contains :math:`N` series, you can use any of the following with the `color` argument:\n",
"\n",
"Alternate Color Maps\n",
"~~~~~~~~~~~~~~~~~~~~\n",
"\n",
"When you supply just a color map to the `color` argument, Toyplot applies it to a set of implicit color values in the range :math:`[0, N)` to generate colors for each of the :math:`N` series in the plot. This can create duplicate colors if a categorical map doesn't have enough colors in its palette, as in the following example:"
]
},
{
"cell_type": "code",
"execution_count": 10,
"metadata": {},
"outputs": [
{
"data": {
"text/html": [
"
"
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"style = {\"stroke\" : toyplot.color.black, \"stroke-width\":0.5}\n",
"toyplot.fill(series, color=colormap, style=style, baseline=\"stacked\", width=600, height=300);"
]
},
{
"cell_type": "markdown",
"metadata": {
"collapsed": true
},
"source": [
"A good way to avoid duplicates is to use a linear map instead of a categorical map - then, colors will be sampled across the full range of the palette without repetition, and assigned to each series:"
]
},
{
"cell_type": "code",
"execution_count": 12,
"metadata": {},
"outputs": [
{
"data": {
"text/html": [
"
"
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"toyplot.fill(series, color=colormap, style=style, baseline=\"stacked\", width=600, height=300);"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Scalar Values Plus Color Map\n",
"\n",
"If you want more control over the mapping, you can replace the implicit $[0, N)$ values provided by Toyplot with your own range of $N$ values to be mapped, passing a `(values, colormap)` tuple to `color`:"
]
},
{
"cell_type": "code",
"execution_count": 14,
"metadata": {},
"outputs": [
{
"data": {
"text/html": [
"
"
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"values = numpy.linspace(0, 1, series.shape[1]) ** 0.5\n",
"toyplot.fill(series, color=(values, colormap), style=style, baseline=\"stacked\", width=600, height=300);"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Scalar Values Alone\n",
"\n",
"As a special-case, if you supply just a set of $N$ scalar values to `color`, they will be mapped with a default diverging color map:"
]
},
{
"cell_type": "code",
"execution_count": 15,
"metadata": {},
"outputs": [
{
"data": {
"text/html": [
"
"
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"toyplot.fill(series, color=values, baseline=\"stacked\", width=600, height=300);"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Explicit Colors\n",
"\n",
"Finally, for complete control over color, you can bypass the mapping entirely, and provide a sequence of explicit color values, one per series. As an example, suppose you wanted to highlight one of the series in the following example:"
]
},
{
"cell_type": "code",
"execution_count": 16,
"metadata": {},
"outputs": [
{
"data": {
"text/html": [
"
"
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"colormap = toyplot.color.brewer.map(\"BlueGreenBrown\")\n",
"toyplot.fill(series, color=colormap, baseline=\"stacked\", width=600, height=300);"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Rather than manually create an explicit array of per-series colors from scratch, you can use :func:`toyplot.color.broadcast`:"
]
},
{
"cell_type": "code",
"execution_count": 17,
"metadata": {},
"outputs": [
{
"data": {
"text/html": [
"
"
],
"text/plain": [
"array([( 0. , 0.23529412, 0.18823529, 1.),\n",
" ( 0.02657952, 0.42135076, 0.38997821, 1.),\n",
" ( 0.27320261, 0.63921569, 0.6043573 , 1.),\n",
" ( 0.59477124, 0.84183007, 0.80392157, 1.),\n",
" ( 0.86056645, 0.93681917, 0.92592593, 1.),\n",
" ( 0.96296296, 0.93246187, 0.85185185, 1.),\n",
" ( 0.90457516, 0.81045752, 0.58169935, 1.),\n",
" ( 0.77690632, 0.56252723, 0.24618736, 1.),\n",
" ( 0.57124183, 0.33856209, 0.05446623, 1.),\n",
" ( 0.32941176, 0.18823529, 0.01960784, 1.)], \n",
" dtype=[('r', '"
],
"text/plain": [
"array([( 0. , 0.23529412, 0.18823529, 1.),\n",
" ( 0.02657952, 0.42135076, 0.38997821, 1.),\n",
" ( 1. , 0.92156863, 0.03921569, 1.),\n",
" ( 0.59477124, 0.84183007, 0.80392157, 1.),\n",
" ( 0.86056645, 0.93681917, 0.92592593, 1.),\n",
" ( 0.96296296, 0.93246187, 0.85185185, 1.),\n",
" ( 0.90457516, 0.81045752, 0.58169935, 1.),\n",
" ( 0.77690632, 0.56252723, 0.24618736, 1.),\n",
" ( 0.57124183, 0.33856209, 0.05446623, 1.),\n",
" ( 0.32941176, 0.18823529, 0.01960784, 1.)], \n",
" dtype=[('r', '"
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"toyplot.fill(series, color=colors, baseline=\"stacked\", width=600, height=300);"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Of course, you are free to generate color data from scratch, as a numpy array of CSS color strings, or a list containing an arbitrary sequence of CSS color strings, RGB, and RGBA tuples. This is useful when you have an explicit color scheme dictated by your data and you don't wish to create a Toyplot palette to match. For example:"
]
},
{
"cell_type": "code",
"execution_count": 20,
"metadata": {},
"outputs": [
{
"data": {
"text/html": [
"
"
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"colors = [\"crimson\", \"mediumseagreen\", \"royalblue\"]\n",
"toyplot.fill(series[:,:3], color=colors, baseline=\"stacked\", width=600, height=300);"
]
},
{
"cell_type": "raw",
"metadata": {
"raw_mimetype": "text/restructuredtext"
},
"source": [
"Per-Datum Colors\n",
"----------------\n",
"\n",
"For plot types that support it - such as bar plots and scatter plots - you can choose to map colors to individual datums instead of entire series. To enable per-datum color with a plot that takes an $M \\times N$ matrix containing $M$ datums and $N$ series, you simply provide an $M \\times N$ matrix of color values or scalars. As a special case, when your plot only contains a single series you can enable per-datum color by providing an array of $M$ color values or scalars."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Scalar Values Plus Color Map\n",
"\n",
"As with per-series data, you can specify a set of per-datum scalars and a color map:"
]
},
{
"cell_type": "code",
"execution_count": 21,
"metadata": {},
"outputs": [
{
"data": {
"text/html": [
"
"
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"toyplot.bars(series, color=series, baseline=\"stacked\", width=600, height=300);"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Explicit Colors\n",
"\n",
"Finally, you can still supply explicit per-datum color values using :func:`toyplot.color.broadcast`. In the following example we will use it to highlight the ten largest values in the data:"
]
},
{
"cell_type": "code",
"execution_count": 25,
"metadata": {},
"outputs": [
{
"data": {
"text/html": [
"
"
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"colors = toyplot.color.broadcast((series, colormap), shape=series.shape)\n",
"\n",
"order = numpy.argsort(series, axis=None)\n",
"colors.flat[order[-10:]] = toyplot.color.css(\"yellow\")\n",
"\n",
"toyplot.bars(series, color=colors, baseline=\"stacked\", width=600, height=300);"
]
},
{
"cell_type": "raw",
"metadata": {
"raw_mimetype": "text/restructuredtext"
},
"source": [
"Color Arguments\n",
"---------------\n",
"\n",
"In the preceeding examples we used the `color` argument to supply color mapping data for various types of visualization. Keep in mind that many plot types provide more than one color argument, depending on the structure of the plot. For example, you can use color mapping to control the per-series color of a set of line plots:"
]
},
{
"cell_type": "code",
"execution_count": 27,
"metadata": {},
"outputs": [
{
"data": {
"text/html": [
"
"
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"colormap = toyplot.color.brewer.map(\"Dark2\")\n",
"toyplot.plot(series[::3,:2], color=colormap, width=600, height=200);"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"... but you can also apply color mapping to per-datum markers in the plot:"
]
},
{
"cell_type": "code",
"execution_count": 28,
"metadata": {},
"outputs": [
{
"data": {
"text/html": [
"