Merge pull request #146 from ropensci-review-tools/use-case

finish simil-fns sec of vignette #118

Author: mpadge

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: pkgmatch
 Title:  Find R Packages Matching Either Descriptions or Other R Packages
-Version: 0.5.0.002
+Version: 0.5.0.003
 Authors@R: c(
     person("Mark", "Padgham", , "[email protected]", role = c("aut", "cre"),
            comment = c(ORCID = "0000-0003-2172-5265")),

codemeta.json

@@ -8,7 +8,7 @@
   "codeRepository": "https://github.com/ropensci-review-tools/pkgmatch",
   "issueTracker": "https://github.com/ropensci-review-tools/pkgmatch/issues",
   "license": "https://spdx.org/licenses/MIT",
-  "version": "0.5.0.002",
+  "version": "0.5.0.003",
   "programmingLanguage": {
     "@type": "ComputerLanguage",
     "name": "R",

vignettes/F_extended-use-case.Rmd

@@ -156,10 +156,11 @@ by pkgmatch.
 
 pkgmatch can also be used when writing R functions or scripts, to answer the
 question of which R packages may already exist which do what I am trying to
-code. The easiest way to illustrate this is with a concrete example:
+code. The easiest way to illustrate this is with a concrete example, like the
+following attempt to use [the `httr2` package](https://httr2.r-lib.org/) to
+extract data from a search API:
 
 ```{r search-code}
-library (httr2)
 search_api_results <- function (q) {
     url <- "https://mysearchapi.com/search"
     q <- httr2::httr_request (url) |>
@@ -192,7 +193,8 @@ whether any of those packages might help develop our function. We can also
 search for the closest matching _functions_ instead of packages, although
 function matching is restricted to the rOpenSci corpus only.
 ```{r fn-fn-search, eval = FALSE}
-pkgmatch_similar_fns (s)
+fns <- pkgmatch_similar_fns (s)
+fns
 ```
 ```{r fn-fn-search-out, echo = FALSE}
 c (
@@ -201,3 +203,49 @@ c (
     "webmockr::build_httr_request"
 )
 ```
+
+Again, web pages for all of those functions can be opened by passing the `fns`
+result to [the `pkgmatch_browse()`
+function](https://docs.ropensci.org/pkgmatch/reference/pkgmatch_browse.html).
+That will open the documentation pages on
+[docs.ropensci.org](https://docs.ropensci.org), with all function documentation
+entries include a link to the corresponding source code at the top of the page.
+This demonstrates how pkgmatch can be used to identify similar source code to
+any given code input.
+
+## Searches based on entire packages
+
+Entire packages can also be used as input to pkgmatch functions. The simplest
+way to do this is to submit the name of an installed package, like this:
+
+```{r whole-pkg-search, eval = FALSE}
+pkgs <- pkgmatch_similar_pkgs ("osmdata", corpus = "cran")
+```
+
+As explained in [the _How does pkgmatch work?_
+vignette](https://docs.ropensci.org/pkgmatch/articles/B_how-does-it-work.html),
+pkgmatch extracts all code and text from the nominated packages and uses these
+to generate three sets of embeddings: of all package code, and of all text both
+with and without text from individual function descriptions. Matches with other
+packages are based on combinations of matches with these three sets of
+embeddings, as well as matches based on inverse document frequencies for
+package text (as also explained in [the _How does pkgmatch work?_
+vignette](https://docs.ropensci.org/pkgmatch/articles/B_how-does-it-work.html#token-frequency-similarities)).
+The above call yields this result:
+
+```{r whole-pkg-search-output-fakey, eval = FALSE}
+pkgs
+```
+```{r whole-pkg-search-output, echo = FALSE}
+list (
+    text = c ("factormodel", "crul", "healthequal", "httr2", "crumble"),
+    code = c ("shinyKGode", "crul", "sphereML", "irtawsi", "httr2")
+)
+```
+
+As expected, the `crul` package appears in the top results for matching both
+text and code (although not in first place, for reasons described in [the
+_Why are the results not what I expect?_
+vignette](https://docs.ropensci.org/pkgmatch/articles/E_why-are-the-results-not-what-i-expect.html)).
+Moreover, the only two packages matched on both code and text are `crul`
+itself, and the highly-similar [`httr2` package](https://httr2.r-lib.org/).