Skip to contents

If you are not familiar with iRODS, understanding how to access and manipulate data with it may be less than intuitive. In this vignette, we’ll go through the main functions for setting and changing the working directory and for creating, saving, reading and removing data, comparing R functions for manipulation of local files and the rirods counterparts.

The main point to understand is that the iRODS server is not simply another location that you can access by editing a path. While you can use file.remove() to remove any file in your computer, there is no path you can provide that will remove a data object in iRODS. Instead, you need to use irm(), which connects to the iRODS server to apply the same action. This is the sort of comparison we will see in this vignette.

A second point to keep in mind is that, normally, you need to stage and unstage your data in order to manipulate it, rather than modifying your iRODS data directly. This is always the case with other clients, such as iCommands: if you want to read a dataframe you have in iRODS, you first need to copy it to your local computer and then open that file; if you want to save a modified version of that file you have to copy the local (modified) version back to iRODS. rirods offers one exception to this by allowing to save R objects in RDS format (only) directly into iRODS and read them back, with isaveRDS() and ireadRDS() respectively.

Finally, most of the functions in rirods are inspired by iCommands, which are themselves modelled after Unix commands and prefixed by an i. So, for example, the Unix command to change a directory is cd, its iCommands counterpart is icd, and then the rirods equivalent is icd().

Set and change working directory

In R we can check the working directory with getwd() and change it with setwd(dir), where dir is the path we want to set as the new working directory. Both functions return the current working directory; before the change and invisibly in the case of setwd().

The rirods counterparts are ipwd() (“print working directory”) and icd(dir) (“change directory”) respectively.

For the purposes of this vignette, we’ll use a temporary directory locally. This is the current output of getwd() and ipwd() respectively:

getwd()
#> [1] "/tmp/RtmpdI7Lnm"
ipwd()
#> [1] "/tempZone/home/rods"

We can see their contents with dir(path) or list.files(path) and ils(path) respectively. If path is not provided, the current working directory is used as default:

dir()
#> [1] "data"                            "fileaff529dc4f7a"               
#> [3] "fileaff544b8c30f"                "fileaff56397de86"               
#> [5] "libloc_177_4deaa61661921490.rds" "libloc_220_e632dc491489e26.rds" 
#> [7] "libloc_248_96893be67ad5663d.rds" "local-irods"                    
#> [9] "rmarkdown-straff52a03d943.html"
ils()
#> 
#> ==========
#> iRODS Zone
#> ==========
#>              logical_path       type
#>  /tempZone/home/rods/data collection

We can focus on the “data” local directory with setwd("data")1 and on the “data” iRODS collection with icd("data"). Then the output of getwd() and ipwd(), respectively, are updated, and dir() and ils() will show the contents of “data” by default.

old_local <- setwd("data")
dir()
#> character(0)
old_irods <- icd("data")
ils()
#> This collection does not contain any objects or collections.

We can reset our working directories by providing the old path to setwd() and icd() respectively. Note that moving upwards in the file system is also possible by providing “../” for each level up you want to go: icd("../") changes the iRODS working directory to its parent collection.

setwd(old_local)
getwd()
#> [1] "/tmp/RtmpdI7Lnm"

icd(old_irods)
ipwd()
#> [1] "/tempZone/home/rods"

Create directories

Directories can be created in R with dir.create(path); collections can be created in iRODS with imkdir(path) (“make directory”), providing a path relative to the working directory. For example, the code below creates an “analysis” directory under our working directory, first locally and then in iRODS.

dir.create("analysis")
dir()
#>  [1] "analysis"                        "data"                           
#>  [3] "fileaff510914354"                "fileaff529dc4f7a"               
#>  [5] "fileaff536e4e75"                 "fileaff544b8c30f"               
#>  [7] "fileaff54cef0acd"                "fileaff54d5ab61f"               
#>  [9] "fileaff56397de86"                "fileaff5642d5552"               
#> [11] "fileaff573faea96"                "libloc_177_4deaa61661921490.rds"
#> [13] "libloc_220_e632dc491489e26.rds"  "libloc_248_96893be67ad5663d.rds"
#> [15] "local-irods"                     "rmarkdown-straff52a03d943.html"

imkdir("analysis")
ils()
#> 
#> ==========
#> iRODS Zone
#> ==========
#>                  logical_path       type
#>  /tempZone/home/rods/analysis collection
#>      /tempZone/home/rods/data collection

Save data

R and several R packages (such as readr) provide a number of functions to save data locally. For example, writeLines(some_vector, path) can be used to write a vector into a text file with one item per line; write.csv(dataframe, path) can be used to write a dataframe as a comma-separated file; saveRDS(R_object, path) can be used to write any R object into an RDS file. This path can be relative to the working directory or absolute paths.

For example, let’s simulate some data and store it in our “data” directory with write.csv().

set.seed(1234)
fake_data <- data.frame(x = rnorm(20, mean = 1))
fake_data$y <- fake_data$x * 2 + 3 - rnorm(20, sd = 0.6)
write.csv(fake_data, file.path("data", "data.csv"), row.names=FALSE)
dir("data")
#> [1] "data.csv"    "local-irods"

When saving data in iRODS, we don’t have these kinds of options. Instead, we can either transfer a file of any type from our local system to iRODS with iput(local_path, irods_path) or save an R object as an RDS file with isaveRDS(some_object, irods_path). In the case of our simulated data, we use the first option:

iput("data/data.csv", "data/data_from_local.csv")
ils("data")
#> 
#> ==========
#> iRODS Zone
#> ==========
#>                                  logical_path        type
#>  /tempZone/home/rods/data/data_from_local.csv data_object

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.

m <- lm(y ~ x, data = fake_data)
m
#> 
#> Call:
#> lm(formula = y ~ x, data = fake_data)
#> 
#> Coefficients:
#> (Intercept)            x  
#>       3.249        2.130

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.

isaveRDS(m, "analysis/linear_model.rds")
ils("analysis")
#> 
#> ==========
#> iRODS Zone
#> ==========
#>                                   logical_path        type
#>  /tempZone/home/rods/analysis/linear_model.rds data_object
dir("analysis") # nothing was saved locally
#> character(0)

Read data

Just like we have many different R functions to save files to different formats, there are specific functions to read files in different formats. And just like with rirods we either save in RDS format or transfer files from a local system to iRODS, we either read RDS files or transfer files back from iRODS to the local system. If we want to read “data_from_local.csv”, we first need to retrieve it with iget(irods_path, local_path) and then open it with an appropriate R function.

iget("data/data_from_local.csv", "data/data_from_irods.csv")
dir("data")
#> [1] "data_from_irods.csv" "data.csv"            "local-irods"
read.csv("data/data_from_irods.csv") # same as fake_data
#>               x           y
#> 1  -0.207065749  2.50541557
#> 2   1.277429242  5.84927002
#> 3   2.084441177  7.43321108
#> 4  -1.345697703  0.03285093
#> 5   1.429124689  6.27448153
#> 6   1.506055892  6.88103473
#> 7   0.425260040  3.50566665
#> 8   0.453368144  4.52092972
#> 9   0.435548001  3.88017898
#> 10  0.109962171  3.78149350
#> 11  0.522807300  3.38423607
#> 12  0.001613555  3.28858296
#> 13  0.223746105  3.87315623
#> 14  1.064458817  5.42967247
#> 15  1.959494059  7.89644420
#> 16  0.889714506  5.48000057
#> 17  0.488990494  5.28600478
#> 18  0.088804583  3.98220508
#> 19  0.162828320  3.50223295
#> 20  3.415835178 10.11120888

For the RDS files, we could also use iget() if we wanted to store them locally, or simply ireadRDS(irods_path) to read the file directly.

# copy locally first
iget("analysis/linear_model.rds", "analysis/linear_model_in_local.rds")
dir("analysis")
#> [1] "linear_model_in_local.rds"
readRDS("analysis/linear_model_in_local.rds")
#> 
#> Call:
#> lm(formula = y ~ x, data = fake_data)
#> 
#> Coefficients:
#> (Intercept)            x  
#>       3.249        2.130

# or read directly from iRODS
ireadRDS("analysis/linear_model.rds")
#> 
#> Call:
#> lm(formula = y ~ x, data = fake_data)
#> 
#> Coefficients:
#> (Intercept)            x  
#>       3.249        2.130

Remove data

Finally, local data can be removed with unlink(path) or file.remove(), whereas iRODS data can be removed with irm(path). Both unlink() and irm() take an optional argument recursive that should be TRUE if we want to remove a directory/collection and all its contents. In the case of irm(), the force argument also defines whether the item should be deleted permanently or, if FALSE, sent to the “trash” collection.

unlink("analysis", recursive = TRUE)
dir()
#>  [1] "data"                            "fileaff510914354"               
#>  [3] "fileaff5188b4e98"                "fileaff529dc4f7a"               
#>  [5] "fileaff532431f80"                "fileaff536e4e75"                
#>  [7] "fileaff53ebae039"                "fileaff5403d36cb"               
#>  [9] "fileaff5445477e0"                "fileaff544b8c30f"               
#> [11] "fileaff546d6bb55"                "fileaff54c5ef2fd"               
#> [13] "fileaff54cef0acd"                "fileaff54d5ab61f"               
#> [15] "fileaff550cdd297"                "fileaff55b27b8ea"               
#> [17] "fileaff55fda1776"                "fileaff56397de86"               
#> [19] "fileaff5642d5552"                "fileaff573faea96"               
#> [21] "libloc_177_4deaa61661921490.rds" "libloc_220_e632dc491489e26.rds" 
#> [23] "libloc_248_96893be67ad5663d.rds" "local-irods"                    
#> [25] "rmarkdown-straff52a03d943.html"

irm("data", recursive = TRUE, force = TRUE)
ils()
#> 
#> ==========
#> iRODS Zone
#> ==========
#>                  logical_path       type
#>  /tempZone/home/rods/analysis collection