Plots.jl Documentation

The JuliaPlots ecosystem is composed of several specialized packages. When contributing new functionality, aim to place it in the most appropriate package rather than adding everything to the core Plots package. This helps reduce the scope of the core library.

Package Responsibilities:

• Plots: The core package. Contains plot/plot! definitions, the core processing pipeline, base recipes (e.g., scatter, bar), generic output/layout/animation methods, and core types (Plot, Subplot, Axis, Series).
• Backends: Code linking Plots to specific engines (like GR or Plotly). Backend-specific code should be contributed to the Plots/src/backends directory in the core Plots package.
• RecipesBase: The essential foundation for creating third-party recipes. Use this if you want to define new recipes for custom types.
• PlotUtils: Contains generic, reusable components like color conversions, color gradients, and tick computation.
• PlotThemes: Manages visual themes (attribute defaults like "dark" or "orange").
• StatsPlots: An extension for statistical plotting and tabular data (e.g., histograms, densities, correlation plots, and DataFrame support).
• GraphRecipes: An extension of StatsPlots for graphs, maps, and related visualizations.
• PlotDocs: The home for documentation, built using Documenter.jl.

The @df macro allows you to pass columns of table-like structures (such as DataFrames, IndexedTables, or DataStreams) as symbols. This enables column manipulation inside the plot call as if they were normal arrays.

Key features:

• Column selection: Use symbols for single columns or arrays of symbols for multiple columns.
• cols() utility: Use cols(range) to refer to a range of columns or cols(symbol) to refer to a specific column via a variable.
• Escaping ambiguity: If a symbol is not a column name but is used in a plot argument (like colour), escape it using ^().
• Query.jl integration: You can append @df to the end of a Query.jl pipeline.
• Grouping: Compatible with Plots.jl grouping. Use a tuple of symbols for multiple columns. Use the curly bracket syntax group = {Name = :col} to provide custom legend names.

using DataFrames, IndexedTables
df = DataFrame(a = 1:10, b = 10 .* rand(10), c = 10 .* rand(10))
@df df plot(:a, [:b :c], colour = [:red :blue])
@df df scatter(:a, :b, markersize = 4 .* log.(:c .+ 0.1))

t = table(1:10, rand(10), names = [:a, :b]) # IndexedTable
@df t scatter(2 .* :b)

# Using cols()
@df df plot(:a, cols(2:3), colour = [:red :blue])
s = :b
@df df plot(:a, cols(s))

# Escaping non-column symbols
df[:red] = rand(10)
@df df plot(:a, [:b :c], colour = ^([:red :blue]))

# Query.jl integration
using Query, StatsPlots
df |>
    @filter(_.a > 5) |>
    @map({_.b, d = _.c-10}) |>
    @df scatter(:b, :d)

# Grouping
using RDatasets
school = dataset("mlmRev", "Hsb82")
@df school density(:MAch, group = :Sx)
@df school density(:MAch, group = (:Sx, :Sector), legend = :topleft)
@df school density(:MAch, group = {Sex = :Sx, :Sector})

Some arguments in Plots.jl act as "Magic Arguments." Instead of passing many individual keywords, you can pass a single Tuple of values. The library uses type checking and multiple dispatch to distribute these values to the correct underlying attributes.

axis (and xaxis, yaxis, zaxis)

Passing a tuple to an axis argument allows you to define xlabel, xlims, xticks, xscale, xflip, and xtickfont in one go.

line (alias l)

Sets attributes for a series line, including seriestype, linestyle, arrow, linealpha, linewidth, and linecolor.

fill (aliases f, area)

Sets attributes for a series fill area, including fillrange, fillalpha, and fillcolor.

marker (aliases m, mark)

Sets attributes for a series marker, including markershape, markersize, markeralpha, markercolor, markerstrokewidth, markerstrokealpha, markerstrokecolor, and markerstrokestyle.