Plotting

Most interaction with Gadfly is through the plot function. Plots are described by binding data to aesthetics, and specifying a number of elements including Scales, Coordinates, Guides, and Geometries. Aesthetics are a set of special named variables that are mapped to a geometry. How this mapping occurs is defined by the elements.

This "grammar of graphics" approach tries to avoid arcane incantations and special cases, instead approaching the problem as if one were drawing a wiring diagram: data is connected to aesthetics, which act as input leads, and elements, each self-contained with well-defined inputs and outputs, are connected and combined to produce the desired result.

Functions and Expressions

Along with the standard plot methods operating on DataFrames and Arrays described in the Tutorial, Gadfly has some special signatures to make plotting functions and expressions more convenient.

plot(f::Function, lower, upper, elements...; mapping...)
plot(fs::Vector{T}, lower, upper, elements...; mapping...) where T <: Base.Callable
plot(f::Function, xmin, xmax, ymin, ymax, elements...; mapping...)
spy(M::AbstractMatrix, elements...; mapping...) -> Plot

For example:

p1 = plot([sin,cos], 0, 2pi)
p2 = plot((x,y)->sin(x)+cos(y), 0, 2pi, 0, 2pi)
p3 = spy(ones(33)*sin.(0:(pi/16):2pi)' + cos.(0:(pi/16):2pi)*ones(33)')
hstack(p1,p2,p3)

Wide-formatted data

Gadfly is designed to plot data in so-called "long form", in which data that is of the same type, or measuring the same quantity, are stored in a single column, and any factors or groups are specified by additional columns. This is how data is typically stored in a database.

Sometimes data tables are organized by grouping values of the same type into multiple columns, with a column name used to distinguish the grouping. We refer to this as "wide form" data.

To illustrate the difference consider some historical London birth rate data.

births = RDatasets.dataset("HistData", "Arbuthnot")[[:Year, :Males, :Females]]

This table is wide form because "Males" and "Females" are two columns both measuring number of births. Wide form data can always be transformed to long form (e.g. with the stack function in DataFrames) but this can be inconvenient, especially if the data is not already in a DataFrame.

stack(births, [:Males, :Females])

The resulting table is long form with number of births in one column, here with the default name given by stack: "value". Data in this form can be plotted very conveniently with Gadfly.

plot(stack(births, [:Males, :Females]), x=:Year, y=:value, color=:variable,
     Geom.line)

In some cases, explicitly transforming the data can be burdensome. Gadfly lets you avoid this by referring to columns or groups of columns in an implicit long-form version of the data.

plot(births, x=:Year, y=Col.value(:Males, :Females),
     color=Col.index(:Males, :Females), Geom.line)

┌ Warning: Indexing with colon as row will create a copy in the future. Use `df[col_inds]` to get the columns without copying
│   caller = evalmapping(::Gadfly.MeltedData{DataFrames.DataFrame}, ::Symbol) at mapping.jl:196
└ @ Gadfly ~/build/GiovineItalia/Gadfly.jl/src/mapping.jl:196

Here Col.value produces the concatenated values from a set of columns, and Col.index refers to a vector labeling each value in that concatenation by the column it came from. Also useful is Row.index, which will give the row index of items in a concatenation.

This syntax also lets us more conveniently plot data that is not in a DataFrame, such as matrices or arrays of arrays. Below we recreate the plot above for a third time after first converting the DataFrame to an Array.

births_array = convert(Array{Int}, births)
plot(births_array, x=Col.value(1), y=Col.value(2:3...),
     color=Col.index(2:3...), Geom.line, Scale.color_discrete,
     Guide.colorkey(labels=["Males","Females"]), Guide.xlabel("Year"))

When given no arguments Row.index, Col.index, and Col.value assume all columns are being concatenated.

Plotting arrays of vectors works in much the same way as matrices, but constituent vectors may be of varying lengths.