Package {orbis}

Title:	Interactive and High-Resolution Layered Graphics with Built-in World Maps
Version:	0.1.0
Description:	A layered grammar of graphics that compiles plots to a resolution-independent scene description and renders it through two back-ends: a self-contained SVG writer with embedded 'JavaScript' for interactive figures (tooltips, hover highlighting, zoom, pan and legend toggling) and R's own graphics devices for publication-quality output at any resolution. Geographic layers are first class: a simplified world polygon dataset ships with the package and can be drawn with several map projections, including Robinson, Equal Earth and an orthographic globe. The layered grammar follows Wickham (2010) <doi:10.1198/jcgs.2009.07098>; projections follow Snyder (1987) <doi:10.3133/pp1395> and, for Equal Earth, Savric, Patterson and Jenny (2019) <doi:10.1080/13658816.2018.1504949>; line simplification uses Douglas and Peucker (1973) <doi:10.3138/FM57-6770-U75U-7727>; the default colour scales follow the guidance on perceptually uniform palettes of Crameri, Shephard and Heron (2020) <doi:10.1038/s41467-020-19160-7>.
License:	MIT + file LICENSE
Encoding:	UTF-8
Language:	en-GB
Depends:	R (≥ 4.1.0)
Imports:	grDevices, grid, stats, utils, htmltools
Suggests:	testthat (≥ 3.0.0), knitr, rmarkdown, spelling
VignetteBuilder:	knitr
URL:	https://github.com/mqfarooqi1/orbis, https://mqfarooqi1.github.io/orbis/
BugReports:	https://github.com/mqfarooqi1/orbis/issues
Config/testthat/edition:	3
LazyData:	true
Config/roxygen2/version:	8.0.0
NeedsCompilation:	no
Packaged:	2026-07-26 11:26:22 UTC; faroo
Author:	Muhammad Farooqi [aut, cre]
Maintainer:	Muhammad Farooqi <mqfarooqi@gmail.com>
Repository:	CRAN
Date/Publication:	2026-08-05 07:40:02 UTC

orbis: interactive and high-resolution layered graphics

Description

orbis builds plots from a layered grammar, compiles them to a resolution-independent scene description, and renders that scene through two back-ends:

Details

• a self-contained SVG writer with embedded JavaScript, giving interactive figures (tooltips, hover highlighting, zoom, pan, legend toggling) that need no internet connection and no JavaScript library, and

• R's own graphics devices, giving publication-quality raster or vector output at any resolution.

Geographic layers are first class: a simplified world polygon dataset ships with the package (world_map) and can be drawn in several projections with orb_map(), including an orthographic globe.

Getting started

Start a plot with orb(), add layers with orb_points(), orb_line(), orb_bars(), orb_area() or orb_map(), adjust appearance with orb_labs() and the ⁠orb_theme_*()⁠ functions, then display it, write it with orb_save(), or open the interactive version with orb_interactive().

Author(s)

Maintainer: Muhammad Farooqi mqfarooqi@gmail.com (ORCID)

Authors:

• Muhammad Farooqi mqfarooqi@gmail.com (ORCID)

See Also

Useful links:

• https://github.com/mqfarooqi1/orbis

• https://mqfarooqi1.github.io/orbis/

• Report bugs at https://github.com/mqfarooqi1/orbis/issues

Add layers, scales, labels and themes to a plot

Description

The + operator assembles a plot from parts, in the tradition of a layered grammar of graphics.

Usage

## S3 method for class 'orb_spec'
e1 + e2

Arguments

Value

An orb_spec object.

Examples

orb(mtcars, x = wt, y = mpg) + orb_points() + orb_theme_dark()

Start a plot

Description

orb() creates a plot specification: it records the data and the mapping from variables to visual channels. Layers, labels, scales and themes are added with +. Nothing is drawn until the plot is printed or saved, so a specification is cheap to build and modify.

Usage

orb(data, ...)

Arguments

Details

Mappings are given as bare column names, in the style of a formula-free grammar: orb(df, x = wt, y = mpg, colour = cyl). The recognised channels are x, y, colour (or color), fill, size, label, group and tooltip.

Value

An object of class orb_spec.

See Also

orb_points(), orb_line(), orb_bars(), orb_area(), orb_map(), orb_save(), orb_interactive()

Examples

p <- orb(mtcars, x = wt, y = mpg, colour = cyl) + orb_points()
p

Area layer

Description

Fills the region between a line and a baseline.

Usage

orb_area(
  ...,
  data = NULL,
  fill = NULL,
  alpha = 0.45,
  baseline = 0,
  smooth = FALSE
)

Arguments

Value

An object of class orb_layer.

Examples

df <- data.frame(t = 1:40, v = abs(cumsum(rnorm(40))))
orb(df, x = t, y = v) + orb_area(alpha = 0.5) + orb_line()

Bar layer

Description

Draws one bar per observation. x may be discrete (a factor or character column) or continuous. Bars start at zero.

Usage

orb_bars(
  ...,
  data = NULL,
  width = 0.72,
  fill = NULL,
  colour = NULL,
  alpha = 0.95,
  horizontal = FALSE
)

Arguments

Value

An object of class orb_layer.

Examples

df <- data.frame(g = c("a", "b", "c"), v = c(3, 7, 5))
orb(df, x = g, y = v, fill = g) + orb_bars()

Cartesian coordinates

Description

The default coordinate system. Use it to return to Cartesian coordinates or to force a fixed aspect ratio.

Usage

orb_coord_cartesian(ratio = NULL)

Arguments

Value

An object of class orb_coord.

Examples

orb(mtcars, x = wt, y = mpg) + orb_points() + orb_coord_cartesian()

Map projections

Description

Sets the coordinate system to a geographic projection. Longitude and latitude are projected before being mapped to the panel, so map layers and point layers stay aligned.

Usage

orb_coord_map(projection = "equirectangular", centre = c(0, 0), max_lat = 84)

Arguments

Details

Available projections:

equirectangular

Longitude and latitude used directly; simple and fast, but distorts area away from the equator.

mercator

Conformal cylindrical projection; preserves angles, greatly exaggerates high latitudes. Latitudes are clipped at \pmmax_lat.

robinson

A compromise projection widely used for world maps.

mollweide

Equal-area pseudo-cylindrical projection.

equalearth

The Equal Earth projection of Savric, Patterson and Jenny (2019): equal-area, like Mollweide, but with continents shaped much closer to the familiar Robinson outline. A good modern default for thematic world maps, because areas are not distorted.

orthographic

A view of the globe from infinite distance, centred on centre; the hemisphere facing away from the viewer is hidden.

Value

An object of class orb_coord, to be added to a plot.

References

Snyder, J. P. (1987) "Map Projections: A Working Manual." US Geological Survey Professional Paper 1395. doi:10.3133/pp1395

Savric, B., Patterson, T. & Jenny, B. (2019) "The Equal Earth map projection." International Journal of Geographical Information Science 33, 454-465. doi:10.1080/13658816.2018.1504949

Examples

orb_worldmap() + orb_coord_map("robinson")
orb_worldmap() + orb_coord_map("equalearth")
orb_worldmap() + orb_coord_map("orthographic", centre = c(20, 15))

Draw a plot on the current graphics device

Description

Renders through R's grid graphics, so the plot appears on whatever device is active. orb_save() is usually more convenient.

Usage

orb_draw(plot, width = 820, height = 520)

Arguments

Value

NULL, invisibly. Called for its side effect.

Examples

p <- orb(mtcars, x = wt, y = mpg) + orb_points()
f <- tempfile(fileext = ".png")
grDevices::png(f, width = 820, height = 520)
orb_draw(p)
grDevices::dev.off()
unlink(f)

Split a plot into small multiples

Description

Faceting draws one panel per level of a grouping variable, laid out in a grid. Comparing many small panels that share a scale is often clearer than overplotting every group in one panel.

Usage

orb_facet(by, ncol = NULL, scales = c("fixed", "free_x", "free_y", "free"))

Arguments

Value

An object of class orb_facet, to be added to a plot.

Examples

orb(mtcars, x = wt, y = mpg) + orb_points() + orb_facet(cyl)
orb(mtcars, x = wt, y = mpg) + orb_points() +
  orb_facet(cyl, ncol = 3, scales = "free")

Point layer positioned by longitude and latitude

Description

Places points on a map using the active projection. Use inside a plot that also has an orb_map() layer, mapping x to longitude and y to latitude.

Usage

orb_geo_points(
  ...,
  data = NULL,
  size = 4,
  colour = "#F76707",
  alpha = 0.9,
  stroke = 0.8
)

Arguments

Value

An object of class orb_layer.

Examples

cities <- data.frame(long = c(2.35, -74, 151.2), lat = c(48.86, 40.7, -33.87),
                     pop = c(11, 19, 5))
orb(cities, x = long, y = lat, size = pop) +
  orb_map() + orb_points(colour = "#F76707") + orb_coord_map("robinson")

Open or write an interactive plot

Description

Builds a self-contained HTML document containing the plot as inline SVG plus a small embedded script. The result works offline, needs no JavaScript library, and supports tooltips, hover highlighting, mouse-wheel zoom, dragging to pan, double-click to reset, and clicking legend keys to show or hide series.

Usage

orb_interactive(
  plot,
  file = NULL,
  width = 820,
  height = 520,
  title = "orbis plot"
)

Arguments

Value

If file is given, the path (invisibly); otherwise an htmltools tag object.

Examples

p <- orb(mtcars, x = wt, y = mpg, colour = cyl) + orb_points()
f <- tempfile(fileext = ".html")
orb_interactive(p, file = f)
file.exists(f)
unlink(f)

Axis, legend and plot labels

Description

Axis, legend and plot labels

Usage

orb_labs(
  title = NULL,
  subtitle = NULL,
  x = NULL,
  y = NULL,
  colour = NULL,
  fill = NULL,
  size = NULL,
  caption = NULL
)

Arguments

Value

An object of class orb_labs, to be added to a plot.

Examples

orb(mtcars, x = wt, y = mpg) + orb_points() +
  orb_labs(title = "Fuel use", x = "Weight", y = "Miles per gallon")

Line layer

Description

Connects observations in the order they appear, optionally split by a group or colour mapping.

Usage

orb_line(
  ...,
  data = NULL,
  width = 1.8,
  colour = NULL,
  alpha = 1,
  smooth = FALSE
)

Arguments

Value

An object of class orb_layer.

Examples

df <- data.frame(t = 1:50, v = cumsum(rnorm(50)))
orb(df, x = t, y = v) + orb_line(width = 2, smooth = TRUE)

World map layer

Description

Draws country polygons from the built-in world_map dataset, or from a data frame of your own with long, lat and group columns. The projection is set with orb_coord_map(); if none is given, an equirectangular projection is used.

Usage

orb_map(
  data = NULL,
  values = NULL,
  region_col = "region",
  value_col = NULL,
  fill = "#DEE2E6",
  colour = "#FFFFFF",
  width = 0.4,
  alpha = 1,
  palette = "viridis",
  na_fill = "#E9ECEF",
  ocean = NULL
)

Arguments

Details

To build a choropleth, supply values: a data frame with a region column and a value column, matched to map regions by name.

Value

An object of class orb_layer.

See Also

orb_coord_map(), world_map

Examples

orb_worldmap()

vals <- data.frame(region = c("Brazil", "India", "France"), v = c(3, 9, 5))
orb(world_map) + orb_map(values = vals, region_col = "region",
                         value_col = "v") + orb_coord_map("robinson")

Plot-level options

Description

Plot-level options

Usage

orb_options(legend = NULL, grid = NULL, interactive = NULL)

Arguments

Value

An object of class orb_opts, to be added to a plot.

Examples

orb(mtcars, x = wt, y = mpg) + orb_points() + orb_options(grid = "y")

Colour palettes available in orbis

Description

Lists the palette names accepted by orb_scale_colour() and orb_scale_fill().

Usage

orb_palettes()

Value

A list with two character vectors: continuous (sequential and diverging ramps) and discrete (qualitative palettes).

Examples

orb_palettes()

Point layer

Description

Draws one mark per observation: a scatter plot, or a bubble chart when a size mapping is present.

Usage

orb_points(
  ...,
  data = NULL,
  size = 3.2,
  colour = NULL,
  fill = NULL,
  alpha = 0.9,
  stroke = 0.8
)

Arguments

Value

An object of class orb_layer.

Examples

orb(mtcars, x = wt, y = mpg, colour = cyl) + orb_points(alpha = 0.85)

Save a plot at any resolution

Description

Writes a plot to disk. The format is taken from the file extension:

Usage

orb_save(plot, file, width = 820, height = 520, dpi = 300, interactive = TRUE)

Arguments

Details

.svg

Vector output from the built-in SVG writer. Being a vector format it is resolution independent - it stays sharp at any size.

.html

A self-contained interactive page (see orb_interactive()).

.pdf

Vector output through R's PDF device.

.png, .tiff, .jpeg

Raster output at the requested dpi; use 300 or more for print.

Value

The file path, invisibly.

See Also

orb_svg(), orb_interactive(), orb_draw()

Examples

p <- orb(mtcars, x = wt, y = mpg, colour = cyl) + orb_points()
f <- tempfile(fileext = ".png")
orb_save(p, f, dpi = 300)
file.exists(f)
unlink(f)

Scales

Description

Scales control how data values are converted to visual values: which colours a variable spans, how large points become, and the limits and transformation of the axes.

Usage

orb_scale_colour(palette = "viridis", limits = NULL, reverse = FALSE)

orb_scale_fill(palette = "viridis", limits = NULL, reverse = FALSE)

orb_scale_size(range = c(2, 14), limits = NULL)

orb_scale_x(limits = NULL, trans = "identity", breaks = NULL, expand = 0.04)

orb_scale_y(limits = NULL, trans = "identity", breaks = NULL, expand = 0.04)

Arguments

Value

An object of class orb_scale, to be added to a plot.

Examples

p <- orb(mtcars, x = wt, y = mpg, colour = hp) + orb_points()
p + orb_scale_colour("magma", reverse = TRUE)
p + orb_scale_y(limits = c(10, 35))

Render a plot as SVG

Description

Produces a standalone SVG image of a plot. SVG is a vector format, so the result is resolution independent: it stays sharp at any size or zoom level, which is what makes it suitable both for the web and for print.

Usage

orb_svg(plot, width = 820, height = 520, interactive = TRUE, id = NULL)

Arguments

Value

A character string containing SVG (and, if requested, a wrapping div with the script).

See Also

orb_save(), orb_interactive()

Examples

p <- orb(mtcars, x = wt, y = mpg) + orb_points()
s <- orb_svg(p, interactive = FALSE)
substr(s, 1, 40)

Text layer

Description

Draws a text label at each observation.

Usage

orb_text(..., data = NULL, size = 10, colour = NULL, dy = 0, alpha = 1)

Arguments

Value

An object of class orb_layer.

Examples

df <- data.frame(x = 1:3, y = c(2, 4, 3), n = c("a", "b", "c"))
orb(df, x = x, y = y, label = n) + orb_points() + orb_text(dy = -10)

Visual themes

Description

Themes control the non-data appearance of a plot: colours of the background, grid, axes and text, plus base font size. Add a theme to a plot with +.

Usage

orb_theme_light(base_size = 12, ...)

orb_theme_dark(base_size = 12, ...)

orb_theme_minimal(base_size = 12, ...)

orb_theme_ink(base_size = 12, ...)

Arguments

Value

An object of class orb_theme, to be added to a plot.

Examples

p <- orb(mtcars, x = wt, y = mpg) + orb_points()
p + orb_theme_dark()
p + orb_theme_light(base_size = 14)

A ready-made world map

Description

A convenience wrapper that returns a complete world map plot, optionally shaded by a value per region.

Usage

orb_worldmap(
  values = NULL,
  region_col = "region",
  value_col = NULL,
  projection = "equirectangular",
  palette = "viridis",
  ocean = NULL,
  title = NULL
)

Arguments

Value

An orb_spec object.

Examples

orb_worldmap(projection = "orthographic")

World country polygons

Description

A simplified set of world country outlines, suitable for thematic world maps at typical figure sizes. Polygon rings were simplified with the Douglas-Peucker algorithm to keep the dataset small while preserving the recognisable shape of coastlines and borders.

Usage

world_map

Format

A data frame with four columns:

long

Longitude in degrees, from -180 to 180.

lat

Latitude in degrees, from -90 to 90.

group

Integer identifying the polygon ring a point belongs to. Points must be drawn ring by ring; a country made of several land masses has several rings.

region

Country or territory name.

Details

Coordinates are unprojected longitude and latitude in degrees; use orb_coord_map() to choose a projection.

Source

Derived from the world database of the maps package, whose boundaries come from Natural Earth (https://www.naturalearthdata.com), released into the public domain.

References

Douglas, D. H. & Peucker, T. K. (1973) "Algorithms for the reduction of the number of points required to represent a digitized line or its caricature." Cartographica 10, 112-122. doi:10.3138/FM57-6770-U75U-7727

Examples

str(world_map)
length(unique(world_map$region))
orb_worldmap()