ggplot

ggplot

Production-grade Grammar of Graphics for Go.

A pure-Go data visualization library implementing a rigorous, declarative Grammar of Graphics pipeline. Inspired by Hadley Wickham's renowned ggplot2, but architected specifically for Go's type safety and interface-driven engine architecture.

Overview

ggplot provides an expressive, composable API for generating complex data visualizations. It decouples the data manipulation (Apache Arrow, BigQuery, Memory) from the statistical transformations and the final vector rendering, resulting in highly scalable plotting pipelines.

Gallery

Clifford attractor — 500 k points, alpha blending, continuous color scale	Butterfly curve — parametric path with color interpolation

Why ggplot?

Data science in Go often suffers from fragmented or overly imperative plotting APIs. ggplot solves this by introducing:

• Declarative Compositions — Build complex charts by layering geometries and statistics instead of drawing pixels.
• Provider-Agnostic Engines — Swap out the underlying dataset execution engine (memory vs arrow) without changing a single line of your plotting code.
• Publication-Ready Outputs — Anti-aliased 2D vector rendering powered by gogpu/gg, saving to PNG, SVG, or PDF at configurable DPI scales.

Quick Start

Installation

go get github.com/TuSKan/ggplot

1. Scatter Plot

package main

import (
	"context"
	"log"

	"github.com/TuSKan/ggplot"
	"github.com/TuSKan/ggplot/aes"
	"github.com/TuSKan/ggplot/dataset"
	"github.com/TuSKan/ggplot/dataset/memory"
	"github.com/TuSKan/ggplot/geom"
)

func main() {
	ctx := context.Background()
	// Initialize a memory engine and construct columns explicitly.
	eng := memory.NewEngine(ctx)
	ds, err := dataset.NewDataset(eng,
		eng.NewFloat64Column("x", []float64{1, 2, 3, 4, 5, 6, 7, 8, 9, 10}),
		eng.NewFloat64Column("y", []float64{2, 4, 5, 4, 6, 8, 7, 9, 10, 11}),
	)
	if err != nil {
		log.Fatalln(err)
	}

	// Build the plot using declarative Grammar of Graphics.
	ggplot.New(ds, aes.X("x"), aes.Y("y")).
		Layer(geom.Point(geom.WithSize(5), geom.WithColor("coral"))).
		Layer(geom.Smooth()).
		Labs(ggplot.Title("Quick Start"), ggplot.XLab("X"), ggplot.YLab("Y")).
		Theme("minimal").
		Save(ctx, "scatter.png", 800, 500)
}

2. Faceted Time Series

ggplot.New(ds, aes.X("day"), aes.Y("temp")).
    Layer(geom.Line(geom.WithColor("seagreen"), geom.WithLineWidth(1.5))).
    FacetWrap("season", 2, 0).
    Labs(ggplot.Title("Temperature by Season")).
    Theme("dark").
    Save(ctx, "facets.png", 900, 600)

3. Box Plot with Groups

ggplot.New(ds, aes.X("group"), aes.Y("value")).
    Layer(geom.BoxPlot(geom.WithFill("lightyellow"), geom.WithAlpha(0.8))).
    Labs(ggplot.Title("Distribution by Group")).
    Theme("classic").
    Save(ctx, "boxplot.png", 800, 500)

Architecture & Data Backends

ggplot is built around a rigorous, interface-driven dataset.Table engine. This means you are not limited to []float64 slices. You can back your plots with robust columnar frameworks. See DATASET.md for a deep-dive into the backend engine architecture.

• Memory Engine (dataset/memory): Lightweight, native Go slices. Best for standard web-server rendering.
• Arrow Engine (dataset/arrow): Apache Arrow backed IPC streams and Parquet datasets. Provides zero-copy reads from IPC/Parquet files. Best for datasets >1M rows.
• BigQuery Engine (dataset/bigquery): Lazy SQL pushdown execution. Best for massive data warehouses where filtering and statistics must be executed on the database before streaming the visual aggregate to Go.

Documentation

Project Roadmap

We actively track our development pipeline across multiple capability tiers focusing on Grammar Primitives, Scaling Functions, and Advanced Geometries.

Please see our full Project Roadmap to understand current milestones and architectural expansion goals.

• 🔶 Phases 1–4 — Core architecture, grammar primitives, data backends, production hardening (in progress)
• 🔲 Phases 5–8 — Position/colour/other scales, faceting controls
• 🔲 Phases 9–12 — Annotations, composition (patchwork), maps, networks
• 🔲 Phases 13–19 — Themes deep-dive, guides, output backends, programming/extensibility

Dependencies

Contributing

Contributions are welcome!

License

MIT — see LICENSE.