Add API examples and update release notes

doc/_docstrings/objects.Dash.ipynb

@@ -0,0 +1,168 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "3227e585-7166-44e7-b0c2-8570e098102d",
+   "metadata": {
+    "tags": [
+     "hide"
+    ]
+   },
+   "outputs": [],
+   "source": [
+    "import seaborn.objects as so\n",
+    "from seaborn import load_dataset\n",
+    "penguins = load_dataset(\"penguins\")"
+   ]
+  },
+  {
+   "cell_type": "raw",
+   "id": "1b424322-eaa4-45c7-8007-a671ef2afbde",
+   "metadata": {},
+   "source": [
+    "A line segment is drawn for each datapoint, centered on the value along the orientation axis:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "fc835356-2dc2-4583-a9f9-c1fe0a6cc9ea",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "p = so.Plot(penguins, \"species\", \"body_mass_g\", color=\"sex\")\n",
+    "p.add(so.Dash())"
+   ]
+  },
+  {
+   "cell_type": "raw",
+   "id": "ad9b94de-f19f-4e60-8275-686e749da39c",
+   "metadata": {},
+   "source": [
+    "A number of properties can be mapped or set directly:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "6070a665-ab19-43a6-9eba-e206193d9422",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "p.add(so.Dash(alpha=.5), linewidth=\"flipper_length_mm\")"
+   ]
+  },
+  {
+   "cell_type": "raw",
+   "id": "2c4a8291-0a84-4e70-a992-756850933791",
+   "metadata": {},
+   "source": [
+    "The mark has a `width` property, which is relative to the spacing between orientation values:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "315327da-421e-46c8-8a1b-8b87355d0439",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "p.add(so.Dash(width=.5))"
+   ]
+  },
+  {
+   "cell_type": "raw",
+   "id": "224bf51a-b8d8-4d8e-b0ab-b63ec6788584",
+   "metadata": {},
+   "source": [
+    "When dodged, the width will automatically adapt:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "227e889c-7ce7-49fc-b985-f7746393930e",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "p.add(so.Dash(), so.Dodge())"
+   ]
+  },
+  {
+   "cell_type": "raw",
+   "id": "aa807f57-5d37-4faa-8fd2-1e5378115f9f",
+   "metadata": {},
+   "source": [
+    "This mark works well to show aggregate values when paired with a strip plot:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "5141e0b8-ea1a-4178-adde-21b4bc2e705f",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "(\n",
+    "    p\n",
+    "    .add(so.Dash(), so.Agg(), so.Dodge())\n",
+    "    .add(so.Dots(), so.Dodge(), so.Jitter())\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "raw",
+   "id": "f2abd4b7-5afb-4661-95f3-b51bfa101273",
+   "metadata": {},
+   "source": [
+    "When both coordinate variables are numeric, you can control the orientation explicitly:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "f6d7e236-327f-460f-b12e-46d7444ac348",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "(\n",
+    "    so.Plot(\n",
+    "        penguins[\"body_mass_g\"],\n",
+    "        penguins[\"flipper_length_mm\"].round(-1),\n",
+    "    )\n",
+    "    .add(so.Dash(), orient=\"y\")\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "6811d776-93e5-49ce-88a6-14786a67841d",
+   "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/api.rst

@@ -40,11 +40,11 @@ Mark objects
     :template: object
     :nosignatures:
 
-    Dash
     Line
     Lines
     Path
     Paths
+    Dash
     Range
 
 .. rubric:: Bar marks

doc/whatsnew/v0.12.1.rst

@@ -4,6 +4,8 @@ v0.12.1 (Unreleased)
 
 - |Feature| Added the :class:`objects.Text` mark (:pr:`3051`).
 
+- |Feature| Added the :class:`objects.Dash` mark (:pr:`3074`).
+
 - |Feature| Added the :class:`objects.Perc` stat (:pr:`3063`).
 
 - |Feature| The :class:`Band` and :class:`Range` marks will now cover the full extent of the data if `min` / `max` variables are not explicitly assigned or added in a transform (:pr:`3056`).

seaborn/_marks/line.py

@@ -275,14 +275,19 @@ def _setup_segments(self, data, orient):
 @dataclass
 class Dash(Paths):
     """
-    TODO
+    A line mark drawn as an oriented segment for each datapoint.
+
+    Examples
+    --------
+    .. include:: ../docstrings/objects.Dash.rst
+
     """
     width: MappableFloat = Mappable(.8, grouping=False)
 
     def _setup_segments(self, data, orient):
 
         ori = ["x", "y"].index(orient)
-        xys = data[["x", "y"]].to_numpy()
+        xys = data[["x", "y"]].to_numpy().astype(float)
         segments = np.stack([xys, xys], axis=1)
         segments[:, 0, ori] -= data["width"] / 2
         segments[:, 1, ori] += data["width"] / 2