Add vignette on extending aPPR #22

RoheLab · Oct 27, 2023 · 7bdd4ff · 7bdd4ff
2 parents 501ea58 + 9bc2ca0
commit 7bdd4ff
Show file tree

Hide file tree

Showing 16 changed files with 461 additions and 114 deletions.
diff --git a/.github/workflows/R-CMD-check.yaml b/.github/workflows/R-CMD-check.yaml
@@ -1,4 +1,4 @@
-# Workflow derived from https://github.com/r-lib/actions/tree/master/examples
+# Workflow derived from https://github.com/r-lib/actions/tree/v2/examples
 # Need help debugging build failures? Start at https://github.com/r-lib/actions#where-to-find-help
 #
 # NOTE: This workflow is overkill for most R packages and
@@ -22,32 +22,41 @@ jobs:
       fail-fast: false
       matrix:
         config:
-          - {os: macOS-latest,   r: 'release'}
+          - {os: macos-latest,   r: 'release'}
 
           - {os: windows-latest, r: 'release'}
-
-          # Use older ubuntu to maximise backward compatibility
-          - {os: ubuntu-18.04,   r: 'devel', http-user-agent: 'release'}
-          - {os: ubuntu-18.04,   r: 'release'}
-          - {os: ubuntu-18.04,   r: 'oldrel-1'}
+          # Use 3.6 to trigger usage of RTools35
+          - {os: windows-latest, r: '3.6'}
+          # use 4.1 to check with rtools40's older compiler
+          - {os: windows-latest, r: '4.1'}
+
+          - {os: ubuntu-latest,   r: 'devel', http-user-agent: 'release'}
+          - {os: ubuntu-latest,   r: 'release'}
+          - {os: ubuntu-latest,   r: 'oldrel-1'}
+          - {os: ubuntu-latest,   r: 'oldrel-2'}
+          - {os: ubuntu-latest,   r: 'oldrel-3'}
+          - {os: ubuntu-latest,   r: 'oldrel-4'}
 
     env:
       GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
       R_KEEP_PKG_SOURCE: yes
 
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
 
-      - uses: r-lib/actions/setup-pandoc@v1
+      - uses: r-lib/actions/setup-pandoc@v2
 
-      - uses: r-lib/actions/setup-r@v1
+      - uses: r-lib/actions/setup-r@v2
         with:
           r-version: ${{ matrix.config.r }}
           http-user-agent: ${{ matrix.config.http-user-agent }}
           use-public-rspm: true
 
-      - uses: r-lib/actions/setup-r-dependencies@v1
+      - uses: r-lib/actions/setup-r-dependencies@v2
         with:
-          extra-packages: rcmdcheck
+          extra-packages: any::rcmdcheck
+          needs: check
 
-      - uses: r-lib/actions/check-r-package@v1
+      - uses: r-lib/actions/check-r-package@v2
+        with:
+          upload-snapshots: true
diff --git a/.github/workflows/pkgdown.yaml b/.github/workflows/pkgdown.yaml
@@ -1,8 +1,10 @@
-# Workflow derived from https://github.com/r-lib/actions/tree/master/examples
+# Workflow derived from https://github.com/r-lib/actions/tree/v2/examples
 # Need help debugging build failures? Start at https://github.com/r-lib/actions#where-to-find-help
 on:
   push:
     branches: [main, master]
+  pull_request:
+    branches: [main, master]
   release:
     types: [published]
   workflow_dispatch:
@@ -12,24 +14,35 @@ name: pkgdown
 jobs:
   pkgdown:
     runs-on: ubuntu-latest
+    # Only restrict concurrency for non-PR jobs
+    concurrency:
+      group: pkgdown-${{ github.event_name != 'pull_request' || github.run_id }}
     env:
       GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
+    permissions:
+      contents: write
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
 
-      - uses: r-lib/actions/setup-pandoc@v1
+      - uses: r-lib/actions/setup-pandoc@v2
 
-      - uses: r-lib/actions/setup-r@v1
+      - uses: r-lib/actions/setup-r@v2
         with:
           use-public-rspm: true
 
-      - uses: r-lib/actions/setup-r-dependencies@v1
+      - uses: r-lib/actions/setup-r-dependencies@v2
         with:
-          extra-packages: pkgdown
+          extra-packages: any::pkgdown, local::.
           needs: website
 
-      - name: Deploy package
-        run: |
-          git config --local user.name "$GITHUB_ACTOR"
-          git config --local user.email "$GITHUB_ACTOR@users.noreply.github.com"
-          Rscript -e 'pkgdown::deploy_to_branch(new_process = FALSE)'
+      - name: Build site
+        run: pkgdown::build_site_github_pages(new_process = FALSE, install = FALSE)
+        shell: Rscript {0}
+
+      - name: Deploy to GitHub pages 🚀
+        if: github.event_name != 'pull_request'
+        uses: JamesIves/github-pages-deploy-action@v4.4.1
+        with:
+          clean: false
+          branch: gh-pages
+          folder: docs
diff --git a/.github/workflows/pr-commands.yaml b/.github/workflows/pr-commands.yaml
@@ -1,4 +1,4 @@
-# Workflow derived from https://github.com/r-lib/actions/tree/master/examples
+# Workflow derived from https://github.com/r-lib/actions/tree/v2/examples
 # Need help debugging build failures? Start at https://github.com/r-lib/actions#where-to-find-help
 on:
   issue_comment:
@@ -14,22 +14,24 @@ jobs:
     env:
       GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
 
-      - uses: r-lib/actions/pr-fetch@v1
+      - uses: r-lib/actions/pr-fetch@v2
         with:
           repo-token: ${{ secrets.GITHUB_TOKEN }}
 
-      - uses: r-lib/actions/setup-r@v1
+      - uses: r-lib/actions/setup-r@v2
         with:
           use-public-rspm: true
 
-      - uses: r-lib/actions/setup-r-dependencies@v1
+      - uses: r-lib/actions/setup-r-dependencies@v2
         with:
-          extra-packages: roxygen2
+          extra-packages: any::roxygen2
+          needs: pr-document
 
       - name: Document
-        run: Rscript -e 'roxygen2::roxygenise()'
+        run: roxygen2::roxygenise()
+        shell: Rscript {0}
 
       - name: commit
         run: |
@@ -38,7 +40,7 @@ jobs:
           git add man/\* NAMESPACE
           git commit -m 'Document'
 
-      - uses: r-lib/actions/pr-push@v1
+      - uses: r-lib/actions/pr-push@v2
         with:
           repo-token: ${{ secrets.GITHUB_TOKEN }}
 
@@ -49,19 +51,21 @@ jobs:
     env:
       GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
 
-      - uses: r-lib/actions/pr-fetch@v1
+      - uses: r-lib/actions/pr-fetch@v2
         with:
           repo-token: ${{ secrets.GITHUB_TOKEN }}
 
-      - uses: r-lib/actions/setup-r@v1
+      - uses: r-lib/actions/setup-r@v2
 
       - name: Install dependencies
-        run: Rscript -e 'install.packages("styler")'
+        run: install.packages("styler")
+        shell: Rscript {0}
 
       - name: Style
-        run: Rscript -e 'styler::style_pkg()'
+        run: styler::style_pkg()
+        shell: Rscript {0}
 
       - name: commit
         run: |
@@ -70,6 +74,6 @@ jobs:
           git add \*.R
           git commit -m 'Style'
 
-      - uses: r-lib/actions/pr-push@v1
+      - uses: r-lib/actions/pr-push@v2
         with:
           repo-token: ${{ secrets.GITHUB_TOKEN }}
diff --git a/.github/workflows/test-coverage.yaml b/.github/workflows/test-coverage.yaml
@@ -1,4 +1,4 @@
-# Workflow derived from https://github.com/r-lib/actions/tree/master/examples
+# Workflow derived from https://github.com/r-lib/actions/tree/v2/examples
 # Need help debugging build failures? Start at https://github.com/r-lib/actions#where-to-find-help
 on:
   push:
@@ -15,16 +15,36 @@ jobs:
       GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
 
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
 
-      - uses: r-lib/actions/setup-r@v1
+      - uses: r-lib/actions/setup-r@v2
         with:
           use-public-rspm: true
 
-      - uses: r-lib/actions/setup-r-dependencies@v1
+      - uses: r-lib/actions/setup-r-dependencies@v2
         with:
-          extra-packages: covr
+          extra-packages: any::covr
+          needs: coverage
 
       - name: Test coverage
-        run: covr::codecov()
+        run: |
+          covr::codecov(
+            quiet = FALSE,
+            clean = FALSE,
+            install_path = file.path(normalizePath(Sys.getenv("RUNNER_TEMP"), winslash = "/"), "package")
+          )
         shell: Rscript {0}
+
+      - name: Show testthat output
+        if: always()
+        run: |
+          ## --------------------------------------------------------------------
+          find ${{ runner.temp }}/package -name 'testthat.Rout*' -exec cat '{}' \; || true
+        shell: bash
+
+      - name: Upload test results
+        if: failure()
+        uses: actions/upload-artifact@v3
+        with:
+          name: coverage-test-failures
+          path: ${{ runner.temp }}/package
diff --git a/DESCRIPTION b/DESCRIPTION
@@ -1,6 +1,6 @@
 Package: aPPR
 Title: Approximate Personalized PageRank
-Version: 0.0.0.9103
+Version: 0.0.0.9200
 Authors@R: c(
     person("Alex", "Hayes", , "alexpghayes@gmail.com", role = c("aut", "cre", "cph"),
            comment = c(ORCID = "0000-0002-4985-5160")),
@@ -27,6 +27,7 @@ Suggests:
     covr,
     igraph (>= 1.2.5),
     knitr,
+    rentrez,
     rmarkdown,
     rtweet (>= 0.7.0.9011),
     testthat (>= 3.0.0)
@@ -35,7 +36,7 @@ Remotes:
 Encoding: UTF-8
 LazyData: true
 Roxygen: list(markdown = TRUE)
-RoxygenNote: 7.1.2
+RoxygenNote: 7.2.3
 Collate: 
     'aPPR-package.R'
     'abstract-graph.R'
@@ -45,3 +46,4 @@ Collate:
     'tracker.R'
     'update.R'
 Config/testthat/edition: 3
+VignetteBuilder: knitr
diff --git a/NAMESPACE b/NAMESPACE
@@ -3,6 +3,7 @@
 S3method(appr,abstract_graph)
 S3method(appr,igraph)
 S3method(appr,rtweet_graph)
+S3method(print,abstract_graph)
 S3method(update,Tracker)
 export(abstract_graph)
 export(appr)

diff --git a/R/abstract-graph.R b/R/abstract-graph.R
@@ -22,13 +22,16 @@ abstract_graph <- function(subclass, ...) {
 #'
 #'   - At least one outgoing edge
 #'   - Can get in degree and out degree of node
-#'   - Can get all nodes connected to `node` / the 1-hop neighbhorhood
+#'   - Can get all nodes connected to `node` / the 1-hop neighborhood
 #'
 #' @param graph A graph object.
 #' @param nodes The name(s) of node(s) in `graph` as a character vector.
 #'
 #' @return The subset of `nodes` that are acceptable for inclusion. This
-#'   can be a character vector of length zero if necessary.
+#'   can be a character vector of length zero if necessary. It is critical
+#'   that no entries of `nodes` are duplicated in this output, so we
+#'   recommend calling `unique()` if there is any potential for repeats
+#'   in your checking good.
 #'
 #' @export
 check <- function(graph, nodes) {
@@ -38,13 +41,15 @@ check <- function(graph, nodes) {
 #' Get the in-degree and out-degree of nodes in an abstract graph
 #'
 #' This function is only called nodes that have been [check()]'d. It is
-#' safe to assume that `nodes` is non-empty. (TODO: check this!)
+#' safe to assume that `nodes` is non-empty.
 #'
 #' @param graph A graph object.
 #' @param nodes The name(s) of node(s) in `graph` as a character vector.
+#'   Methods may assume that there are no repeated values in `nodes`.
 #'
 #' @return A [data.frame()] with one row for every node in `nodes` and
-#'   two columns: `in_degree` and `out_degree`.frame with one
+#'   two columns: `in_degree` and `out_degree`. In a symmetric graph,
+#'   `in_degree` and `out_degree` should match.
 #'
 #' @export
 node_degrees <- function(graph, nodes) {
@@ -62,7 +67,10 @@ node_degrees <- function(graph, nodes) {
 #' @return A character vector of all nodes in `graph` connected such that
 #'   there is an outgoing edge for `node` to those nodes. This should
 #'   never be empty, as `neighborhood()` should not be called on nodes
-#'   that fail `check()`.
+#'   that fail `check()`, and `check()` enforces that nodes have out-degree
+#'   of at least one. It is critical node names are duplicated in the
+#'   output recommend calling `unique()` if there is any potential for
+#'   for that to occur.
 #'
 #' @export
 neighborhood <- function(graph, node) {
@@ -76,3 +84,9 @@ neighborhood <- function(graph, node) {
 # memoized versions, these are what actually get used
 #' @importFrom memoise memoise
 memo_neighborhood <- memoise::memoise(neighborhood)
+
+#' @method print abstract_graph
+#' @export
+print.abstract_graph <- function(x, ...) {
+  cat(glue("Abstract graph object (subclass: {class(x)[1]})\n"))
+}
diff --git a/R/graph-rtweet.R b/R/graph-rtweet.R
@@ -8,6 +8,13 @@
 #' @export
 rtweet_graph <- function(retryonratelimit = TRUE, verbose = TRUE, n = 5000) {
 
+  if (!requireNamespace("rtweet", quietly = TRUE)) {
+    stop(
+      "`rtweet` package must be installed to use `rtweet_graph()`",
+      call. = FALSE
+    )
+  }
+
   agraph <- abstract_graph(
     "rtweet_graph",
     retryonratelimit = retryonratelimit,
@@ -22,13 +29,6 @@ rtweet_graph <- function(retryonratelimit = TRUE, verbose = TRUE, n = 5000) {
 #' @export
 appr.rtweet_graph <- function(graph, seeds, ...) {
 
-  if (!requireNamespace("rtweet", quietly = TRUE)) {
-    stop(
-      "`rtweet` package must be installed to use `rtweet_graph()`",
-      call. = FALSE
-    )
-  }
-
   seed_data <- rtweet::lookup_users(
     seeds,
     retryonratelimit = graph$retryonratelimit,
@@ -92,6 +92,7 @@ node_degrees.rtweet_graph <- function(graph, nodes) {
     out_degree = node_data$friends_count
   )
 }
+
 neighborhood.rtweet_graph <- function(graph, node) {
 
   logger::log_debug(glue("Getting neighborhood: {node}"))

diff --git a/README.Rmd b/README.Rmd
@@ -17,8 +17,9 @@ knitr::opts_chunk$set(
 # aPPR
 
 <!-- badges: start -->
-[![R-CMD-check](https://github.com/RoheLab/aPPR/workflows/R-CMD-check/badge.svg)](https://github.com/RoheLab/aPPR/actions)
+[![R-CMD-check](https://github.com/RoheLab/aPPR/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/RoheLab/aPPR/actions/workflows/R-CMD-check.yaml)
 [![Codecov test coverage](https://codecov.io/gh/RoheLab/aPPR/branch/main/graph/badge.svg)](https://app.codecov.io/gh/RoheLab/aPPR?branch=main)
+
 <!-- badges: end -->
 
 `aPPR` helps you calculate approximate personalized pageranks from large graphs, including those that can only be queried via an API. `aPPR` additionally performs degree correction and regularization, allowing you to recover blocks from stochastic blockmodels.