{
"cells": [
{
"cell_type": "markdown",
"id": "fed6d06a-c5a6-49cd-949c-7d4c9ed9b8a1",
"metadata": {},
"source": [
"# Dynamic Text Positioning with Repel Geometries\n",
"\n",
"- `geomTextRepel()`\n",
"- `geomLabelRepel()`\n",
"\n",
"These functions use a force-based layout algorithm to automatically reposition text labels and resolve overlaps.\n",
"\n",
"Labels repel each other and their associated data points while staying within the plot boundaries."
]
},
{
"cell_type": "code",
"execution_count": 1,
"id": "bd28eb0e-f782-4b58-a250-c2dde64c16e4",
"metadata": {
"execution": {
"iopub.execute_input": "2025-12-03T16:04:59.793469Z",
"iopub.status.busy": "2025-12-03T16:04:59.791944Z",
"iopub.status.idle": "2025-12-03T16:05:02.496282Z",
"shell.execute_reply": "2025-12-03T16:05:02.496007Z"
}
},
"outputs": [
{
"data": {
"text/html": [
" \n",
" "
]
},
"metadata": {},
"output_type": "display_data"
},
{
"data": {
"text/html": [
" "
]
},
"metadata": {},
"output_type": "display_data"
},
{
"data": {
"text/html": [
" \n",
" "
]
},
"metadata": {},
"output_type": "display_data"
},
{
"data": {
"text/html": [
" \n",
" "
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"%useLatestDescriptors\n",
"%use dataframe\n",
"%use lets-plot"
]
},
{
"cell_type": "code",
"execution_count": 2,
"id": "81b92ef6-3141-482d-9adf-3313be01ed12",
"metadata": {
"execution": {
"iopub.execute_input": "2025-12-03T16:05:02.497884Z",
"iopub.status.busy": "2025-12-03T16:05:02.497609Z",
"iopub.status.idle": "2025-12-03T16:05:02.528296Z",
"shell.execute_reply": "2025-12-03T16:05:02.528085Z"
}
},
"outputs": [
{
"data": {
"text/plain": [
"Lets-Plot Kotlin API v.4.12.0. Frontend: Notebook with dynamically loaded JS. Lets-Plot JS v.4.8.1.\n",
"Outputs: Web (HTML+JS), Kotlin Notebook (Swing), Static SVG (hidden)"
]
},
"execution_count": 2,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"LetsPlot.getInfo()"
]
},
{
"cell_type": "code",
"execution_count": 3,
"id": "ea3ced8d-e043-4373-8f4e-077fba64da34",
"metadata": {
"execution": {
"iopub.execute_input": "2025-12-03T16:05:02.530929Z",
"iopub.status.busy": "2025-12-03T16:05:02.530426Z",
"iopub.status.idle": "2025-12-03T16:05:02.553508Z",
"shell.execute_reply": "2025-12-03T16:05:02.553094Z"
}
},
"outputs": [],
"source": [
"import kotlin.random.Random\n",
"import org.jetbrains.letsPlot.interact.ggtb"
]
},
{
"cell_type": "code",
"execution_count": 4,
"id": "3ca6c904-55aa-454e-ab16-b121d9100acb",
"metadata": {
"execution": {
"iopub.execute_input": "2025-12-03T16:05:02.556056Z",
"iopub.status.busy": "2025-12-03T16:05:02.555571Z",
"iopub.status.idle": "2025-12-03T16:05:03.484858Z",
"shell.execute_reply": "2025-12-03T16:05:03.484626Z"
}
},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"32 x 12\n",
" model mpg cyl disp hp drat wt qsec vs am gear carb\n"
]
},
{
"name": "stdout",
"output_type": "stream",
"text": [
" 0 Mazda RX4 21.0 6 160.0 110 3.90 2.620 16.46 0 1 4 4\n"
]
},
{
"name": "stdout",
"output_type": "stream",
"text": [
" 1 Mazda RX4 Wag 21.0 6 160.0 110 3.90 2.875 17.02 0 1 4 4\n"
]
},
{
"name": "stdout",
"output_type": "stream",
"text": [
" 2 Datsun 710 22.8 4 108.0 93 3.85 2.320 18.61 1 1 4 1\n"
]
},
{
"name": "stdout",
"output_type": "stream",
"text": [
" 3 Hornet 4 Drive 21.4 6 258.0 110 3.08 3.215 19.44 1 0 3 1\n"
]
},
{
"name": "stdout",
"output_type": "stream",
"text": [
" 4 Hornet Sportabout 18.7 8 360.0 175 3.15 3.440 17.02 0 0 3 2\n",
"\n"
]
}
],
"source": [
"val df = DataFrame.readCsv(\n",
" fileOrUrl = \"https://gist.githubusercontent.com/seankross/a412dfbd88b3db70b74b/raw/5f23f993cd87c283ce766e7ac6b329ee7cc2e1d1/mtcars.csv\",\n",
" delimiter = ',',\n",
" header = listOf(),\n",
" colTypes = mapOf(),\n",
" skipLines = 0,\n",
" readLines = null,\n",
" allowMissingColumns = true,\n",
" parserOptions = null\n",
")\n",
"println(df.size())\n",
"println(df.head())"
]
},
{
"cell_type": "code",
"execution_count": 5,
"id": "a9a5c1ee-a055-47f2-8de7-bdb54f608171",
"metadata": {
"execution": {
"iopub.execute_input": "2025-12-03T16:05:03.487095Z",
"iopub.status.busy": "2025-12-03T16:05:03.486889Z",
"iopub.status.idle": "2025-12-03T16:05:03.757737Z",
"shell.execute_reply": "2025-12-03T16:05:03.757471Z"
}
},
"outputs": [],
"source": [
"val df1 = df.filter { (2.0 < it[\"wt\"] as Double) && ((it[\"wt\"] as Double) < 3.65) }\n",
"val df2 = df\n",
" .filter { (2.0 < it[\"wt\"] as Double) && ((it[\"wt\"] as Double) < 3) }\n",
" .add(\"shape\") { if (it[\"am\"] == 0.0) 16 else 21 }"
]
},
{
"cell_type": "code",
"execution_count": 6,
"id": "35dfc501-3dff-48de-b1ae-dac2f3f86dad",
"metadata": {
"execution": {
"iopub.execute_input": "2025-12-03T16:05:03.759010Z",
"iopub.status.busy": "2025-12-03T16:05:03.758895Z",
"iopub.status.idle": "2025-12-03T16:05:03.831332Z",
"shell.execute_reply": "2025-12-03T16:05:03.831134Z"
}
},
"outputs": [],
"source": [
"val plot1 = ggplot(df1.toMap()) { x = \"wt\"; y = \"mpg\"; label = \"model\" } + geomPoint(color = \"red\")\n",
"val plot2 = ggplot(df2.toMap()) { x = \"wt\"; y = \"mpg\"; label = \"model\" } + geomPoint(color = \"red\")"
]
},
{
"cell_type": "markdown",
"id": "f3c89c08-29a5-4a30-bd6e-a5d157665d9b",
"metadata": {},
"source": [
"### Comparison of geomText() and geomTextRepel()"
]
},
{
"cell_type": "code",
"execution_count": 7,
"id": "d49a03c5-8719-46ab-a8bd-5f918f868042",
"metadata": {
"execution": {
"iopub.execute_input": "2025-12-03T16:05:03.832597Z",
"iopub.status.busy": "2025-12-03T16:05:03.832368Z",
"iopub.status.idle": "2025-12-03T16:05:03.974797Z",
"shell.execute_reply": "2025-12-03T16:05:03.974571Z"
}
},
"outputs": [
{
"data": {
"text/html": [
" \n",
" "
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"gggrid(\n",
" listOf(\n",
" plot2 + geomText() + ggtitle(\"geomText()\"),\n",
" plot2 + geomTextRepel() + ggtitle(\"geomTextRepel()\")\n",
" )\n",
").show()"
]
},
{
"cell_type": "markdown",
"id": "1de52948-f9d2-49be-8c22-b264c52038fd",
"metadata": {},
"source": [
"### geomLabelRepel()\n",
"All of the parameters discussed below apply equally to both `geomTextRepel()` and `geomLabelRepel()`. For simplicity, we will use `geomTextRepel()` in the examples."
]
},
{
"cell_type": "code",
"execution_count": 8,
"id": "12b29f79-b837-445b-ac17-7828818ad354",
"metadata": {
"execution": {
"iopub.execute_input": "2025-12-03T16:05:03.976031Z",
"iopub.status.busy": "2025-12-03T16:05:03.975825Z",
"iopub.status.idle": "2025-12-03T16:05:04.027337Z",
"shell.execute_reply": "2025-12-03T16:05:04.027098Z"
}
},
"outputs": [
{
"data": {
"text/html": [
" \n",
" "
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"gggrid(\n",
" listOf(\n",
" plot2 + geomLabel() + ggtitle(\"geomText()\"),\n",
" plot2 + geomLabelRepel() + ggtitle(\"geomTextRepel()\")\n",
" )\n",
").show()"
]
},
{
"cell_type": "markdown",
"id": "e5f55b41-8d5f-497f-b88d-56bbf55b7523",
"metadata": {},
"source": [
"### `seed` parameter\n",
"\n",
"Controls the randomization to produce the same label layout each time the plot is generated."
]
},
{
"cell_type": "code",
"execution_count": 9,
"id": "6e31322c-0405-41fc-a739-bb6cccdce904",
"metadata": {
"execution": {
"iopub.execute_input": "2025-12-03T16:05:04.028560Z",
"iopub.status.busy": "2025-12-03T16:05:04.028364Z",
"iopub.status.idle": "2025-12-03T16:05:04.092975Z",
"shell.execute_reply": "2025-12-03T16:05:04.092746Z"
}
},
"outputs": [
{
"data": {
"text/html": [
" \n",
" "
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"gggrid(\n",
" listOf(\n",
" plot2 + geomTextRepel() + ggtitle(\"Without seed\"),\n",
" plot2 + geomTextRepel() + ggtitle(\"Without seed\"),\n",
" plot2 + geomTextRepel(seed = 4) + ggtitle(\"With seed\"),\n",
" plot2 + geomTextRepel(seed = 4) + ggtitle(\"With seed\"),\n",
" ), ncol = 2\n",
").show()"
]
},
{
"cell_type": "markdown",
"id": "5017d288-3742-45c3-93ee-babc013fd01f",
"metadata": {},
"source": [
"In some cases, it may be necessary to find a seed value that produces a more optimal label arrangement. A simple approach is to re-render the plot multiple times until you're satisfied with the result, then use the corresponding seed to reproduce it."
]
},
{
"cell_type": "code",
"execution_count": 10,
"id": "ab48d9d3-dc79-4962-81a9-447ef179e3da",
"metadata": {
"execution": {
"iopub.execute_input": "2025-12-03T16:05:04.094121Z",
"iopub.status.busy": "2025-12-03T16:05:04.093988Z",
"iopub.status.idle": "2025-12-03T16:05:04.147881Z",
"shell.execute_reply": "2025-12-03T16:05:04.147698Z"
}
},
"outputs": [
{
"data": {
"text/html": [
" \n",
" "
]
},
"metadata": {},
"output_type": "display_data"
},
{
"name": "stdout",
"output_type": "stream",
"text": [
"seed = 147079684"
]
}
],
"source": [
"val randomSeed = Random.nextInt()\n",
"print(\"seed = $randomSeed\")\n",
"(plot2 + geomTextRepel(seed = randomSeed) + ggtitle(\"Seed = $randomSeed\")).show()"
]
},
{
"cell_type": "markdown",
"id": "4f91e730-949e-4659-b720-42fde24084a0",
"metadata": {},
"source": [
"### `maxIter` parameter\n",
"\n",
"Controls the maximum number of iterations used by the layout algorithm, helping to reduce notebook rendering time. More iterations generally lead to better label placement, but at the cost of increased computation time. For plots with a small number of labels, 200–300 iterations are often sufficient.\n",
"The default value is 2000."
]
},
{
"cell_type": "code",
"execution_count": 11,
"id": "bcbce3ae-4a20-40aa-bd88-8b01e1564d1e",
"metadata": {
"execution": {
"iopub.execute_input": "2025-12-03T16:05:04.149051Z",
"iopub.status.busy": "2025-12-03T16:05:04.148863Z",
"iopub.status.idle": "2025-12-03T16:05:04.205357Z",
"shell.execute_reply": "2025-12-03T16:05:04.205117Z"
}
},
"outputs": [
{
"data": {
"text/html": [
" \n",
" "
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"val seed = 530\n",
"gggrid(\n",
" listOf(\n",
" plot2 + geomTextRepel(seed = seed, maxIter = 2) + ggtitle(\"max_iter=2\"),\n",
" plot2 + geomTextRepel(seed = seed, maxIter = 20) + ggtitle(\"max_iter=20\"),\n",
" plot2 + geomTextRepel(seed = seed, maxIter = 200) + ggtitle(\"max_iter=200\"),\n",
" )\n",
").show()"
]
},
{
"cell_type": "markdown",
"id": "0694f1fd-2144-4179-af25-ee9180c6f349",
"metadata": {},
"source": [
"### `maxTime` parameter\n",
"\n",
"Another way to limit plot rendering time is by using the `maxTime` parameter. This primarily serves as a safeguard against excessive computation when a large number of text labels are involved. Time is specified in seconds. The default value is `5` seconds, but you can disable the time limit by setting it to `-1` if needed."
]
},
{
"cell_type": "code",
"execution_count": 12,
"id": "6a7e7d37-3426-44c7-b297-d391b1fa1142",
"metadata": {
"execution": {
"iopub.execute_input": "2025-12-03T16:05:04.206572Z",
"iopub.status.busy": "2025-12-03T16:05:04.206382Z",
"iopub.status.idle": "2025-12-03T16:05:04.262346Z",
"shell.execute_reply": "2025-12-03T16:05:04.262122Z"
}
},
"outputs": [
{
"data": {
"text/html": [
" \n",
" "
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"gggrid(\n",
" listOf(\n",
" plot2 + geomTextRepel(seed = seed, maxTime = 0.001) + ggtitle(\"max_time=0.001\"),\n",
" plot2 + geomTextRepel(seed = seed, maxTime = 0.01) + ggtitle(\"max_time=0.01\"),\n",
" plot2 + geomTextRepel(seed = seed, maxTime = -1.0) + ggtitle(\"max_time=-1\"),\n",
" )\n",
").show()"
]
},
{
"cell_type": "markdown",
"id": "fb6279e2-36ed-4991-9918-066a98e092c1",
"metadata": {},
"source": [
"### `direction` parameter\n",
"\n",
"Restricts the movement of a text label relative to its anchor point to a specific direction. The default value is `both`."
]
},
{
"cell_type": "code",
"execution_count": 13,
"id": "a64f29ce-417c-4d32-88c1-fee074711f56",
"metadata": {
"execution": {
"iopub.execute_input": "2025-12-03T16:05:04.264322Z",
"iopub.status.busy": "2025-12-03T16:05:04.264084Z",
"iopub.status.idle": "2025-12-03T16:05:04.333726Z",
"shell.execute_reply": "2025-12-03T16:05:04.333468Z"
}
},
"outputs": [
{
"data": {
"text/html": [
" \n",
" "
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"gggrid(\n",
" listOf(\n",
" plot2 + geomTextRepel(seed = seed, direction = \"x\") + ggtitle(\"direction = 'x'\"),\n",
" plot2 + geomTextRepel(seed = seed, direction = \"y\") + ggtitle(\"direction = 'y'\"),\n",
" plot2 + geomTextRepel(seed = seed, direction = \"both\") + ggtitle(\"direction = 'both'\"),\n",
" )\n",
").show()"
]
},
{
"cell_type": "markdown",
"id": "6f770d41-6840-4926-84a5-c1e87418b573",
"metadata": {},
"source": [
"As we can see, this option is of limited use for randomly scattered points, but in certain cases it can be extremely helpful:"
]
},
{
"cell_type": "code",
"execution_count": 14,
"id": "1689cd18-3d39-44ec-b35c-94a58baef036",
"metadata": {
"execution": {
"iopub.execute_input": "2025-12-03T16:05:04.335588Z",
"iopub.status.busy": "2025-12-03T16:05:04.335391Z",
"iopub.status.idle": "2025-12-03T16:05:04.451367Z",
"shell.execute_reply": "2025-12-03T16:05:04.451153Z"
}
},
"outputs": [
{
"data": {
"text/html": [
" \n",
" "
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"val plotX = ggplot(df2.toMap()) { x = \"wt\"; label = \"model\" } +\n",
" geomPoint(y = 1, color = \"red\") + xlim(2 to 3) + ylim(1 to 1.3) +\n",
" geomTextRepel(y = 1, nudgeY = 0.05, direction = \"x\", angle = 90, hjust = 0.0, seed = seed)\n",
"\n",
"val plotY = ggplot(df2.toMap()) { y = \"mpg\"; label = \"model\" } +\n",
" geomPoint(x = 1, color = \"red\") + xlim(0.9 to 1.3) + ylim(19 to 35) +\n",
" geomTextRepel(x = 1, nudgeX = 0.05, direction = \"y\", hjust = 0.0, seed = seed)\n",
"\n",
"gggrid(\n",
" listOf(\n",
" plotX + ggtitle(\"direction = x\"),\n",
" plotY + ggtitle(\"direction = y\"),\n",
" )\n",
").show()"
]
},
{
"cell_type": "markdown",
"id": "47a85094-deb1-42e1-9f20-fbfc2b881b15",
"metadata": {},
"source": [
"### `pointPadding` and `boxPadding` parameters\n",
"\n",
"These parameters control the amount of spacing around text labels.\n",
"\n",
"- `pointPadding` adds space between the label and all nearby points, but does not affect spacing between labels.\n",
"\n",
"- `boxPadding` adds space between labels, but does not affect spacing between the label and the data point."
]
},
{
"cell_type": "code",
"execution_count": 15,
"id": "f8dd256e-0371-4b2e-ab93-aeecb4a6560d",
"metadata": {
"execution": {
"iopub.execute_input": "2025-12-03T16:05:04.453230Z",
"iopub.status.busy": "2025-12-03T16:05:04.452891Z",
"iopub.status.idle": "2025-12-03T16:05:04.496602Z",
"shell.execute_reply": "2025-12-03T16:05:04.496348Z"
}
},
"outputs": [
{
"data": {
"text/html": [
" \n",
" "
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"gggrid(\n",
" listOf(\n",
" plot2 + geomTextRepel(seed = seed, maxTime = -1.0, pointPadding = 10) + ggtitle(\"pointPadding\"),\n",
" plot2 + geomTextRepel(seed = seed, maxTime = -1.0, boxPadding = 10) + ggtitle(\"boxPadding\"),\n",
" )\n",
").show()"
]
},
{
"cell_type": "markdown",
"id": "a9cfeffe-aed8-47e6-8a26-a73c958a65dc",
"metadata": {},
"source": [
"### `maxOverlaps` parameter\n",
"\n",
"Specifies the maximum allowed number of overlaps with other labels. Labels that exceed this threshold will be omitted from the plot. The default value is `10`. You can disable overlap filtering entirely by setting this parameter to `-1`."
]
},
{
"cell_type": "code",
"execution_count": 16,
"id": "60ced1e9-99ea-49e0-8bb7-3b6952e9f64f",
"metadata": {
"execution": {
"iopub.execute_input": "2025-12-03T16:05:04.498436Z",
"iopub.status.busy": "2025-12-03T16:05:04.498230Z",
"iopub.status.idle": "2025-12-03T16:05:04.548767Z",
"shell.execute_reply": "2025-12-03T16:05:04.548493Z"
}
},
"outputs": [
{
"data": {
"text/html": [
" \n",
" "
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"gggrid(\n",
" listOf(\n",
" plot1 + geomTextRepel(seed = seed, maxTime = -1.0, maxOverlaps = 5) + ggtitle(\"maxOverlaps=5\"),\n",
" plot1 + geomTextRepel(seed = seed, maxTime = -1.0, maxOverlaps = -1) + ggtitle(\"maxOverlaps=-1\"),\n",
" )\n",
").show()"
]
},
{
"cell_type": "markdown",
"id": "f4ff9886-b49f-46b9-8541-e8bf80b41ad1",
"metadata": {},
"source": [
"### `minSegmentLength` parameter\n",
"\n",
"Sets the minimum length for the line connecting a label to its associated point. Lines shorter than this length will not be drawn. To display all lines, use the default value of `0`. To hide all lines, set the value to something very large.\n",
"`minSegmentLength` uses the same units as `pointSize`, so be careful when using `minSegmentLength` together with `sizeUnit` (see below)."
]
},
{
"cell_type": "code",
"execution_count": 17,
"id": "bcd4fd08-dab7-487e-a927-7d71df037a75",
"metadata": {
"execution": {
"iopub.execute_input": "2025-12-03T16:05:04.550346Z",
"iopub.status.busy": "2025-12-03T16:05:04.550077Z",
"iopub.status.idle": "2025-12-03T16:05:04.603032Z",
"shell.execute_reply": "2025-12-03T16:05:04.602832Z"
}
},
"outputs": [
{
"data": {
"text/html": [
" \n",
" "
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"gggrid(\n",
" listOf(\n",
" plot1 + geomTextRepel(seed = seed, maxTime = -1.0, minSegmentLength = 0) + ggtitle(\"minSegmentLength=0\"),\n",
" plot1 + geomTextRepel(\n",
" seed = seed,\n",
" maxTime = -1.0,\n",
" minSegmentLength = 9999\n",
" ) + ggtitle(\"minSegmentLength=9999\"),\n",
" )\n",
").show()"
]
},
{
"cell_type": "markdown",
"id": "7870166b-b312-4f03-8c0d-471df42f2813",
"metadata": {},
"source": [
"## Point settings\n",
"\n",
"`geomTextRepel()` does not draw points itself, but for it to work correctly, the values of parameters and aesthetics that control point size must match those used in the associated `geomPoint()` layer."
]
},
{
"cell_type": "code",
"execution_count": 18,
"id": "4fd33dd1-7a5b-4141-a83d-9cdfa32feafc",
"metadata": {
"execution": {
"iopub.execute_input": "2025-12-03T16:05:04.604744Z",
"iopub.status.busy": "2025-12-03T16:05:04.604306Z",
"iopub.status.idle": "2025-12-03T16:05:04.701513Z",
"shell.execute_reply": "2025-12-03T16:05:04.701298Z"
}
},
"outputs": [
{
"data": {
"text/html": [
" \n",
" "
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"(ggplot(df2.toMap()) { x = \"wt\"; y = \"mpg\"; label = \"model\" }\n",
" + geomPoint(sizeUnit = \"y\") { size = \"gear\"; stroke = \"vs\"; shape = \"shape\" }\n",
" + geomTextRepel(sizeUnit = \"y\") { pointSize = \"gear\"; pointStroke = \"vs\"; shape = \"shape\" }\n",
" + theme().legendPositionNone()\n",
" + scaleSize(range = 0.5 to 1, guide = \"none\")\n",
" + scaleStroke(range = 1 to 4, guide = \"none\")\n",
" + scaleShapeIdentity()\n",
" )\n",
" .show()"
]
},
{
"cell_type": "markdown",
"id": "d520d0fa-8329-45a6-a55f-f44a062463fd",
"metadata": {},
"source": [
"### `pointSize` aesthetic\n",
"\n",
"Allows you to pass to `geomTextRepel()` the data used to determine point sizes in a `geomPoint()` layer. This helps accurately detect overlaps between labels and points when point sizes vary."
]
},
{
"cell_type": "code",
"execution_count": 19,
"id": "6f4c0ff5-0fad-441a-a297-b91627a4ef1e",
"metadata": {
"execution": {
"iopub.execute_input": "2025-12-03T16:05:04.702934Z",
"iopub.status.busy": "2025-12-03T16:05:04.702742Z",
"iopub.status.idle": "2025-12-03T16:05:04.783558Z",
"shell.execute_reply": "2025-12-03T16:05:04.783336Z"
}
},
"outputs": [
{
"data": {
"text/html": [
" \n",
" "
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"val plot31 = (ggplot(df2.toMap()) { x = \"wt\"; y = \"mpg\"; label = \"model\" }\n",
" + geomPoint(color = \"red\") { size = \"gear\" }\n",
" + theme().legendPositionNone())\n",
"\n",
"gggrid(\n",
" listOf(\n",
" plot31 + geomTextRepel(seed = seed, maxTime = -1.0) + ggtitle(\"without pointSize\"),\n",
" plot31 + geomTextRepel(seed = seed, maxTime = -1.0) { pointSize = \"gear\" } + ggtitle(\"with pointSize\"),\n",
" )).show()"
]
},
{
"cell_type": "markdown",
"id": "96b499b0-4fe8-4998-aff6-725ef02eff4f",
"metadata": {},
"source": [
"You can also provide a constant value instead."
]
},
{
"cell_type": "code",
"execution_count": 20,
"id": "7e5ce02c-ec1e-4e1b-8469-2f304b6c2e5d",
"metadata": {
"execution": {
"iopub.execute_input": "2025-12-03T16:05:04.784944Z",
"iopub.status.busy": "2025-12-03T16:05:04.784757Z",
"iopub.status.idle": "2025-12-03T16:05:04.849182Z",
"shell.execute_reply": "2025-12-03T16:05:04.848968Z"
}
},
"outputs": [
{
"data": {
"text/html": [
" \n",
" "
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"val plot32 = (ggplot(df2.toMap()) { x = \"wt\"; y = \"mpg\"; label = \"model\" }\n",
" + geomPoint(size = 10, color = \"red\")\n",
" + theme().legendPositionNone())\n",
"\n",
"gggrid(\n",
" listOf(\n",
" plot32 + geomTextRepel(seed = seed, maxTime = -1.0) + ggtitle(\"without pointSize\"),\n",
" plot32 + geomTextRepel(seed = seed, maxTime = -1.0, pointSize = 10) + ggtitle(\"with pointSize\"),\n",
" )\n",
").show()"
]
},
{
"cell_type": "markdown",
"id": "1f038fb6-5a0c-4210-8053-01f8fc030442",
"metadata": {},
"source": [
"Set `pointSize = 0` to prevent label repulsion away from data points.\n",
"\n",
"Labels will still move away from each other and away from the edges of the plot."
]
},
{
"cell_type": "code",
"execution_count": 21,
"id": "70ad0737-eb12-4ab4-9ee7-2fd70681cad6",
"metadata": {
"execution": {
"iopub.execute_input": "2025-12-03T16:05:04.850701Z",
"iopub.status.busy": "2025-12-03T16:05:04.850513Z",
"iopub.status.idle": "2025-12-03T16:05:05.128047Z",
"shell.execute_reply": "2025-12-03T16:05:05.128173Z"
}
},
"outputs": [
{
"data": {
"text/html": [
" \n",
" "
]
},
"metadata": {},
"output_type": "display_data"
},
{
"data": {
"application/plot+json": {
"apply_color_scheme": true,
"output": {
"figures": [
{
"data": {
"am": [
1.0,
1.0,
1.0,
1.0,
0.0,
1.0,
1.0,
1.0
],
"carb": [
4.0,
4.0,
1.0,
1.0,
1.0,
2.0,
6.0,
2.0
],
"cyl": [
6.0,
6.0,
4.0,
4.0,
4.0,
4.0,
6.0,
4.0
],
"disp": [
160.0,
160.0,
108.0,
78.7,
120.1,
120.3,
145.0,
121.0
],
"drat": [
3.9,
3.9,
3.85,
4.08,
3.7,
4.43,
3.62,
4.11
],
"gear": [
4.0,
4.0,
4.0,
4.0,
3.0,
5.0,
5.0,
4.0
],
"hp": [
110.0,
110.0,
93.0,
66.0,
97.0,
91.0,
175.0,
109.0
],
"model": [
"Mazda RX4",
"Mazda RX4 Wag",
"Datsun 710",
"Fiat 128",
"Toyota Corona",
"Porsche 914-2",
"Ferrari Dino",
"Volvo 142E"
],
"mpg": [
21.0,
21.0,
22.8,
32.4,
21.5,
26.0,
19.7,
21.4
],
"qsec": [
16.46,
17.02,
18.61,
19.47,
20.01,
16.7,
15.5,
18.6
],
"shape": [
21.0,
21.0,
21.0,
21.0,
21.0,
21.0,
21.0,
21.0
],
"vs": [
0.0,
0.0,
1.0,
1.0,
1.0,
0.0,
0.0,
1.0
],
"wt": [
2.62,
2.875,
2.32,
2.2,
2.465,
2.14,
2.77,
2.78
]
},
"data_meta": {
"series_annotations": [
{
"column": "model",
"type": "str"
},
{
"column": "mpg",
"type": "float"
},
{
"column": "cyl",
"type": "int"
},
{
"column": "disp",
"type": "float"
},
{
"column": "hp",
"type": "int"
},
{
"column": "drat",
"type": "float"
},
{
"column": "wt",
"type": "float"
},
{
"column": "qsec",
"type": "float"
},
{
"column": "vs",
"type": "int"
},
{
"column": "am",
"type": "int"
},
{
"column": "gear",
"type": "int"
},
{
"column": "carb",
"type": "int"
},
{
"column": "shape",
"type": "int"
}
]
},
"ggtitle": {
"text": "without pointSize"
},
"kind": "plot",
"layers": [
{
"color": "red",
"geom": "point",
"mapping": {},
"position": "identity",
"stat": "identity"
},
{
"geom": "text_repel",
"mapping": {},
"max_time": -1.0,
"position": "identity",
"seed": 530.0,
"stat": "identity"
}
],
"mapping": {
"label": "model",
"x": "wt",
"y": "mpg"
},
"scales": []
},
{
"data": {
"am": [
1.0,
1.0,
1.0,
1.0,
0.0,
1.0,
1.0,
1.0
],
"carb": [
4.0,
4.0,
1.0,
1.0,
1.0,
2.0,
6.0,
2.0
],
"cyl": [
6.0,
6.0,
4.0,
4.0,
4.0,
4.0,
6.0,
4.0
],
"disp": [
160.0,
160.0,
108.0,
78.7,
120.1,
120.3,
145.0,
121.0
],
"drat": [
3.9,
3.9,
3.85,
4.08,
3.7,
4.43,
3.62,
4.11
],
"gear": [
4.0,
4.0,
4.0,
4.0,
3.0,
5.0,
5.0,
4.0
],
"hp": [
110.0,
110.0,
93.0,
66.0,
97.0,
91.0,
175.0,
109.0
],
"model": [
"Mazda RX4",
"Mazda RX4 Wag",
"Datsun 710",
"Fiat 128",
"Toyota Corona",
"Porsche 914-2",
"Ferrari Dino",
"Volvo 142E"
],
"mpg": [
21.0,
21.0,
22.8,
32.4,
21.5,
26.0,
19.7,
21.4
],
"qsec": [
16.46,
17.02,
18.61,
19.47,
20.01,
16.7,
15.5,
18.6
],
"shape": [
21.0,
21.0,
21.0,
21.0,
21.0,
21.0,
21.0,
21.0
],
"vs": [
0.0,
0.0,
1.0,
1.0,
1.0,
0.0,
0.0,
1.0
],
"wt": [
2.62,
2.875,
2.32,
2.2,
2.465,
2.14,
2.77,
2.78
]
},
"data_meta": {
"series_annotations": [
{
"column": "model",
"type": "str"
},
{
"column": "mpg",
"type": "float"
},
{
"column": "cyl",
"type": "int"
},
{
"column": "disp",
"type": "float"
},
{
"column": "hp",
"type": "int"
},
{
"column": "drat",
"type": "float"
},
{
"column": "wt",
"type": "float"
},
{
"column": "qsec",
"type": "float"
},
{
"column": "vs",
"type": "int"
},
{
"column": "am",
"type": "int"
},
{
"column": "gear",
"type": "int"
},
{
"column": "carb",
"type": "int"
},
{
"column": "shape",
"type": "int"
}
]
},
"ggtitle": {
"text": "with pointSize = 0"
},
"kind": "plot",
"layers": [
{
"color": "red",
"geom": "point",
"mapping": {},
"position": "identity",
"stat": "identity"
},
{
"geom": "text_repel",
"mapping": {},
"max_time": -1.0,
"point_size": 0.0,
"position": "identity",
"seed": 530.0,
"stat": "identity"
}
],
"mapping": {
"label": "model",
"x": "wt",
"y": "mpg"
},
"scales": []
}
],
"kind": "subplots",
"layout": {
"align": false,
"fit": true,
"name": "grid",
"ncol": 2,
"nrow": 1
}
},
"output_type": "lets_plot_spec",
"swing_enabled": true
},
"text/html": [
" \n",
" \n",
" "
]
},
"execution_count": 21,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"val plot33 = (ggplot(df2.toMap()) { x = \"wt\"; y = \"mpg\"; label = \"model\" }\n",
" + geomPoint(color = \"red\"))\n",
"\n",
"gggrid(\n",
" listOf(\n",
" plot33 + geomTextRepel(seed = seed, maxTime = -1.0) + ggtitle(\"without pointSize\"),\n",
" plot33 + geomTextRepel(seed = seed, maxTime = -1.0, pointSize = 0) + ggtitle(\"with pointSize = 0\"),\n",
" )\n",
")"
]
},
{
"cell_type": "markdown",
"id": "a3701287-59a8-4b08-ad36-35ad84a7b690",
"metadata": {},
"source": [
"### `pointStroke` and `shape` aesthetics\n",
"\n",
"Allow you to pass to `geomTextRepel()` the data used to determine point stroke width and shape in a `geomPoint()` layer. This ensures accurate collision detection between labels and points."
]
},
{
"cell_type": "code",
"execution_count": 22,
"id": "588e87ad-e30c-44fc-a29d-d3f6f46a10f4",
"metadata": {
"execution": {
"iopub.execute_input": "2025-12-03T16:05:05.129972Z",
"iopub.status.busy": "2025-12-03T16:05:05.129836Z",
"iopub.status.idle": "2025-12-03T16:05:05.211866Z",
"shell.execute_reply": "2025-12-03T16:05:05.211735Z"
}
},
"outputs": [
{
"data": {
"text/html": [
" \n",
" "
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"val plot34 = (ggplot(df2.toMap()) { x = \"wt\"; y = \"mpg\"; label=\"model\" }\n",
" + geomPoint(shape=21, size=10, color=\"red\") { stroke=\"gear\" }\n",
" + theme().legendPositionNone())\n",
"\n",
"gggrid(listOf(\n",
" plot34 + geomTextRepel(seed=seed, maxTime=-1.0, pointSize=10) + ggtitle(\"without pointStroke\"),\n",
" plot34 + geomTextRepel(shape=21, pointSize=10, seed=seed, maxTime=-1.0) { pointStroke=\"gear\" } + ggtitle(\"with pointStroke\"),\n",
")).show()\n"
]
},
{
"cell_type": "markdown",
"id": "6416d311-a608-40c8-a442-191882e97227",
"metadata": {},
"source": [
"### `sizeUnit` parameter\n",
"\n",
"The `sizeUnit` parameter can be used in `geomPoint()` to define the unit of measurement for the `size` aesthetic. In this case, it is recommended to also use `sizeUnit` in `geomTextRepel()` to ensure that point sizes are calculated correctly."
]
},
{
"cell_type": "code",
"execution_count": 23,
"id": "b18e356c-1418-4067-95e5-ae7245331556",
"metadata": {
"execution": {
"iopub.execute_input": "2025-12-03T16:05:05.213297Z",
"iopub.status.busy": "2025-12-03T16:05:05.213063Z",
"iopub.status.idle": "2025-12-03T16:05:05.296946Z",
"shell.execute_reply": "2025-12-03T16:05:05.296713Z"
}
},
"outputs": [
{
"data": {
"text/html": [
" \n",
" "
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"val plot4 = (ggplot(df2.toMap()) { x = \"wt\"; y = \"mpg\"; label = \"model\" }\n",
" + geomPoint(size = 1, sizeUnit = \"y\", color = \"red\")\n",
" + theme().legendPositionNone())\n",
"\n",
"(gggrid(\n",
" listOf(\n",
" plot4 + geomTextRepel(seed = seed, maxTime = -1.0, pointSize = 1) + ggtitle(\"without sizeUnit\"),\n",
" plot4 + geomTextRepel(\n",
" seed = seed,\n",
" maxTime = -1.0,\n",
" pointSize = 1,\n",
" sizeUnit = \"y\"\n",
" ) + ggtitle(\"with sizeUnit\"),\n",
" )\n",
") + ggtb()).show()"
]
},
{
"cell_type": "markdown",
"id": "a5de7618-3475-465a-9af3-063f733dd68f",
"metadata": {},
"source": [
"##### `sizeUnit` applies to all size-related parameters: `pointSize`, `minSegmentLength`, `pointPadding`, and `boxPadding`\n",
"\n",
"As an example, consider how it affects `minSegmentLength`.\n",
"As mentioned earlier, `minSegmentLength` uses the same units as `pointSize`. Therefore, in the following example, with the same `minSegmentLength` value, some lines are not drawn in the second case because their length is less than one unit along the y-axis."
]
},
{
"cell_type": "code",
"execution_count": 24,
"id": "69063269-f4bb-43d0-ba7e-8d3e84a4cd90",
"metadata": {
"execution": {
"iopub.execute_input": "2025-12-03T16:05:05.298705Z",
"iopub.status.busy": "2025-12-03T16:05:05.298489Z",
"iopub.status.idle": "2025-12-03T16:05:05.396732Z",
"shell.execute_reply": "2025-12-03T16:05:05.396497Z"
}
},
"outputs": [
{
"data": {
"text/html": [
" \n",
" "
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"val plot5 = (ggplot(df2.toMap()) { x = \"wt\"; y = \"mpg\"; label = \"model\" }\n",
" + theme().legendPositionNone())\n",
"\n",
"(gggrid(\n",
" listOf(\n",
" (plot5 + geomPoint(size = 10, color = \"red\")\n",
" + geomTextRepel(seed = seed, maxTime = -1.0, pointSize = 10, minSegmentLength = 1)\n",
" + ggtitle(\"without sizeUnit\")),\n",
" (plot5 + geomPoint(size = 1, sizeUnit = \"y\", color = \"red\")\n",
" + geomTextRepel(seed = seed, maxTime = -1.0, pointSize = 1, minSegmentLength = 1, sizeUnit = \"y\")\n",
" + ggtitle(\"with sizeUnit\")),\n",
" )\n",
") + ggtb()).show()"
]
},
{
"cell_type": "markdown",
"id": "3ed6370a-942e-4d3a-8c33-deada9565d7d",
"metadata": {},
"source": [
"### `segmentColor` aesthetic\n",
"\n",
"Allows you to specify the color of the line connecting the label to the point. By default, the line color matches the text color and follows the `color` aesthetic. In the example below, the `color` aesthetic is defined globally for all layers, so the colors of the points, text, and lines are the same."
]
},
{
"cell_type": "code",
"execution_count": 25,
"id": "cb322efa-8f0a-4609-b58b-a1d4b02deee4",
"metadata": {
"execution": {
"iopub.execute_input": "2025-12-03T16:05:05.398258Z",
"iopub.status.busy": "2025-12-03T16:05:05.398073Z",
"iopub.status.idle": "2025-12-03T16:05:05.444183Z",
"shell.execute_reply": "2025-12-03T16:05:05.443790Z"
}
},
"outputs": [
{
"data": {
"text/html": [
" \n",
" "
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"(ggplot(df2.toMap()) { x = \"wt\"; y = \"mpg\"; label = \"model\"; color = \"wt\" }\n",
" + geomPoint()\n",
" + geomTextRepel(seed = seed, maxTime = -1.0)\n",
" )\n",
" .show()"
]
},
{
"cell_type": "markdown",
"id": "868e31d0-36cc-4ef5-9304-e4d622ab5a7f",
"metadata": {},
"source": [
"By using the `color` and `segmentColor` aesthetics together, you can assign different colors to the points, labels, and connecting lines."
]
},
{
"cell_type": "code",
"execution_count": 26,
"id": "23c59549-79fc-4f5d-9ff7-2c6269368144",
"metadata": {
"execution": {
"iopub.execute_input": "2025-12-03T16:05:05.445962Z",
"iopub.status.busy": "2025-12-03T16:05:05.445629Z",
"iopub.status.idle": "2025-12-03T16:05:05.554818Z",
"shell.execute_reply": "2025-12-03T16:05:05.554592Z"
}
},
"outputs": [
{
"data": {
"text/html": [
" \n",
" "
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"val plot6 = (ggplot(df2.toMap()) { x = \"wt\"; y = \"mpg\"; label = \"model\" }\n",
" + theme().legendPositionNone())\n",
"\n",
"gggrid(\n",
" listOf(\n",
" plot6 + geomPoint() { color = \"wt\" }\n",
" + geomTextRepel(seed = seed, maxTime = -1.0) { segmentColor = \"wt\" }\n",
" + ggtitle(\"Same color for points and lines\"),\n",
" plot6 + geomPoint(color = \"red\")\n",
" + geomTextRepel(seed = seed, maxTime = -1.0) { color = \"wt\" }\n",
" + ggtitle(\"Same color for text and line\"),\n",
" plot6 + geomPoint(color = \"red\")\n",
" + geomTextRepel(color = \"green\", segmentColor = \"blue\", seed = seed, maxTime = -1.0)\n",
" + ggtitle(\"Different colors\"),\n",
" )).show()"
]
},
{
"cell_type": "markdown",
"id": "de08c1f3-18c1-42af-b9cf-fdfe50e06669",
"metadata": {},
"source": [
"### `segmentAlpha` aesthetic\n",
"\n",
"Specifies the transparency level of the connecting lines between labels and points. By default, the segment transparency inherits from the text and is governed by the `alpha` aesthetic."
]
},
{
"cell_type": "code",
"execution_count": 27,
"id": "4ac608a2-3a48-4e9d-a8bf-93cadb0fcaa7",
"metadata": {
"execution": {
"iopub.execute_input": "2025-12-03T16:05:05.556322Z",
"iopub.status.busy": "2025-12-03T16:05:05.555975Z",
"iopub.status.idle": "2025-12-03T16:05:05.599442Z",
"shell.execute_reply": "2025-12-03T16:05:05.599196Z"
}
},
"outputs": [
{
"data": {
"text/html": [
" \n",
" "
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"(ggplot(df2.toMap()) { x = \"wt\"; y = \"mpg\"; label = \"model\" }\n",
" + geomPoint(color = \"red\")\n",
" + geomTextRepel(pointPadding = 20, color = \"red\", segmentAlpha = 0.1, seed = seed, maxTime = -1.0)\n",
" ).show()"
]
},
{
"cell_type": "markdown",
"id": "a15e840f-4bde-4841-96b4-aeede9b10498",
"metadata": {},
"source": [
"### `segmentSize` aesthetic\n",
"\n",
"Specifies the width of the line connecting the label to the point."
]
},
{
"cell_type": "code",
"execution_count": 28,
"id": "9e20ad8d-d7a6-4001-923c-5c93b390259a",
"metadata": {
"execution": {
"iopub.execute_input": "2025-12-03T16:05:05.601159Z",
"iopub.status.busy": "2025-12-03T16:05:05.600968Z",
"iopub.status.idle": "2025-12-03T16:05:05.624329Z",
"shell.execute_reply": "2025-12-03T16:05:05.624109Z"
}
},
"outputs": [
{
"data": {
"text/html": [
" \n",
" "
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"(plot2 + geomTextRepel(segmentSize=2, seed=seed, maxTime=-1.0)).show()"
]
},
{
"cell_type": "markdown",
"id": "f9d213d9-beba-41ba-8625-a8d770854d65",
"metadata": {},
"source": [
"### `linetype` aesthetic"
]
},
{
"cell_type": "code",
"execution_count": 29,
"id": "77421562-83f3-4f80-b572-6a45b9ab2cec",
"metadata": {
"execution": {
"iopub.execute_input": "2025-12-03T16:05:05.625956Z",
"iopub.status.busy": "2025-12-03T16:05:05.625761Z",
"iopub.status.idle": "2025-12-03T16:05:05.682599Z",
"shell.execute_reply": "2025-12-03T16:05:05.682412Z"
}
},
"outputs": [
{
"data": {
"text/html": [
" \n",
" "
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"(ggplot(df2.toMap()) { y=\"mpg\"; label=\"model\" } + geomPoint(x=1, color=\"red\") + xlim(0.9 to 1.3) + ylim(19 to 35)\n",
" + geomTextRepel(x=1, nudgeX=0.2, direction=\"y\", hjust=0.0, seed=seed) { linetype=\"disp\" })\n",
" .show()"
]
},
{
"cell_type": "markdown",
"id": "5a951ee9-2752-4aa2-b206-7bc9d9980e03",
"metadata": {},
"source": [
"### `arrow` parameter"
]
},
{
"cell_type": "code",
"execution_count": 30,
"id": "0af8fccd-a08a-4125-b258-8a45b442b48f",
"metadata": {
"execution": {
"iopub.execute_input": "2025-12-03T16:05:05.684275Z",
"iopub.status.busy": "2025-12-03T16:05:05.684081Z",
"iopub.status.idle": "2025-12-03T16:05:05.743718Z",
"shell.execute_reply": "2025-12-03T16:05:05.743523Z"
}
},
"outputs": [
{
"data": {
"text/html": [
" \n",
" "
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"(ggplot(df2.toMap()) { y=\"mpg\"; label=\"model\" }\n",
" + geomPoint(x=1, color=\"red\")\n",
" + geomTextRepel(\n",
" x = 1,\n",
" nudgeX = 0.2,\n",
" direction = \"y\",\n",
" hjust = 0.0,\n",
" arrow = arrow(type = \"closed\", angle = 10, ends = \"both\"),\n",
" seed = seed\n",
" )\n",
" + xlim(0.9 to 1.3)\n",
" + ylim(19 to 35)\n",
" ).show()"
]
}
],
"metadata": {
"kernelspec": {
"display_name": "Kotlin",
"language": "kotlin",
"name": "kotlin"
},
"language_info": {
"codemirror_mode": "text/x-kotlin",
"file_extension": ".kt",
"mimetype": "text/x-kotlin",
"name": "kotlin",
"nbconvert_exporter": "",
"pygments_lexer": "kotlin",
"version": "2.2.20-Beta2"
}
},
"nbformat": 4,
"nbformat_minor": 5
}