Overview

This package is a collection of functions and types which make it convenient to generate LaTeX output, which can in turn be compiled by PGFPlots to produce vector or bitmap images like pdf, svg or png, or used directly in LaTeX documents.

PGFPlots has a very detailed manual (a local copy should be available in TeXLive and MikTeX installations) which should be your primary source of documentation, and its contents are not repeated here. It is assumed that you read the relevant parts of this manual, and look for solutions there first.

Instead, this manual describes a way to conveniently generate what LaTeX output from Julia, using the types introduced in this package, other packages, and Julia's built-in constructs. When working with this package, it is frequently convenient to examine the LaTeX representation of objects. print_tex is a method that prints LaTeX code that is written out when saving plots; we use it extensively in this manual for demonstrations, while in practice one would use it for debugging.

As an example, consider the following trivial plot:

\begin{tikzpicture}
\begin{axis}
    \addplot+[only marks] table {
            x  y
            1  3
            2  4
        };
    \addplot+ table {
            x  y
            5  1
            6  2
        };
\end{axis}
\end{tikzpicture}

which can be produced by this package with the code

@pgf TikzPicture(
        Axis(
            PlotInc({ only_marks },
                Table(; x = 1:2, y = 3:4)),
            PlotInc(
                Table(; x = 5:6, y = 1:2))))

(The unconventional use of linebreaks in the Julia code is to emphasize the structural similarities between the two pieces of code).

The plot is built up from two Tables, which are tabular representations of data with (usually) named columns. These provide data for Plots, here using the PlotInc constructor which corresponds to the \addplot+ command: the + tells PGFPlots to use a default style that varies with each plot. Each plot can have a single source of data.

Plots are grouped together into an Axis, which corresponds to what most other libraries would call a “plot” (we use the term flexibly, too). Besides grouping plots, Axis allows the customization of ticks, labels, axis styles, legends, and related objects.

TikzPicture wraps the Axis. If you omit this, this package will do it for you automatically. Similarly, if you have a single Plot-like object and don't want to customize the Axis, it will also be added automatically.

Finally, @pgf is a convenient syntax for specifying options. It is is a macro that traverses its argument recursively, and converts it to a PGFPlotsX.Options object. It is recommended that you use this macro. The convention of this library is to apply @pgf to whole expressions to avoid repetition, but this is not required.

PGFPlotsX allows building up plots from types that correspond very closely to PGFPlots counterparts. The table below gives an overview of the types defined by this package. For most PGFPlots constructs, [] can be used to specify options, this corresponds to the [options] argument in the table above.

PGFPlots (`[]` indicates options)	`PGFPlotsX`	remark
`table[] { ... }`	`Table([options], ...`)	preferred to `Coordinates`
`coordinates { ... }`	`Coordinates(...)`	useful error bars
`\addplot[] { ... }` & friends	`Plot([options], ...)` & friends	also `PlotInc`, `Plot3`, `Plot3Inc`
`\legend`, `\legendentry[]`	`Legend`, `Legendentry([options])`
`{expression}`	`Expression(...)`	math formulas
`graphics[] { ... }`	`Graphics([options], ...)`	bitmaps
`\axis[] { ... }` & friends	`Axis([options], ...)` & friends	can have multiple `Plot`s & similar
`\begin{tikzpicture} ...`	`TikzPicture([options], ...)`	rarely used directly
`\begin{document} ...`	`TikzDocument(...; ...)`	rarely used directly

The following sections document these.