Creating a better universe with dverse

This article shows how to create a global search for any collection of R packages, i.e. a universe. Your universe may be on CRAN, large, and popular like the tidyverse or pharmaverse. But it may also be not on CRAN, small, company-specific or personal.

The example here uses the ‘admiralverse’ – a toy universe defined as every package on CRAN today (2024-12-07), with a website, and a name starting with ‘admiral’.

You need:

• the package {dverse} to document your universe,
• each package in the toy ‘admiralverse’ to access the documentation metadata,
• {dplyr} to manipulate the output of {dverse} , and
• {DT} to create a searchable table.

library(dverse)
library(admiral)
library(admiraldev)
library(admiralonco)
library(admiralophtha)
library(admiralpeds)
library(admiralvaccine)
library(dplyr)
library(DT)

Versions

packageVersion("dverse")
## [1] '0.2.0'
packageVersion("admiral")
## [1] '1.1.1'
packageVersion("admiraldev")
## [1] '1.1.0'
packageVersion("admiralonco")
## [1] '1.1.0'
packageVersion("admiralophtha")
## [1] '1.1.0'
packageVersion("admiralpeds")
## [1] '0.1.0'
packageVersion("admiralvaccine")
## [1] '0.3.0'
packageVersion("dplyr")
## [1] '1.1.4'
packageVersion("DT")
## [1] '0.33'

dverse::document_universe() takes the names of the packages in the ‘admiralverse’, and a template pointing to each help file (topic) in each package.

admiralverse <- c(
  "admiral",
  "admiraldev",
  "admiralonco",
  "admiralophtha",
  "admiralpeds",
  "admiralvaccine"
)
# For example: https://pharmaverse.github.io/admiral/reference/queries.html
template <- "https://pharmaverse.github.io/{package}/reference/{topic}.html"

docs <- dverse::document_universe(admiralverse, template)
docs
## # A tibble: 344 × 7
##    topic                               alias title concept type  keyword package
##    <chr>                               <chr> <chr> <chr>   <chr> <chr>   <chr>  
##  1 <a href=https://pharmaverse.github… %>%   Pipe… reexpo… help  <NA>    admiral
##  2 <a href=https://pharmaverse.github… %not… Nega… dev_ut… help  <NA>    admira…
##  3 <a href=https://pharmaverse.github… %or%  Or    dev_ut… help  <NA>    admira…
##  4 <a href=https://pharmaverse.github… adbc… Crea… <NA>    vign… <NA>    admira…
##  5 <a href=https://pharmaverse.github… adce  Crea… <NA>    vign… <NA>    admira…
##  6 <a href=https://pharmaverse.github… add_… Add … quo     help  <NA>    admira…
##  7 <a href=https://pharmaverse.github… adfa… Crea… <NA>    vign… <NA>    admira…
##  8 <a href=https://pharmaverse.github… adis  Crea… <NA>    vign… <NA>    admira…
##  9 <a href=https://pharmaverse.github… admi… admi… intern… help  intern… admiral
## 10 <a href=https://pharmaverse.github… admi… Lab … datase… help  datase… admiral
## # ℹ 334 more rows

You may need to exclude some topics, such as reexported objects from other packages. Because topics outside your universe yield broken links, you can exclude them with dverse::is_online() .

docs |> filter(!dverse::is_online(topic))
## # A tibble: 9 × 7
##   topic                                alias title concept type  keyword package
##   <chr>                                <chr> <chr> <chr>   <chr> <chr>   <chr>  
## 1 <a href=https://pharmaverse.github.… %>%   Pipe… reexpo… help  <NA>    admiral
## 2 <a href=https://pharmaverse.github.… %not… Nega… dev_ut… help  <NA>    admira…
## 3 <a href=https://pharmaverse.github.… %or%  Or    dev_ut… help  <NA>    admira…
## 4 <a href=https://pharmaverse.github.… anti… Join… joins   help  <NA>    admira…
## 5 <a href=https://pharmaverse.github.… deat… Pre-… source… help  <NA>    admiral
## 6 <a href=https://pharmaverse.github.… deat… Pre-… source… help  <NA>    admira…
## 7 <a href=https://pharmaverse.github.… desc  dply… reexpo… help  <NA>    admiral
## 8 <a href=https://pharmaverse.github.… exprs rlan… reexpo… help  <NA>    admiral
## 9 <a href=https://pharmaverse.github.… rsp_… Pre-… source… help  <NA>    admira…

online <- docs |> filter(dverse::is_online(topic))

Consider the different kinds of documentation in your universe.

online |> count(type, keyword)
## # A tibble: 4 × 3
##   type     keyword      n
##   <chr>    <chr>    <int>
## 1 help     datasets    26
## 2 help     internal    27
## 3 help     <NA>       243
## 4 vignette <NA>        39

You may organize the documentation however you like. For inspiration see the pactaverse, the toy ‘admiralverse’, fgeo and tidymodels.

Here it makes sense to place vignettes, datasets, and public functions in separate tables.

Vignettes

Here are all the vignettes available across packages in the ‘admiralverse’. Click on each topic to read its corresponding vignette.

vignettes <- online |> filter(type == "vignette")

vignettes |>
  distinct(topic, title, package) |>
  datatable(escape = FALSE)

You don’t see what you expect?

• This works with vignettes but not articles, so usethis::use_vignette() not usethis::use_article() .

• When you install the packages in your universe ensure to install the vignettes. Vignettes install by default when you install your packages from CRAN with install.packages() or pak::pak() . But if you install them from source with devtools::install() or remotes::install_github() , then you need build_vignettes = TRUE.

Datasets

Here are all the datasets. Click on each topic to read about it.

datasets <- online |> filter(keyword == "datasets")

datasets |>
  distinct(topic, title, package) |>
  datatable(escape = FALSE)

Functions

Here are all the functions. Click on each topic to read about it.

internal <- online |> filter(keyword == "internal")

public <- online |>
  anti_join(vignettes) |>
  anti_join(datasets) |>
  anti_join(internal)

public |>
  distinct(topic, title, package) |>
  datatable(escape = FALSE)

Learn More

To learn more see the toy ‘admiralverse’ meta-package – which models the main use case of {dverse} .

You may also enjoy these videos:

• Creating a meta-package for the toy ‘admiralverse’ (5’).
• Creating a website for the toy ‘admiralverse’ (9’).

Was this useful? Do you want to report bugs, propose changes or request features?.

Let’s connect.

Last updated

2024-12-13 13:35:11.818454

Details

Source, Session info