In NJLyon-Projects/helpR: Support Functions for Wrangling and Visualization

#| include: false
knitr::opts_chunk$set(collapse = TRUE, comment = "#>")

#| echo: false
#| message: false

# devtools::install_github("njlyon0/supportR", force = TRUE)

Finally, I've written several functions that allow you to interact with APIs (Application Programming Interfaces) outside of R via R functions with hopefully more comfortable syntax. Because these functions rely on user credentials, they cannot be run non-interactively (as in the submission of version updates for supportR to CRAN) so the following code chunks are not evaluated but are included as examples of the proper syntax for your reference.

GitHub-Related Functions

For GitHub users, I've developed two related functions: github_ls and github_tree. github_ls accepts the URL to a GitHub repository to which you have access (public or private). It creates a dataframe of that repository's contents including their names, types, and full paths within the repository. Listing of a particular folder and recursive listing of all nested subfolders within a repository are both supported via additional arguments.

If the folder argument is set to NULL (the default) the top level of the repository is listed.

#| eval: false
# List all files in a GitHub repository
supportR::github_ls(repo = "https://github.com/njlyon0/supportR",
                    recursive = TRUE, quiet = FALSE)

##                          name type                path
## 1               .Rbuildignore file                   .
## 2                     .github  dir                   .
## 3                  .gitignore file                   .
## 4                 DESCRIPTION file                   .
## 5                     LICENSE file                   .

#| eval: false
# Or list files in only a particular folder
supportR::github_ls(repo = "https://github.com/njlyon0/supportR", folder = "R",
                    recursive = FALSE, quiet = TRUE)

##                   name type path
## 1         array_melt.R file    R
## 2              count.R file    R
## 3           crop_tri.R file    R
## 4         date_check.R file    R

github_tree is an extension of github_ls that identifies all files in a repository and creates a file tree diagram of that folder structure that is simple and human-readable. Unlike github_ls, github_tree only supports recursive identification of all files beginning at the top level of the repository. It does however allow users to exclude the listings of particular folders by specifying their names in the exclude argument.

I think this could be particularly useful to embed in a repository's README.Rmd to create a quick-and-easy file map for visitors to use as a guide in navigating the repository's contents.

#| eval: false
# Create a file tree diagram of a GitHub repository
supportR::github_tree(repo = "https://github.com/njlyon0/supportR",
                      exclude = c("docs", "man", ".github"), quiet = FALSE)

##                               levelName
## 1  .                                   
## 2   ¦--.Rbuildignore                   
## 3   ¦--.github                         
## 4   ¦   °--11 excluded items           
## 5   ¦--.gitignore                      
## 6   ¦--DESCRIPTION                     
## 7   ¦--LICENSE

External File-Related Functions

Valuable information is sometimes stored as markdown files which--while consistently formatted internally--are not always easily parsed through R. I've written tabularize_md to ingest a markdown file and collapse it into a table while still preserving the nested structure of any headings that may be in the source file. This function accepts either a local markdown file name/path or a connection (via URL) to an online markdown file. I'll demonstrate the URL-based variant here but to use it on a local file you need only provide the file name/path as you would to any other reading function (e.g., read.csv, etc.)

#| eval: false

# Identify URL to the NEWS.md file in `supportR` GitHub repo
md_cxn <- url("https://raw.githubusercontent.com/njlyon0/supportR/main/NEWS.md")

# Transform it into a table
md_df <- supportR::tabularize_md(file = md_cxn)

# Close connection (just good housekeeping to do so)
close(md_cxn)

# Check out the table format
str(md_df)

## 'data.frame':    25 obs. of  2 variables:
##  $ level_1: chr  "supportR Version 1.4.0.900" "supportR Version 1.4.0.900" "supportR Version 1.4.0" "supportR Version 1.4.0" ...
##  $ text   : chr  "Development version, changes from preceding version are listed below:" "- Function fix: Fixed issue with `replace_non_ascii` where if `include_letters` was set to `FALSE` a warning wa"| __truncated__ "Changes from preceding version are listed below" "- New function: `replace_non_ascii`. Replaces non-ASCII characters with ASCII characters that are as visually s"| __truncated__

Google Drive-Related Functions

For users who create RMarkdown reports and want to store them in a Google Drive folder, rmd_export knits and exports a given R Markdown file both locally and to a user-designated Google Drive folder. Note that you MUST authenticate your R session with the googledrive package so that it has permission to access the Drive folder you supply. I recommend running googledrive::drive_auth() and doing the authentication "dance" in a browser before using rmd_export to reduce the chances of any errors.

#| eval: false

# Authorize R to interact with GoogleDrive
googledrive::drive_auth()

# Use `rmd_export()` to knit and export an .Rmd file
supportR::rmd_export(rmd = "my_markdown.Rmd",
                     in_path = file.path("Folder in my WD with the .Rmd named in `rmd`"),
                     out_path = file.path("Folder in my WD to save the knit file to"),
                     out_name = "desired name for output",
                     out_type = "html",
                     drive_link = "<Full Google Drive link>")