Skip to contents

pkgmatch

A tool to help find R packages, by matching packages either to a text description, or to any given package. Can find matching packages either from rOpenSci’s suite of packages, or from all packages currently on CRAN.

Installation

The easiest way to install this package is via the associated r-universe. As shown there, simply enable the universe with

options (repos = c (
    ropenscireviewtools = "https://ropensci-review-tools.r-universe.dev",
    CRAN = "https://cloud.r-project.org"
))

And then install the usual way with,

install.packages ("pkgmatch")

Alternatively, the package can be installed by first installing either the remotes or pak packages and running one of the following lines:

remotes::install_github ("ropensci-review-tools/pkgmatch")
pak::pkg_install ("ropensci-review-tools/pkgmatch")

The package can then loaded for use with

The package takes input either from a text description or local path to an R package, and finds similar packages based on both Large Language Model (LLM) embeddings, and more traditional text and code matching algorithms. The LLM embeddings require a locally-running instance of ollama, as described in the following sub-section.

Setting up the LLM embeddings

This package does not access LLM embeddings through external APIs, for reasons explained in vignette("why-local-lllms"). The LLM embeddings are extracted from a locally-running instance of ollama. That means you need to download and install ollama on your own computer in order to use this package. Once downloaded, ollama can be started by calling ollama serve. The particular models used to extract the embeddings will be automatically downloaded by this package if needed, or you can do this manually by running the following two commands (in a system console; not in R):

ollama pull jina/jina-embeddings-v2-base-en
ollama pull ordis/jina-embeddings-v2-base-code

You’ll likely need to wait up to half an hour or more for the models to download before proceeding.

Using the pkgmatch package

The package has two main functions:

  • pkgmatch_similar_pkgs() to find similar rOpenSci or CRAN packages based input as either a local path to an entire package, or as a single descriptive text string; and
  • pkgmatch_similar_fns() to find similar functions from rOpenSci packages based on descriptive text input. (Not available for functions from CRAN packages.)

The following code demonstrates how these functions work, first matching general text strings packages from rOpenSci:

input <- "
Packages for analysing evolutionary trees, with a particular focus
on visualising inter-relationships among distinct trees.
"
pkgmatch_similar_pkgs (input)
## [1] "lingtypology"   "treedata.table" "treestartr"     "babette"       
## [5] "canaper"

Corresponding websites can also be automatically opened, either by passing browse = TRUE, or by specifying a return value and passing that to the pkgmatch_browse() function.

Matching entire packages

The input parameter can also be a local path to an entire package. The following code finds the most similar packages to this very package by passing input = ".", again by default matching against all rOpenSci packages:

## $text
## [1] "rdataretriever" "pkgcheck"       "c14bazAAR"      "elastic"       
## [5] "textreuse"     
## 
## $code
## [1] "autotest"    "pkgcheck"    "roreviewapi" "rtweet"      "srr"

And the most similar packages in terms of text descriptions include several general search and retrieval packages, and only the pkgcheck package from the ropensci-review-tools suite. In contrast, four of the five most similar packages in terms of code structure are packages from the same ropensci-review-tools suite. Packages from CRAN can be matched by specifying the corpus parameter:

pkgmatch_similar_pkgs (".", corpus = "cran")
## $text
## [1] "searcher"   "typetracer" "ore"        "ehelp"      "RWsearch"  
## 
## $code
## [1] "remotes"   "RInno"     "workflowr" "cffr"      "miniCRAN"

The input parameter can also be a local path to compressed .tar.gz binary object directly downloaded from CRAN.

Finding functions

There is an additional function to find functions within packages which best match a text description.

input <- "A function to label a set of geographic coordinates"
pkgmatch_similar_fns (input)
## [1] "GSODR::nearest_stations"          "refsplitr::plot_addresses_points"
## [3] "slopes::elevation_extract"        "quadkeyr::grid_to_polygon"       
## [5] "rnoaa::meteo_nearby_stations"
input <- "Identify genetic sequences matching a given input fragment"
pkgmatch_similar_fns (input)
## [1] "charlatan::SequenceProvider" "beastier::is_alignment"     
## [3] "charlatan::ch_gene_sequence" "beautier::is_phylo"         
## [5] "textreuse::align_local"

Setting browse = TRUE will then open the documentation pages corresponding to those best-matching functions.

Prior Art