Declarative Plotting with ggplot2 • plotit

简体中文 | English

⚠️ Early development stage.
plotit is under active, pre-release development. Breaking changes are extremely likely with every update. The API is incomplete, many planned features are missing, and bugs are expected. Do not use in production. Use at your own risk. Feedback and contributions are welcome.

Overview

plotit is a declarative, pipeline-first R package for creating publication-quality visualisations. Built on ggplot2, it replaces +-based layering with a unified verb-prefix API powered by the native pipe (|>). Sensible defaults eliminate boilerplate — colour, theme, and sizing work out of the box.

library(plotit)

iris |>
  plotit(encode(x = Sepal.Width, y = Sepal.Length, colour = Species)) |>
  mark_point(size = 2, alpha = 0.7) |>
  scale_color(range = "viridis") |>
  label_title("Iris Sepal Dimensions") |>
  style(ggplot2::theme_minimal(base_size = 14)) |>
  export("iris_plot.pdf")

Installation

You can install the development version of plotit from GitHub:

# install.packages("pak")
pak::pak("zorrooz/plotit")

Quick start

library(plotit)

# Scatter plot with colour mapping
iris |>
  plotit(encode(x = Sepal.Width, y = Sepal.Length, colour = Species)) |>
  mark_point()

# Bar chart of counts
mtcars |>
  plotit(encode(x = factor(cyl))) |>
  mark_bar()

# Line chart for time series
ggplot2::economics |>
  plotit(encode(x = date, y = unemploy)) |>
  mark_line()

# Multi-plot dashboard
p1 <- plotit(iris, encode(x = Sepal.Width, y = Sepal.Length)) |> mark_point()
p2 <- plotit(iris, encode(x = Species, y = Sepal.Length)) |> mark_boxplot()
compose_grid(p1, p2, tag_levels = "A") |>
  label_title("Iris Dashboard") |>
  export("dashboard.png")

The pipeline

Every plotit chart follows a consistent pipeline:

data |> plotit(encode(...)) |> mark_*() |> scale_*() |> split_*() |> project_*() |> label_*() |> style() |> export()

Step	Verb	Role
1. Initialise	`plotit()` + `encode()`	Bind data and aesthetic mappings
2. Layer	`mark_*()`	Add geometric layers (points, lines, bars, …)
3. Scale	`scale_*()`	Control how data maps to visual properties
4. Facet	`split_*()`	Split into small multiples
5. Coordinate	`project_*()`	Choose coordinate system (cartesian, polar, map)
6. Label	`label_*()`	Set titles, axis labels, legend titles
7. Theme	`style()`	Apply a complete theme
8. Export	`export()`	Render to file

Multi-plot compositions follow their own outermost pipeline:

compose_*(p1, p2, ...) |> label_*() |> style() |> export()

Function families

`mark_*` — Geometric layers

Function	ggplot2	Description
`mark_point()`	`geom_point()`	Scatter plots
`mark_line()`	`geom_line()`	Lines and trends
`mark_area()`	`geom_area()`	Filled area / stream graph
`mark_bar()`	`geom_bar()` / `geom_col()`	Bar charts
`mark_text()`	`geom_text()` / `ggrepel`	Text labels and annotations
`mark_boxplot()`	`geom_boxplot()`	Box-and-whisker plots
`mark_histogram()`	`geom_histogram()`	Histograms
`mark_density()`	`geom_density()`	1D kernel density
`mark_violin()`	`geom_violin()`	Violin plots
`mark_map()`	`geom_sf()`	Geographic maps

`scale_*` — Data-to-visual mapping

Function	Aesthetic
`scale_color()`	colour
`scale_fill()`	fill
`scale_size()`	size
`scale_alpha()`	alpha
`scale_shape()`	shape
`scale_linetype()`	linetype
`scale_x()`	x-axis
`scale_y()`	y-axis

`label_*` — Text labels

Function	Scope
`label_title()`	Main title
`label_subtitle()`	Subtitle
`label_caption()`	Caption
`label_axis()`	Axis titles
`label_legend()`	Legend titles

`project_*` — Coordinate systems

Function	Description
`project_cartesian()`	Cartesian (zoom, flip, ratio, transform)
`project_polar()`	Polar
`project_parallel()`	Parallel coordinates
`project_map()`	Geographic projection

`split_*` — Facets

Function	Description
`split_wrap()`	Wrapped facets
`split_grid()`	Grid facets

`compose_*` — Multi-plot assembly

Function	Description
`compose_grid()`	Grid arrangement
`compose_inset()`	Floating inset overlay
`compose_marginal()`	Scatter with marginal distributions

Theme

Function	Description
`style()`	Apply a ggplot2 theme
`style_default()`	Restore plotit’s built-in theme

Export

Function	Description
`export()`	Render to file (pdf, png, svg, …)

Custom extensions

Function	Description
`make_mark()`	Register a custom mark from any ggplot2 geom
`make_theme()`	Create a reusable theme preset function

Documentation

Full documentation is available at zorrooz.github.io/plotit.

Contributing

plotit is in early development. Bug reports, feature requests, and pull requests are welcome on GitHub Issues.

License

plotit is licensed under the MIT License. See LICENSE for details.

plotit