download a github release asset to the stow R user directory

Use stow to abstract away the process of downloading a file or a GitHub release asset to a user's data directory, only downloading files that have not already been downloaded.

Usage

stow_gh_release(owner, repo, dpkg, overwrite = FALSE)

stow(uri, overwrite = FALSE)

stow_url(url, overwrite = FALSE)

Arguments

owner: string of repo owner
repo: string of repo name
dpkg: string of gh release tag (will be the same as the filename without the .parquet extension)
overwrite: logical; re-download the remote file even though a local file with the same name exists?
uri: character string universal resource identifier; currently, must begin with http://, https://, or gh://
url: a URL string starting with http:// or https://

Value

path to the stowed file or url to github release

Details

Supported URI prefixes include:

https://, http://: download from a file
gh://: download a github release asset, formatted as gh://owner/repo/name

Stow downloads files to the users data directory; see ?tools::R_user_dir. Specify an alternative download location by setting the R_USER_DATA_DIR environment variable. The stow cache works by name only; that is, if a file with the same URI has already been downloaded once, it will not be re-downloaded again (unless overwrite = TRUE).

Examples

Sys.setenv(R_USER_DATA_DIR = tempfile("stow"))
# get by using URL
stow("https://github.com/geomarker-io/appc/releases/download/v0.1.0/nei_2020.rds",
     overwrite = TRUE) |>
  readRDS()
#> # A tibble: 369,063 × 4
#>    pollutant_code total_emissions emissions_uom s2            
#>    <chr>                    <dbl> <chr>         <s2_cell>     
#>  1 EC                  0.00137    TON           -3.419770e-306
#>  2 NO3                 0          TON           -3.419770e-306
#>  3 OC                  0.0317     TON           -3.419770e-306
#>  4 PM25-PRI            0.782      TON           -3.419770e-306
#>  5 PMFINE              0.746      TON           -3.419770e-306
#>  6 SO4                 0.00278    TON           -3.419770e-306
#>  7 EC                  0.0000182  TON           -3.355024e-306
#>  8 NO3                 0.00000638 TON           -3.355024e-306
#>  9 OC                  0.000129   TON           -3.355024e-306
#> 10 PM25-PRI            0.0007     TON           -3.355024e-306
#> # ℹ 369,053 more rows

# will be faster (even in later R sessions) next time
stow("https://github.com/geomarker-io/appc/releases/download/v0.1.0/nei_2020.rds") |>
  readRDS()
#> # A tibble: 369,063 × 4
#>    pollutant_code total_emissions emissions_uom s2            
#>    <chr>                    <dbl> <chr>         <s2_cell>     
#>  1 EC                  0.00137    TON           -3.419770e-306
#>  2 NO3                 0          TON           -3.419770e-306
#>  3 OC                  0.0317     TON           -3.419770e-306
#>  4 PM25-PRI            0.782      TON           -3.419770e-306
#>  5 PMFINE              0.746      TON           -3.419770e-306
#>  6 SO4                 0.00278    TON           -3.419770e-306
#>  7 EC                  0.0000182  TON           -3.355024e-306
#>  8 NO3                 0.00000638 TON           -3.355024e-306
#>  9 OC                  0.000129   TON           -3.355024e-306
#> 10 PM25-PRI            0.0007     TON           -3.355024e-306
#> # ℹ 369,053 more rows

# get a data package from a GitHub release
stow("gh://cole-brokamp/dpkg/mtcars-v0.0.0.9000", overwrite = TRUE) |>
  arrow::read_parquet()
#> # [☰] mtcars-v0.0.0.9000
#> # title: "Foofy Cars"
#> # homepage: https://github.com/cole-brokamp/dpkg
#> # ℹ Use `dpkg_meta() to get all metadata
#> # A tibble: 32 × 11
#>      mpg   cyl  disp    hp  drat    wt  qsec    vs    am  gear  carb
#>    <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl>
#>  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
#>  6  18.1     6  225    105  2.76  3.46  20.2     1     0     3     1
#>  7  14.3     8  360    245  3.21  3.57  15.8     0     0     3     4
#>  8  24.4     4  147.    62  3.69  3.19  20       1     0     4     2
#>  9  22.8     4  141.    95  3.92  3.15  22.9     1     0     4     2
#> 10  19.2     6  168.   123  3.92  3.44  18.3     1     0     4     4
#> # ℹ 22 more rows

stow("gh://cole-brokamp/dpkg/mtcars-v0.0.0.9000") |>
  arrow::read_parquet()
#> # [☰] mtcars-v0.0.0.9000
#> # title: "Foofy Cars"
#> # homepage: https://github.com/cole-brokamp/dpkg
#> # ℹ Use `dpkg_meta() to get all metadata
#> # A tibble: 32 × 11
#>      mpg   cyl  disp    hp  drat    wt  qsec    vs    am  gear  carb
#>    <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl>
#>  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
#>  6  18.1     6  225    105  2.76  3.46  20.2     1     0     3     1
#>  7  14.3     8  360    245  3.21  3.57  15.8     0     0     3     4
#>  8  24.4     4  147.    62  3.69  3.19  20       1     0     4     2
#>  9  22.8     4  141.    95  3.92  3.15  22.9     1     0     4     2
#> 10  19.2     6  168.   123  3.92  3.44  18.3     1     0     4     4
#> # ℹ 22 more rows