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
.
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
.
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.