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 specs are given, the series will be plotted as solid lines with a predefined sequence of colors.

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)

stair(x[, y, spec; kwargs...])
stair(x1, y1, x2, y2...; kwargs...)
stair(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
stair(x, y)
# Plot y with indices for x values
stair(y)
# step directly after x each position
stair(y, where="pre")
# step between two x positions
stair(y, where="mid")
# step immediately before x each position
stair(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. Alternatively, if various lines have the same X and Y coordinates, their Y values can be grouped as columns in a matrix.

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

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)

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.

Use the keyword arguments barwidth, baseline or horizontal 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)

Examples

# Create example data (continent population in million people)
population = Dict("Africa" => 1216,
                 "America" => 1002,
                 "Asia" => 4436,
                 "Europe" => 739,
                 "Oceania" => 38)
# Plot data in "normal" bars
barplot(keys(population), values(population))
# Plot with respect to 1,000 millions of people
barplot(keys(population), values(population), baseline=1000)
# Horizontal bars
barplot(keys(population), values(population), horizontal=true)

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

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.

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.

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.

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.

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.

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, which can be one of the following:

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=2)

heatmap(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 an uniform grid of square cells,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 columns.

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

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

shade(x, y; kwargs...)

Draw a point- or line-based heatmap.

The current colormap is used to display a series of points or polylines. For line data, NaN values can be used as separator.

Points and lines leave a footprint on the plane that is represented by colors. The value of that footprint is determined by a transformation that can be adjusted by the keyword argument xform.

The available transformation types are:

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=3)

imshow(img; kwargs...)

Draw an image.

The input img can be either a string with a valid file name of an image, or a matrix of values between 0 and 1, which will be drawn with a hue corresponding to the relative position of each value in the current colormap.

Examples

# Create an image
x = LinRange(-3, 3, 150)
y = LinRange(-2, 2, 100)
data = (sin.(exp.(x'.^2 .+ y.^2)) .+ sin.(x') .+ cos.(y) .+ 3) ./ 6
# Draw the image as a color scale
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 = (r, g, b), with the red, green and blue values (between 0 and 1).

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=(0.6, 1.0, 0.85))