{
"cells": [
{
"cell_type": "markdown",
"id": "f06e1ccf-cf80-4b5f-8ffb-9b8ec97c2b2a",
"metadata": {},
"source": [
"# Configuring Nudge Units in Position Adjustments\n",
"\n",
"The position adjustment `position_nudge()` now supports the `unit` parameter that specifies the measurement system for nudge offsets.
\n",
"Equivalent parameter is also available as `nudge_unit` in `geom_text()` and `geom_label()` 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\n",
"\n"
]
},
{
"cell_type": "code",
"execution_count": 1,
"id": "9ef6598d-3dcf-4297-8010-75f90c7838c6",
"metadata": {
"execution": {
"iopub.execute_input": "2025-11-05T13:41:19.952817Z",
"iopub.status.busy": "2025-11-05T13:41:19.952698Z",
"iopub.status.idle": "2025-11-05T13:41:19.984582Z",
"shell.execute_reply": "2025-11-05T13:41:19.984278Z"
}
},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"The geodata is provided by © OpenStreetMap contributors and is made available here under the Open Database License (ODbL).\n"
]
}
],
"source": [
"from lets_plot import *\n",
"from lets_plot.geo_data import *"
]
},
{
"cell_type": "code",
"execution_count": 2,
"id": "2c2b568d-2da5-491d-8bad-7792afd7b68f",
"metadata": {
"execution": {
"iopub.execute_input": "2025-11-05T13:41:19.985425Z",
"iopub.status.busy": "2025-11-05T13:41:19.985340Z",
"iopub.status.idle": "2025-11-05T13:41:19.987450Z",
"shell.execute_reply": "2025-11-05T13:41:19.987173Z"
}
},
"outputs": [
{
"data": {
"text/html": [
"\n",
" \n",
" \n",
" "
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"LetsPlot.setup_html()"
]
},
{
"cell_type": "markdown",
"id": "78a745d4-30e6-4c63-947b-99543875d337",
"metadata": {},
"source": [
"#### 1. Without nudge"
]
},
{
"cell_type": "code",
"execution_count": 3,
"id": "44c46535-64ac-49d2-9a43-76b44d2aa8f1",
"metadata": {
"execution": {
"iopub.execute_input": "2025-11-05T13:41:19.988270Z",
"iopub.status.busy": "2025-11-05T13:41:19.988196Z",
"iopub.status.idle": "2025-11-05T13:41:19.994732Z",
"shell.execute_reply": "2025-11-05T13:41:19.994461Z"
}
},
"outputs": [
{
"data": {
"text/html": [
" \n",
" "
],
"text/plain": [
""
]
},
"execution_count": 3,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"ggplot() + \\\n",
" geom_point(x=0, y=0, size=10, color='#DA8459') + \\\n",
" geom_text(x=0, y=0, label='text without nudge') + \\\n",
" ggsize(400, 300)"
]
},
{
"cell_type": "markdown",
"id": "75564153-0761-456f-ad25-21a9f965ecce",
"metadata": {},
"source": [
"#### 2. Unit Comparison: Pixel, Size, and Identity\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 (`nudge_y=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": "7ee95dd2-7096-4dc0-86d5-c88f75f072f8",
"metadata": {
"execution": {
"iopub.execute_input": "2025-11-05T13:41:19.995478Z",
"iopub.status.busy": "2025-11-05T13:41:19.995404Z",
"iopub.status.idle": "2025-11-05T13:41:20.000221Z",
"shell.execute_reply": "2025-11-05T13:41:19.999970Z"
}
},
"outputs": [
{
"data": {
"text/html": [
" \n",
" "
],
"text/plain": [
""
]
},
"execution_count": 4,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"ggplot() + \\\n",
" xlim(-1, 4) + \\\n",
" geom_point(x=0, y=1, size=5, color='#B9534C') + \\\n",
" geom_text(x=0, y=1, label='identity 0.2', nudge_y=0.2) + \\\n",
" geom_point(x=1, y=1, size=5, color='#DA8459') + \\\n",
" geom_text(x=1, y=1, label='px 40', nudge_y=40, nudge_unit='px') + \\\n",
" geom_point(x=2, y=1, size=30, color='#EEAB65') + \\\n",
" geom_text(x=2, y=1, label='size 15', nudge_y=15, nudge_unit='size') + \\\n",
" geom_point(x=3, y=1, size=30, color='#F6C971') + \\\n",
" geom_text(x=3, y=1, label='size 15 vjust 0', nudge_y=15, vjust=0, nudge_unit='size') + \\\n",
" geom_text(x=3, y=1, label='size -15 vjust 1', nudge_y=-15, vjust=1, nudge_unit='size')"
]
},
{
"cell_type": "markdown",
"id": "343d2dda-6faf-4dcd-95ef-cc95e12b915e",
"metadata": {},
"source": [
"#### 3. Parameter `unit` in `position_nudge()`"
]
},
{
"cell_type": "code",
"execution_count": 5,
"id": "a0c7a82f-7e27-4427-9b88-3282349e2944",
"metadata": {
"execution": {
"iopub.execute_input": "2025-11-05T13:41:20.000976Z",
"iopub.status.busy": "2025-11-05T13:41:20.000903Z",
"iopub.status.idle": "2025-11-05T13:41:20.003973Z",
"shell.execute_reply": "2025-11-05T13:41:20.003734Z"
}
},
"outputs": [
{
"data": {
"text/html": [
" \n",
" "
],
"text/plain": [
""
]
},
"execution_count": 5,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"ggplot() + \\\n",
" geom_point(x=0, y=0, size=50, color='#DA8459') + \\\n",
" geom_point(x=0, y=0, size=20, color='blue', position=position_nudge(0, 25, 'size')) + \\\n",
" geom_text(x=0, y=0, label='position_nudge size 25', position=position_nudge(50, 25, 'size'))"
]
},
{
"cell_type": "markdown",
"id": "75b464e4-129e-4f3a-869c-7ebe0f7f8a0e",
"metadata": {},
"source": [
"#### 4. LiveMap\n",
"There are specific behaviors of nudge on LiveMap:\n",
"\n",
"- `'identity'`: A value of 1 corresponds to 1 degree of latitude or longitude. The offset visually changes when zooming in.\n",
"- `'size'`: Like point size, it follows the `const_size_zoomin` parameter when zooming in.\n",
"- `'px'`: Maintains the offset in pixels regardless of zoom level."
]
},
{
"cell_type": "code",
"execution_count": 6,
"id": "0a99e214-03f0-4425-9d3e-15f1f5b4a5fc",
"metadata": {
"execution": {
"iopub.execute_input": "2025-11-05T13:41:20.004735Z",
"iopub.status.busy": "2025-11-05T13:41:20.004665Z",
"iopub.status.idle": "2025-11-05T13:41:20.006836Z",
"shell.execute_reply": "2025-11-05T13:41:20.006571Z"
}
},
"outputs": [],
"source": [
"layers = geom_point(x=-60, y=30, size=20, color='#B9534C') + \\\n",
" geom_text(x=-60, y=30, label='identity 5', nudge_y=5) + \\\n",
" geom_point(x=-40, y=30, size=20, color='#DA8459') + \\\n",
" geom_text(x=-40, y=30, label='px 40', nudge_y=40, nudge_unit='px') + \\\n",
" geom_point(x=-20, y=30, size=20, color='#EEAB65') + \\\n",
" geom_text(x=-20, y=30, label='size 15', nudge_y=15, nudge_unit='size')\n",
"\n",
"scale_true = ggplot() + \\\n",
" geom_livemap(const_size_zoomin=-1)\n",
" \n",
"scale_false = ggplot() + \\\n",
" geom_livemap(const_size_zoomin=0)"
]
},
{
"cell_type": "code",
"execution_count": 7,
"id": "d1e2bf35-d34b-4371-a400-b20eee45b810",
"metadata": {
"execution": {
"iopub.execute_input": "2025-11-05T13:41:20.007511Z",
"iopub.status.busy": "2025-11-05T13:41:20.007438Z",
"iopub.status.idle": "2025-11-05T13:41:20.012142Z",
"shell.execute_reply": "2025-11-05T13:41:20.011885Z"
}
},
"outputs": [
{
"data": {
"text/html": [
" \n",
" "
],
"text/plain": [
""
]
},
"execution_count": 7,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"gggrid([\n",
" scale_true + layers + ggtitle('Point size: scaled'), \n",
" scale_false + layers + ggtitle('Point size: fixed') \n",
"]) + ggtitle('Try Zooming the Map') + theme(plot_title=element_text(hjust=0.5, size=30)) + ggsize(900, 500)"
]
}
],
"metadata": {
"kernelspec": {
"display_name": "Python 3 (ipykernel)",
"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.10.13"
}
},
"nbformat": 4,
"nbformat_minor": 5
}