diff --git a/DESCRIPTION b/DESCRIPTION index d5c6dc32..bcb6647b 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -19,7 +19,9 @@ Description: The open sourced data management software 'Integrated Rule-Oriented with R. Storage of annotated files and R objects in 'iRODS' ensures findability, accessibility, interoperability, and reusability of data. License: MIT + file LICENSE -URL: https://github.com/irods/irods_client_library_rirods +URL: + https://github.com/irods/irods_client_library_rirods, + https://rirods.irods4r.org BugReports: https://github.com/irods/irods_client_library_rirods/issues Depends: R (>= 4.1) @@ -50,3 +52,4 @@ Encoding: UTF-8 Language: en-US Roxygen: list(markdown = TRUE) RoxygenNote: 7.2.3 +SystemRequirements: iRODS C++ REST API 0.9.3 (https://github.com/irods/irods_client_rest_cpp) diff --git a/README.Rmd b/README.Rmd index 8828f2b2..77534bfb 100644 --- a/README.Rmd +++ b/README.Rmd @@ -20,7 +20,7 @@ knitr::opts_knit$set( ) ``` -# rirods +# rirods [![Codecov test coverage](https://codecov.io/gh/irods/irods_client_library_rirods/branch/main/graph/badge.svg)](https://app.codecov.io/gh/irods/irods_client_library_rirods?branch=main) diff --git a/README.md b/README.md index 5f54292d..e712e046 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,7 @@ + -# rirods +# rirods @@ -15,27 +16,33 @@ The rirods package is an R client for iRODS. You can install the development version of rirods like so: - install.packages("rirods") +``` r +install.packages("rirods") +``` Or, the development version from GitHub, like so: - # install.packages("devtools") - devtools::install_github("irods/irods_client_library_rirods") +``` r +# install.packages("devtools") +devtools::install_github("irods/irods_client_library_rirods") +``` ## Prerequisites This package connects to the iRODS C++ REST API - -. +https://github.com/irods/irods_client_rest_cpp. Launch a local demonstration iRODS service (including the REST API): - # load - library(rirods) - # setup a mock iRODS server (https://github.com/irods/irods_demo) - use_irods_demo("alice", "passWORD") +``` r +# load +library(rirods) +# setup a mock iRODS server (https://github.com/irods/irods_demo) +use_irods_demo("alice", "passWORD") +``` This will result in the demonstration REST API running at - (or later version). +http://localhost/irods-rest/0.9.3 (or later version). These Docker containers are designed to easily stand up a **DEMONSTRATION** of the iRODS server. It is intended for education and @@ -49,8 +56,10 @@ To connect to the REST API endpoint of your choice, load `rirods`, connect with `create_irods()`, and authenticate with your iRODS credentials: - # connect - create_irods("http://localhost/irods-rest/0.9.3", "/tempZone/home") +``` r +# connect +create_irods("http://localhost/irods-rest/0.9.3", "/tempZone/home") +``` ### Authentication @@ -59,53 +68,44 @@ herself with `iauth()`. This prompts a dialog where you can enter your username and password without hardcoding this information in your scripts. - # login as alice with password "passWORD" - iauth() # or iauth("alice", "passWORD") +``` r +# login as alice with password "passWORD" +iauth() # or iauth("alice", "passWORD") +``` ### Save R objects Suppose Alice would like to upload an R object from her current R session to an iRODS collection. For this, use the `isaveRDS()` command: - # some data - foo <- data.frame(x = c(1, 8, 9), y = c("x", "y", "z")) +``` r +# some data +foo <- data.frame(x = c(1, 8, 9), y = c("x", "y", "z")) - # check where we are in the iRODS namespace - ipwd() - #> [1] "/tempZone/home/alice" +# check where we are in the iRODS namespace +ipwd() - # store data in iRODS - isaveRDS(foo, "foo.rds") +# store data in iRODS +isaveRDS(foo, "foo.rds") +``` ### Metadata To truly appreciate the strength of iRODS, we can add some metadata that describes the data object “foo”: - # add some metadata - imeta( - "foo.rds", - "data_object", - operations = - data.frame(operation = "add", attribute = "foo", value = "bar", units = "baz") - ) - - # check if file is stored with associated metadata - ils(metadata = TRUE) - #> - #> ======== - #> metadata - #> ======== - #> /tempZone/home/alice/foo.rds : - #> attribute value units - #> foo bar baz - #> - #> - #> ========== - #> iRODS Zone - #> ========== - #> logical_path type - #> /tempZone/home/alice/foo.rds data_object +``` r +# add some metadata +imeta( + "foo.rds", + "data_object", + operations = + data.frame(operation = "add", attribute = "foo", value = "bar", units = "baz") +) + +# check if file is stored with associated metadata +ils(metadata = TRUE) +``` For more on using metadata, check out `vignette("metadata")`. @@ -114,12 +114,10 @@ For more on using metadata, check out `vignette("metadata")`. If Alice wanted to copy the foo R object from an iRODS collection to her current R session, she would use `ireadRDS()`: - # retrieve in native R format - ireadRDS("foo.rds") - #> x y - #> 1 1 x - #> 2 8 y - #> 3 9 z +``` r +# retrieve in native R format +ireadRDS("foo.rds") +``` ### Other file formats @@ -127,44 +125,27 @@ Possibly Alice does not want a native R object to be stored on iRODS but a file type that can be accessed by other programs. For this, use the `iput()` command: - library(readr) +``` r +library(readr) - # creates a csv file of foo - write_csv(foo, "foo.csv") +# creates a csv file of foo +write_csv(foo, "foo.csv") - # send file - iput("foo.csv", "foo.csv") +# send file +iput("foo.csv", "foo.csv") - # check whether it is stored - ils() - #> - #> ========== - #> iRODS Zone - #> ========== - #> logical_path type - #> /tempZone/home/alice/foo.csv data_object - #> /tempZone/home/alice/foo.rds data_object +# check whether it is stored +ils() +``` Later on somebody else might want to download this file again and store it locally: - # retrieve it again later - iget("foo.csv", "foo.csv") - read_csv("foo.csv") - #> Rows: 3 Columns: 2 - #> ── Column specification ──────────────────────────────────────────────────────── - #> Delimiter: "," - #> chr (1): y - #> dbl (1): x - #> - #> ℹ Use `spec()` to retrieve the full column specification for this data. - #> ℹ Specify the column types or set `show_col_types = FALSE` to quiet this message. - #> # A tibble: 3 × 2 - #> x y - #> - #> 1 1 x - #> 2 8 y - #> 3 9 z +``` r +# retrieve it again later +iget("foo.csv", "foo.csv") +read_csv("foo.csv") +``` ### Query @@ -172,17 +153,15 @@ By adding metadata you and others can more easily discover data in future projects. Objects can be searched with General Queries and `iquery()`: - # look for objects in the home collection with a wildcard `%` - iquery("SELECT COLL_NAME, DATA_NAME WHERE COLL_NAME LIKE '/tempZone/home/%'") - #> COLL_NAME DATA_NAME - #> 1 /tempZone/home/alice foo.csv - #> 2 /tempZone/home/alice foo.rds +``` r +# look for objects in the home collection with a wildcard `%` +iquery("SELECT COLL_NAME, DATA_NAME WHERE COLL_NAME LIKE '/tempZone/home/%'") +``` - # or for data objects with a name that starts with "foo" - iquery("SELECT COLL_NAME, DATA_NAME WHERE DATA_NAME LIKE 'foo%'") - #> COLL_NAME DATA_NAME - #> 1 /tempZone/home/alice foo.csv - #> 2 /tempZone/home/alice foo.rds +``` r +# or for data objects with a name that starts with "foo" +iquery("SELECT COLL_NAME, DATA_NAME WHERE DATA_NAME LIKE 'foo%'") +``` For more on querying, check out `vignette("metadata")`. @@ -190,15 +169,18 @@ For more on querying, check out `vignette("metadata")`. Finally, we can clean up Alice’s home collection: - # delete object - irm("foo.rds", force = TRUE) - irm("foo.csv", force = TRUE) - - # check if objects are removed - ils() - #> This collection does not contain any objects or collections. - - # close the server - stop_irods_demo() - # optionally remove the Docker images - # irods:::remove_docker_images() +``` r +# delete object +irm("foo.rds", force = TRUE) +irm("foo.csv", force = TRUE) + +# check if objects are removed +ils() +``` + +``` r +# close the server +stop_irods_demo() +# optionally remove the Docker images +# irods:::remove_docker_images() +``` diff --git a/_pkgdown.yml b/_pkgdown.yml index 82650219..1b796c1a 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -1,7 +1,9 @@ url: https://irods.github.io/irods_client_library_rirods/ template: bootstrap: 5 - bootswatch: minty + bslib: + bg: "#ffffff" + fg: "#005e56" reference: - title: "Connecting and authentication" diff --git a/inst/WORDLIST b/inst/WORDLIST index d7ce371e..7533668f 100644 --- a/inst/WORDLIST +++ b/inst/WORDLIST @@ -1,31 +1,49 @@ +ATTR AVU AVUs CMD +COLN CONFIG Codecov +GenQuery GeneralQuery Hostname IRODS +POSIXct +RStudio +WSL arg +behaviour childtoresc cpp csv +datetime devtools +dir +ectory +findability github +hange hardcoding http https iCAT +iCommand iCommands iRODS icommands iquest +irectory irods macOS mockfiles -findability -accessibility +modelled +modelling +myfile +nrow +oved reusability -interoperability +submodules tempZone +unstage usethis diff --git a/man/figures/logo.png b/man/figures/logo.png index 8571106f..fad10389 100644 Binary files a/man/figures/logo.png and b/man/figures/logo.png differ diff --git a/pkgdown/favicon/apple-touch-icon-120x120.png b/pkgdown/favicon/apple-touch-icon-120x120.png index e4b783ac..e9fcdb1f 100644 Binary files a/pkgdown/favicon/apple-touch-icon-120x120.png and b/pkgdown/favicon/apple-touch-icon-120x120.png differ diff --git a/pkgdown/favicon/apple-touch-icon-152x152.png b/pkgdown/favicon/apple-touch-icon-152x152.png index b404958d..7b217a1e 100644 Binary files a/pkgdown/favicon/apple-touch-icon-152x152.png and b/pkgdown/favicon/apple-touch-icon-152x152.png differ diff --git a/pkgdown/favicon/apple-touch-icon-180x180.png b/pkgdown/favicon/apple-touch-icon-180x180.png index 59f3da4b..b6644d87 100644 Binary files a/pkgdown/favicon/apple-touch-icon-180x180.png and b/pkgdown/favicon/apple-touch-icon-180x180.png differ diff --git a/pkgdown/favicon/apple-touch-icon-60x60.png b/pkgdown/favicon/apple-touch-icon-60x60.png index 4ac55568..fabf3591 100644 Binary files a/pkgdown/favicon/apple-touch-icon-60x60.png and b/pkgdown/favicon/apple-touch-icon-60x60.png differ diff --git a/pkgdown/favicon/apple-touch-icon-76x76.png b/pkgdown/favicon/apple-touch-icon-76x76.png index dc7f66e4..92b9cd95 100644 Binary files a/pkgdown/favicon/apple-touch-icon-76x76.png and b/pkgdown/favicon/apple-touch-icon-76x76.png differ diff --git a/pkgdown/favicon/apple-touch-icon.png b/pkgdown/favicon/apple-touch-icon.png index caf31517..600fe486 100644 Binary files a/pkgdown/favicon/apple-touch-icon.png and b/pkgdown/favicon/apple-touch-icon.png differ diff --git a/pkgdown/favicon/favicon-16x16.png b/pkgdown/favicon/favicon-16x16.png index b67611ec..6c12aca7 100644 Binary files a/pkgdown/favicon/favicon-16x16.png and b/pkgdown/favicon/favicon-16x16.png differ diff --git a/pkgdown/favicon/favicon-32x32.png b/pkgdown/favicon/favicon-32x32.png index f20a95ff..efbaf403 100644 Binary files a/pkgdown/favicon/favicon-32x32.png and b/pkgdown/favicon/favicon-32x32.png differ diff --git a/pkgdown/favicon/favicon.ico b/pkgdown/favicon/favicon.ico index f4af98e6..d115728c 100644 Binary files a/pkgdown/favicon/favicon.ico and b/pkgdown/favicon/favicon.ico differ diff --git a/vignettes/demo.Rmd b/vignettes/demo.Rmd index fac2cda1..796069e4 100644 --- a/vignettes/demo.Rmd +++ b/vignettes/demo.Rmd @@ -40,7 +40,7 @@ sudo dockerd Make sure you don't need `sudo` for `docker`, though, by [adding yourself to the `docker` group](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user). You can check that this is the case by running `docker run hello-world` on the command line. -If you use WSL, you can start RStudio Server with `sudo rstudio-server start` and run it from your browser (http://localhost:8787). [The Posit site](https://posit.co/download/rstudio-server/) has installation instructions for R and RStudio Server in Linux. +If you use WSL, you can start RStudio Server with `sudo rstudio-server start` and run it from your browser (`http://localhost:8787`). [The Posit site](https://posit.co/download/rstudio-server/) has installation instructions for R and RStudio Server in Linux. Then, in your script or console, load `{rirods}` and run `use_irods_demo()`: diff --git a/vignettes/local-irods.Rmd b/vignettes/local-irods.Rmd index 947011fe..9c1521ea 100644 --- a/vignettes/local-irods.Rmd +++ b/vignettes/local-irods.Rmd @@ -141,12 +141,11 @@ ils("data") ``` Note that the file name need not stay the same in the local and iRODS systems. -Now, let's say that we have processed our data with some linear regression modelling and plotting. +Now, let's say that we have processed our data with some linear regression modelling. ```{r} m <- lm(y ~ x, data = fake_data) m -p <- plot(fake_data) ``` We could certainly store the output locally, but we could also decide to only store it in iRODS if we save it in RDS format. So let's save it in the "analysis" collection. @@ -157,7 +156,6 @@ change_state() ```{r} isaveRDS(m, "analysis/linear_model.rds") -isaveRDS(p, "analysis/plot.rds") ils("analysis") dir("analysis") # nothing was saved locally ``` diff --git a/vignettes/metadata.Rmd b/vignettes/metadata.Rmd index 71dca72c..30d791be 100644 --- a/vignettes/metadata.Rmd +++ b/vignettes/metadata.Rmd @@ -76,7 +76,7 @@ ils() ``` For illustration purposes, we'll create some data objects (i.e. files). -First, we simulate a study with a small dataframe, a scatterplot and a linear model. +First, we simulate a study with a small dataframe and a linear model. ```{r} set.seed(1234) @@ -84,10 +84,9 @@ fake_data <- data.frame(x = rnorm(20, mean = 1)) fake_data$y <- fake_data$x * 2 + 3 - rnorm(20, sd = 0.6) m <- lm(y ~ x, data = fake_data) m -p <- plot(fake_data) ``` -Then we store the dataframe as csv and the plot and linear model as RDS objects on iRODS. The csv file must be stored locally first, but the other two can be directly streamed to iRODS. +Then we store the dataframe as csv and the linear model as RDS objects on iRODS. The csv file must be stored locally first, but the other two can be directly streamed to iRODS. ```{r, include=FALSE} change_state() @@ -96,13 +95,11 @@ change_state() ```{r} data_path <- "data.csv" lm_path <- "analysis/linear_model.rds" -plot_path <- "analysis/plot.rds" write.csv(fake_data, data_path) # write locally iput(data_path, data_path) # transfer to iRODS imkdir("analysis") # create directory # save directly as rds isaveRDS(m, lm_path) -isaveRDS(p, plot_path) ``` If we add `metadata=TRUE` to the `ils()` call, we will see that these new data objects have no metadata attached to them. @@ -178,9 +175,9 @@ change_state() ```{r, message=FALSE, results="hide"} file_md <- data.frame( - path = c(data_path, lm_path, plot_path), - type = c("dataframe", "lm", "scatterplot"), - responsible = c("abby", "bob", "bob") + path = c(data_path, lm_path), + type = c("dataframe", "lm"), + responsible = c("abby", "bob") ) pmap(file_md, function(path, type, responsible) { imeta(path, operations = list(