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(