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 < bslib-tooltip placement="auto" bsoptions="[]" data-require-bs-version="5" data-require-bs-caller="tooltip()"> < template>GitHub – maurolepore/dverse: Document a Universe of Packages {dverse} to document your universe,
• each package in the toy ‘admiralverse’ to access the documentation metadata,
• < bslib-tooltip placement="auto" bsoptions="[]" data-require-bs-version="5" data-require-bs-caller="tooltip()"> < template>A Grammar of Data Manipulation • dplyr {dplyr} to manipulate the output of < bslib-tooltip placement="auto" bsoptions="[]" data-require-bs-version="5" data-require-bs-caller="tooltip()"> < template>GitHub – maurolepore/dverse: Document a Universe of Packages {dverse} , and
• < bslib-tooltip placement="auto" bsoptions="[]" data-require-bs-version="5" data-require-bs-caller="tooltip()"> < template>GitHub – rstudio/DT: R Interface to the jQuery Plug-in DataTables {DT} to create a searchable table.

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

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

< bslib-tooltip placement="auto" bsoptions="[]" data-require-bs-version="5" data-require-bs-caller="tooltip()"> < template>Create a data frame with documentation metadata of one or more packages — document_universe • dverse 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: 345 × 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
## # ℹ 335 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 < bslib-tooltip placement="auto" bsoptions="[]" data-require-bs-version="5" data-require-bs-caller="tooltip()"> < template>Is each URL (or href) online? — is_online • dverse 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    22
## 2 help     internal    30
## 3 help     <NA>       245
## 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 < bslib-tooltip placement="auto" bsoptions="[]" data-require-bs-version="5" data-require-bs-caller="tooltip()"> < template>Create a vignette or article — use_vignette • usethis usethis::use_vignette() not < bslib-tooltip placement="auto" bsoptions="[]" data-require-bs-version="5" data-require-bs-caller="tooltip()"> < template>Create a vignette or article — use_vignette • usethis 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 < bslib-tooltip placement="auto" bsoptions="[]" data-require-bs-version="5" data-require-bs-caller="tooltip()"> < template>Install specified required packages — pak • pak pak::pak() . But if you install them from source with < bslib-tooltip placement="auto" bsoptions="[]" data-require-bs-version="5" data-require-bs-caller="tooltip()"> < template>Install a local development package. — install • devtools devtools::install() or < bslib-tooltip placement="auto" bsoptions="[]" data-require-bs-version="5" data-require-bs-caller="tooltip()"> < template>Attempts to install a package directly from GitHub. — install_github • remotes 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 < bslib-tooltip placement="auto" bsoptions="[]" data-require-bs-version="5" data-require-bs-caller="tooltip()"> < template>GitHub – maurolepore/dverse: Document a Universe of Packages {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.

@online{lepore2024,
  author = {Lepore, Mauro},
  title = {Creating a Better Universe with Dverse},
  date = {2024-12-13},
  url = {https://pharmaverse.github.io/blog/posts/2024-12-13_document_yo.../document_your_universe_with_dverse.html},
  langid = {en}
}