Options

Options, which usually occur between brackets ([]) after commands like \addplot, table, or beginnings of environments like \begin{axis} in LaTeX code, are key to most of the functionality of PGFPlots.

The @pgf macro

Use the @pgf {} macro to define options.

PGFPlotsX.@pgfMacro
@pgf { ... }

@pgf some(nested(form({ ... })),
with_multiple_options({ ... }))

Construct Options from comma-delimited key (without value), key = value, key : value, or key => value pairs enclosed in { ... }, anywhere in the expression.

The argument is traversed recursively, allowing { ... } expressions in multiple places.

Multi-word keys need to be either quoted, or written with underscores replacing spaces.

@pgf {
"only marks",
mark_size = "0.6pt",
mark = "o",
color => "black",
}

Another Options can be spliced into one being created using ..., e.g.

theme = @pgf {xmajorgrids, x_grid_style = "white"}

axis_opt = @pgf {theme..., title = "My figure"}

Use {} for empty options that print as [] in LaTeX.

source

For constructors that accept options, they always come first. When omitted, there are assumed to be no options.

julia> c = Coordinates([1, 2, 3], [2, 4, 8]);

julia> p = @pgf PlotInc({ "very thick", "mark" => "halfcircle" }, c);

julia> print_tex(p); # print_tex can be used to preview the generated .tex
coordinates {
(1,2)
(2,4)
(3,8)
}
;

Inside the expression following @pgf, {} expressions can be nested, and can also occur in multiple places.

julia> @pgf a = Axis(
{
"axis background/.style" =
{
top_color = "gray",
bottom_color = "white",
},
ymode = "log"
},
PlotInc(
{
smooth
},
c)
);

which is converted to LaTeX as

julia> print_tex(a)
\begin{axis}[axis background/.style={shade, top color={gray}, bottom color={white}}, ymode={log}]
coordinates {
(1,2)
(2,4)
(3,8)
}
;
\end{axis}
Note

If you use @pgf inside argument lists, make sure you wrap its argument in parentheses, eg

Plot(@pgf({ scatter }), some_table)

Otherwise Julia will also pass the subsequent arguments through @pgf, which results in an error since they are combined into a tuple.

Each option is either a standalone keyword (without value, modifying the plot by itself), or a keyword-value pair. Keywords can be entered

1. as Julia identifiers, which is useful for keywords with no spaces (eg smooth),

2. separated by underscores, which are replaced by spaces (eg only_marks will appear in LaTeX code as only marks),

3. or quoted as strings, eg "very thick".

Values are provided after a =, :, or =>, so the following are equivalent:

1. @pgf { draw = "black" },

2. @pgf { draw : "black" },

3. @pgf { draw => "black" }.

Values should be valid Julia expressions, as they are evaluated, so you cannot use @pgf { draw = black } unless black is assigned to some Julia value in that context.

Note

Keys that contain symbols that in Julia are operators (e.g the key "axis background/.style") have to be entered as strings.

Transformations

In addition to replacing underscores in keys, the following transformations of values are done when the options are written in .tex style:

• A list as a value is written as “comma joined” e.g. [1, 2, 3] -> "1, 2, 3".

• A tuple as a value is written with braces delimiting the elements e.g. (60, 30) -> {60}{30}

Modifying options after an object is created

It is sometimes convenient to set and get options after an object has been created.

You can use getindex, setindex! (ie obj["option"] or obj["option"] = value, respectively), and delete! just like you would for modifiable associative collections (eg a Dict).

julia> c = Coordinates([1, 2, 3], [2, 4, 8]);

julia> p = PlotInc(c);

julia> p["fill"] = "blue";

julia> p["fill"]
"blue"

julia> @pgf p["axis background/.style"] = { shade, top_color = "gray", bottom_color = "white" };

julia> p["axis background/.style"]["top_color"];

julia> p["very thick"] = nothing # Set a value-less options;

julia> delete!(p, "fill");

julia> print_tex(p)
coordinates {
(1,2)
(2,4)
(3,8)
}
;

Working with options

Collections of options are first-class objects: they can be used independently of Plot, Axis, and similar, copied, modified, and merged.

This allows a disciplined approach to working with complex plots: for example, you can create a set of default options for some purpose (eg plots in a research paper, with a style imposed by a journal), and then modify this as needed for individual plots. It is then easy to apply, for example, a “theme” to an axis where the theme is a set of options already saved.

Another use case is creating orthogonal sets of options, eg one for axis annotations and another one for legends, and merging these as necessary.

Extending and combining options

Use ... to splice an option into another one, e.g.

julia> theme = @pgf {xmajorgrids, ymajorgrids};

julia> a = Axis(
@pgf {theme..., title = "Foo"}
);

julia> print_tex(a)
\begin{axis}[xmajorgrids, ymajorgrids, title={Foo}]
\end{axis}

julia> print_tex(theme) # original is not modified
[xmajorgrids, ymajorgrids]

You can also merge sets of options:

julia> O1 = @pgf { color = "red" };

julia> O2 = @pgf { dashed };

julia> O3 = @pgf { no_marks };

julia> print_tex(Plot(merge(O1, O2, O3), Table(1:2, 1:2)))
table[row sep={\\}]
{
\\
1  1  \\
2  2  \\
}
;

Again, the value of original options is unchanged above.

Modifying options

You can modify existing options with push!, append!, and merge!. The first two expect pairs of a string and a value (may be nothing for options like "red"), and are mostly useful when you are generating options using a function. merge! of course accepts options.

julia> opt = @pgf {};

julia> push!(opt, :color => "red", :mark => "x");

julia> append!(opt, [:style => "thick", :mark_options => @pgf { scale = 0.4 }]);

julia> merge!(opt, @pgf { "error bars/y dir=both", "error bars/y explicit" });

julia> print_tex(opt)
[color={red}, mark={x}, style={thick}, mark options={scale={0.4}}, error bars/y dir=both, error bars/y explicit]

All containers with options also support using merge! directly.

julia> a = Axis();

julia> @pgf opts = {xmin = 0, ymax = 1, ybar};

julia> merge!(a, opts);

julia> print_tex(a)
\begin{axis}[xmin={0}, ymax={1}, ybar]
\end{axis}

Empty options

Empty options are not emitted by default, but using in LaTeX code [] can be useful in some cases, eg when combined with global settings \pgfplotsset{every axis plot/.append style={...}}. In order to force printing empty options, it is recommended to use {} in expressions like

@pgf Plot({}, ...)

The PGFPlotsX.Options constructor

PGFPlotsX.OptionsType
Options(args; print_empty)


Options passed to PGFPlots for various structures (table, plot, etc).

Contents emitted in key = value form, or key when value ≡ nothing. Example:

julia> PGFPlotsX.Options(:color => "red", :only_marks => nothing)
[color={red}, only marks]

The constuctor is not exported but part of the API, for use in packages that depend on PGFPlotsX, or code producing complicated plots. It is recommended that the @pgf macro is used in scripts and interactive code.

When print_empty = false (the default), empty options are not printed. Use print_empty = true to force printing a [] in this case.

source