Download notebook (.ipynb)

Configuring Nudge Units in Position Adjustments#

The position adjustment position_nudge() now supports the unit parameter that specifies the measurement system for nudge offsets.
Equivalent parameter is also available as nudge_unit in geom_text() and geom_label() directly.

Available Units:

  • 'identity' (default): nudge in data coordinates - a value of 1 corresponds to the distance from 0 to 1 on the axis

  • 'size': nudge relative to point size - a value of 1 corresponds to the diameter of a point with size 1

  • 'px': nudge in fixed pixels - a value of 1 corresponds to 1 pixel

from lets_plot import *
from lets_plot.geo_data import *

The geodata is provided by © OpenStreetMap contributors and is made available here under the Open Database License (ODbL).

LetsPlot.setup_html()

1. Without nudge#

ggplot() + \
    geom_point(x=0, y=0, size=10, color='#DA8459') + \
    geom_text(x=0, y=0, label='text without nudge') + \
    ggsize(400, 300)

2. Unit Comparison: Pixel, Size, and Identity#

The 'size' unit enables precise positioning relative to point dimensions.

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.

ggplot() + \
    xlim(-1, 4) + \
    geom_point(x=0, y=1, size=5, color='#B9534C') + \
    geom_text(x=0, y=1, label='identity 0.2', nudge_y=0.2) + \
    geom_point(x=1, y=1, size=5, color='#DA8459') + \
    geom_text(x=1, y=1, label='px 40', nudge_y=40, nudge_unit='px') + \
    geom_point(x=2, y=1, size=30, color='#EEAB65') + \
    geom_text(x=2, y=1, label='size 15', nudge_y=15, nudge_unit='size') + \
    geom_point(x=3, y=1, size=30, color='#F6C971') + \
    geom_text(x=3, y=1, label='size 15 vjust 0', nudge_y=15, vjust=0, nudge_unit='size') + \
    geom_text(x=3, y=1, label='size -15 vjust 1', nudge_y=-15, vjust=1, nudge_unit='size')

3. Parameter unit in position_nudge()#

ggplot() + \
    geom_point(x=0, y=0, size=50, color='#DA8459') + \
    geom_point(x=0, y=0, size=20, color='blue', position=position_nudge(0, 25, 'size')) + \
    geom_text(x=0, y=0, label='position_nudge size 25', position=position_nudge(50, 25, 'size'))

4. LiveMap#

There are specific behaviors of nudge on LiveMap:

  • 'identity': A value of 1 corresponds to 1 degree of latitude or longitude. The offset visually changes when zooming in.

  • 'size': Like point size, it follows the const_size_zoomin parameter when zooming in.

  • 'px': Maintains the offset in pixels regardless of zoom level.

layers = geom_point(x=-60, y=30, size=20, color='#B9534C') + \
    geom_text(x=-60, y=30, label='identity 5', nudge_y=5) + \
    geom_point(x=-40, y=30, size=20, color='#DA8459') + \
    geom_text(x=-40, y=30, label='px 40', nudge_y=40, nudge_unit='px') + \
    geom_point(x=-20, y=30, size=20, color='#EEAB65') + \
    geom_text(x=-20, y=30, label='size 15', nudge_y=15, nudge_unit='size')

scale_true = ggplot() + \
    geom_livemap(const_size_zoomin=-1)
    
scale_false = ggplot() + \
    geom_livemap(const_size_zoomin=0)

gggrid([
    scale_true + layers + ggtitle('Point size: scaled'), 
    scale_false + layers + ggtitle('Point size: fixed')    
]) + ggtitle('Try Zooming the Map') + theme(plot_title=element_text(hjust=0.5, size=30)) + ggsize(900, 500)