Adding a package

Scaffold, house style, and shared assets for a new malariaverse package

Note

This is a maintainer-facing page, and part of the packages pillar of maintenance. See also Versioning & releases and Governance.

A malariaverse package is just an ordinary R package that meets a small minimum bar and follows a few shared conventions so it looks and behaves like its siblings. This page is the checklist for creating one.

Minimum bar

A package is ready to join the malariaverse when it:

  • passes R CMD check cleanly on GitHub Actions,
  • has a test suite (testthat),
  • has a published pkgdown site,
  • has a hex logo and a README carrying a repostatus status badge, and
  • has a card added to the malariaverse home page.

Governance for who signs off on a new package is on the Governance page.

Scaffold with usethis

The existing packages were all scaffolded with usethis + the r-lib/actions workflows, so new packages should be too — it keeps the CI identical across the suite and avoids hand-rolled config drifting out of date.

# 1. Create the package
usethis::create_package("mypkg")
usethis::use_mit_license("Imperial College of Science, Technology and Medicine")   # or as appropriate
usethis::use_git()
usethis::use_github(organisation = "mrc-ide")

# 2. Tests
usethis::use_testthat()
usethis::use_test("myfunction")

# 3. Continuous integration (matches the rest of the suite)
usethis::use_github_action("check-standard")   # -> .github/workflows/check-standard.yaml
usethis::use_github_action("test-coverage")    # -> .github/workflows/test-coverage.yaml

# 4. pkgdown site + GitHub Pages deploy
usethis::use_pkgdown_github_pages()            # creates _pkgdown.yml + .github/workflows/pkgdown.yaml

# 5. README with badges
usethis::use_readme_rmd()

This is the CI layout to aim for: check-standard.yaml, pkgdown.yaml and test-coverage.yaml, so that a maintainer moving between repos finds CI in the same place. site, postie and netz already follow it.

Note that the older packages do not, and are not worth churning just for consistency: cali uses R-CMD-check.yaml in place of check-standard.yaml, and malariasimulation has R-CMD-check.yaml, pkgdown.yml (note the extension) and touchstone.yaml for benchmarking, with no test-coverage workflow. If you are looking at an existing package and its CI does not match the scaffold above, that is why.

Depending on other mrc-ide packages

mrc-ide packages are installed from GitHub, not CRAN, so declare them in both Imports:/Suggests: and Remotes: in DESCRIPTION (the r-lib/actions check installs Remotes automatically via pak):

Imports:
    malariasimulation
Remotes:
    mrc-ide/malariasimulation

Before releasing a change that other packages depend on, follow the compatibility checks on the Versioning & releases page.

pkgdown conventions

  • template: bootstrap: 5 (all suite sites use Bootstrap 5).

  • For a package that will announce breaking changes, add a 📢 Latest changes navbar component pointing at a Latest-changes article — this is the suite’s release-communication convention (see Versioning & releases). Example from site/_pkgdown.yml:

    navbar:
  structure:
    left:  [intro, changes, articles, news]
    right: [search, github]
  components:
    changes:
      text: 📢 Latest changes
      href: articles/Latest-changes.html

Because pkgdown serves man/figures/ at reference/figures/ on the built site, the malariaverse home page can pull each hex logo live from https://mrc-ide.github.io/<pkg>/reference/figures/<Pkg>.png.

House visual style

The canonical plotting style lives in the site package (R/plot.R, exported), built around navy #1B2A6C. Reuse it — don’t reinvent it.

  • If your package already depends on site, call site::theme_site() and the site palette helpers directly.
  • Otherwise, reproduce the same look. The pieces are:
# Navy used throughout
navy <- "#1B2A6C"

# theme_site(): theme_bw() with navy axis/title text, no minor gridlines,
# no major x gridline, rotated x labels, default 1/3 aspect ratio.
theme_site <- function(aspect.ratio = 1 / 3) {
  ggplot2::theme_bw() +
    ggplot2::theme(
      legend.background = ggplot2::element_blank(),
      panel.grid.minor  = ggplot2::element_blank(),
      panel.grid.major.x = ggplot2::element_blank(),
      axis.text.x = ggplot2::element_text(angle = 90, vjust = 0.5, hjust = 1, colour = navy),
      axis.text.y = ggplot2::element_text(colour = navy),
      axis.title  = ggplot2::element_text(colour = navy),
      plot.title  = ggplot2::element_text(colour = navy, face = "bold", size = 12),
      aspect.ratio = aspect.ratio
    )
}

The shared palettes (also in site::):

Helper Purpose Colours
site_age_palette(n) ordered/sequential (age groups) ramp of #2A9D8F → #E9C46A → #E76F51
site_vector_palette(n) categorical (vector species) #2A9D8F, #E76F51, #1B2A6C, #E9C46A, #D81B60, #6A4C93, #1982C4, #FF595E
prevalence colours Pf / Pv pfpr = #D81B60, pvpr = #1E88E5
Tip

This is the palette as it exists in code today — it is not the Okabe-Ito palette. If the group decides to move to a colourblind-safe standard in future, change it in site:: and have other packages inherit from there, so the suite stays consistent.

Hex stickers and shared assets

The problem: each package’s hex currently lives only in that package’s own repo (man/figures/<Pkg>.png, served at reference/figures/<Pkg>.png), and the original source files (Illustrator/SVG/R scripts) are not version-controlled anywhere public.

Conventions to follow for a new package:

  • Name the file <Pkg>.png with a capitalised first letter (Netz.png, Site.png, …), matching the rest of the suite, and place it in man/figures/. (malariasimulation is the one lowercase exception.)
  • Add it to the home-page card in index.qmd alongside the Access / R-CMD-check / repostatus badges.

Recommended home for the source files (for group sign-off): keep a durable, version-controlled copy of every hex and its source (.svg/.ai/generating R scripts) so it survives staff changes. The current working source is held on an internal drive:

Internal-drive location: <add the path to the shared drive folder here>

An internal drive is fine as a working store but is not discoverable by future maintainers and is easily lost at handover. The recommendation is therefore to commit a copy into a single shared, version-controlled location — either an assets/hex/ folder in this malariaverse repo (it is already the hub that displays them), or a dedicated mrc-ide/hexstickers repo if full separation is preferred. (Not yet created — awaiting confirmation of the approach and the drive path above.)