The iSEEindexS3Resource class

The iSEEindexS3Resource class represents a cloud storage resource accessible via the paws.storage R package. A URI for this type of resource uses the prefix “s3://”.

Usage

iSEEindexS3Resource(x)

Arguments

x

List of metadata. See Details.

Value

The constructor function iSEEindexS3Resource() returns an object of object of class iSEEindexS3Resource.

Details

Required metadata:

uri

Character scalar. URI of the resource.

Slot overview

This class inherits all slots from its parent class iSEEindexResource.

Furthermore, this class defines the additional slot(s) below:

region

AWS region.

Supported methods

In the following code snippets, x is an instance of a iSEEindexS3Resource class. Refer to the documentation for each method for more details on the remaining arguments.

• precache(x, ..., temp_dir = tempdir()) trims the s3:// prefix, parses information encoded in the remainder of the URI, downloads the resource from AWS S3 using that information, and caches a copy of the resource located at the resulting file path using BiocFileCache, before returning the file path to the cached file.

URI format

The URI must correspond to an existing file in an AWS S3 compatible cloud storage system.

For instance:

s3://bucket/prefix/index.rds

For details about authentication, see section “AWS Credentials” below.

Pre-caching

Additional arguments to the precache(x, ..., temp_dir = tempdir()):

temp_dir

Scalar character, the directory to store the downloaded file in before it is handed over to BiocFileCache. This directory will be created recursively if it doesn't already exist.

AWS Credentials and region settings

For detailed information, please consult the paws R package documentation.

Currently, you must have the AWS Command Line Interface installed to use AWS SSO with paws.storage.

A default AWS region can be set in the file ~/.aws/config. For instance:

[default]
region=eu-west-2

Optionally, a field named region can be added in the list of resource metadata to set the AWS S3 region for each individual resource, e.g.

- id: ID1
  title: ReprocessedAllenData
  uri: s3://example/ReprocessedAllenData.rds
  description: |
    Reprocessed Allen Data.
  region: eu-west-2

Regions set in individual resource metadata override the default AWS region set in ~/.aws/config (if any). The region metadata does not need to be set for resources that should use the default region, and resource classes that do not require region information.

If a default region is NOT set in ~/.aws/config, then the region MUST be set in the metadata.

Credentials for all services can be set in the AWS shared credentials file ~/.aws/credentials. For instance:

[default]
aws_access_key_id=your AWS access key
aws_secret_access_key=your AWS secret key

Author

Thomas Sandmann, Kevin Rue-Albrecht

Examples

# Without region metadata
metadata <- list(uri = "s3://example/path/to/bucket")
x <- iSEEindexS3Resource(metadata)
str(x)
#> Formal class 'iSEEindexS3Resource' [package "iSEEindex"] with 2 slots
#>   ..@ region: chr NA
#>   ..@ uri   : chr "s3://example/path/to/bucket"

# With region metadata
# NOTE: The @region slot is set to NA pending bugfix (see above).
metadata <- list(uri = "s3://example/path/to/bucket", region = "eu-west-2")
x <- iSEEindexS3Resource(metadata)
str(x)
#> Formal class 'iSEEindexS3Resource' [package "iSEEindex"] with 2 slots
#>   ..@ region: chr "eu-west-2"
#>   ..@ uri   : chr "s3://example/path/to/bucket"