Skip to contents

Changelog

Source: NEWS.md

ggseg 2.2.1.9000 (development)

  • position_brain() now ignores the hemi term (with a warning) for slice-based atlases (subcortical, cerebellar, tract). Those views are whole slices already containing both hemispheres, so hemi ~ view no longer splits the grey-brain context into its own row away from the structures — each view now renders with its anatomical context integrated, matching plot().

  • New brain_test_plot() builds a minimal, deterministic atlas plot (regions filled by label, no legend, theme_void()) — the canonical construction for vdiffr snapshots across the ggsegverse, so a stray legend or title cannot creep into a snapshot and every atlas is rendered identically.

  • Tests, examples, and vignettes now resolve region names dynamically through ggseg.formats::atlas_regions() (and the schema-stable label column) instead of hard-coding region strings, so R CMD check passes cleanly against both the released and the development ggseg.formats schema. Visual regression tests that use vdiffr now skip_on_cran(), since their snapshots are geometry-specific and cannot match both schema versions.

  • Examples, tests, and vignettes now use the new ggseg.formats short region keys (e.g. "superiorparietal", "transversetemporal"). The fully spelled-out long names moved to the atlas names column, so passing a long name in a region = position no longer matches. Any user data joined to an atlas by region must use the short keys.

  • Breaking: geom_brain() no longer colours the atlas by its built-in palette when you map no fill. A bare geom_brain(atlas = dk()) now renders grey, matching how regions you supply no value for already looked. geom_brain() is for plotting your data on the brain; for a palette-coloured atlas overview use plot(atlas) (from ggseg.formats), or map it yourself with aes(fill = region) and scale_fill_brain(). This also removes the discrete palette scale that geom_brain() used to inject silently, so a continuous fill set in ggplot() — ggplot(df, aes(fill = value)) + geom_brain(atlas = dk()) — no longer errors with “Continuous value supplied to a discrete scale”.

  • geom_brain() now combines multiple data rows that map to the same atlas region into a single value with a new fun argument (default mean). Long data with several rows per region — e.g. one per subject — is summarised per region instead of overplotting. Any reducing function works, so geom_brain(atlas = dk(), fun = median) draws the median.

  • Faceting no longer needs dplyr::group_by(). The atlas geometry is now drawn by a Stat (StatBrain), which ggplot2 recomputes per panel, so facet_wrap() / facet_grid() work directly from your data. Faceting on a variable of your own (e.g. a cohort) draws the complete brain in every panel; faceting on an atlas column (e.g. hemi or view) draws that slice in each panel, as before. The old grouped-data-frame replication in the polygon path is gone (the deprecated sf path is unchanged).

  • New stat_brain() and exported StatBrain ggproto — the stat-first spelling of geom_brain(). Both build the same layer; use stat_brain() to pair StatBrain with a different geom.

  • Roxygen documentation now uses markdown.

  • geom_brain() again warns when rows of your data match no atlas region. The default polygon renderer joins your data onto the atlas with a left join, which silently dropped unmatched rows — so a region name the atlas does not use (e.g. the short "bankssts" against the long region name) vanished without notice. It now surfaces those rows with the same “Some data not merged properly” warning the sf renderer gives (#121).

  • Internal geom/layer consolidation: the exported GeomBrain ggproto is now the polygon geom that backs the default geom_brain() (a GeomPolygon subclass). The deprecated sf renderer’s geom was renamed to the internal GeomBrainSf. Only affects code reaching for the GeomBrain object directly.

  • geom_brain() now ignores (with a warning) a user aes() mapping for x, y, group, or subgroup. These are derived from the atlas geometry — group is the polygon feature id and subgroup marks holes — so mapping them previously corrupted the rendering silently (e.g. aes(group = region) collapsed each region’s separate polygon pieces).

  • Polygon draw order now follows your data’s row order, so overlapping region outlines layer predictably. The renderer used to force alphabetical draw order, so when you mapped a variable to colour the outlines stacked in an order unrelated to that variable. Regions now draw in the order they appear in your data (later rows on top), and regions you supply no value for stay underneath in atlas order — so arrange() your data to control layering (#162).

  • geom_brain() again maps aes(colour = ...) and aes(linewidth = ...) to region outlines. The default outline colour (grey35) and width (0.2) were injected as fixed geom parameters, which silently overrode any mapping. They are now default_aes on a dedicated GeomPolygon subclass, so a mapping (or an explicit constant) takes precedence while the defaults still apply when neither is given (#160).

  • geom_brain() again respects data and aesthetics set in the top-level ggplot() call. The default polygon renderer built the atlas eagerly, before the plot existed, so it never saw inherited data/aes() and fell back to colouring by region label — e.g. ggplot(df, aes(fill = value)) + geom_brain(atlas = dk()) errored with “Discrete value supplied to a continuous scale”. The atlas is now flattened and joined at plot-build time, so inherited mappings, inherited data, and faceting all work (#158).

ggseg 2.2.1

CRAN release: 2026-07-03

  • The test suite now builds its sf fixtures through the public atlas accessors instead of reaching into atlas internals, so tests no longer break when the internal atlas layout changes.

ggseg 2.2.0

CRAN release: 2026-06-22

This release makes the sf package optional. ggseg now draws brains from a lightweight polygon representation by default, so it installs and plots even on systems where sf (and its GDAL / GEOS / PROJ system libraries) is unavailable — including WebAssembly and air-gapped setups.

sf is now optional

New plotting features

  • Zoom in on regions of interest. position_brain(zoom = ...) crops each view onto the regions you’re highlighting so they fill the panel, with the surrounding brain reduced to a tidy grey frame. Use zoom = TRUE to follow the regions in your data, or name them explicitly; zoom_pad sets the margin. Especially handy for focus atlases where only a few structures carry values.
  • Readable view labels. annotate_brain() now places labels clear of the brain instead of on top of it. The new padding argument (5% of the plot height by default) controls the gap.
  • One annotation function. annotate_brain() works with whichever position you gave the geom — there’s no separate labelling function to remember.
  • Hide context regions. geom_brain(context = FALSE) drops the grey, unlabelled regions and tightens the layout around the regions you’re plotting.
  • Faceting. Group your data with dplyr::group_by() and facet_wrap() / facet_grid() draw the full atlas in every panel.
  • FreeSurfer labels. Data keyed by label (e.g. "lh_bankssts") now joins to the atlas directly, in addition to region.

Other changes

  • When no fill is mapped, geom_brain() fills regions with the atlas’s own colours, and the stray “No shared levels” warning that appeared when filtering by hemisphere or view is gone.
  • New coord_brain() keeps brain proportions undistorted; geom_brain() applies it automatically, so you rarely need to add it yourself.
  • The deprecated scale_brain() family keeps working with the current ggseg.formats.
  • The suit cerebellar atlas is re-exported alongside dk(), aseg(), and tracula().

ggseg 2.1.1

CRAN release: 2026-04-16

  • Fix minor bug with ggproto

ggseg 2.1.0

CRAN release: 2026-04-03

  • Support cerebellar atlas type in 2D view stacking. Cerebellar atlases now use the same stacking layout as subcortical atlases in position_brain().

ggseg 2.0.0

CRAN release: 2026-02-19

This is a major release that simplifies the package architecture by moving atlas data structures and utilities to the ggseg.formats package.

Breaking changes

New features

  • New annotate_brain() function adds view labels (e.g., “left lateral”) to brain plots, respecting the layout from position_brain().

  • New scale_brain_manual() family for applying custom named colour palettes to brain plots.

  • position_brain() gains nrow, ncol, and views arguments for grid-based layout control of subcortical and tract atlases.

  • adapt_scales() now accepts atlas objects directly (not just pre-converted coordinate data frames), and handles "tract" atlas types alongside subcortical.

  • geom_brain() now automatically applies the atlas colour palette when no fill aesthetic is mapped.

Improvements

  • Messaging uses cli for all user-facing output (brain_join() warnings and info messages).

  • Rewrote and reorganised all vignettes with updated examples and renamed files for cleaner URLs.

  • Added tracula (white matter tract) atlas as a re-export from ggseg.formats.

  • Improved documentation throughout with updated roxygen2 docs.

ggseg 1.6

ggseg 1.6.8

  • Increased C++ standard to C++17 to comply with CRAN policies

ggseg 1.6.7

  • Fixed testthat issues with latest version of testthat
  • Fixed vignette build issues on CRAN
  • removed sf minimum version requirement

ggseg 1.6.5

  • Bump version to 1.6.5
  • rm freesurfer dep
  • rm old remnants
  • update readme img
  • switch cerebellum labels for wm, gm, fix #80
  • fix aseg labels to original, fix #78
  • add vis as categorical. fix #76
  • change aseg data class , fix #56
  • bump version, small CRAN fixes
  • add sysreq
  • fix axial to coronal in vignette
  • change axial to coronal in aseg data
  • re-add ggplot2 depends

1.6.4

  • Added options hemi and side to geom
  • improved position_brain() to accept character vector, and also support subcortical atlases
  • Altered axial to coronal in aseg atlas

1.6.3.01

  • fixed broken geom after changes to ggplot2 internals
  • fixed spelling mistakes in docs

ggseg 1.6.3

  • removed function to display ggseg palettes
  • preparations for CRAN submission
    • added examples to more functions
    • updated links

ggseg 1.6.02

  • bug fixes in atlas objects and method internals
  • tests in vdiffr
  • vctrs class for polygon ggseg data

ggseg 1.6.02

  • No longer depends on ggplot2, but imports it.
    • as is advised practice
    • users must explicitly load ggplot2 to access further ggplot2 functions

ggseg 1.6.01

  • fixed installation issues by making sure package depends on R>3.3 for polygon holes.

ggseg 1.6.00

New large update, many new features. Of particular note is the introduction of the brain sf geom, which improved speed, and adaptability of the plots.

  • ggseg() will stay for a while, but is superseded by a simple features geom
  • geom_brain introduced as a new function to plot the atlas data
    • an sf geom provides a lot of new features to the package
    • more control over display of the slices through position_brain()
    • improved capabilities for atlases with regions that have holes
  • new atlas class brain_atlas which contains simple features data
  • new functions to allow compatibility between sf and polygon data
  • utility functions to use on the atlas data for easy access to information
    • plot() functions for ggseg_atlas and brain_atlas classes for a quick look at atlases
    • brain_regions functions to easily extract the unique names of regions for an atlas
    • improved print method for atlases classes ggseg_atlas and brain_atlas

ggseg 1.5

ggseg 1.5.5

  • dk atlas regions renamed to better reflect correct naming
    • pre central and post central are precentral and postcentral
  • dk atlas now also includes the corpus callosum, as the original atlas contains

ggseg 1.5

ggseg 1.5.4

  • dkt renamed to dk
    • the dkt (Desikan-Killiany-Tourville) atlas is not yet available
  • atlas columns area renamed to region
    • to avoid confusion with the calculation of cortical/surface area
  • dk atlas region name “medial orbito frontal” changed to “medial orbitofrontal”

ggseg 1.5.3

  • Split ggseg, and ggseg3d into two different packages

ggseg 1.5.2

  • Adapted to work with dplyr 0.8.1

ggseg 1.5.1

  • Changed ggseg_atlas-class to have nested columns for easier viewing and wrangling

ggseg 1.5

  • Changed atlas.info to function atlas_info()

  • Changed brain.pal to function brain_pal()

  • Changed atlas.info to function atlas_info()

  • Reduced code necessary for brain_pals_info

  • Simplified display_brain_pal()

  • Moved palettes of ggsegExtra atlases to ggsegExtra package

  • Added a NEWS.md file to track changes to the package.

  • Added compatibility with grouped data.frames

  • Reduced internal atlases, to improve CRAN compatibility

  • Added function to install extra atlases from github easily

  • Changes vignettes to comply with new functionality