Simple Examples


These examples are available as Jupyter notebooks. You can execute them online with binder or just view them with nbviewer by clicking on the badges above!

These examples show what Unitful recipes are all about.

First we need to tell Julia we are using Unitful and Plots

using Unitful, Plots

Simplest plot

This is the most basic example

y = randn(10)*u"kg"

Add some more plots, and it will be aware of the units you used previously (note y2 is about 10 times smaller than y1)

y2 = 100randn(10)*u"g"

Unitful recipes will not allow you to plot with different unit-dimensions, so


won't work here.

But you can add inset subplots with different axes that have different dimensions

plot!(rand(10)*u"m", inset=bbox(0.5, 0.5, 0.3, 0.3), subplot=2)

Axis label

If you specify an axis label, the unit will be appended to it.

plot(y, ylabel="mass")

Unless you want it untouched, in which case you can use a "protected" string using the @P_str macro.

plot(y, ylabel=P"mass in kilograms")

Just like with the label keyword for legends, no axis label is added if you specify the axis label to be an empty string.

plot(y, ylabel="")

Unit formatting

If you prefer some other formatting over the round parentheses, you can supply a keyword unitformat, which can be a number of different things:

unitformat can be a boolean or nothing:

plot([plot(y, ylab="mass", title=repr(s), unitformat=s) for s in (nothing, true, false)]...)

unitformat can be one of a number of predefined symbols, defined in

URsymbols = if isdefined(Base, :get_extension)
     getproperty(Base.get_extension(Plots, :UnitfulExt), :UNIT_FORMATS)
end |> keys
KeySet for a Dict{Symbol, Any} with 11 entries. Keys:

which correspond to these unit formats:

plot([plot(y, ylab="mass", title=repr(s), unitformat=s) for s in URsymbols]...)

unitformat can also be a Char, a String, or a Tuple (of Chars or Strings), which will be inserted around the label and unit depending on the length of the tuple:

URtuples = [", in ", (", in (", ")"), ("[", "] = (", ")"), ':', ('$', '$'), (':', ':', ':')]
plot([plot(y, ylab="mass", title=repr(s), unitformat=s) for s in URtuples]...)

For extreme customizability, you can also supply a function that turns two arguments (label, unit) into a string:

formatter(l, u) = string("\$\\frac{\\textrm{", l, "}}{\\mathrm{", u, "}}\$")
plot(y, ylab="mass", unitformat=formatter)

Axis unit

You can use the axis-specific keyword arguments to convert units on the fly

plot(y, yunit=u"g")

Axis limits and ticks

Setting the axis limits and ticks can be done with units

x = (1:length(y)) * u"μs"
plot(x, y, ylims=(-1000u"g",2000u"g"), xticks = x[[1,end]])

or without

plot(x, y, ylims=(-1,2), xticks=1:3:length(x))

Multiple series

You can plot multiple series as 2D arrays

x, y = rand(10,3)*u"m", rand(10,3)*u"g"
plot(x, y)

Or vectors of vectors (of potentially different lengths)

x, y = [rand(10), rand(15), rand(20)]*u"m", [rand(10), rand(15), rand(20)]*u"g"
plot(x, y)


It works in 3D

x, y = rand(10)*u"km", rand(10)*u"hr"
z = x ./ y
plot(x, y, z)


For which colorbar limits (clims) can have units

heatmap((1:5)u"μs", 1:4, rand(5,4)u"m", clims=(0u"m", 2u"m"))

Scatter plots

You can do scatter plots

scatter(x, y, zcolor=z, clims=(5,20).*unit(eltype(z)))

and 3D scatter plots too

scatter(x, y, z, zcolor=z)

Contour plots

for contours plots

x, y = (1:0.01:2)*u"m", (1:0.02:2)*u"s"
z = x' ./ y
contour(x, y, z)

and filled contours, again with optional clims units

contourf(x, y, z, clims=(0u"m/s", 3u"m/s"))