---
title: "Contributing an atlas package"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Contributing an atlas package}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r}
#| label: setup
#| include: false
library(ggseg.extra)
```

ggseg atlases live in their own R packages, distributed through the [ggsegverse r-universe](https://ggsegverse.r-universe.dev).
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:

```{r}
#| label: setup-repo
#| eval: false
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:

```r
#' 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:

```r
.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:

```{r}
#| label: document
#| eval: false
devtools::document()
```

### Getting tests to pass

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

```{r}
#| label: run-tests
#| eval: false
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:

```r
#' 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:

```r
.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:

```{r}
#| label: run-check
#| eval: false
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](https://github.com/ggsegverse/ggsegverse.r-universe.dev) 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:

```json
[
  {
    "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:

```json
{
  "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](https://ggsegverse.r-universe.dev).

## Installing from r-universe

Users can then install your atlas with:

```{r}
#| label: install-example
#| eval: false
install.packages("yourpackage", repos = "https://ggsegverse.r-universe.dev")
```

Or use the ggseg.extra helper:

```{r}
#| label: install-helper
#| eval: false
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`.