# 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. `Table`

s 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
```

`PGFPlotsX.TableData`

— TypeTabular 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.

`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`

.

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 \\
}
```

You can give a type that supports the `Tables.jl`

as the second argument to `Table`

and the data and column names will be inferred. For example, if you load the DataFrames package, you can create tables from data frames, see the examples in Julia types.

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,`Coordinate`

s, 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]))`

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

Two dimensional coordinates from two vectors, with error bars.

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

Three dimensional coordinates from two vectors, with error bars.

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

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.

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

Convenience constructor for 2-dimensional coordinates.

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

Convenience constructor for 3-dimensional coordinates.

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

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

Example:

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

## Strings in `Plot`

Strings (technically, all subtypes of `AbstractString`

) are also accepted by plots, and will be emitted into LaTeX *as is*. This is mostly useful for using constructs from TikZ that do not have a native representation in this package direcly as LaTeX code. See this example.