Add Text API examples and update properties tutorial

doc/_docstrings/objects.Text.ipynb

@@ -0,0 +1,188 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "cd1cdefe-b8c1-40b9-be31-006d52ec9f18",
+   "metadata": {
+    "tags": [
+     "hide"
+    ]
+   },
+   "outputs": [],
+   "source": [
+    "import seaborn.objects as so\n",
+    "from seaborn import load_dataset\n",
+    "glue = (\n",
+    "    load_dataset(\"glue\")\n",
+    "    .pivot(index=[\"Model\", \"Encoder\"], columns=\"Task\", values=\"Score\")\n",
+    "    .assign(Average=lambda x: x.mean(axis=1).round(1))\n",
+    "    .sort_values(\"Average\")\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "raw",
+   "id": "3e49ffb1-8778-4cd5-80d6-9d7e1438bc9c",
+   "metadata": {},
+   "source": [
+    "Add text at x/y locations on the plot:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "3bf21068-d39e-436c-8deb-aa1b15aeb2b3",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "(\n",
+    "    so.Plot(glue, x=\"SST-2\", y=\"MRPC\", text=\"Model\")\n",
+    "    .add(so.Text())\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "raw",
+   "id": "a4b9a8b2-6603-46db-9ede-3b3fb45e0e64",
+   "metadata": {},
+   "source": [
+    "Add bar annotations, horizontally-aligned with `halign`:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "f68501f0-c868-439e-9485-d71cca86ea47",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "(\n",
+    "    so.Plot(glue, x=\"Average\", y=\"Model\", text=\"Average\")\n",
+    "    .add(so.Bar())\n",
+    "    .add(so.Text(color=\"w\", halign=\"right\"))\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "raw",
+   "id": "a9d39479-0afa-477b-8403-fe92a54643c9",
+   "metadata": {},
+   "source": [
+    "Fine-tune the alignment using `offset`:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "b5da4a9d-79f3-4c11-bab3-f89da8512ce4",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "(\n",
+    "    so.Plot(glue, x=\"Average\", y=\"Model\", text=\"Average\")\n",
+    "    .add(so.Bar())\n",
+    "    .add(so.Text(color=\"w\", halign=\"right\", offset=0.5))\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "raw",
+   "id": "e9c43798-70d5-42b5-bd91-b85684d1b671",
+   "metadata": {},
+   "source": [
+    "Add text above dots, mapping the text color with a third variable:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "b2d26ebc-24ac-4531-9ba2-fa03720c58bc",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "(\n",
+    "    so.Plot(glue, x=\"SST-2\", y=\"MRPC\", color=\"Encoder\", text=\"Model\")\n",
+    "    .add(so.Dot())\n",
+    "    .add(so.Text(valign=\"bottom\"))\n",
+    "\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "raw",
+   "id": "f31aaa38-6728-4299-8422-8762c52c9857",
+   "metadata": {},
+   "source": [
+    "Map the text alignment for better use of space:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "cf4bbf0c-0c5f-4c31-b971-720ea8910918",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "(\n",
+    "    so.Plot(glue, x=\"RTE\", y=\"MRPC\", color=\"Encoder\", text=\"Model\")\n",
+    "    .add(so.Dot())\n",
+    "    .add(so.Text(offset=.5), halign=\"Encoder\")\n",
+    "    .scale(halign={\"LSTM\": \"left\", \"Transformer\": \"right\"})\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "raw",
+   "id": "a5de35a6-1ccf-4958-8013-edd9ed1cd4b0",
+   "metadata": {},
+   "source": [
+    "Use additional matplotlib parameters to control the appearance of the text:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "9c4be188-1614-4c19-9bd7-b07e986f6a23",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "(\n",
+    "    so.Plot(glue, x=\"RTE\", y=\"MRPC\", color=\"Encoder\", text=\"Model\")\n",
+    "    .add(so.Dot())\n",
+    "    .add(so.Text({\"fontweight\": \"bold\"}, offset=.5), halign=\"Encoder\")\n",
+    "    .scale(halign={\"LSTM\": \"left\", \"Transformer\": \"right\"})\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "95fb7aee-090a-4415-917c-b5258d2b298b",
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "py310",
+   "language": "python",
+   "name": "py310"
+  },
+  "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.0"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

doc/_tutorial/properties.ipynb

@@ -916,6 +916,157 @@
     ")"
    ]
   },
+  {
+   "cell_type": "raw",
+   "id": "c2ca33db-df52-4958-889a-320b4833a0d7",
+   "metadata": {},
+   "source": [
+    "Text properties\n",
+    "---------------"
+   ]
+  },
+  {
+   "cell_type": "raw",
+   "id": "b75af2fe-4d81-407c-9858-23362710f25f",
+   "metadata": {},
+   "source": [
+    ".. _horizontalalignment_property:\n",
+    "\n",
+    ".. _verticalalignment_property:\n",
+    "\n",
+    "halign, valign\n",
+    "~~~~~~~~~~~~~~\n",
+    "\n",
+    "The `halign` and `valign` properties control the *horizontal* and *vertical* alignment of text marks. The options for horizontal alignment are `'left'`, `'right'`, and `'center'`, while the options for vertical alignment are `'top'`, `'bottom'`, `'center'`, `'baseline'`, and `'center_baseline'`."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "e9588309-bee4-4b97-b428-eb91ea582105",
+   "metadata": {
+    "tags": [
+     "hide-input"
+    ]
+   },
+   "outputs": [],
+   "source": [
+    "x = [\"left\", \"right\", \"top\", \"bottom\", \"baseline\", \"center\"]\n",
+    "ha = x[:2] + [\"center\"] * 4\n",
+    "va = [\"center_baseline\"] * 2 + x[2:]\n",
+    "y = np.zeros(len(x))\n",
+    "(\n",
+    "    so.Plot(x=[f\"'{_x_}'\" for _x_ in x], y=y, halign=ha, valign=va)\n",
+    "    .add(so.Dot(marker=\"+\", color=\"r\", alpha=.5, stroke=1, pointsize=24))\n",
+    "    .add(so.Text(text=\"XyZ\", fontsize=14, offset=0))\n",
+    "    .scale(y=so.Continuous().tick(at=[]), halign=None, valign=None)\n",
+    "    .limit(x=(-.25, len(x) - .75))\n",
+    "    .layout(size=(9, .6), engine=None)\n",
+    "    .theme({\n",
+    "        **axes_style(\"ticks\"),\n",
+    "        **{f\"axes.spines.{side}\": False for side in [\"left\", \"right\", \"top\"]},\n",
+    "        \"xtick.labelsize\": 12,\n",
+    "        \"axes.xmargin\": .015,\n",
+    "        \"ytick.labelsize\": 12,\n",
+    "    })\n",
+    "    .plot()\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "raw",
+   "id": "ea74c7e5-798b-47bc-bc18-9086902fb5c6",
+   "metadata": {},
+   "source": [
+    ".. _fontsize_property:\n",
+    "\n",
+    "fontsize\n",
+    "~~~~~~~~\n",
+    "\n",
+    "The `fontsize` property controls the size of textual marks. The value has point units:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "c515b790-385d-4521-b14a-0769c1902928",
+   "metadata": {
+    "tags": [
+     "hide-input"
+    ]
+   },
+   "outputs": [],
+   "source": [
+    "from string import ascii_uppercase\n",
+    "n = 26\n",
+    "s = np.arange(n) + 1\n",
+    "y = np.zeros(n)\n",
+    "t = list(ascii_uppercase[:n])\n",
+    "(\n",
+    "    so.Plot(x=s, y=y, text=t, fontsize=s)\n",
+    "    .add(so.Text())\n",
+    "    .scale(x=so.Nominal(), y=so.Continuous().tick(at=[]))\n",
+    "    .layout(size=(9, .5), engine=None)\n",
+    "    .theme({\n",
+    "        **axes_style(\"ticks\"),\n",
+    "        **{f\"axes.spines.{side}\": False for side in [\"left\", \"right\", \"top\"]},\n",
+    "        \"xtick.labelsize\": 12,\n",
+    "        \"axes.xmargin\": .015,\n",
+    "        \"ytick.labelsize\": 12,\n",
+    "    })\n",
+    "    .plot()\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "raw",
+   "id": "4b367f36-fb96-44fa-83a3-1cc66c7a3279",
+   "metadata": {},
+   "source": [
+    ".. _offset_property:\n",
+    "\n",
+    "offset\n",
+    "~~~~~~\n",
+    "\n",
+    "The `offset` property controls the spacing between a text mark and its anchor position. It applies when *not* using `center` alignment (i.e., when using left/right or top/bottom). The value has point units. "
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "25a49331-9580-4578-8bdb-d0d1829dde71",
+   "metadata": {
+    "tags": [
+     "hide-input"
+    ]
+   },
+   "outputs": [],
+   "source": [
+    "n = 17\n",
+    "x = np.linspace(0, 8, n)\n",
+    "y = np.full(n, .5)\n",
+    "(\n",
+    "    so.Plot(x=x, y=y, offset=x)\n",
+    "    .add(so.Bar(color=\".6\", edgecolor=\"k\"))\n",
+    "    .add(so.Text(text=\"abc\", valign=\"bottom\"))\n",
+    "    .scale(\n",
+    "        x=so.Continuous().tick(every=1, minor=1),\n",
+    "        y=so.Continuous().tick(at=[]),\n",
+    "        offset=None,\n",
+    "    )\n",
+    "    .limit(y=(0, 1.5))\n",
+    "    .layout(size=(9, .5), engine=None)\n",
+    "    .theme({\n",
+    "        **axes_style(\"ticks\"),\n",
+    "        **{f\"axes.spines.{side}\": False for side in [\"left\", \"right\", \"top\"]},\n",
+    "        \"axes.xmargin\": .015,\n",
+    "        \"xtick.labelsize\": 12,\n",
+    "        \"ytick.labelsize\": 12,\n",
+    "    })\n",
+    "    .plot()\n",
+    ")"
+   ]
+  },
   {
    "cell_type": "raw",
    "id": "77723ffd-2da3-4ece-a97a-3c00e864c743",
@@ -932,6 +1083,11 @@
    "source": [
     ".. _property_property:\n",
     "\n",
+    "text\n",
+    "~~~~\n",
+    "\n",
+    "The `text` property is used to set the content of a textual mark. It is always used literally (not mapped), and cast to string when necessary.\n",
+    "\n",
     "group\n",
     "~~~~~\n",
     "\n",

doc/api.rst

@@ -66,6 +66,15 @@ Mark objects
     Area
     Band
 
+.. rubric:: Text marks
+
+.. autosummary::
+    :toctree: generated/
+    :template: object
+    :nosignatures:
+
+    Text
+
 Stat objects
 ~~~~~~~~~~~~