Plotting functions

plot(x[, y, spec; kwargs...])
plot(x1, y1, x2, y2...; kwargs...)
plot(x1, y1, spec1...; kwargs...)

Draw one or more line plots.

Lines are defined by the x and y coordinates of the connected points, given as numeric vectors, and optionally the format string spec that defines the line and marker style and color as in matplotlib.

The y vector can be replaced by a callable that defines the Y coordinates as a function of the X coordinates.

Multiple lines can be defined by pairs of x and y coordinates (and optionally their format strings), passed sequentially as arguments of plot. Alternatively, if various lines have the same X coordinates, their Y values can be grouped as columns in a matrix.

If no spec is given, the series will be plotted as solid lines with a predefined sequence of colors.

Additionally, specifications of lines and markers can be defined by keyword arguments:

• linewidth: line width scale factor.
• markersize: marker size scale factor.
• linecolor: hexadecimal RGB color code for the line.
• markercolor: hexadecimal RGB color code for the markers.

This function can receive a single numeric vector or matrix, which will be interpreted as the Y coordinates; in such case the X coordinates will be a sequence of integers starting at 1.

Examples

# Create example data
x = LinRange(-2, 2, 40)
f(t) = t^3 + t^2 + t
y = f.(x)
# Plot x and y
plot(x, y)
# Plot x using the callable
plot(x, f)
# Plot y, using its indices for the x values
plot(y)
# Plot two columns
plot(x, [y 3x.^2 .- 3])
# Plot various series them with custom line specs
y2 = 3x.^2 .- 3
plot(x, y, "-r", x, y2, ":*b")

oplot(args...; kwargs...)

Draw one or more line plots over another plot.

Equivalent to calling plot after holding the current plot, except that the axes limits are not re-adjusted to the new data.

Examples

# Create example data
x = LinRange(-2, 2, 40)
y = 2 .* x .+ 4
# Draw the first plot
plot(x, y)
# Plot another graph over it
oplot(x, x -> x^3 + x^2 + x)

stairs(x[, y, spec; kwargs...])
stairs(x1, y1, x2, y2...; kwargs...)
stairs(x1, y1, spec1...; kwargs...)

Draw one or more staircase or step plots.

The coordinates and format of the stair outlines are defined as for line plots (cf. plot).

Additionally, the keyword argument where can be used to define where the "stairs" (vertical discontinuities between Y values) shoud be placed:

• where = "pre" to make the steps stop at each point (x[i], y[i]), starting at the previous x coordinate except for the first point.
• where = "post" to make the steps start at each point (x[i], y[i]), stopping at the next x coordinate except for the last point.
• where = "mid" (default) to make the steps go through each point (x[i], y[i]) starting and ending in the middle of the surrounding x-intervals, except for the first and last points.

Examples

# Create example data
x = LinRange(-2, 2, 40)
y = x.^3 .+ x.^2 .+ x
# Plot x and y
stairs(x, y)
# Plot y with indices for x values
stairs(y)
# step directly after x each position
stairs(y, where="pre")
# step between two x positions
stairs(y, where="mid")
# step immediately before x each position
stairs(y, where="post")

plot3(x, y, z[, spec; kwargs...])
plot3(x1, y1, z1, x2, y2, z2...; kwargs...)
plot3(x1, y1, z1, spec1...; kwargs...)

Draw one or more three-dimensional line plots.

Lines are defined by the x, y and z coordinates of the connected points, given as numeric vectors, and optionally the format string spec that defines the line and marker style and color as in matplotlib.

The z vector can be replaced by a callable that defines the Z coordinates as a function of the X and Y coordinates.

Multiple lines can be defined by triplets of x, y and z coordinates (and optionally their format strings), passed sequentially as arguments of plot3.

If no specs are given, the series will be plotted as solid lines with a predefined sequence of colors.

Additionally, specifications of lines and markers can be defined by keyword arguments:

• linewidth: line width scale factor.
• markersize: marker size scale factor.
• linecolor: hexadecimal RGB color code for the line.
• markercolor: hexadecimal RGB color code for the markers.

Examples

# Create example data
x = LinRange(0, 30, 1000)
y = cos.(x) .* x
z = sin.(x) .* x
# Draw a solid line and another with star markers
# in one of every 10 points
plot3(x, y, z, x[1:10:end], y[1:10:end], z[1:10:end], "p")

polar(angle, radius[, spec; kwargs...])

Draw one or more polar plots.

The first coordinate the represents the angle, and the second the radius of the line points. The rest is defined as for line plots, except that the first variable (angle) is always required. (cf. plot).

The first variable is by default considered to be radians, and the angular labels of the grid are shown as factors of π. Use the keyword argument radians = false to pass and show angles in degrees.

Examples

# Create example data
angles = LinRange(0, 360, 40)
radii = LinRange(0, 2, 40)
# Draw the polar plot in degrees
polar(angles, radii, radians=false)

scatter(x[, y, size, color; kwargs...])

Draw a scatter plot.

Points are defined by their x and y coordinates, given as numeric vectors. Additionally, values for markers' size and color can be provided. Size values will determine the marker size in percent of the regular size, and color values will be used in combination with the current colormap.

The last variable can be replaced by a callable that defines it as a function of the previous variables.

This function can receive a single numeric vector or matrix, which will be interpreted as the Y coordinates; in such case the X coordinates will be a sequence of integers starting at 1.

Examples

# Create example data
x = LinRange(0, 1, 11)
y = LinRange(0, 1, 11)
s = LinRange(50, 400, 11)
c = LinRange(0, 255, 11)
# Plot the points with increasing size and color
scatter(x, y, s, c)

scatter3(x, y, z[, color; kwargs...])

Draw a three-dimensional scatter plot.

Points are defined by their x, y and z coordinates, given as numeric vectors. Additionally, values for markers' color can be provided, which will be used in combination with the current colormap.

The last variable can be replaced by a callable that defines it as a function of the previous variables.

Examples

# Create example data
x = 2 .* rand(100) .- 1
y = 2 .* rand(100) .- 1
z = 2 .* rand(100) .- 1
c = 999 .* rand(100) .+ 1
# Plot the points with colors
scatter3(x, y, z, c)

stem(x[, y, spec; kwargs...])
stem(x1, y1, x2, y2...; kwargs...)
stem(x1, y1, spec1...; kwargs...)

Draw a stem plot

The coordinates and format of the stems and markers are defined as for line plots (cf. plot).

Additionally, the keyword argument baseline can be used to define the Y coordinate where stems should start from.

Examples

# Create example data
x = LinRange(-2, 2, 40)
y = x.^3 .+ x.^2 .+ x .+ 6
# Plot x and y, with dashed stems ended in a star
stem(x, y, "--p")
# Move the baseline to 5
stem(x, y, baseline = 5)

errorbar(x, y, err[, spec; kwargs...])
errorbar(x, y, errlow, errhigh[, spec; kwargs...])

Draw a series of error bars.

Error bars are defined by their x and y coordinates, and the size of the error bars at either of each (x, y) point. For symmetric error bars, only a vector err is required, such that their total size will be 2 .* err. For asymmetric error bars, two vectors errlow and errhigh are required, such that the size of the error bars will be errlow .+ errhigh.

The optional format string spec defines the style and color of the lines of error bars and the markers at (x, y), as in matplotlib. If no specs are given, the error bars will be plotted as solid lines with a predefined sequence of colors, without markers.

Additionally, the following keyword arguments can be used to modify the aspect of the error bars:

• linewidth::Float64: line width scale factor.
• markersize::Float64: marker size scale factor.
• linecolor: hexadecimal RGB color code for the line.
• horizontal::Bool: set it to true to draw horizontal error bars).
• capwidth: fixed value of the width of the bar "caps", in units of the X axis (or Y axis if horizontal is true). If it is not given, the cap width will be automatically adjusted to 0.3 times the mean separation between data points.

Examples

# Create example data
x = LinRange(-2, 2, 10)
y = x.^3 .+ x.^2 .+ x .+ 6
err = LinRange(0.5, 3, 10)
# Draw symmetric, horizontal error bars
errorbar(x, y, err, horizontal=true)
# Draw asymmetric error bars with markers
errorbar(x, y, err, err./2, "-o")

bar(labels, heights; kwargs...)
bar(heights; kwargs...)

Draw a bar plot.

If no specific labels are given, the bars are labelled with integer numbers starting from 1.

If heights is a matrix, each column is taken as a different set of data, which are represented as bars of different colors. Use the keyword argument barposition with the values "grouped" (default) or "stacked" to control if the bars are positioned side by side or stacked on top of the previous series.

The keyword arguments barwidth, baseline and horizontal can also be used to modify the aspect of the bars, which by default is:

• barwidth = 0.8 (80% of the separation between bars).
• baseline = 0.0 (bars starting at zero).
• horizontal = false (vertical bars)

The color of the bars is selected automatically, unless a specific hexadecimal RGB color code is given through the keyword argument color.

Examples

# Create example data (continent population in million people)
continents = ["Africa", "America", "Asia", "Europe", "Oceania"]
population_1960 = [285, 425, 1687, 606, 16]
population_2010 = [1044, 944, 4170, 735, 36]
population_matrix = [population_1960 population_2010]
# Plot with respect to 500 millions of people
barplot(continents, population_matrix, baseline=500)
legend("1960", "2010") # add legend

quiver(x, y, u, v[, spec; kwargs...])

Draw a vector field at points (x,y) with arrows of size (u,v).

The style and color of the arrow lines and – optionally – the markers drawn at the (x,y) points can be configured through the format string spec and keyword arguments, as in plot and other functions.

Use the keyword arguments arrowscale and headsize to give a scale factor for the size of the arrows and their heads.

Examples

# Create example data
x = repeat(LinRange(-2, 2, 20), inner=10)
y = repeat(LinRange(-1, 1, 10), outer=20)
u = x .* (x.^2 .+ y.^2)
v = y .* (x.^2 .+ y.^2)
# Plot arrows
quiver(x, y, u, y, arrowscale=0.1)
# Expand the y-axes to see the whole arrows
ylim(-1.15, 1.15)

quiver3(x, y, z, u, v, w[, spec; kwargs...])

Draw a three-dimensional vector field at points (x,y,z) with arrows of size (u,v,w).

The style and color of the arrow lines and – optionally – the markers drawn at the (x,y,z) points can be configured through the format string spec and keyword arguments, as in plot and other functions.

Use the keyword argument arrowscale to give a scale factor for the size of the arrows.

Examples

# Create example data
x = repeat(LinRange(-2, 2, 20), inner=10)
y = repeat(LinRange(0, pi, 10), outer=20)
z = sin.(x) .+ cos.(y)
u = 0.1ones(200)
v = zeros(200)
w = 0.5z
# Plot vectors
quiver3(x, y, z, u, v, w, "o", markersize=0.5)

histogram(data; kwargs...)

Draw a histogram of data.

The following keyword arguments can be supplied:

• nbins: Number of bins; by default, or if a number smaller than 1 is given, the number of bins is computed as 3.3 * log10(n) + 1, with n being the number of elements in data.
• horizontal: whether the histogram should be horizontal (false by default).
• color: hexadecimal RGB color code for the bars.

Examples

# Create example data
data = 2 .* randn(100) .- 1
# Draw the histogram with 19 bins
histogram(data, nbins=19)
# Horizontal histogram with log scale
histogram(data, horizontal=true, xlog=true)

polarhistogram(data; kwargs...)

Draw a polar histogram of angle values contained in data.

The following keyword arguments can be supplied:

• nbins: Number of bins; by default, or if a number smaller than 1 is given, the number of bins is computed as 3.3 * log10(n) + 1, with n being the number of elements in data.
• radians: Set this argument to false to pass and show the angles as degrees. By default, data is assumed to be radians and the angular labels of the grid are presented as factors of π.
• fullcircle: Set this argument to true to scale the angular coordinates of the histogram and make the bars span over the whole circle.
• color: hexadecimal RGB color code for the bars.

Examples

# Create example data
data = randn(100)
# Draw a polar histogram with 19 bins
polarhistogram(data, nbins = 19, fullcircle=true)

hexbin(x, y; kwargs...)

Draw a hexagon binning plot.

Hexagonal binning and the the current colormap are used to display a bi-dimensional series of points given by x and y. The number of bins is 40 by default; use the keyword argument nbins to set it as a different number.

Examples

# Create example data
x = randn(100_000)
y = randn(100_000)
# Draw the hexbin plot
hexbin(x, y)

contour([x, y,] z; kwargs...)

Draw a contour plot.

The current colormap is used to display a either a series of points or a two-dimensional array as a contour plot. It can receive one of the following:

• x values, y values and z values.
• M sorted values of the x axis, N sorted values of the y axis, and a set of z values on a N×M grid.
• M sorted values of the x axis, N sorted values of the y axis, and a callable to determine z values.
• z values on a N×M grid, with the x and y axes defined as the indices of the columns and rows of the grid, respectively.

If a series of points is passed to this function, their values will be interpolated on a grid. For grid points outside the convex hull of the provided points, a value of 0 will be used.

Contour lines are colored by default, using the current colormap as color scale. Colored lines can be disabled by removing the color bar (with keyword argument colorbar == false).

The following keyword arguments can be provided to set the number and aspect of the contour lines:

• levels::Int, the number of contour lines that will be fitted to the data (20 by default).
• majorlevels::Int, the number of levels between labelled contour lines (no labels by default for colored lines, all lines labelled by default if color is removed).

Examples

# 1. Create example point data
x = 8 .* rand(100) .- 4
y = 8 .* rand(100) .- 4
z = sin.(x) + cos.(y)
# Contour plot on the left without color (lines labelled by default)
subplot(1, 2, 1)
contour(x, y, z, colorbar = false)
# 2. Create example grid data with a callable
x = LinRange(-2, 2, 40)
y = LinRange(0, pi, 20)
f(x, y) = sin(x) + cos(y)
# Contour plot on the right with color
# and explicit labels every three lines
subplot(1, 2, 2)
contour(x, y, f, majorlevels = 3)

contourf([x, y,] z; kwargs...)

Draw a filled contour plot.

The current colormap is used to display a either a series of points or a two-dimensional array as a filled contour plot. It can receive one of the following:

• x values, y values and z values.
• M sorted values of the x axis, N sorted values of the y axis, and a set of z values on a N×M grid.
• M sorted values of the x axis, N sorted values of the y axis, and a callable to determine z values.
• z values on a N×M grid, with the x and y axes defined as the indices of the columns and rows of the grid, respectively.

If a series of points is passed to this function, their values will be interpolated on a grid. For grid points outside the convex hull of the provided points, a value of 0 will be used.

The following keyword arguments can be provided to set the number and aspect of the contour lines:

• levels::Int, the number of contour lines that will be fitted to the data (20 by default).
• majorlevels::Int, the number of levels between labelled contour lines (no labels by default).

Examples

# 1. Create example point data
x = 8 .* rand(100) .- 4
y = 8 .* rand(100) .- 4
z = sin.(x) + cos.(y)
# Contour plot
contourf(x, y, z)
# 2. Create example grid data with a callable
x = LinRange(-2, 2, 40)
y = LinRange(0, pi, 20)
f(x, y) = sin(x) + cos(y)
# Contour plot with 25 lines, labelling a quarter of them
contourf(x, y, f, levels = 25, majorlevels = 4)

tricont(x, y, z; kwargs...)

Draw a triangular contour plot.

The current colormap is used to display a series of points as a triangular contour plot. z values are interpolated between x and y values through Delaunay triangulation.

The number of contour lines can be set by the keyword argument levels (by default levels = 20).

Examples

# Create example point data
x = 8 .* rand(100) .- 4
y = 8 .* rand(100) .- 4
z = sin.(x) + cos.(y)
# Tricontour plot
tricont(x, y, z)

surface([x, y,] z; kwargs...)

Draw a three-dimensional surface plot.

Either a series of points or a two-dimensional array is drawn as a surface plot, colored according to the Z coordinates and the current colormap. It can receive one of the following:

• x values, y values and z values.
• M sorted values of the x axis, N sorted values of the y axis, and a set of z values on a N×M grid.
• M sorted values of the x axis, N sorted values of the y axis, and a callable to determine z values.
• z values on a N×M grid, with the x and y axes defined as the indices of the columns and rows of the grid, respectively.

If a series of points is passed to this function, their values will be interpolated on a grid. For grid points outside the convex hull of the provided points, a value of 0 will be used.

Examples

# Create example grid data
x = LinRange(-2, 2, 40)
y = LinRange(0, pi, 20)
z = sin.(x') .+ cos.(y)
# Surface plot
surface(x, y, z)

tricont(x, y, z; kwargs...)

Draw a triangular surface plot.

Either a series of points or a two-dimensional array is drawn as a triangular surface plot. z values are interpolated between x and y values through Delaunay triangulation.

Examples

# Create example point data
x = 8 .* rand(100) .- 4
y = 8 .* rand(100) .- 4
z = sin.(x) + cos.(y)
# Tricontour plot
tricont(x, y, z)

wireframe([x, y,] z; kwargs...)

Draw a three-dimensional wireframe plot.

Either a series of points or a two-dimensional array is drawn as a wireframe plot. It can receive one of the following:

• x values, y values and z values.
• M sorted values of the x axis, N sorted values of the y axis, and a set of z values on a N×M grid.
• M sorted values of the x axis, N sorted values of the y axis, and a callable to determine z values.
• z values on a N×M grid, with the x and y axes defined as the indices of the columns and rows of the grid, respectively.

Also use the attributes color and linecolor to set the color of the surface and lines of the mesh, as RGB hexadecimal color values.

If a series of points is passed to this function, their values will be interpolated on a grid. For grid points outside the convex hull of the provided points, a value of 0 will be used.

Examples

# Create example grid data
x = LinRange(-2, 2, 40)
y = LinRange(0, pi, 20)
z = sin.(x') .+ cos.(y)
# Wireframe plot
wireframe(x, y, z)

volume(v; kwargs...)

Draw a the three-dimensional array v, using volume rendering.

The volume data is reduced to a two-dimensional image using an emission or absorption model, or by a maximum intensity projection. After the projection the current colormap is applied to the result.

The method to reduce volume data can be defined by the keyword argument algorithm –- a number or a string from the following table:

Examples

# Create example data
x = LinRange(-1, 1, 40)
y = LinRange(-1, 1, 40)
z = LinRange(-1, 1, 40)
v = 1 .- (x.^2 .+ y'.^2 .+ reshape(z,1,1,:).^2).^0.5 - 0.25 .* rand(40, 40, 40)
# Draw the 3d volume data using an emission model
volume(v, algorithm="mip")

heatmap([x, y,] data; kwargs...)

Draw a heatmap.

The current colormap is used to display a two-dimensional array data as a heatmap.

If data is an N×M array, the cells of the heatmap will be plotted in a grid of rectangular cells, whose edges are defined by the coordinates x (a sorted vector with M+1 values) and y (a sorted vector with N+1 values).

If x and y are not given, a uniform grid is drawn spanning the interval [1, M+1] in the X-axis, and [1, N+1] in the Y-axis.

The array is drawn with its first value in the bottom left corner, so in some cases it may be neccessary to flip the axes.

By default column and row indices are used for the x- and y-axes, respectively, so setting the axis limits is recommended. Also note that the values in the array must lie within the current z-axis limits so it may be neccessary to adjust these limits or clip the range of array values.

Examples

# Uniform heatmap on the left
subplot(1,2,1)
x = LinRange(-2, 2, 40)
y = LinRange(0, pi, 20)
z = sin.(x') .+ cos.(y)
heatmap(z)
# Non uniform heatmap on the right
subplot(1,2,2)
x = [0, 2, 3, 4.5, 5]
y = [2, 3, 4.5, 5, 6, 8]
z = rand(5, 4)
heatmap(x, y, z)

polarheatmap(data; kwargs...)

Draw a polar heatmap

The current colormap is used to display a two-dimensional array data as a polar heatmap.

If data is an N×M array, the cells of the matrix will be plotted in a circle divided in M angular sectors and N rings, such that the values of the first row will be concentrated in the center of the circle, and the following rows will be drawn in increasing concentric rings. The columns of the array are drawn as radii of the circle in a counterclockwise order, starting and ending in horizontal axis pointing to the right.

Examples

# Create example data
angle = LinRange(0, 2π, 40)
radius = LinRange(0, 10, 20)
z = sin.(angle') .* cos.(radius)
polarheatmap(z)

shade(x, y; kwargs...)

Draw a point- or line-based heatmap.

The current colormap is used to display the footprint left by the pairs of x, y values. If the data contain NaN or missing, the footprints will be based on lines separated by those values. Otherwise the footprints will be based on points. The type of footprint can be enforced regardless of the input by the keyword argument footprint = "lines" or footprint = "points".

The value of that footprint is determined by a transformation that can be adjusted by the keyword argument xform –- a number or a string from the following table:

Examples

# Create line data with NaN as polyline separator
x = [randn(10000); NaN; randn(10000) .+ 5 ]
y = [randn(10000); NaN; randn(10000) .+ 5]
# Draw shade
shade(x, y, xform="loglog")

imshow(img; kwargs...)
imshow(img, (minval, maxval); kwargs...)

Draw an image, defined by any of the following:

• A string with a valid file name of an image.
• A 3-dimensional H×W×C array, which will be drawn as an image W pixels wide and H pixels high, with C channels (3 or 4), corresponding to RGB or RGBA values between 0 and 1.
• A matrix of values, which will be drawn with a hue corresponding to their relative position in the current colormap. The range of values mapped in the colormap is by default [0, 1], but can be set to an arbitrary range between minval and maxval. Setting either limit to nothing will cause it to be automatically determined based on the data.

Examples

# Create an image
x = LinRange(-3, 3, 150)
y = LinRange(-2, 2, 100)
# RGB values
r = (1 .+ cos.(atan.(y, x')))/2
g = (1 .+ sin.(atan.(y, x')))/2
b = exp.(-(x'.^2 .+ y.^2)/4)
data = cat(r, g, b, dims=3)
# Draw the image
imshow(data)

isosurface(data, isovalue; kwargs...)

Draw an isosurface determined by the region of the three-dimensional array data around a given isovalue.

The isosurface is calculated so that values in data greater than isovalue are considered to be outside the surface, and the values lower than isovalue are inside the surface.

The color of the isosurface can be chosen with the keyword argument color, with the hexadecimal RGB color code.

Examples

# Create example data
s = LinRange(-4, 4, 50)
v = cos.(s) .+ cos.(s)' .+ cos.(reshape(s,1,1,:))
# Draw the isosurface
isosurface(v, 0.5, color=0x99ffcc)

annotations(x, y, s; kwargs...)

Add one ore more text annotations to the current plot.

x and y can be scalars or vectors of coordinates, and s a string or a vector of strings, respectively. Annotations are only available for 2-D plots.

By default the coordinates indicate the lower left corner of the text box. This can be changed by the following keyword arguments:

• halign for the horizontal alignment ("left", "center" or "right").
• valign for the vertical alignment ("bottom", "center" or "top").

Use the keyword argument wc = false if x and y are expressed in normalized device coordinates, instead of world coordinates – which is the default.

Examples

# Create example data
numbers = [10, 15, 35, 20]
# Plot bars with labels on top
barplot(numbers)
annotations(1:4, numbers .+1 , string.(numbers), halign="center")