Data

There are multiple ways of representing data in PGFPlots.

Table and TableData

A Table represents a matrix of data where each column is labeled. It can simply point to an external data file or store the data inline in the tex file. Tables can have options.

TableData is the representation of just the data, without the table[options] part. It is useful for inline tables in specials cases. Also, calls to Table use TableData to convert the arguments, so if you want to learn about all the ways to construct a Table, see the methods of TableData.

PGFPlotsX.Table — Type.

Table([options], ...; ...)

Tabular data with options, corresponding to table[options] { ... } in PGFPlots.

options stores the options. If that is followed by an AbstractString, that will be used as a filename to read data from, otherwise all the arguments are passed on to TableData.

Examples:

Table(["x" => 1:10, "y" => 11:20])        # from a vector

Table([1:10, 11:20])                      # same contents, unnamed

Table(Dict(:x => 1:10, :y = 11:20))       # a Dict with symbols

@pgf Table({ "x index" = 2, "y index" = 1" }, randn(10, 3))

let x = range(0; stop = 1, length = 10), y = range(-2; stop =  3, length = 15)
    Table(x, y, sin.(x + y'))             # edges & matrix
end

source

PGFPlotsX.TableData — Type.

Tabular data with optional column names.

This corresponds to the part of tables between {}'s in PGFPlots, without the options or table, so that it can also be used for “inline” tables. Table will call the constructor for this type to convert arguments after options.

data is a matrix, which contains the contents of the table, which will be printed using print_tex. colnames is a vector of column names (converted to string), or nothing for a table with no column names.

When rowsep is true, an additional \\ is used as a row separator. The default is true, this is recommended to avoid “fragility” issues with inline tables.

Note

Table queries TableData for its rowsep, and adds the relevant option accordingly. When using “inline” tables, eg in options, you have to specify this manually for the container. See the gallery for examples.

After each index in scanlines, extra row separators are inserted. This can be used for skipping coordinates or implicitly defining the dimensions of a matrix for surf and mesh plots. They are expanded using expand_scanlines.

source

Examples:

julia> t = @pgf Table({x = "Dof"}, "data.dat");

julia> print_tex(t)
table [x={Dof}] {
    <ABSPATH>/data.dat
}

Inline data is constructed using a keyword constructor:

julia> t = @pgf Table({x => "Dof", y => "Err"},
                      [:Dof => [1, 2, 4], :Err => [2.0, 1.0, 0.1]]);

julia> print_tex(t)
table[row sep={\\}, x={Dof}, y={Err}]
{
    Dof  Err  \\
    1.0  2.0  \\
    2.0  1.0  \\
    4.0  0.1  \\
}

If you load the DataFrames package, you can also create tables from data frames, see the examples in Julia types.

Note

By default, PGFPlots expects rows to be separated in a table with a newline. This can be “fragile” in LaTeX, in the sense that linebreaks may be merged with other whitespace within certain constructs, eg macros. In order to prevent this, this package uses the option rowsep=\\ by default. This is taken care of automatically, except for inline tables where you have to specify it manually. See the patch plot in the gallery.

Using coordinates

Coordinates are a list of points (x,y) or (x,y,z). PGFPlotsX wraps these in the Coordinate type, but for multiple coordinates, it is recommended that you use the Coordinates constructor, which has convenience features like converting non-finite numbers to skipped points (represented by nothing).

Strings are also accepted in place of numbers, and can be used for symbolic coordinates (eg for categorical data). See this example.

`Coordinates`

Coordinates(x, y, [z]) where x and y (and optionally z) are lists.
Coordinates(points) where points is a list of tuples, Coordinates, or nothing, e.g. x = [(1.0, 2.0), (2.0, 4.0)].

Errors can be added to Coordinates with keywords.

PGFPlotsX.Coordinates — Type.

Coordinates(itr)

Convert the argument, which can be any iterable object, to coordinates.

Specifically,

Coordinate and Nothing are passed through as is,
2- or 3-element tuples of finite real numbers or strings are interpreted as coordinates,
(), and tuples with non-finite numbers become nothing (representing empty lines).

The resulting coordinates are checked for dimension consistency.

Examples

The following are equivalent:

Coordinates((x, 1/x) for x in -5:5)
Coordinates(x == 0 ? () : (x, 1/x) for x in -5:5)
Coordinates(x == 0 ? nothing : Coordinate((x, 1/x)) for x in -5:5)

Use enumerate to add 1, 2, … for the x-axis to an existing set of y coordinates:

Coordinates(enumerate([1, 4, 9]))

source

Coordinates(x, y; xerror, yerror, xerrorplus, yerrorplus, xerrorminus, yerrorminus, meta)

Two dimensional coordinates from two vectors, with error bars.

source

Coordinates(x, y, z; xerror, yerror, zerror, xerrorplus, yerrorplus, zerrorplus, xerrorminus, yerrorminus, zerrorminus, meta)

Three dimensional coordinates from two vectors, with error bars.

source

Coordinates(x, y, z; meta)

Construct coordinates from a matrix of values and edge vectors, such that z[i,j] corresponds to x[i] and y[j]. Empty scanlines are inserted, consistently with the mesh/ordering=x varies option of PGFPlots (the default).

x = range(0; stop = 1, length = 10)
y = range(-1; stop = 2, length = 13)
z = sin.(x) + cos.(y')
Coordinates(x, y, z)

source

Examples:

julia> x = [1, 2, 3]; y = [2, 4, 8]; z = [-1, -2, -3];

julia> print_tex(Coordinates(x, y))
coordinates {
    (1,2)
    (2,4)
    (3,8)
}

julia> print_tex(Coordinates(x, y, z))
coordinates {
    (1,2,-1)
    (2,4,-2)
    (3,8,-3)
}

julia> print_tex(Coordinates(x, x.^3))
coordinates {
    (1,1)
    (2,8)
    (3,27)
}

julia> print_tex(Coordinates([(1.0, 2.0), (2.0, 4.0)]))
coordinates {
    (1.0,2.0)
    (2.0,4.0)
}

julia> c = Coordinates(x, y, xerror = [0.2, 0.3, 0.5], yerror = [0.2, 0.1, 0.5]);

julia> print_tex(c)
coordinates {
    (1,2) +- (0.2,0.2)
    (2,4) +- (0.3,0.1)
    (3,8) +- (0.5,0.5)
}

Individual coordinates

Use this constructor when you need just a single Coordinate, eg as in

@pgf Axis(
    {
        legend_style =
        {
            at = PGFPlotsX.Coordinate(0.5, -0.15),
            anchor = "north",
            legend_columns = -1
        },
    }, ...)

PGFPlotsX.Coordinate — Type.

Coordinate(data; error, errorplus, errorminus, meta)

Construct a coordinate, with optional error bars and metadata. data should be a 2- or 3-element tuples of finite real numbers.

You can specify either

error, which will then be used for error bars in both directions, or
errorplus and/or errorminus, for asymmetrical error bars.

Error values can be tuples of the same kind as data, or nothing.

Metadata can be provided in meta.

Users rarely need to use this constructor, see methods of Coordinates for constructing coordinates from arrays.

source

Coordinate(x, y; args...)

Convenience constructor for 2-dimensional coordinates.

source

Coordinate(x, y, z; args...)

Convenience constructor for 3-dimensional coordinates.

source

Expression

PGFPlotsX.Expression — Type.

Expression(expressions::Vector{String})

Expression(strings::String...)

An Expression is a string or multiple strings, representing a function, and is written in a way LaTeX understands.

source

Example:

julia> ex = Expression("exp(-x^2)");

julia> print_tex(ex)
{exp(-x^2)}

Graphics

PGFPlotsX.Graphics — Type.

Graphics([options], filename)

Graphics data simply wraps an image (eg a .png file).

source

Example:

julia> print_tex(Graphics("img.png"))
graphics {img.png}