Plot attributes

The following functions can be used to modify existing plots, adding titles and other textual guides, changing their dimensions, colors, etc.

The majority of those attributes can also be defined at the time of the creation of the plot, adding a keyword argument with the name of the corresponding function and the value of its argument, e.g. plot(x, y, grid=false). That option is commented in the descriptions of the functions that support it.

Texts with LaTeX expressions

Attributes with text like titles, axis guides and legends accept strings with UTF-8 characters and LaTeX expressions. The package LaTeXStrings can be used to reduce the burden of writing escape sequences in LaTeX expressions.

Titles

GRUtils.titleFunction
title(s)

Set the plot title as the string s.

Use the keyword argument title=s in plotting functions, to set the title during the creation of plots.

Examples

# Set the plot title to "Example Plot"
title("Example Plot")
# Clear the plot title
title("")
source

Axis guides

GRUtils.gridFunction
grid(flag::Bool)

Draw or disable the grid of the current plot axes.

Use the keyword argument grid=<true/false>, etc. in plotting functions, to set the grid during the creation of plots.

source
GRUtils.xlabelFunction
xlabel(s)
ylabel(s)
zlabel(s)

Set the X, Y or Z axis labels as the string s.

Use the keyword argument xlab=s, etc. in plotting functions, to set the axis labels during the creation of plots.

Examples

# Set the x-axis label to "x"
xlabel("x")
# Clear the y-axis label
ylabel("")
source
GRUtils.xticksFunction
xticks(minor[, major = 1])
yticks(minor[, major = 1])
zticks(minor[, major = 1])

Set the minorintervals of the ticks for the X, Y or Z axis, and (optionally) the number of minor ticks between major ticks.

Use the keyword argument xticks=(minor, major), etc. in plotting functions, to set the tick intervals during the creation of plots (both the minor and major values are required in this case).

Examples

# Minor ticks every 0.2 units in the X axis
xticks(0.2)
# Major ticks every 1 unit (5 minor ticks) in the Y axis
yticks(0.2, 5)
source
GRUtils.xticklabelsFunction
xticklabels(f)
yticklabels(f)

Customize the string of the X and Y axes tick labels.

The labels of the tick axis can be defined by a function with one argument (the numeric value of the tick position) that returns a string, or by an array of strings that are located sequentially at X = 1, 2, etc.

Use the keyword argument xticklabels=s, etc. in plotting functions, to set the axis tick labels during the creation of plots.

Examples

# Label the range (0-1) of the Y-axis as percent values
yticklabels(p -> Base.Printf.@sprintf("%0.0f%%", 100p))
# Label the X-axis with a sequence of strings
xticklabels(["first", "second", "third"])
source

Axis dimensions

GRUtils.xlimFunction
xlim(inf, sup [, adjust::Bool = false])
xlim((inf, sup), ...)
ylim(inf, sup, ...)
ylim((inf, sup), ...)
zlim(inf, sup, ...)
zlim((inf, sup), ...)

Set the limits for the plot axes.

The axis limits can either be passed as individual arguments or as a tuple of (inf, sup) values. Setting either limit to nothing will cause it to be automatically determined based on the data, which is the default behavior.

Additionally to the limits, the flag adjust can be used to tell whether or not the limits have to be adjusted.

Use the keyword argument xlim=(inf, sup), etc. in plotting functions, to set the axis limits during the creation of plots.

Examples

# Set the x-axis limits to -1 and 1
xlim((-1, 1))
# Reset the x-axis limits to be determined automatically
xlim()
# Set the y-axis upper limit and set the lower limit to 0
ylim((0, nothing))
# Reset the y-axis lower limit and set the upper limit to 1
ylim((nothing, 1))
source
GRUtils.aspectratioFunction
aspectratio(r)

Set the aspect of the current plot to a given width : height ratio.

Use the keyword argument aspectratio=r, etc. in plotting functions, to set the aspect ratio during the creation of plots.

Examples

# Create example data
x = LinRange(-2, 2, 40)
y = x.^3 .+ x.^2 .+ x
# Draw a plot with panoramic ratio (16:9)
plot(x, y)
aspectratio(16/9)
source
GRUtils.zoomFunction
zoom(r)

Zoom the plot by the ratio indicated by r.

In two-dimensional plots, the "zoomed" axes are centered around the same point, but proportionally resized to r times the original size.

In three-dimensional scenes defined with "camera" settings (e.g. in isosurface plots), the camera distance is divided by r.

Examples

# Reduce the axes to half their size
zoom(0.5)
source
GRUtils.panzoomFunction
panzoom(x, y[, s = 0])

Pan/zoom the axes of the current plot.

The focus of the zoom is set at a point with an offset of (x, y) units in normalized device coordinates (NDC) from the center of the current axes. The corners of the axes are linearly displaced towards that point, such that the size of the new axes is s times their original size.

If s is set to 0 (the default value), the center of the axes is displaced at the focus, without resizing-

Example

# Move the center 1 unit right and 0.2 up (NDC)
panzoom(1, 0.2)
# Reduce the focus of the axes to half their size
# focusing on the previous point
panzoom(1, 0.2, 0.5)
source

3-D views

GRUtils.viewpointFunction
viewpoint(rotation, tilt)

Set the viewpoint of three-dimensional plots.

rotation and tilt must be integer values that indicate the "azimuth" and "elevation" angles of the line of sight (in degrees).

If both angles are zero, the plot is viewed in the direction of the Y axis (i.e. the X-Z plane is seen). Positive rotation values mean a counterclockwise rotation of the line of sight (or a clockwise rotation of the scene) around the vertical (Z) axis. Positive tilt values mean an ascension of the view point.

Examples

# Reset the view to the X-Y plane
# (rotation=0, tilt=90)
viewpoint(0, 90)
source
GRUtils.rotateFunction
rotate(angle::Int)

Rotate the viewpoint of the current plot by angle degrees around the vertical axis of the scene, with respect to its current position.

Examples

# Rotate 10 degrees to the right
rotate(10)
source
GRUtils.tiltFunction
tilt(angle::Int)

Tilt (elevate) the viewpoint of the current plot by angle degrees over the horizontal plane, with respect to its current position.

Examples

# Tilt 10 degrees up
tilt(10)
source
GRUtils.movefocusFunction
movefocus(target)

Rotate the camera view axis, moving the focus to the target point.

This only affects 3-D scenes created with camera settings, e.g. isosurface plots. Moving the focus point rotates the camera without changing its position; in order to rotate the camera around the center of the scene, use the functions rotate, tilt or viewpoint.

Examples

# Move the focus to the point (1.0, 0.5, 0.0)
movefocus([1.0, 0.5, 0.0])
source
GRUtils.turncameraFunction
turncamera(angle)

Turn the orientation of the camera by angle degrees around its view axis (only for 3-D scenes created with camera settings).

Examples

# Turn the perspective 10 degrees
turncamera(10)
source

Axis scales

GRUtils.xflipFunction
xflip(flag)
yflip(flag)
zflip(flag)

Reverse the direction of the X-, Y- or Z-axis (flag == true), or set them back to their normal direction (flag == false ).

Use the keyword argument xflip=<true/false>, etc. in plotting functions, to set reversed axes during the creation of plots.

Examples

# Reverse the x-axis
xflip(true)
# Ensure that the y-axis is not reversed
yflip(false)
source
GRUtils.xlogFunction
xlog(flag)
ylog(flag)
zlog(flag)

Set the X-, Y- or Z-axis to be drawn in logarithmic scale (flag == true), or in linear scale (flag == false).

Use the keyword argument xlog=<true/false>, etc. in plotting functions, to set the logarithmic axes during the creation of plots.

Note

When the axis is set to logarithmic scale, its lower limit is adjusted to represent only positive values, even if the data of the plot contain zero or negative values. The aspect of logarithmic axes with limits explicitly set to contain negative values (with xlim, etc.) is undefined.

Examples

# Set the x-axis limits to log scale
xlog(true)
# Ensure that the y-axis is in linear scale
ylog(false)
source
GRUtils.radiansFunction
radians(flag::Bool)

Set the scale of angles in polar plots.

Use radians(true) to represent angles in radians (default setting), and radians(false) to represent them in degrees.

This operation only modifies the guides of the polar plot grid lines. The existing geometries are left without changes

Use the keyword argument radians=<true/false>, etc. in plotting functions, to set the scale of angles during the creation of polar plots.

Example

# Example data
θ = LinRange(0, 2π, 40)
r = sin.(θ)
# Draw the polar plot (by default in radians)
polar(θ, r)
# Change the angula scale
radians(false)
source

Geometry guides

GRUtils.legendFunction
legend(labels...; kwargs...)

Set the legend of the plot, using a series of labels (strings).

In addition to the legend strings, the keyword argument location can be used to define the location of the legend with respect to the plot axes and the keyword argument maxrows to distribute the legend labels in a grid with a maximum number of rows.

Locations are defined as a number or a string, as indicated in the following table –- based on the convention of Matplotlib legends:

⁣#String
0"none"
1"upper right"
2"upper left"
3"lower left"
4"lower right"
5"right"
6"center left"
7"center right"
8"lower center"
9"upper center"
10"center"
11"outer upper right"
12"outer center right"
13"outer lower right"

The labels are assigned to the geometries contained in the plot, in the same order as they were created. The assignment can be restricted to specific kinds of geometries through the keyword argument kinds, which can take a Symbol or a collection of Symbols that identify the kinds. Use the helper function geometrykinds to see the list of kinds available in the current plot.

Only geometries with non-empty labels and an available guide for legends will be presented in the legend.

Examples

# Set the legends to "a" and "b"
legend("a", "b")
source
GRUtils.geometrykindsFunction
geometrykinds([p])

Return a list with symbols that represent the kind of the geometries included in the given plot or figure p.

If no argument is given, it takes the current plot of the current figure.

Examples

julia> # Plot a set of points at values `(x, y)`
julia> # and a regression line passing through `(x, ŷ)`
julia> scatter(x, y)
julia> plot(x, ŷ)
julia> geometrykinds()
2-element Array{Symbol,1}:
 :scatter
 :line
source
GRUtils.colorbarFunction
colorbar(flag::Bool)
colorbar(levels::Integer)

Set the color bar of the current plot.

The input argument can be a Bool (true or false) to show or hide the colorbar – if it is available, or an Integer to set the number of levels shown in the color bar (256 levels by default).

Color bars are only presented when there is actual color data in the plot, regardless of the usage of this function.

Use the keyword argument colorbar=<true/false>, etc. in plotting functions, to enable or disable the color bar during the creation of plots.

source

Colors

GRUtils.backgroundFunction
background(color[, alpha])

Add a custom background color to the current figure.

The argument can be an hexadecimal color code or nothing for a transparent background. A partially transparent color can be defined adding the alpha value between 0 and 1 as second argument.

Use the keyword arguments backgroundcolor and backgroundalpha in plotting functions, to set a particular background color configuration during the creation of plots.

This overrides the default background defined by the colorscheme for the area outside the axes and legends of all the plots contained in the figure. Use background! to modify the background of individual subplots.

Examples

# Create a plot with light blue background
plot(x, y, backgroundcolor=0x88ccff)
# Remove the background
background(nothing)
source
GRUtils.background!Function
background!(p, bgcolor[, alpha])

Add a custom background color to the given plot object or to all the plots inside the given figure. See background for more details.

source
GRUtils.colormapFunction
colormap(cmap)
colormap([cmap,] T::Type{<:Integer}[, byteorder::Bool=false])

Set or retrieve the values of the current colormap.

Give the identifier cmap to set the colormap. This identifier can be the number or a string with the name of any of the GR built-in colormaps.

Give an integer data type T to return the set of colors defined in the current colormap, as a vector of hexadecimal color codes. By default those codes represent the word-ordered RGB values in a little-endian system. The optional argument byteorder can be set to true in order to retrieve the codes as byte-ordered codes.

At least one of the arguments cmap::Union{Integer, AbstractString} or T::Type{<:Integer} are required. If cmap not given, the previous colormap is left as current. If T is not given, the function returns nothing.

Examples

# Create example point data
x = 8 .* rand(100) .- 4
y = 8 .* rand(100) .- 4
z = sin.(x) + cos.(y)
# Use the "hot" colormap
colormap("hot")
contourf(x, y, z)
source
GRUtils.colormap!Function
colormap!(p, cmap)

Apply a colormap cmap to the given plot p, which can be a PlotObject, or a Figure (in such case the colormap is applied to all the plots contained in it).

The value of cmap can be the number or the name of any of the GR built-in colormaps (see colormap for more details).

Use the keyword argument colormap in plotting functions, to set a particular colormap during the creation of plots (in this case it can only be identified by its number).

Examples

# Create a surface plot with the "grayscale" colormap (2)
surface(x, y, z, colormap=2)
# Change it to the "viridis" colormap
colormap!(gcf(), "viridis")
source
GRUtils.colorschemeFunction
colorscheme(scheme)

Set the color scheme for subsequent plots.

The value of the scheme can be one of the following numbers or strings:

  • 0: "none"
  • 1: "light"
  • 2: "dark"
  • 3: "solarized light"
  • 4: "solarized dark"

The scheme applies to all plots that are drawn after calling colorscheme, even if they have been created beforehand. To apply a particular scheme to some plot or figure, use colorscheme!.

If the scheme is "none" (0), the standard scheme is set, which is the same as "light" (1), except that the default background of the figure is transparent.

Examples

# Create example data
x = LinRange(0, 3, 20)
y = [sin.(x) exp.(-x)]
# Set a new color scheme and plot the data
subplot(1,2,1)
colorscheme("light")
plot(x, y)
# Make a second plot with a particular scheme
subplot(1,2,2)
plot(x, y, scheme=3) # solarized light
# Now change the global scheme and redraw
# (this only affects the first plot)
colorscheme("solarized dark")
draw(gcf())
source
GRUtils.colorscheme!Function
colorscheme!(p, scheme)

Apply a color scheme to the given plot p, which can be a PlotObject, or a Figure (in such case the scheme is applied to all the plots contained in it).

The value of scheme can be the number or the name of any available color scheme (see colorscheme for more details).

Use the keyword argument scheme in plotting functions, to set a particular color scheme during the creation of plots (in this case only the number of an already exisiting scheme is allowed).

Examples

# Create a plot with a dark scheme (2)
plot(x, y, scheme=2)
# Change it to the standard light scheme
colorscheme!(currentplot(), "light")
source