GnuplotEx.Plot (gnuplot_ex v0.2.0)

High-level plot builder with fluent API.

Build plots using a pipeline of functions:

GnuplotEx.new()
|> GnuplotEx.title("My Plot")
|> GnuplotEx.scatter(data, label: "Points", color: "#E95420")
|> GnuplotEx.x_label("X Axis")
|> GnuplotEx.y_label("Y Axis")
|> GnuplotEx.to_svg("/tmp/plot.svg")

3D Plots

GnuplotEx.scatter3d(points)
|> GnuplotEx.z_label("Z Axis")
|> GnuplotEx.view_angle(60, 30)
|> GnuplotEx.to_svg("/tmp/scatter3d.svg")

Fields

:title - Plot title
:x_label, :y_label, :z_label - Axis labels
:x_range, :y_range, :z_range - Axis ranges (Range or tuple)
:legend - Legend position (:top_right, :bottom_left, :off, etc.)
:theme - Theme atom or struct
:size - Plot size as {width, height}
:terminal - Output terminal (:svg, :png, :dumb, etc.)
:output - Output file path
:series - List of Series structs
:commands - Additional raw gnuplot commands
:view - 3D view angle as {rotation, elevation}
:azimuth - Azimuth angle for 3D
:is_3d - Flag indicating 3D plot (auto-set)
:palette - Color palette for surfaces (atom or list of colors)
:colorbar_range - Range for the colorbar
:colorbar - Show/hide colorbar (:on or :off)
:nonlinear - Nonlinear axis transformations (map of axis => transform)
:datablocks - Named data blocks for reuse (map of name => data)

Summary

Types

legend_position()

nonlinear_axis()

nonlinear_preset()

nonlinear_transform()

t()

Functions

azimuth(plot, angle)

Set the azimuth angle for 3D plots.

colorbar(plot, setting)

Show or hide the colorbar.

colorbar_range(plot, range)

Set the colorbar range.

command(plot, cmd)

Add a raw gnuplot command.

contour(plot, data_or_fn, opts \\ [])

Add a contour plot.

datablock(plot, name, data)

Define a named data block for reuse.

donut(plot, data, opts \\ [])

Add a donut chart series.

histogram(plot, data, opts \\ [])

Add a histogram series to the plot.

legend(plot, position)

Set the legend position.

line(plot, data, opts \\ [])

Add a line series to the plot.

new(opts \\ [])

Create a new empty plot.

nonlinear(plot, axis, transform)

Apply a nonlinear transformation to an axis.

palette(plot, palette)

Set the color palette for surfaces and heatmaps.

parallel(plot, data, opts \\ [])

Add a parallel coordinates series.

parametric_surface(plot, func, opts)

Add a parametric surface plot.

pie(plot, data, opts \\ [])

Add a pie chart series.

polygon3d(plot, data, opts \\ [])

Add a 3D polygon mesh series.

polygon(plot, data, opts \\ [])

Add a 2D polygon series.

scatter3d(plot, data, opts \\ [])

Add a 3D scatter series to the plot.

scatter(plot, data, opts \\ [])

Add a scatter series to the plot.

size(plot, arg)

Set the plot size.

spider(plot, data, opts \\ [])

Add a spider/radar chart series.

surface(plot, data_or_fn, opts \\ [])

Add a surface plot from data.

theme(plot, theme)

Set the plot theme.

title(plot, title_text)

Set the plot title.

unset_nonlinear(plot, axis)

Remove a nonlinear transformation from an axis.

view_angle(plot, rotation, elevation)

Set the 3D view angle.

x_label(plot, label)

Set the X-axis label.

x_range(plot, range)

Set the X-axis range.

y_label(plot, label)

Set the Y-axis label.

y_range(plot, range)

Set the Y-axis range.

z_label(plot, label)

Set the Z-axis label (for 3D plots).

z_range(plot, range)

Set the Z-axis range (for 3D plots).

Types

legend_position()

@type legend_position() ::
  :top_right
  | :top_left
  | :bottom_right
  | :bottom_left
  | :top_center
  | :bottom_center
  | :center
  | :off

nonlinear_axis()

@type nonlinear_axis() :: :x | :x2 | :y | :y2 | :z | :r | :cb

nonlinear_preset()

@type nonlinear_preset() :: :log10 | :log | :sqrt | :inverse | :probit | :logit

nonlinear_transform()

@type nonlinear_transform() ::
  nonlinear_preset() | {String.t(), String.t()} | keyword()

t()

@type t() :: %GnuplotEx.Plot{
  azimuth: number() | nil,
  colorbar: :on | :off | nil,
  colorbar_range: Range.t() | {number(), number()} | nil,
  commands: [list()],
  datablocks: %{required(atom()) => Enumerable.t()},
  is_3d: boolean() | nil,
  legend: legend_position() | nil,
  nonlinear: %{required(nonlinear_axis()) => nonlinear_transform()} | nil,
  output: String.t() | nil,
  palette: atom() | [String.t()] | GnuplotEx.Plot.Palette.t() | nil,
  series: [GnuplotEx.Plot.Series.t()],
  size: {pos_integer(), pos_integer()} | nil,
  terminal: atom() | nil,
  theme: atom() | map() | nil,
  title: String.t() | nil,
  view: {number(), number()} | nil,
  x_label: String.t() | nil,
  x_range: Range.t() | {number(), number()} | nil,
  y_label: String.t() | nil,
  y_range: Range.t() | {number(), number()} | nil,
  z_label: String.t() | nil,
  z_range: Range.t() | {number(), number()} | nil
}

Functions

azimuth(plot, angle)

@spec azimuth(t(), number()) :: t()

Set the azimuth angle for 3D plots.

Controls additional rotation around the viewing axis.

Example

plot |> GnuplotEx.Plot.azimuth(30)

colorbar(plot, setting)

@spec colorbar(t(), :on | :off) :: t()

Show or hide the colorbar.

Example

plot |> GnuplotEx.colorbar(:off)

colorbar_range(plot, range)

@spec colorbar_range(t(), Range.t() | {number(), number()}) :: t()

Set the colorbar range.

Controls the data range mapped to the color palette.

Example

plot |> GnuplotEx.colorbar_range(0..100)
plot |> GnuplotEx.colorbar_range({-1, 1})

command(plot, cmd)

@spec command(t(), list()) :: t()

Add a raw gnuplot command.

This is an escape hatch for commands not covered by the high-level API.

Example

plot |> GnuplotEx.Plot.command([:set, :grid, :xtics])

contour(plot, data_or_fn, opts \\ [])

@spec contour(t(), Enumerable.t() | fun(), keyword()) :: t()

Add a contour plot.

Options

:label - Legend label
:contour_levels - Number of contour levels
:contour_style - :base (default), :surface, or :both
:samples - Grid resolution

Example

data = for x <- -5..5, y <- -5..5, do: [x, y, x*x + y*y]
plot |> GnuplotEx.Plot.contour(data, contour_levels: 10, contour_style: :base)

datablock(plot, name, data)

@spec datablock(t(), atom(), Enumerable.t()) :: t()

Define a named data block for reuse.

Data blocks allow you to define data once and reference it in multiple series. This is useful when you want to plot the same data with different styles (e.g., both scatter and line), or when referencing data multiple times in complex plots.

Parameters

plot - The plot struct
name - Atom name for the datablock (e.g., :mydata)
data - The data to store (list, DataFrame, Tensor, etc.)

Example

GnuplotEx.new()
|> GnuplotEx.datablock(:points, [[1, 2], [3, 4], [5, 6]])
|> GnuplotEx.scatter(:points, label: "Scatter")
|> GnuplotEx.line(:points, label: "Line")
|> GnuplotEx.render(:svg)

donut(plot, data, opts \\ [])

@spec donut(t(), Enumerable.t(), keyword()) :: t()

Add a donut chart series.

Donut charts are pie charts with a hole in the center. This is a convenience wrapper for pie/3 with an :inner_radius option.

Options

All options from pie/3 plus:

:inner_radius - Inner radius ratio 0.0-1.0 (default: 0.5)

Example

data = [30, 25, 20, 15, 10]
GnuplotEx.donut(data, inner_radius: 0.6)
|> GnuplotEx.to_svg("/tmp/donut.svg")

histogram(plot, data, opts \\ [])

@spec histogram(t(), Enumerable.t(), keyword()) :: t()

Add a histogram series to the plot.

Options

:label - Legend label
:color - Bar color
:bins - Number of bins (uses gnuplot auto if not specified)
:fill - Fill style (:solid, :transparent, etc.)

Example

plot |> GnuplotEx.Plot.histogram(values, bins: 20, fill: :solid)

legend(plot, position)

@spec legend(t(), legend_position()) :: t()

Set the legend position.

Positions

:top_right (default)
:top_left
:bottom_right
:bottom_left
:top_center
:bottom_center
:center
:off - Hide legend

Example

plot |> GnuplotEx.Plot.legend(:top_left)
plot |> GnuplotEx.Plot.legend(:off)

line(plot, data, opts \\ [])

@spec line(t(), Enumerable.t(), keyword()) :: t()

Add a line series to the plot.

Options

:label - Legend label
:color - Line color
:line_width - Line width
:smooth - Smoothing (:csplines, :bezier, etc.)

Abbreviations

:t - title/label
:c - color
:lw - line_width

Example

plot |> GnuplotEx.Plot.line(data, label: "Trend", color: "#666", line_width: 2)

new(opts \\ [])

@spec new(keyword()) :: t()

Create a new empty plot.

Options

:title - Plot title
:size - Plot dimensions as {width, height}
:theme - Theme preset or custom theme

Example

GnuplotEx.new()
GnuplotEx.new(title: "My Plot", size: {800, 600})

nonlinear(plot, axis, transform)

@spec nonlinear(t(), nonlinear_axis(), nonlinear_transform()) :: t()

Apply a nonlinear transformation to an axis.

Nonlinear transformations use gnuplot 6's set nonlinear command to create log scales, square root scales, and other nonlinear axis mappings.

Preset Transformations

:log10 - Base-10 logarithmic scale
:log - Natural logarithmic scale
:sqrt - Square root scale
:inverse - Reciprocal scale (1/x)
:probit - Probit (normal CDF) scale
:logit - Logit scale

Supported Axes

:x, :x2 - X axes
:y, :y2 - Y axes
:z - Z axis (3D)
:r - Radial axis (polar)
:cb - Colorbar axis

Examples

# Log scale on X axis
plot |> GnuplotEx.nonlinear(:x, :log10)

# Multiple axes
plot
|> GnuplotEx.nonlinear(:x, :log10)
|> GnuplotEx.nonlinear(:y, :sqrt)

# Custom transformation
plot |> GnuplotEx.nonlinear(:y, via: "sqrt(y)", inverse: "y**2")

palette(plot, palette)

@spec palette(t(), atom() | [String.t()] | GnuplotEx.Plot.Palette.t()) :: t()

Set the color palette for surfaces and heatmaps.

Named Palettes

:viridis - Perceptually uniform, colorblind-friendly
:magma - Dark to light, warm tones
:plasma - Blue to yellow through pink
:inferno - Dark to light, fire-like
:cividis - Colorblind-optimized blue-yellow
:turbo - Rainbow-like, high contrast

Example

plot |> GnuplotEx.palette(:viridis)
plot |> GnuplotEx.palette(["#440154", "#21918c", "#fde725"])

parallel(plot, data, opts \\ [])

@spec parallel(t(), map() | Enumerable.t(), keyword()) :: t()

Add a parallel coordinates series.

Parallel coordinates display multivariate data with each variable represented as a vertical axis. Data points are lines connecting values across all axes.

Data Formats

Single map: %{var1: value1, var2: value2, ...} (one line)
List of maps: [%{var1: v1, var2: v2}, ...] (multiple lines)
List of lists: [[v1, v2, ...], ...] (with :axes option)

Options

:label - Legend label for this series
:axes - List of axis names (required for list-of-lists format)
:color - Line color
:line_width - Line width

Example

data = [
  %{price: 25000, mpg: 30, hp: 150},
  %{price: 35000, mpg: 25, hp: 200}
]
GnuplotEx.new()
|> GnuplotEx.parallel(data, label: "Cars")
|> GnuplotEx.to_svg("/tmp/parallel.svg")

parametric_surface(plot, func, opts)

@spec parametric_surface(t(), fun(), keyword()) :: t()

Add a parametric surface plot.

The function should take (u, v) parameters and return {x, y, z}.

Options

:label - Legend label
:u_range - U parameter range (required)
:v_range - V parameter range (required)
:samples - Grid resolution as {u, v} or single value
:surface_style - :pm3d (default), :lines, or :hidden3d

Example

# Sphere
sphere = fn u, v ->
  {:math.cos(u) * :math.cos(v),
   :math.sin(u) * :math.cos(v),
   :math.sin(v)}
end

plot |> GnuplotEx.Plot.parametric_surface(sphere,
  u_range: {0, 2 * :math.pi()},
  v_range: {-:math.pi()/2, :math.pi()/2})

pie(plot, data, opts \\ [])

@spec pie(t(), Enumerable.t(), keyword()) :: t()

Add a pie chart series.

Pie charts display proportional data as circular sectors.

Data Formats

List of values: [30, 25, 20, 15, 10]
List of maps: [%{label: "A", value: 30}, %{label: "B", value: 25}]
List of tuples: [{"A", 30}, {"B", 25}]

Options

:labels - List of slice labels
:colors - List of colors or palette name (e.g., :viridis)
:explode - List of slice indices to explode (offset outward)
:start_angle - Starting angle in degrees (0 = top, clockwise)

Example

data = [
  %{label: "Category A", value: 30},
  %{label: "Category B", value: 25},
  %{label: "Category C", value: 20}
]
GnuplotEx.pie(data, colors: ["#E95420", "#3daee9", "#27ae60"])
|> GnuplotEx.to_svg("/tmp/pie.svg")

polygon3d(plot, data, opts \\ [])

@spec polygon3d(t(), Enumerable.t(), keyword()) :: t()

Add a 3D polygon mesh series.

3D polygons are filled closed shapes in 3D space, useful for meshes and surfaces.

Data Formats

Single polygon: [[x1, y1, z1], [x2, y2, z2], [x3, y3, z3], ...]
Multiple polygons (mesh): [[[x1, y1, z1], ...], [[x2, y2, z2], ...]]

Options

:label - Legend label
:color - Fill color
:fill - Fill style (:solid, :transparent, :pattern, :empty)
:alpha - Fill transparency 0.0-1.0 (for transparent fill)
:border_color - Border line color
:border_width - Border line width

Abbreviations

:c - color
:bc - border_color
:bw - border_width
:a - alpha

Example

# 3D triangle
vertices = [[0, 0, 0], [1, 0, 0], [0.5, 1, 0.5]]
GnuplotEx.polygon3d(vertices, color: "#E95420")

# Mesh (multiple polygons)
mesh = [
  [[0, 0, 0], [1, 0, 0], [0.5, 1, 0.5]],
  [[1, 0, 0], [1, 1, 0], [0.5, 1, 0.5]]
]
GnuplotEx.polygon3d(mesh, fill: :transparent, alpha: 0.8)

polygon(plot, data, opts \\ [])

@spec polygon(t(), Enumerable.t(), keyword()) :: t()

Add a 2D polygon series.

Polygons are filled closed shapes defined by vertices.

Data Formats

Single polygon: [[x1, y1], [x2, y2], [x3, y3], ...]
Multiple polygons: [[[x1, y1], ...], [[x2, y2], ...]]

Options

:label - Legend label
:color - Fill color
:fill - Fill style (:solid, :transparent, :pattern, :empty)
:alpha - Fill transparency 0.0-1.0 (for transparent fill)
:border_color - Border line color
:border_width - Border line width

Abbreviations

:c - color
:bc - border_color
:bw - border_width
:a - alpha

Example

# Triangle
vertices = [[0, 0], [1, 0], [0.5, 1]]
GnuplotEx.polygon(vertices, color: "#3daee9")

# Multiple shapes
shapes = [
  [[0, 0], [1, 0], [1, 1], [0, 1]],
  [[2, 0], [3, 0], [2.5, 1]]
]
GnuplotEx.polygon(shapes, fill: :solid, border_color: "#000")

scatter3d(plot, data, opts \\ [])

@spec scatter3d(t(), Enumerable.t(), keyword()) :: t()

Add a 3D scatter series to the plot.

Data should be a list of [x, y, z] points.

Options

:label - Legend label
:color - Point color
:point_type - Point shape (1-14 or atom like :circle)
:point_size - Point size multiplier

Example

points = for _ <- 1..100, do: [:rand.uniform(), :rand.uniform(), :rand.uniform()]
plot |> GnuplotEx.Plot.scatter3d(points, label: "Random Points")

scatter(plot, data, opts \\ [])

@spec scatter(t(), Enumerable.t(), keyword()) :: t()

Add a scatter series to the plot.

Options

:label - Legend label
:color - Point color
:point_type - Point shape (1-14 or atom like :circle)
:point_size - Point size multiplier

Abbreviations

:t - title/label
:c - color
:ps - point_size
:pt - point_type

Example

plot |> GnuplotEx.Plot.scatter(data, label: "Points", color: "#E95420")

size(plot, arg)

@spec size(
  t(),
  {pos_integer(), pos_integer()}
) :: t()

Set the plot size.

Example

plot |> GnuplotEx.Plot.size({800, 600})

spider(plot, data, opts \\ [])

@spec spider(t(), map() | Enumerable.t(), keyword()) :: t()

Add a spider/radar chart series.

Spider charts display multivariate data on axes radiating from a center point. Useful for comparing multiple entities across several metrics.

Data Formats

Map: %{axis1: value1, axis2: value2, ...}
List of maps: [%{name: "A", axis1: v1, ...}, ...]
List of lists: [[v1, v2, ...], ...] (with :axes option)

Options

:label - Legend label
:axes - List of axis names (required for list-of-lists data)
:filled - Fill the spider area (default: false)
:alpha - Fill transparency 0.0-1.0 (default: 0.3)
:color - Line/fill color

Abbreviations

:f - filled
:a - alpha

Examples

# Single entity
stats = %{speed: 8, power: 6, defense: 7, magic: 5}
plot |> GnuplotEx.Plot.spider(stats, label: "Warrior", filled: true)

# Multiple entities
data = [
  %{name: "Warrior", speed: 8, power: 6, defense: 7},
  %{name: "Mage", speed: 5, power: 9, defense: 4}
]
plot |> GnuplotEx.Plot.spider(data)

# Matrix format
plot |> GnuplotEx.Plot.spider([[8, 6, 7], [5, 9, 4]],
  axes: [:speed, :power, :defense], filled: true)

surface(plot, data_or_fn, opts \\ [])

@spec surface(t(), Enumerable.t() | fun(), keyword()) :: t()

Add a surface plot from data.

Data can be:

A list of [x, y, z] points (will be arranged in grid)
A 2D matrix of z values (with x_range/y_range for coordinates)
A function (x, y) -> z (with x_range/y_range for sampling)

Options

:label - Legend label
:color - Surface color
:surface_style - :pm3d (default), :lines, or :hidden3d
:samples - Grid resolution as {x, y} or single value

Examples

# From data points
data = for x <- 0..10, y <- 0..10, do: [x, y, x*x + y*y]
plot |> GnuplotEx.Plot.surface(data)

# From function
plot |> GnuplotEx.Plot.surface(fn x, y -> :math.sin(x) * :math.cos(y) end,
  x_range: -5..5, y_range: -5..5, samples: {50, 50})

theme(plot, theme)

@spec theme(t(), atom() | map()) :: t()

Set the plot theme.

Presets

:default - Minimal theme with grid
:dark - Dark background theme
:publication - Publication-ready styling

Example

plot |> GnuplotEx.Plot.theme(:dark)

title(plot, title_text)

@spec title(t(), String.t()) :: t()

Set the plot title.

Example

plot |> GnuplotEx.Plot.title("My Plot")

unset_nonlinear(plot, axis)

@spec unset_nonlinear(t(), nonlinear_axis()) :: t()

Remove a nonlinear transformation from an axis.

Returns the axis to linear scaling.

Example

plot
|> GnuplotEx.nonlinear(:x, :log10)
|> GnuplotEx.unset_nonlinear(:x)

view_angle(plot, rotation, elevation)

@spec view_angle(t(), number(), number()) :: t()

Set the 3D view angle.

Controls the viewing angle for 3D plots using rotation and elevation.

rotation - Rotation around the Z-axis in degrees (0-360)
elevation - Elevation angle in degrees (0-90, where 90 is top-down)

Example

plot |> GnuplotEx.Plot.view_angle(60, 30)

x_label(plot, label)

@spec x_label(t(), String.t()) :: t()

Set the X-axis label.

Example

plot |> GnuplotEx.Plot.x_label("Time (s)")

x_range(plot, range)

@spec x_range(t(), Range.t() | {number(), number()}) :: t()

Set the X-axis range.

Example

plot |> GnuplotEx.Plot.x_range(0..100)
plot |> GnuplotEx.Plot.x_range({-10, 10})

y_label(plot, label)

@spec y_label(t(), String.t()) :: t()

Set the Y-axis label.

Example

plot |> GnuplotEx.Plot.y_label("Value")

y_range(plot, range)

@spec y_range(t(), Range.t() | {number(), number()}) :: t()

Set the Y-axis range.

Example

plot |> GnuplotEx.Plot.y_range(-1..1)
plot |> GnuplotEx.Plot.y_range({0, 100})

z_label(plot, label)

@spec z_label(t(), String.t()) :: t()

Set the Z-axis label (for 3D plots).

Example

plot |> GnuplotEx.Plot.z_label("Height (m)")

z_range(plot, range)

@spec z_range(t(), Range.t() | {number(), number()}) :: t()

Set the Z-axis range (for 3D plots).

Example

plot |> GnuplotEx.Plot.z_range(0..100)
plot |> GnuplotEx.Plot.z_range({-10, 10})