{
"cells": [
{
"cell_type": "markdown",
"id": "bbba8dfc-38a5-4bb0-be7c-011843f0ae95",
"metadata": {},
"source": [
"# Configuring Nudge Units in Position Adjustments\n",
"\n",
"The position adjustment `positionNudge()` now supports the `unit` parameter that specifies the measurement system for nudge offsets.
\n",
"Equivalent parameter is also available as `nudgeUnit` in `geomText()` and `geomLabel()` directly. \n",
"\n",
"Available Units:\n",
"\n",
"- `\"identity\"` (default): nudge in data coordinates - a value of 1 corresponds to the distance from 0 to 1 on the axis\n",
"- `\"size\"`: nudge relative to point size - a value of 1 corresponds to the diameter of a point with size 1\n",
"- `\"px\"`: nudge in fixed pixels - a value of 1 corresponds to 1 pixel"
]
},
{
"cell_type": "code",
"execution_count": 1,
"id": "9b462fcf-68da-4abd-aacf-595979a62133",
"metadata": {
"execution": {
"iopub.execute_input": "2025-12-03T15:57:44.381719Z",
"iopub.status.busy": "2025-12-03T15:57:44.379018Z",
"iopub.status.idle": "2025-12-03T15:57:46.331460Z",
"shell.execute_reply": "2025-12-03T15:57:46.331178Z"
}
},
"outputs": [
{
"data": {
"text/html": [
" \n",
" "
]
},
"metadata": {},
"output_type": "display_data"
},
{
"data": {
"text/html": [
" \n",
" "
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"%useLatestDescriptors\n",
"%use lets-plot"
]
},
{
"cell_type": "code",
"execution_count": 2,
"id": "ecabca69-383a-46d8-afb0-01d42d0a408e",
"metadata": {
"execution": {
"iopub.execute_input": "2025-12-03T15:57:46.334189Z",
"iopub.status.busy": "2025-12-03T15:57:46.333704Z",
"iopub.status.idle": "2025-12-03T15:57:46.368578Z",
"shell.execute_reply": "2025-12-03T15:57:46.367997Z"
}
},
"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": "markdown",
"id": "3ceb8835-e571-4aac-94c6-310f2011a5a8",
"metadata": {},
"source": [
"#### 1. Without nudge"
]
},
{
"cell_type": "code",
"execution_count": 3,
"id": "ea4c9641-75e2-463d-bd12-560d3bb96af8",
"metadata": {
"execution": {
"iopub.execute_input": "2025-12-03T15:57:46.370950Z",
"iopub.status.busy": "2025-12-03T15:57:46.370497Z",
"iopub.status.idle": "2025-12-03T15:57:46.610022Z",
"shell.execute_reply": "2025-12-03T15:57:46.610143Z"
}
},
"outputs": [
{
"data": {
"text/html": [
" \n",
" "
]
},
"metadata": {},
"output_type": "display_data"
},
{
"data": {
"application/plot+json": {
"apply_color_scheme": true,
"output": {
"ggsize": {
"height": 300.0,
"width": 400.0
},
"kind": "plot",
"layers": [
{
"color": "#DA8459",
"geom": "point",
"mapping": {},
"position": "identity",
"size": 10.0,
"stat": "identity",
"x": 0.0,
"y": 0.0
},
{
"geom": "text",
"label": "text without nudge",
"mapping": {},
"position": "identity",
"stat": "identity",
"x": 0.0,
"y": 0.0
}
],
"mapping": {},
"scales": []
},
"output_type": "lets_plot_spec",
"swing_enabled": true
},
"text/html": [
" \n",
" \n",
" "
]
},
"execution_count": 3,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"letsPlot() + \n",
" geomPoint(x = 0, y = 0, size = 10, color = \"#DA8459\") + \n",
" geomText(x = 0, y = 0, label = \"text without nudge\") + \n",
" ggsize(400, 300)"
]
},
{
"cell_type": "markdown",
"id": "1e8597bb-2986-429c-bab3-26a58f89bddf",
"metadata": {},
"source": [
"#### 2. Unit Comparison: Pixel, Size, and Identity\n",
"\n",
"The `\"size\"` unit enables precise positioning relative to point dimensions.\n",
"\n",
"In this example, the point has `size = 30` and text is positioned at half that distance (`nudgeY = 15`). When combined with `vjust`/`hjust`, this allows for placing text at specific locations relative to the point boundary."
]
},
{
"cell_type": "code",
"execution_count": 4,
"id": "8acd87f8-94f4-4d5a-81a6-a2e5a0e8a71f",
"metadata": {
"execution": {
"iopub.execute_input": "2025-12-03T15:57:46.612528Z",
"iopub.status.busy": "2025-12-03T15:57:46.612040Z",
"iopub.status.idle": "2025-12-03T15:57:46.729554Z",
"shell.execute_reply": "2025-12-03T15:57:46.729374Z"
}
},
"outputs": [
{
"data": {
"application/plot+json": {
"apply_color_scheme": true,
"output": {
"kind": "plot",
"layers": [
{
"color": "#B9534C",
"geom": "point",
"mapping": {},
"position": "identity",
"size": 5.0,
"stat": "identity",
"x": 0.0,
"y": 1.0
},
{
"geom": "text",
"label": "identity 0.2",
"mapping": {},
"nudge_y": 0.2,
"position": "identity",
"stat": "identity",
"x": 0.0,
"y": 1.0
},
{
"color": "#DA8459",
"geom": "point",
"mapping": {},
"position": "identity",
"size": 5.0,
"stat": "identity",
"x": 1.0,
"y": 1.0
},
{
"geom": "text",
"label": "px 40",
"mapping": {},
"nudge_unit": "px",
"nudge_y": 40.0,
"position": "identity",
"stat": "identity",
"x": 1.0,
"y": 1.0
},
{
"color": "#EEAB65",
"geom": "point",
"mapping": {},
"position": "identity",
"size": 30.0,
"stat": "identity",
"x": 2.0,
"y": 1.0
},
{
"geom": "text",
"label": "size 15",
"mapping": {},
"nudge_unit": "size",
"nudge_y": 15.0,
"position": "identity",
"stat": "identity",
"x": 2.0,
"y": 1.0
},
{
"color": "#F6C971",
"geom": "point",
"mapping": {},
"position": "identity",
"size": 30.0,
"stat": "identity",
"x": 3.0,
"y": 1.0
},
{
"geom": "text",
"label": "size 15 vjust 0",
"mapping": {},
"nudge_unit": "size",
"nudge_y": 15.0,
"position": "identity",
"stat": "identity",
"vjust": 0.0,
"x": 3.0,
"y": 1.0
},
{
"geom": "text",
"label": "size -15 vjust 1",
"mapping": {},
"nudge_unit": "size",
"nudge_y": -15.0,
"position": "identity",
"stat": "identity",
"vjust": 1.0,
"x": 3.0,
"y": 1.0
}
],
"mapping": {},
"scales": [
{
"aesthetic": "x",
"limits": [
-1.0,
4.0
]
}
]
},
"output_type": "lets_plot_spec",
"swing_enabled": true
},
"text/html": [
" \n",
" \n",
" "
]
},
"execution_count": 4,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"letsPlot() +\n",
" xlim(-1 to 4) +\n",
" geomPoint(x = 0, y = 1, size = 5, color = \"#B9534C\") +\n",
" geomText(x = 0, y = 1, label = \"identity 0.2\", nudgeY = 0.2) +\n",
" geomPoint(x = 1, y = 1, size = 5, color = \"#DA8459\") +\n",
" geomText(x = 1, y = 1, label = \"px 40\", nudgeY = 40, nudgeUnit = \"px\") +\n",
" geomPoint(x = 2, y = 1, size = 30, color = \"#EEAB65\") +\n",
" geomText(x = 2, y = 1, label = \"size 15\", nudgeY = 15, nudgeUnit = \"size\") +\n",
" geomPoint(x = 3, y = 1, size = 30, color = \"#F6C971\") +\n",
" geomText(x = 3, y = 1, label = \"size 15 vjust 0\", nudgeY = 15, vjust = 0, nudgeUnit = \"size\") +\n",
" geomText(x = 3, y = 1, label = \"size -15 vjust 1\", nudgeY = -15, vjust = 1, nudgeUnit = \"size\")"
]
},
{
"cell_type": "markdown",
"id": "b8f317a8-5aec-4ba7-8646-cbad83c13742",
"metadata": {},
"source": [
"#### 3. Parameter `unit` in `positionNudge()`"
]
},
{
"cell_type": "code",
"execution_count": 5,
"id": "7abb1d30-0e36-409a-bad4-acd11b86c9b7",
"metadata": {
"execution": {
"iopub.execute_input": "2025-12-03T15:57:46.731770Z",
"iopub.status.busy": "2025-12-03T15:57:46.731302Z",
"iopub.status.idle": "2025-12-03T15:57:46.792879Z",
"shell.execute_reply": "2025-12-03T15:57:46.793000Z"
}
},
"outputs": [
{
"data": {
"application/plot+json": {
"apply_color_scheme": true,
"output": {
"kind": "plot",
"layers": [
{
"color": "#DA8459",
"geom": "point",
"mapping": {},
"position": "identity",
"size": 50.0,
"stat": "identity",
"x": 0.0,
"y": 0.0
},
{
"color": "blue",
"geom": "point",
"mapping": {},
"position": {
"name": "nudge",
"unit": "size",
"x": 0.0,
"y": 25.0
},
"size": 20.0,
"stat": "identity",
"x": 0.0,
"y": 0.0
},
{
"geom": "text",
"label": "positionNudge size 25",
"mapping": {},
"position": {
"name": "nudge",
"unit": "size",
"x": 50.0,
"y": 25.0
},
"stat": "identity",
"x": 0.0,
"y": 0.0
}
],
"mapping": {},
"scales": []
},
"output_type": "lets_plot_spec",
"swing_enabled": true
},
"text/html": [
" \n",
" \n",
" "
]
},
"execution_count": 5,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"letsPlot() + \n",
" geomPoint(x = 0, y = 0, size = 50, color = \"#DA8459\") + \n",
" geomPoint(x = 0, y = 0, size = 20, color = \"blue\", position = positionNudge(0, 25, \"size\")) + \n",
" geomText(x = 0, y = 0, label = \"positionNudge size 25\", position = positionNudge(50, 25, \"size\"))"
]
}
],
"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
}