demos/more_examples/graphistry_features/encodings-colors.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Color encodings tutorial\n",
    "\n",
    "See the examples below for common ways to map data to node/edge color in Graphistry.\n",
    "\n",
    "Colors are often used with node size, icon, label, and badges to provide more visual information. Most encodings work both for points and edges. The [PyGraphistry Python client](https://github.com/graphistry/pygraphistry) makes it easier to use the [URL settings API](https://hub.graphistry.com/docs/api/1/rest/url/) and the [REST upload API](https://hub.graphistry.com/docs/api/2/rest/upload/). For dynamic control, you can use also use the [JavaScript APIs](https://hub.graphistry.com/docs/). "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Setup\n",
    "\n",
    "Mode `api=3` is recommended. It is required for `complex_encodings` (ex: `.encode_point_color(...)`). Mode `api=1` works with the simpler `.bind(point_color='col_a')` form."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# ! pip install --user graphistry\n",
    "import graphistry\n",
    "\n",
    "# To specify Graphistry account & server, use:\n",
    "# graphistry.register(api=3, username='...', password='...', protocol='https', server='hub.graphistry.com')\n",
    "# For more options, see https://github.com/graphistry/pygraphistry#configure\n",
    "\n",
    "graphistry.__version__"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import datetime, pandas as pd\n",
    "e_df = pd.DataFrame({\n",
    "    's': ['a', 'b', 'c', 'a', 'd', 'e'],\n",
    "    'd': ['b', 'c', 'a', 'c', 'e', 'd'],\n",
    "    'time': [datetime.datetime(1987, 10, 1), datetime.datetime(1987, 10, 2), datetime.datetime(1987, 10, 3),\n",
    "          datetime.datetime(1988, 10, 1), datetime.datetime(1988, 10, 2), datetime.datetime(1988, 10, 3)]\n",
    "})\n",
    "n_df = pd.DataFrame({\n",
    "    'n': ['a', 'b', 'c', 'd', 'e'],\n",
    "    'score': [ 0, 30, 50, 70, 90 ],\n",
    "    'palette_color_int32': pd.Series(\n",
    "        [0, 1, 2, 3, 4],\n",
    "        dtype='int32'),\n",
    "    'hex_color_int64': pd.Series(\n",
    "        [0xFF000000, 0xFFFF0000, 0xFFFFFF00, 0x00FF0000, 0x0000FF00],\n",
    "        dtype='int64'),\n",
    "    'type': ['mac', 'macbook', 'mac', 'macbook', 'sheep']\n",
    "})\n",
    "g = graphistry.edges(e_df, 's', 'd').nodes(n_df, 'n')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Colors\n",
    "\n",
    "\n",
    "Options: default, built-in palette, RGBA, continuous palette, and categorical mapping\n",
    "\n",
    "Applies to both nodes and edges\n",
    "\n",
    "* Use the `.encode_point_color()` and `.encode_edge_color()` calls\n",
    "* For palette and RGBA bindings (non-complex), you can also use the shorthand `.bind(point_color='col_a', edge_color='col_b')`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Default\n",
    "* Node: Graphistry looks at the local graph structure to auto-color nodes\n",
    "* Edges: Gradient from the src/dst node color to reinforce the node color decision"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "g.plot()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Built-in palette\n",
    "Bind an int32 column where values are intepreted by the [predefined color palette tabble](https://hub.graphistry.com/docs/api/api-color-palettes/)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(g._nodes['palette_color_int32'].dtype)\n",
    "g.encode_point_color('palette_color_int32').plot()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### RGBA colors"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(g._nodes['hex_color_int64'].dtype)\n",
    "g.encode_point_color('hex_color_int64').plot()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Continuous colors\n",
    "Create a gradient effect by linearly mapping the input column to an evenly-spaced palette.\n",
    "\n",
    "Great for tasks like mapping timestamps, counts, and scores to low/high and low/medium/high intervals."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "g.encode_point_color('score', palette=['silver', 'maroon', '#FF99FF'], as_continuous=True).plot()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Categorical colors\n",
    "\n",
    "Map distinct values to specific colors. Optionally, set a default, else black."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "g.encode_point_color(\n",
    "    'type',\n",
    "    categorical_mapping={\n",
    "        'mac': '#F99',\n",
    "        'macbook': '#99F'\n",
    "    },\n",
    "    default_mapping='silver'\n",
    ").plot()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Edge colors\n",
    "\n",
    "Edge colors work the same as node colors by switching to call `.encode_edge_color()`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "g.encode_edge_color('time', palette=['blue', 'red'], as_continuous=True).plot()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Legend support\n",
    "Categorical node colors will appear in legend when driven by column `type`: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "g.encode_point_color(\n",
    "    'type',\n",
    "    categorical_mapping={\n",
    "        'mac': '#F99',\n",
    "        'macbook': '#99F'\n",
    "    },\n",
    "    default_mapping='silver'\n",
    ").plot()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "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.11"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}