Getting started with orbis

The hardware and bandwidth for this mirror is donated by METANET, the Webhosting and Full Service-Cloud Provider.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]metanet.ch.

orbis describes a plot with a layered grammar, then compiles that description to a scene of drawing primitives. Because the scene is resolution independent, the same plot object can become an interactive figure in a browser or a 600 dpi image for a journal, with nothing re-specified.

The grammar

A plot starts with data and a mapping from variables to visual channels. Layers are added with +.

p <- orb(mtcars, x = wt, y = mpg, colour = hp, size = disp) +
  orb_points() +
  orb_labs(title = "Fuel economy", x = "Weight (1000 lbs)",
           y = "Miles per gallon", colour = "Horsepower")
p

Recognised channels are x, y, colour (or color), fill, size, label, group and tooltip. A mapping given inside a layer applies to that layer only.

Continuous variables mapped to colour use a perceptually uniform ramp; character or factor variables get a qualitative palette and an interactive legend.

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

Layers

set.seed(1)
df <- data.frame(t = 1:80, v = cumsum(rnorm(80, 0.05)))

orb(df, x = t, y = v) +
  orb_area(alpha = 0.3) +
  orb_line(width = 2, smooth = TRUE) +
  orb_labs(title = "A smoothed series")

orb_bars() accepts a discrete x:

counts <- data.frame(g = c("alpha", "beta", "gamma", "delta"),
                     v = c(23, 41, 17, 35))
orb(counts, x = g, y = v, fill = g) +
  orb_bars() +
  orb_options(legend = FALSE, grid = "y") +
  orb_theme_ink()

Small multiples

orb_facet() draws one panel per level of a variable. Panels share their scales by default, which is what makes them comparable at a glance.

orb(mtcars, x = wt, y = mpg, colour = hp) +
  orb_points() +
  orb_facet(cyl) +
  orb_labs(title = "By cylinder count", x = "Weight", y = "MPG")

Use scales = "free" (or "free_x", "free_y") when panels cover very different ranges, and ncol to control the grid:

set.seed(3)
d <- data.frame(t = rep(1:40, 3),
                v = c(cumsum(rnorm(40)), cumsum(rnorm(40, 0.3)),
                      cumsum(rnorm(40, -0.2))),
                region = rep(c("north", "south", "east"), each = 40))
orb(d, x = t, y = v) +
  orb_area(alpha = 0.3) + orb_line() +
  orb_facet(region, ncol = 3, scales = "free_y")

Colours and sizes are resolved across the whole data set rather than per panel, so a colour means the same thing everywhere.

Scales

Scales set palettes, limits and axis transformations.

orb(mtcars, x = wt, y = mpg, colour = hp) +
  orb_points() +
  orb_scale_colour("magma", reverse = TRUE) +
  orb_scale_size(range = c(3, 16)) +
  orb_scale_y(limits = c(10, 35))

Available palettes:

orb_palettes()
#> $continuous
#> [1] "viridis"  "magma"    "mako"     "ember"    "ice"      "spectral" "balance" 
#> 
#> $discrete
#> [1] "orbis" "vivid" "earth" "neon"

Maps

A simplified world dataset ships with the package.

str(world_map)
#> 'data.frame':    26953 obs. of  4 variables:
#>  $ long  : num  -69.9 -70.1 -70 -69.9 74.9 ...
#>  $ lat   : num  12.5 12.5 12.6 12.5 37.2 ...
#>  $ group : int  1 1 1 1 2 2 2 2 2 2 ...
#>  $ region: chr  "Aruba" "Aruba" "Aruba" "Aruba" ...

orb_worldmap() is the quickest way to a map. Supply values to shade regions by a variable.

vals <- data.frame(region = c("Brazil", "India", "France", "China", "Nigeria"),
                   v = c(3, 9, 5, 8, 6))
orb_worldmap(values = vals, value_col = "v", projection = "robinson") +
  orb_labs(title = "A small choropleth")

Six projections are built in. equalearth is a good modern default for thematic maps: it is equal-area, so shaded country sizes are directly comparable, while keeping continents close to their familiar shapes.

orb_worldmap(values = vals, value_col = "v", projection = "equalearth",
             palette = "ice") +
  orb_labs(title = "Equal Earth")

The orthographic projection draws a globe and hides the hemisphere facing away from the viewer.

orb_worldmap(projection = "orthographic", ocean = "#0B1F33") +
  orb_coord_map("orthographic", centre = c(20, 15)) +
  orb_theme_dark()

Points are placed on the active projection with orb_geo_points():

cities <- data.frame(
  long = c(2.35, -74.0, 151.2, 77.2, -43.2),
  lat  = c(48.86, 40.7, -33.87, 28.6, -22.9),
  pop  = c(11, 19, 5, 32, 13)
)
orb(cities, x = long, y = lat, size = pop) +
  orb_map(fill = "#E9ECEF") +
  orb_geo_points(colour = "#F76707") +
  orb_coord_map("robinson") +
  orb_labs(title = "Cities")

Output

One plot object, several destinations. The format follows the file extension.

orb_save(p, "figure.png", dpi = 600)   # high-resolution raster for print
orb_save(p, "figure.pdf")              # vector
orb_save(p, "figure.svg")              # vector, still interactive
orb_save(p, "figure.html")             # self-contained interactive page
orb_interactive(p)                     # open in the viewer

Raster output is laid out at width x height logical pixels and then rendered at the requested dpi, so a 300 or 600 dpi figure keeps the same proportions as what you saw on screen.

The interactive output supports:

hovering a mark for a tooltip,
scrolling to zoom and dragging to pan,
double-clicking to reset the view,
clicking a legend key to hide or show that series.

Set orb_options(interactive = FALSE) if a document must not contain scripts.

What orbis does not do yet

There are no statistical layers, so summarise data before plotting: there is no smoother, boxplot or histogram geometry yet. Text is measured approximately when laying out axes and legends, because the SVG writer does not query a font engine, so very long labels can be spaced imperfectly. The bundled world map is simplified for figure-sized output rather than for detailed cartography.

These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.