Creating a better universe with dverse

Posted on December 12, 2024 by Mauro Lepore in R bloggers | 0 Comments

[This article was first published on pharmaverse blog, and kindly contributed to R-bloggers]. (You can report issue about the content on this page here)

Want to share your content on R-bloggers? click here if you have a blog, or here if you don't.

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.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'

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 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 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} .

Last updated

2025-01-21 14:39:29.180649

Details

Source, Session info

Reuse

CC BY 4.0

Citation

BibTeX citation:

@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}
}

For attribution, please cite this work as:

Lepore, Mauro. 2024. “Creating a Better Universe with Dverse.” December 13, 2024. https://pharmaverse.github.io/blog/posts/2024-12-13_document_yo.../document_your_universe_with_dverse.html.

To leave a comment for the author, please follow the link and comment on their blog: pharmaverse blog.

R-bloggers.com offers daily e-mail updates about R news and tutorials about learning R and many other topics. Click here if you're looking to post or find an R/data-science job.

Want to share your content on R-bloggers? click here if you have a blog, or here if you don't.

R-bloggers

R news and tutorials contributed by hundreds of R bloggers

Creating a better universe with dverse

Vignettes

You don’t see what you expect?

Datasets

Functions

Learn More

Last updated

Details

Reuse

Citation

Related

Vignettes

You don’t see what you expect?

Datasets

Functions

Learn More

Last updated

Details

Reuse

Citation

Related

Never miss an update! Subscribe to R-bloggers to receive e-mails with the latest R posts. (You will not see this message again.)

Never miss an update!
Subscribe to R-bloggers to receive
e-mails with the latest R posts.
(You will not see this message again.)