WARNING: these functions are deprecated.
Applications are expected to handle acquisition of files before loaders are called.
Acquire a file or metadata for loading.
As one might expect, these are typically used inside a load* function.
acquireFile(project, path)
acquireMetadata(project, path)
# S4 method for class 'character'
acquireFile(project, path)
# S4 method for class 'character'
acquireMetadata(project, path)acquireFile methods return a local path to the file corresponding to the requested resource.
acquireMetadata methods return a named list of metadata for the requested resource.
By default, files and metadata are loaded from the same staging directory that is written to by stageObject.
alabaster applications can define custom methods to obtain the files and metadata from a different location, e.g., remote databases.
This is achieved by dispatching on a different class of project.
Each custom acquisition method should take two arguments.
The first argument is an R object representing some concept of a “project”.
In the default case, this is a string containing a path to the staging directory representing the project.
However, it can be anything, e.g., a number containing a database identifier, a list of identifiers and versions, and so on -
as long as the custom acquisition method is capable of understanding it, the load* functions don't care.
The second argument is a string containing the relative path to the resource inside that project.
This should be the path to a specific file inside the project, not the subdirectory containing the file.
More concretely, it should be equivalent to the path in the output of stageObject,
not the path to the subdirectory used as the input to the same function.
The return value for each custom acquisition function should be the same as their local counterparts. That is, any custom file acquisition function should return a file path, and any custom metadata acquisition function should return a naamed list of metadata.
# Staging an example DataFrame:
library(S4Vectors)
#> Loading required package: stats4
#> Loading required package: BiocGenerics
#>
#> Attaching package: ‘BiocGenerics’
#> The following objects are masked from ‘package:stats’:
#>
#> IQR, mad, sd, var, xtabs
#> The following objects are masked from ‘package:base’:
#>
#> Filter, Find, Map, Position, Reduce, anyDuplicated, aperm, append,
#> as.data.frame, basename, cbind, colnames, dirname, do.call,
#> duplicated, eval, evalq, get, grep, grepl, intersect, is.unsorted,
#> lapply, mapply, match, mget, order, paste, pmax, pmax.int, pmin,
#> pmin.int, rank, rbind, rownames, sapply, setdiff, table, tapply,
#> union, unique, unsplit, which.max, which.min
#>
#> Attaching package: ‘S4Vectors’
#> The following object is masked from ‘package:utils’:
#>
#> findMatches
#> The following objects are masked from ‘package:base’:
#>
#> I, expand.grid, unname
df <- DataFrame(A=1:10, B=LETTERS[1:10])
tmp <- tempfile()
dir.create(tmp)
info <- stageObject(df, tmp, path="coldata")
writeMetadata(info, tmp)
#> $type
#> [1] "local"
#>
#> $path
#> [1] "coldata/simple.csv.gz"
#>
# Retrieving the metadata:
meta <- acquireMetadata(tmp, "coldata/simple.csv.gz")
str(meta)
#> List of 6
#> $ $schema : chr "csv_data_frame/v1.json"
#> $ path : chr "coldata/simple.csv.gz"
#> $ is_child : logi FALSE
#> $ data_frame :List of 4
#> ..$ columns :List of 2
#> .. ..$ :List of 2
#> .. .. ..$ name: chr "A"
#> .. .. ..$ type: chr "integer"
#> .. ..$ :List of 2
#> .. .. ..$ name: chr "B"
#> .. .. ..$ type: chr "string"
#> ..$ row_names : logi FALSE
#> ..$ dimensions:List of 2
#> .. ..$ : int 10
#> .. ..$ : int 2
#> ..$ version : int 2
#> $ csv_data_frame:List of 1
#> ..$ compression: chr "gzip"
#> $ md5sum : chr "042b00e066dfa96577b5d6ac3c3ee700"
# Retrieving the file:
acquireFile(tmp, "coldata/simple.csv.gz")
#> [1] "/tmp/RtmpChCVYK/file26ca990a2a/coldata/simple.csv.gz"