Contributing an atlas package

ggseg atlases live in their own R packages, distributed through the ggsegverse r-universe. This provides a single place for all ggseg-compatible packages, whether hosted on GitHub, GitLab, or elsewhere.

If you have a working atlas and want it available through r-universe, follow these steps.

Requirements

1. The data must work with ggseg, ggseg3d, or both.
2. The data must be in its own R package.
3. The R package must be hosted in a public version control repository (GitHub, GitLab, etc.).
4. The package must pass R CMD check without errors.

Setting up the package repository

Since setting up a data package can be tricky, we provide a function to get you started. It includes tests and the general structure we expect from a ggseg-atlas package. If you already make R packages comfortably, skip this step.

To create a ggseg repo, use the RStudio New Project creation GUI and look for the ggseg icon. Or call setup_atlas_repo() directly:

ggseg.extra::setup_atlas_repo("ggsegMyatlas", "myatlas")

Edit DESCRIPTION

The DESCRIPTION file contains important metadata about your package. You need to edit it for several reasons:

• List yourself (and collaborators) as authors and maintainers. Remove the template authors and add your own names. ORCID is optional.
• Update the Description: section to reflect your package contents.
• Change URL: and BugReports to point to your remote repository. If your host doesn’t support issues, delete BugReports entirely.

Create your atlas

Run the script in data-raw/create-atlas.R. This walks you through the atlas creation pipeline and saves the result as internal package data in R/sysdata.rda.

The pipeline produces a ggseg_atlas object validated by is_ggseg_atlas().

How atlas data is stored

Atlas packages store their data as internal objects accessed through exported functions. This avoids lazy-loading issues and gives you full control over how the atlas is loaded.

The pattern looks like this:

R/data.R – the exported accessor function:

#' My Atlas
#'
#' @references
#' Author A, Author B (Year). Title. *Journal*. doi
#'
#' @return A [ggseg.formats::ggseg_atlas] object.
#' @export
#' @family ggseg_atlases
myatlas <- function() .myatlas

data-raw/create-atlas.R – saves the atlas as internal data:

.myatlas <- myatlas
usethis::use_data(.myatlas, internal = TRUE, overwrite = TRUE, compress = "xz")

This creates R/sysdata.rda containing the dot-prefixed object .myatlas. The exported function myatlas() returns it. Users call myatlas() (with parentheses) to access the atlas.

Do not use LazyData: true or place .rda files in data/.

Document your atlas

Edit R/data.R to describe your atlas. Pay particular attention to:

• The @references tag: cite the original publication for the parcellation.
• The @return tag: specify the atlas type (cortical, subcortical, tract).
• The @family ggseg_atlases tag: this is required for the pkgdown documentation site to work.

After editing, regenerate documentation:

devtools::document()

Getting tests to pass

Once data is saved and documentation is updated, run the tests:

devtools::test()

There will likely be failures. Try to resolve them by reading the error messages.

Common things to check:

• If you only have a 2D or 3D atlas, comment out test sections that refer to the atlas type you’re not including.
• If you have a ggseg-atlas, the tests check for a palette matching atlas$region. Palettes are stored in atlas$palette as a named character vector. Names should match region labels and values should be hexadecimal colour codes.

Let us know if you struggle. We would love to improve this tutorial with the issues you encounter.

Multiple atlases in one package

If your package contains multiple atlases (e.g. yeo7 and yeo17), create one accessor function per atlas:

#' Yeo 7-Network Atlas
#' @return A [ggseg.formats::ggseg_atlas] object.
#' @export
#' @family ggseg_atlases
yeo7 <- function() .yeo7

#' Yeo 17-Network Atlas
#' @return A [ggseg.formats::ggseg_atlas] object.
#' @export
#' @family ggseg_atlases
yeo17 <- function() .yeo17

Save all objects together in one call:

.yeo7 <- yeo7
.yeo17 <- yeo17
usethis::use_data(.yeo7, .yeo17, internal = TRUE, overwrite = TRUE, compress = "xz")

Getting package checks to pass

Once all tests pass, run package checks:

devtools::check()

This attempts to build your package and verify everything works.

Read error messages carefully and try to resolve them.

Common things to check:

• If you haven’t added a license, try usethis::use_mit_license("Your Name Here").

If everything passes, push to your remote repository.

Adding your package to r-universe

Once your package is ready and hosted publicly, submit it to the ggsegverse r-universe.

1. Fork the r-universe repository

Go to source repository for r-universe setup and fork the repository.

2. Edit packages.json

The packages.json file lists all packages in the ggsegverse r-universe. Add an entry for your package:

[
  {
    "package": "ggsegYeo2011",
    "url": "https://github.com/ggsegverse/ggsegYeo2011"
  },
  {
    "package": "yourpackage",
    "url": "https://github.com/yourusername/yourpackage"
  }
]

Each entry needs:

• package: The exact package name (must match your DESCRIPTION file).
• url: The URL to your repository.

For packages not on GitHub, you can also specify a branch or use other URL schemes:

{
  "package": "yourpackage",
  "url": "https://gitlab.com/yourusername/yourpackage",
  "branch": "main"
}

3. Submit a pull request

Commit your changes and open a pull request to the ggseg/universe repository. Include a brief description of your atlas and a link to any relevant publication.

4. Wait for review

We will check that:

• The package installs correctly
• It passes R CMD check
• The atlas works with ggseg and/or ggseg3d

Once merged, r-universe automatically builds your package. It typically appears within an hour at ggsegverse.r-universe.dev.

Installing from r-universe

Users can then install your atlas with:

install.packages("yourpackage", repos = "https://ggsegverse.r-universe.dev")

Or use the ggseg.extra helper:

ggseg_atlas_repos("yourpackage")
install_ggseg_atlas("yourpackage")

Updating your package

When you push updates to your repository, r-universe automatically rebuilds the package. No action needed on your part after the initial setup.

If you move the repository to a different URL, submit a pull request to update packages.json.