### pb_download example Source: https://docs.ropensci.org/piggyback/reference/pb_download.html An example of using pb_download, wrapped in \donttest{} to avoid running in examples. The output shows a progress indicator. ```r # \donttest{ #> ⠙ 4 items, page 1 | 2ms # } ``` -------------------------------- ### Example usage of pb_list Source: https://docs.ropensci.org/piggyback/reference/pb_list.html An example showing how to list assets for a specific repository. ```R if (FALSE) { # \dontrun{ pb_list("cboettig/piggyback-tests") } # } ``` -------------------------------- ### pb_release_create usage example Source: https://docs.ropensci.org/piggyback/reference/pb_release_create.html An example of how to call pb_release_create to create a release for a specific repository and tag. ```R if (FALSE) { # \dontrun{ pb_release_create("cboettig/piggyback-tests", "v0.0.5") } # } ``` -------------------------------- ### Install piggyback from CRAN Source: https://docs.ropensci.org/piggyback/index.html Standard installation command for the piggyback package from CRAN. ```R install.packages("piggyback") ``` -------------------------------- ### Example of uploading a file with pb_upload Source: https://docs.ropensci.org/piggyback/reference/pb_upload.html A basic example showing how to write a file and upload it to a specific GitHub repository using pb_upload. ```R if (FALSE) { # \dontrun{ # Needs your real token to run readr::write_tsv(mtcars,"mtcars.tsv.xz") pb_upload("mtcars.tsv.xz", "cboettig/piggyback-tests") } # } ``` -------------------------------- ### pb_download_url example output Source: https://docs.ropensci.org/piggyback/reference/pb_download_url.html Example output showing the URLs returned by pb_download_url for files associated with a specific GitHub release. ```R # \donttest{ #> ⠙ 6 items, page 1 | 2ms #> [1] "https://github.com/tanho63/piggyback-tests/releases/download/v0.0.2/mtcars.csv" #> [2] "https://github.com/tanho63/piggyback-tests/releases/download/v0.0.2/mtcars.parquet" #> [3] "https://github.com/tanho63/piggyback-tests/releases/download/v0.0.2/mtcars.rds" #> [1] "https://github.com/tanho63/piggyback-tests/releases/download/v0.0.2/mtcars.csv" #> No encoding supplied: defaulting to UTF-8. # } ``` -------------------------------- ### Install piggyback development version Source: https://docs.ropensci.org/piggyback/index.html Installation commands for the development version of piggyback using r-universe or remotes. ```R install.packages("piggyback", repos = c('https://ropensci.r-universe.dev', getOption("repos"))) # install.packages("remotes") remotes::install_github("ropensci/piggyback") ``` -------------------------------- ### Example: delete release with pb_release_delete Source: https://docs.ropensci.org/piggyback/reference/pb_release_delete.html Example wrapped in if (FALSE) to avoid running during checks. Deletes the release with tag 'v0.0.5' from the repository 'cboettig/piggyback-tests'. ```r if (FALSE) { # \dontrun{ pb_release_delete("cboettig/piggyback-tests", "v0.0.5") } # } ``` -------------------------------- ### pb_releases example with output Source: https://docs.ropensci.org/piggyback/reference/pb_releases.html Example call to pb_releases on the nflverse/nflverse-data repository, wrapped in try() to prevent CRAN errors. The displayed output shows a progress message and a dataframe of release names, release IDs, and release bodies. ```r # \donttest{ try({ # wrapped in try block to prevent CRAN errors pb_releases("nflverse/nflverse-data") }) #> ⠙ 25 items, page 1 | 2ms #> release_name release_id #> 1 trades 251527510 #> 2 teams 251328051 #> 3 schedules 251386473 #> 4 Team Summary Stats 236670540 #> 5 Player Summary Stats 236670328 #> 6 ftn_charting 119740650 #> 7 espn_data 121931789 #> 8 weekly_rosters 73313637 #> 9 players_components 109160206 #> 10 players 69785162 #> 11 pbp_participation 71636554 #> 12 officials 69773595 #> 13 misc 69471165 #> 14 test 66262662 #> 15 draft_picks 66254658 #> 16 contracts 65273753 #> 17 snap_counts 58153010 #> 18 rosters 58152863 #> 19 player_stats 58152881 #> 20 pfr_advstats 58152981 #> 21 pbp 58152862 #> 22 nextgen_stats 58152931 #> 23 injuries 58152949 #> 24 depth_charts 58152948 #> 25 combine 60901499 #> release_body #> 1 data is maintained by Lee Sharpe here https://github.com/nflverse/nfldata/blob/master/data/trades.csv and automated to push common data formats into this release #> 2 NFL team names, colors, logo urls, and more.\r\n\r\nDocumented in [nflfastR](https://www.nflfastr.com/reference/teams_colors_logos.html). \r\nAccess with\r\n```r\r\nnflreadr::load_teams()\r\n```\r\nor\r\n```python\r\nimport nflreadpy as nfl\r\nnfl.load_teams()\r\n```\r\n\r\nData maintained in [nflverse-pbp](https://github.com/nflverse/nflverse-pbp/blob/master/teams_colors_logos.csv). \r\nData in this release updates automatically if the linked file changes. #> 3 NFL game/schedule data.\r\n\r\nDocumented in [nflreadr](https://nflreadr.nflverse.com/articles/dictionary_schedules.html). \r\nAccess with\r\n```r\r\nnflreadr::load_schedules()\r\n```\r\nor\r\n```python\r\nimport nflreadpy as nfl\r\nnfl.load_schedules()\r\n```\r\n\r\nData maintained in [Lee Sharpe's nfldata](https://github.com/nflverse/nfldata/blob/master/data/games.rds). \r\nData in this release updates automatically if the linked file changes. #> 4 Team stats in different summary levels created with `nflfastR::calculate_stats()` #> 5 Player stats in different summary levels created with `nflfastR::calculate_stats()` ``` -------------------------------- ### pb_delete() example with upload and delete Source: https://docs.ropensci.org/piggyback/reference/pb_delete.html Example usage of pb_delete() to delete a file from a GitHub release. It is wrapped in if (FALSE) { # \dontrun{ ... } } to prevent execution during package checks. The example writes a file, uploads it with pb_upload(), then deletes it with pb_delete(). ```r if (FALSE) { # \dontrun{ readr::write_tsv(mtcars, "mtcars.tsv.gz") ## Upload pb_upload("mtcars.tsv.gz", repo = "cboettig/piggyback-tests", overwrite = TRUE) pb_delete("mtcars.tsv.gz", repo = "cboettig/piggyback-tests", tag = "v0.0.1") } # } ``` -------------------------------- ### Read a file from a GitHub release Source: https://docs.ropensci.org/piggyback/reference/pb_read.html Example of using pb_read to download and read a tsv file from a specific GitHub repository. ```R # \donttest{ try({ # try block is to avoid CRAN issues and is not required in ordinary usage piggyback::pb_read("mtcars.tsv.gz", repo = "cboettig/piggyback-tests") }) #> mpg cyl disp hp drat wt qsec vs am gear carb #> 1 21.0 6 160.0 110 3.90 2.620 16.46 0 1 4 4 #> 2 21.0 6 160.0 110 3.90 2.875 17.02 0 1 4 4 #> 3 22.8 4 108.0 93 3.85 2.320 18.61 1 1 4 1 #> 4 21.4 6 258.0 110 3.08 3.215 19.44 1 0 3 1 #> 5 18.7 8 360.0 175 3.15 3.440 17.02 0 0 3 2 #> 6 18.1 6 225.0 105 2.76 3.460 20.22 1 0 3 1 #> 7 14.3 8 360.0 245 3.21 3.570 15.84 0 0 3 4 #> 8 24.4 4 146.7 62 3.69 3.190 20.00 1 0 4 2 #> 9 22.8 4 140.8 95 3.92 3.150 22.90 1 0 4 2 #> 10 19.2 6 167.6 123 3.92 3.440 18.30 1 0 4 4 #> 11 17.8 6 167.6 123 3.92 3.440 18.90 1 0 4 4 #> 12 16.4 8 275.8 180 3.07 4.070 17.40 0 0 3 3 #> 13 17.3 8 275.8 180 3.07 3.730 17.60 0 0 3 3 #> 14 15.2 8 275.8 180 3.07 3.780 18.00 0 0 3 3 #> 15 10.4 8 472.0 205 2.93 5.250 17.98 0 0 3 4 #> 16 10.4 8 460.0 215 3.00 5.424 17.82 0 0 3 4 #> 17 14.7 8 440.0 230 3.23 5.345 17.42 0 0 3 4 #> 18 32.4 4 78.7 66 4.08 2.200 19.47 1 1 4 1 #> 19 30.4 4 75.7 52 4.93 1.615 18.52 1 1 4 2 #> 20 33.9 4 71.1 65 4.22 1.835 19.90 1 1 4 1 #> 21 21.5 4 120.1 97 3.70 2.465 20.01 1 0 3 1 #> 22 15.5 8 318.0 150 2.76 3.520 16.87 0 0 3 2 #> 23 15.2 8 304.0 150 3.15 3.435 17.30 0 0 3 2 #> 24 13.3 8 350.0 245 3.73 3.840 15.41 0 0 3 4 #> 25 19.2 8 400.0 175 3.08 3.845 17.05 0 0 3 2 #> 26 27.3 4 79.0 66 4.08 1.935 18.90 1 1 4 1 #> 27 26.0 4 120.3 91 4.43 2.140 16.70 0 1 5 2 #> 28 30.4 4 95.1 113 3.77 1.513 16.90 1 1 5 2 #> 29 15.8 8 351.0 264 4.22 3.170 14.50 0 1 5 4 #> 30 19.7 6 145.0 175 3.62 2.770 15.50 0 1 5 6 #> 31 15.0 8 301.0 335 3.54 3.570 14.60 0 1 5 8 #> 32 21.4 4 121.0 109 4.11 2.780 18.60 1 1 4 2 # } ``` -------------------------------- ### Read a CSV directly from a URL with pb_download_url() and read.csv() Source: https://docs.ropensci.org/piggyback/articles/piggyback.html Many read functions accept URLs directly, including read.csv(), arrow::read_parquet(), readr::read_csv(), data.table::fread(), and jsonlite::fromJSON(). This example passes the URL from pb_download_url() to read.csv() to read a CSV file. ```R pb_download_url("mtcars.csv", repo = "tanho63/piggyback-tests", tag = "v0.0.2") %>% read.csv() #> # A data.frame: 32 × 12 #> X mpg cyl disp hp drat wt qsec vs am gear #> #> 1 Mazda… 21 6 160 110 3.9 2.62 16.5 0 1 4 #> 2 Mazda… 21 6 160 110 3.9 2.88 17.0 0 1 4 #> 3 Datsu… 22.8 4 108 93 3.85 2.32 18.6 1 1 4 #> 4 Horne… 21.4 6 258 110 3.08 3.22 19.4 1 0 3 #> 5 Horne… 18.7 8 360 175 3.15 3.44 17.0 0 0 3 #> # ℹ 27 more rows #> # ℹ 1 more variable: carb #> # ℹ Use `print(n = ...)` to see more rows ``` -------------------------------- ### GNU GPL License Notice Template Source: https://docs.ropensci.org/piggyback/LICENSE.html A standard notice to be attached to the start of each source file to declare the program as free software under the GNU General Public License. ```text Copyright (C) 2018 Carl Boettiger This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program. If not, see . ``` -------------------------------- ### Interactive Terminal Copyright Notice Source: https://docs.ropensci.org/piggyback/LICENSE.html A short notice to display when the program starts in interactive mode, including copyright information and warranty disclaimers. ```text piggyback Copyright (C) 2018 Carl Boettiger This program comes with ABSOLUTELY NO WARRANTY; for details type 'show w'. This is free software, and you are welcome to redistribute it under certain conditions; type 'show c' for details. ``` -------------------------------- ### Read a private RDS file with authentication via url() Source: https://docs.ropensci.org/piggyback/articles/piggyback.html For private repositories, use url_type = "api" and pass authentication headers to url(). This example uses a Bearer token from gh::gh_token(). Remember to close the connection after reading. ```R pb_url <- pb_download_url("mtcars.rds", repo = "tanho63/piggyback-private", url_type = "api") %>% url( headers = c( "Accept" = "application/octet-stream", "Authorization" = paste("Bearer", gh::gh_token()) ) ) readRDS(pb_url) #> # A tibble: 32 × 11 #> mpg cyl disp hp drat wt qsec vs am gear carb #> #> 1 21 6 160 110 3.9 2.62 16.5 0 1 4 4 #> 2 21 6 160 110 3.9 2.88 17.0 0 1 4 4 #> 3 22.8 4 108 93 3.85 2.32 18.6 1 1 4 1 #> 4 21.4 6 258 110 3.08 3.22 19.4 1 0 3 1 #> 5 18.7 8 360 175 3.15 3.44 17.0 0 0 3 2 #> # ℹ 27 more rows #> # ℹ Use `print(n = ...)` to see more rows close(pb_url) ``` -------------------------------- ### Create a GitHub release Source: https://docs.ropensci.org/piggyback/index.html Initializes a new release on a GitHub repository using pb_release_create. ```R pb_release_create(repo = "cboettig/piggyback-tests", tag = "v0.0.2") #> ✔ Created new release "v0.0.2". ``` -------------------------------- ### Load the piggyback package Source: https://docs.ropensci.org/piggyback/articles/cloud_native.html Initializes the piggyback package for use in the R environment. ```r library(piggyback) ``` -------------------------------- ### Get API download URLs with pb_download_url(url_type = "api") Source: https://docs.ropensci.org/piggyback/articles/piggyback.html Use url_type = "api" to get API download URLs, which are accessible for private repositories since auth tokens are handled by the GitHub API. The browser URLs are not accessible for private repositories. ```R pb_download_url(repo = "cboettig/piggyback-tests", tag = "v0.0.1", url_type = "api") #> [1] https://api.github.com/repos/cboettig/piggyback-tests/releases/assets/44261315 #> [2] https://api.github.com/repos/cboettig/piggyback-tests/releases/assets/41841778 #> [3] https://api.github.com/repos/cboettig/piggyback-tests/releases/assets/18538636 #> [4] https://api.github.com/repos/cboettig/piggyback-tests/releases/assets/8990141 ``` -------------------------------- ### Load piggyback and magrittr Source: https://docs.ropensci.org/piggyback/articles/piggyback.html Loads the piggyback package and the magrittr pipe operator for use in the vignette examples. ```R library(piggyback) library(magrittr) ``` -------------------------------- ### Initialize DuckDB with httpfs Source: https://docs.ropensci.org/piggyback/articles/cloud_native.html Connect to an in-memory DuckDB instance and enable the httpfs extension to allow reading files over HTTP. ```r conn <- DBI::dbConnect(duckdb::duckdb()) DBI::dbExecute(conn, "INSTALL 'httpfs'; LOAD 'httpfs';") ``` -------------------------------- ### List files on a GitHub release with pb_list() Source: https://docs.ropensci.org/piggyback/articles/piggyback.html Lists all files piggybacking on a given release. Omit the tag argument to see files on all releases. The output shows a data frame with columns file_name, size, timestamp, tag, owner, and repo. ```R pb_list(repo = "cboettig/piggyback-tests", tag = "v0.0.1") #> file_name size timestamp tag owner repo #> 1 diamonds.tsv.gz 571664 2021-09-07 23:38:31 v0.0.1 cboettig piggyback-tests #> 2 iris.tsv.gz 846 2021-08-05 20:00:09 v0.0.1 cboettig piggyback-tests #> 3 iris.tsv.xz 848 2020-03-07 06:18:32 v0.0.1 cboettig piggyback-tests #> 4 iris2.tsv.gz 846 2018-10-05 17:04:33 v0.0.1 cboettig piggyback-tests ``` -------------------------------- ### Download all files from a release with pb_download() Source: https://docs.ropensci.org/piggyback/articles/piggyback.html When the file argument is NULL (default), pb_download() downloads all files connected to the release. The use_timestamps argument defaults to TRUE, so files with unchanged timestamps are skipped. ```R pb_download( repo = "cboettig/piggyback-tests", tag = "v0.0.1", dest = tempdir() ) #> ℹ Downloading "diamonds.tsv.gz"... #> |======================================================| 100% #> ℹ Downloading "iris.tsv.gz"... #> |======================================================| 100% #> ℹ Downloading "iris.tsv.xz"... #> |======================================================| 100% fs::dir_tree(tempdir()) #> /tmp/RtmpWxJSZj #> ├── diamonds.tsv.gz #> ├── iris.tsv.gz #> ├── iris.tsv.xz #> └── iris2.tsv.gz ``` -------------------------------- ### Usage of pb_list Source: https://docs.ropensci.org/piggyback/reference/pb_list.html The standard function signature for listing release assets. ```R pb_list(repo = guess_repo(), tag = NULL, .token = gh::gh_token()) ``` -------------------------------- ### pb_release_create(repo, tag, commit, name, body, draft, prerelease, .token) Source: https://docs.ropensci.org/piggyback/reference/pb_release_create.html Creates a new release on a GitHub repository. This function is part of the piggyback R package and is used to create a release with a specified tag, optionally specifying the commit, name, body, draft status, prerelease status, and authentication token. ```APIDOC ## pb_release_create(repo, tag, commit, name, body, draft, prerelease, .token) ### Description Creates a new release on a GitHub repository. This function is part of the piggyback R package and is used to create a release with a specified tag, optionally specifying the commit, name, body, draft status, prerelease status, and authentication token. ### Usage ```r pb_release_create( repo = guess_repo(), tag, commit = NULL, name = tag, body = "Data release", draft = FALSE, prerelease = FALSE, .token = gh::gh_token() ) ``` ### Arguments - **repo** (character) - Required - Repository name in format "owner/repo". Will guess the current repo if not specified. - **tag** (character) - Required - Tag to create for this release. - **commit** (character) - Optional - Specifies the commit-ish value that determines where the Git tag is created from. Can be any branch or full commit SHA (not the short hash). Unused if the git tag already exists. Default: the repository's default branch (usually `master`). - **name** (character) - Optional - The name of the release. Defaults to tag. - **body** (character) - Optional - Text describing the contents of the tag. Default text is "Data release". - **draft** (logical) - Optional - Default `FALSE`. Set to `TRUE` to create a draft (unpublished) release. - **prerelease** (logical) - Optional - Default `FALSE`. Set to `TRUE` to identify the release as a pre-release. - **.token** (character) - Optional - GitHub authentication token, see `[gh::gh_token()]`. ### Example ```r if (FALSE) { # \dontrun{ pb_release_create("cboettig/piggyback-tests", "v0.0.5") } # } ``` ### See also Other release_management: `pb_release_delete()` ``` -------------------------------- ### Get browser download URLs with pb_download_url() Source: https://docs.ropensci.org/piggyback/articles/piggyback.html Returns the browser_download_url for each file in the release. These URLs are served by GitHub's web servers and are less restrictive with rate-limiting. The function shares default behaviors with pb_download for file, repo, and tag arguments. ```R pb_download_url(repo = "cboettig/piggyback-tests", tag = "v0.0.1") #> [1] "https://github.com/cboettig/piggyback-tests/releases/download/v0.0.1/diamonds.tsv.gz" #> [2] "https://github.com/cboettig/piggyback-tests/releases/download/v0.0.1/iris.tsv.gz" #> [3] "https://github.com/cboettig/piggyback-tests/releases/download/v0.0.1/iris.tsv.xz" #> [4] "https://github.com/cboettig/piggyback-tests/releases/download/v0.0.1/iris2.tsv.gz" ``` -------------------------------- ### Download a single file with pb_download() Source: https://docs.ropensci.org/piggyback/articles/piggyback.html Downloads a specific file from a GitHub release. The repo argument defaults to the current git repo, tag defaults to 'latest', and dest defaults to the working directory. Here dest is set to tempdir() to meet CRAN policies. ```R pb_download( file = "iris2.tsv.gz", dest = tempdir(), repo = "cboettig/piggyback-tests", tag = "v0.0.1" ) #> ℹ Downloading "iris2.tsv.gz"... #> |======================================================| 100% fs::dir_tree(tempdir()) #> /tmp/RtmpWxJSZj #> └── iris2.tsv.gz ``` -------------------------------- ### Override pb_read() read_function with qs::qread Source: https://docs.ropensci.org/piggyback/articles/piggyback.html When the file extension is not in the default list, pb_read() raises an error and asks for a read_function. This example overrides the default with qs::qread to read a .qs file from the nflverse-data release. The output shows a tibble with 42,251 rows and 372 columns. ```R pb_read( file = "play_by_play_2023.qs", repo = "nflverse/nflverse-data", tag = "pbp", tread_function = qs::qread ) #> # A tibble: 42,251 × 372 #> play_id game_id old_game_id home_team away_team season_type week posteam #> #> 1 1 2023_01_ARI_W… 2023091007 WAS ARI REG 1 NA #> 2 39 2023_01_ARI_W… 2023091007 WAS ARI REG 1 WAS #> 3 55 2023_01_ARI_W… 2023091007 WAS ARI REG 1 WAS #> 4 77 2023_01_ARI_W… 2023091007 WAS ARI REG 1 WAS #> 5 102 2023_01_ARI_W… 2023091007 WAS ARI REG 1 WAS #> # ℹ 42,246 more rows #> # ℹ 364 more variables: posteam_type , defteam , side_of_field , #> # yardline_100 , game_date , quarter_seconds_remaining , #> # half_seconds_remaining , game_seconds_remaining , game_half , #> # quarter_end , drive , sp , qtr , down , #> # goal_to_go , time , yrdln , ydstogo , ydsnet , #> # desc , play_type , yards_gained , shotgun , … ``` -------------------------------- ### Read a file with pb_read() and a custom read function Source: https://docs.ropensci.org/piggyback/articles/piggyback.html Use pb_read() to read a file from a GitHub release, providing a read function that accepts the filename as the first argument. Additional parameters are passed via ... . The example reads a CSV with readr::read_csv() and shows the first 10 rows. ```R pb_read( file = "play_by_play_2023.csv", n_max = 10, repo = "nflverse/nflverse-data", tag = "pbp", read_function = readr::read_csv ) #> # A tibble: 10 × 372 #> play_id game_id old_game_id home_team away_team season_type week posteam #> #> 1 1 2023_01_ARI_W… 2023091007 WAS ARI REG 1 NA #> 2 39 2023_01_ARI_W… 2023091007 WAS ARI REG 1 WAS #> 3 55 2023_01_ARI_W… 2023091007 WAS ARI REG 1 WAS #> 4 77 2023_01_ARI_W… 2023091007 WAS ARI REG 1 WAS #> 5 102 2023_01_ARI_W… 2023091007 WAS ARI REG 1 WAS #> # ℹ 5 more rows #> # ℹ 364 more variables: posteam_type , defteam , side_of_field , #> # yardline_100 , game_date , quarter_seconds_remaining , #> # half_seconds_remaining , game_seconds_remaining , game_half , #> # quarter_end , drive , sp , qtr , down , #> # goal_to_go , time , yrdln , ydstogo , ydsnet , #> # desc , play_type , yards_gained , shotgun , … ``` -------------------------------- ### pb_list(repo, tag, .token) Source: https://docs.ropensci.org/piggyback/reference/pb_list.html Lists all assets attached to a GitHub release. Returns a data.frame of asset names, release tags, timestamps, owner, and repo. ```APIDOC ## pb_list(repo, tag, .token) ### Description List all assets attached to a release. Returns a data.frame of release asset names, release tag, timestamp, owner, and repo. ### Usage ```r pb_list(repo = guess_repo(), tag = NULL, .token = gh::gh_token()) ``` ### Arguments - **repo** (string) - Required - GitHub repository name in format "owner/repo". Default `guess_repo()` tries to guess based on current working directory's git repository. - **tag** (character) - Optional - Which release tag(s) do we want information for? If `NULL` (default), will return a table for all available release tags. - **.token** (string) - Required - GitHub authentication token, see `gh::gh_token()`. ### Value a data.frame of release asset names, release tag, timestamp, owner, and repo. ### Examples ```r if (FALSE) { # \dontrun{ pb_list("cboettig/piggyback-tests") } # } ``` ### See also `pb_releases` for a list of all releases in repository. ```