annotation

Makie.annotation Function

annotation(x_target, y_target)
annotation(x_label, y_label, x_target, y_target)
annotation(points_target)
annotation(points_label, points_target)

Annotate one or more target points with a combination of optional text labels and connections between labels and targets, typically in the form of an arrow.

If no label positions are given, they will be determined automatically such that overlaps between labels and data points are reduced. In this mode, the labels should be very close to their associated data points so connection plots are typically not visible.

Plot type

The plot type alias for the annotation function is Annotation.

source

Automatic label placement

If only target points are specified, text label offsets are automatically optimized for less overlap with their data points, each other and the axis boundary.

In this example, you can see how the text recipe results in an unreadable overlap for some labels, while annotation pushes labels apart.

using CairoMakie
f = Figure()

points = [(-2.15, -0.19), (-1.66, 0.78), (-1.56, 0.87), (-0.97, -1.91), (-0.96, -0.25), (-0.79, 2.6), (-0.74, 1.68), (-0.56, -0.44), (-0.36, -0.63), (-0.32, 0.67), (-0.15, -1.11), (-0.07, 1.23), (0.3, 0.73), (0.72, -1.48), (0.8, 1.12)]

fruit = ["Apple", "Banana", "Cherry", "Date", "Elderberry", "Fig", "Grape", "Honeydew",
          "Indian Fig", "Jackfruit", "Kiwi", "Lychee", "Mango", "Nectarine", "Orange"]

limits = (-3, 1.5, -3, 3)

ax1 = Axis(f[1, 1]; limits, title = "text")

scatter!(ax1, points)
text!(ax1, points, text = fruit)

ax2 = Axis(f[1, 2]; limits, title = "annotation")

scatter!(ax2, points)
annotation!(ax2, points, text = fruit)

hidedecorations!.([ax1, ax2])

f

Attributes

algorithm

Defaults to automatic

The algorithm used to automatically place labels with reduced overlaps. The positioning of the labels with a given input may change between non-breaking versions.

align

Defaults to (:center, :center)

The alignment of text relative to the label anchor position.

clipstart

Defaults to automatic

Determines which object is used to clip the path at the start. If set to automatic, the boundingbox of the text label is used.

color

Defaults to @inherit linecolor

The basic color of the connection object. For more fine-grained adjustments, modify the style object directly.

font

Defaults to @inherit font

Sets the font. Can be a Symbol which will be looked up in the fonts dictionary or a String specifying the (partial) name of a font or the file path of a font file.

fonts

Defaults to @inherit fonts

Used as a dictionary to look up fonts specified by Symbol, for example :regular, :bold or :italic.

fontsize

Defaults to @inherit fontsize

The size of the label font.

justification

Defaults to automatic

Sets the alignment of text w.r.t its bounding box. Can be :left, :center, :right or a fraction. Will default to the horizontal alignment in align.

labelspace

Defaults to :relative_pixel

The space in which the label positions are given. Can be :relative_pixel (the positions are given in screen space relative to the target data positions) or :data. If a text label should be positioned somewhere close to the labeled point, :relative_pixel is usually easier to get a consistent visual result. If an arrow is supposed to point from one data point to another, :data is the appropriate choice.

using CairoMakie
g(x) = cos(6x) * exp(x)
xs = 0:0.01:4
ys = g.(xs)

f, ax, _ = lines(xs, ys; axis = (; xgridvisible = false, ygridvisible = false))

annotation!(ax, 1, 20, 2.1, g(2.1),
    text = "(1, 20)\nlabelspace = :data",
    path = Ann.Paths.Arc(0.3),
    style = Ann.Styles.LineArrow(),
    labelspace = :data
)

annotation!(ax, -100, -100, 2.65, g(2.65),
    text = "(-100, -100)\nlabelspace = :relative_pixel",
    path = Ann.Paths.Arc(-0.3),
    style = Ann.Styles.LineArrow()
)

f

lineheight

Defaults to 1.0

The lineheight multiplier.

linewidth

Defaults to 1.0

The default line width for connection styles that have lines

maxiter

Defaults to automatic

The maximum number of iterations that the label placement algorithm is allowed to run.

path

Defaults to Ann.Paths.Line()

One path type or an array of path types that determine how to connect each label to its point. Suitable objects can be found in the module Makie.Ann.Paths.

using CairoMakie
fig = Figure()
ax = Axis(fig[1, 1], yautolimitmargin = (0.3, 0.3), xgridvisible = false, ygridvisible = false)
scatter!(ax, fill(0, 4), 0:-1:-3)
annotation!(-200, 0, 0, 0, path = Ann.Paths.Line(), text = "Line()")
annotation!(-200, 0, 0, -1, path = Ann.Paths.Arc(height = 0.1), text = "Arc(height = 0.1)")
annotation!(-200, 0, 0, -2, path = Ann.Paths.Arc(height = 0.3), text = "Arc(height = 0.3)")
annotation!(-200, 30, 0, -3, path = Ann.Paths.Corner(), text = "Corner()")
fig

shrink

Defaults to (5.0, 7.0)

One tuple or an array of tuples with two numbers, where each number specifies the radius of a circle in screen space which clips the connection path at the start or end, respectively, to add a little bit of visual space between arrow and label or target.

using CairoMakie
fig = Figure()
ax = Axis(fig[1, 1], xgridvisible = false, ygridvisible = false)
shrinks = [(0, 0), (5, 5), (10, 10), (20, 20), (5, 20), (20, 5)]
for (i, shrink) in enumerate(shrinks)
    annotation!(ax, -200, 0, 0, i; text = "shrink = $shrink", shrink, style = Ann.Styles.LineArrow())
    scatter!(ax, 0, i)
end
fig

style

Defaults to automatic

One style object or an array of style objects that determine how the path from a label to its point is visualized. Suitable objects can be found in the module Makie.Ann.Styles.

using CairoMakie
fig = Figure()
ax = Axis(fig[1, 1], yautolimitmargin = (0.3, 0.3), xgridvisible = false, ygridvisible = false)
annotation!(-200, 0, 0, 0, style = Ann.Styles.Line())
annotation!(-200, 0, 0, -1, style = Ann.Styles.LineArrow())
annotation!(-200, 0, 0, -2, style = Ann.Styles.LineArrow(head = Ann.Arrows.Head()))
annotation!(-200, 0, 0, -3, style = Ann.Styles.LineArrow(tail = Ann.Arrows.Line(length = 20)))
fig

text

Defaults to ""

One object or an array of objects that determine the textual content of the labels.

textcolor

Defaults to automatic

The color of the text labels. If automatic, textcolor matches color.

visible

Defaults to true

No docs available.