Package 'DataSpaceR' reference manual

Title:	Interface to 'the CAVD DataSpace'
Description:	Provides a convenient API interface to access immunological data within 'the CAVD DataSpace'(<https://dataspace.cavd.org>), a data sharing and discovery tool that facilitates exploration of HIV immunological data from pre-clinical and clinical HIV vaccine studies.
Authors:	Ju Yeong Kim [aut], Sean Hughes [rev], Jason Taylor [aut, cre], Helen Miller [aut], CAVD DataSpace [cph]
Maintainer:	Jason Taylor <[email protected]>
License:	GPL-3
Version:	0.7.6
Built:	2024-08-15 05:38:23 UTC
Source:	https://github.com/ropensci/DataSpaceR

DataSpaceR

Description

DataSpaceR provides a convenient API for accessing datasets within the DataSpace database.

Details

Uses the Rlabkey package to connect to DataSpace. Implements convenient methods for accessing datasets.

Author(s)

Ju Yeong Kim

Check netrc file

Description

Check that there is a netrc file with a valid entry for the CAVD DataSpace.

Usage

checkNetrc(netrcFile = getNetrcPath(), onStaging = FALSE, verbose = TRUE)
checkNetrc(netrcFile = getNetrcPath(), onStaging = FALSE, verbose = TRUE)

Arguments

`netrcFile`	A character. File path to netrc file to check.
`onStaging`	A logical. Whether to check the staging server instead of the production server.
`verbose`	A logical. Whether to print the extra details for troubleshooting.

Value

The name of the netrc file

Examples

try(checkNetrc())
try(checkNetrc())

Create a connection to DataSpace

Description

Constructor for DataSpaceConnection

Usage

connectDS(login = NULL, password = NULL, verbose = FALSE, onStaging = FALSE)
connectDS(login = NULL, password = NULL, verbose = FALSE, onStaging = FALSE)

Arguments

`login`	A character. Optional argument. If there is no netrc file a temporary one can be written by passing login and password of an active DataSpace account.
`password`	A character. Optional. The password for the selected login.
`verbose`	A logical. Whether to print the extra details for troubleshooting.
`onStaging`	A logical. Whether to connect to the staging server instead of the production server.

Details

Instantiates an DataSpaceConnection. The constructor will try to take the values of the various labkey.* parameters from the global environment. If they don't exist, it will use default values. These are assigned to 'options', which are then used by the DataSpaceConnection class.

Value

an instance of DataSpaceConnection

Examples

## Not run: 
con <- connectDS()

## End(Not run)

con <- try(connectDS())
if (inherits(con, "try-error")) {
  warning("Read README for more information on how to set up a .netrc file.")
}
## Not run: 
con <- connectDS()

## End(Not run)

con <- try(connectDS())
if (inherits(con, "try-error")) {
  warning("Read README for more information on how to set up a .netrc file.")
}

The DataSpaceConnection class

Description

The DataSpaceConnection class

Constructor

connectDS

Active bindings

config: A list. Stores configuration of the connection object such as URL, path and username.
availableStudies: A data.table. The table of available studies.
availableGroups: A data.table. The table of available groups.
availablePublications: A data.table. The table of available publications.
mabGridSummary: A data.table. The filtered grid with updated n_ columns and geometric_mean_curve_ic50.
mabGrid: A data.table. The filtered mAb grid.
virusMetadata: A data.table. Metadata about all viruses in the DataSpace.
virusNameMappingTables: A list of data.table objects. This list contains 'virusMetadataAll', 'virusLabId', and 'virus_synonym' which are described in the vignette 'Virus_Name_Mapping_Tables'.

Methods

Public methods

DataSpaceConnection$new()
DataSpaceConnection$print()
DataSpaceConnection$getStudy()
DataSpaceConnection$getGroup()
DataSpaceConnection$filterMabGrid()
DataSpaceConnection$resetMabGrid()
DataSpaceConnection$getMab()
DataSpaceConnection$downloadPublicationData()
DataSpaceConnection$refresh()
DataSpaceConnection$clone()

Method `new()`

Initialize a DataSpaceConnection object. See connectDS.

Usage

DataSpaceConnection$new(
  login = NULL,
  password = NULL,
  verbose = FALSE,
  onStaging = FALSE
)

Arguments

login: A character. Optional argument. If there is no netrc file a temporary one can be written by passing login and password of an active DataSpace account.
password: A character. Optional. The password for the selected login.
verbose: A logical. Whether to print the extra details for troubleshooting.
onStaging: A logical. Whether to connect to the staging server instead of the production server.

Returns

A new 'DataSpaceConnection' object.

Method `print()`

Print the DataSpaceConnection object.

Usage

DataSpaceConnection$print()

Method `getStudy()`

Create a DataSpaceStudy object.

Usage

DataSpaceConnection$getStudy(studyName)

Arguments

studyName: A character. Name of the study to retrieve.

Method `getGroup()`

Create a DataSpaceStudy object.

Usage

DataSpaceConnection$getGroup(groupId)

Arguments

groupId: An integer. ID of the group to retrieve.

Method `filterMabGrid()`

Filter rows in the mAb grid by specifying the values to keep in the columns found in the mabGrid field. It takes the column and the values and filters the underlying tables.

Usage

DataSpaceConnection$filterMabGrid(using, value)

Arguments

using: A character. Name of the column to filter.
value: A character vector. Values to keep in the mAb grid.

Method `resetMabGrid()`

Reset the mAb grid to the unfiltered state.

Usage

DataSpaceConnection$resetMabGrid()

Method `getMab()`

Create a DataSpaceMab object.

Usage

DataSpaceConnection$getMab()

Method `downloadPublicationData()`

Download publication data for a chosen publication.

Usage

DataSpaceConnection$downloadPublicationData(
  publicationId,
  outputDir = getwd(),
  unzip = TRUE,
  verbose = TRUE
)

Arguments

publicationId: A character/integer. ID for the publication to download data for.
outputDir: A character. Path to directory to download publication data.
unzip: A logical. If TRUE, unzip publication data to outputDir.
verbose: A logical. Default TRUE.

Method `refresh()`

Refresh the connection object to update available studies and groups.

Usage

DataSpaceConnection$refresh()

Method `clone()`

The objects of this class are cloneable with this method.

Usage

DataSpaceConnection$clone(deep = FALSE)

Arguments

deep: Whether to make a deep clone.

Examples

## Not run: 
# Create a connection (Initiate a DataSpaceConnection object)
con <- connectDS()
con

# Connect to cvd408
# https://dataspace.cavd.org/cds/CAVD/app.view#learn/learn/Study/cvd408?q=408
cvd408 <- con$getStudy("cvd408")

# Connect to all studies
cvd <- con$getStudy("cvd408")

# Connect to the NYVAC durability comparison group
# https://dataspace.cavd.org/cds/CAVD/app.view#group/groupsummary/220
nyvac <- con$getGroup(220)

# Refresh the connection object to update available studies and groups
con$refresh()

## End(Not run)

## Not run: 
# Create a connection (Initiate a DataSpaceConnection object)
con <- connectDS()
con

# Connect to cvd408
# https://dataspace.cavd.org/cds/CAVD/app.view#learn/learn/Study/cvd408?q=408
cvd408 <- con$getStudy("cvd408")

# Connect to all studies
cvd <- con$getStudy("cvd408")

# Connect to the NYVAC durability comparison group
# https://dataspace.cavd.org/cds/CAVD/app.view#group/groupsummary/220
nyvac <- con$getGroup(220)

# Refresh the connection object to update available studies and groups
con$refresh()

## End(Not run)

The DataSpaceMab class

Description

The DataSpaceMab class

Constructor

DataSpaceConnection$getMab()

Active bindings

config: A list. Stores configuration of the connection object such as URL, path and username.
studyAndMabs: A data.table. The table of available mAbs by study.
mabs: A data.table. The table of available mAbs and their attributes.
nabMab: A data.table. The table of mAbs and their neutralizing measurements against viruses.
studies: A data.table. The table of available studies.
assays: A data.table. The table of assay status by study.
variableDefinitions: A data.table. The table of variable definitions.

Methods

Method `new()`

Initialize DataSpaceMab object. See DataSpaceConnection.

Usage

DataSpaceMab$new(mabMixture, filters, config)

Arguments

mabMixture: A character vector.
filters: A list.
config: A list.

Method `print()`

Print the DataSpaceMab object summary.

Usage

DataSpaceMab$print()

Method `refresh()`

Refresh the DataSpaceMab object to update datasets.

Usage

DataSpaceMab$refresh()

Method `getLanlMetadata()`

Applies LANL metadata to mabs table.

Usage

DataSpaceMab$getLanlMetadata()

Method `clone()`

The objects of this class are cloneable with this method.

Usage

DataSpaceMab$clone(deep = FALSE)

Arguments

deep: Whether to make a deep clone.

Examples

## Not run: 
# Create a connection (Initiate a DataSpaceConnection object)
con <- connectDS()

# Browse the mAb Grid
con$mabGridSummary

# Filter the grid by viruses
con$filterMabGrid(using = "virus", value = c("242-14", "Q23.17", "6535.3", "BaL.26", "DJ263.8"))

# Filter the grid by donor species (llama)
con$filterMabGrid(using = "donor_species", value = "llama")

# Check the updated grid
con$mabGridSummary

# Retrieve available viruses in the filtered grid
con$mabGrid[, unique(virus)]

# Retrieve available clades for 1H9 mAb mixture in the filtered grid
con$mabGrid[mab_mixture == "1H9", unique(clade)]

# Create a DataSpaceMab object that contains the filtered mAb data
mab <- con$getMab()
mab

# Inspect the `nabMab` field
mab$nabMab

## End(Not run)

## Not run: 
# Create a connection (Initiate a DataSpaceConnection object)
con <- connectDS()

# Browse the mAb Grid
con$mabGridSummary

# Filter the grid by viruses
con$filterMabGrid(using = "virus", value = c("242-14", "Q23.17", "6535.3", "BaL.26", "DJ263.8"))

# Filter the grid by donor species (llama)
con$filterMabGrid(using = "donor_species", value = "llama")

# Check the updated grid
con$mabGridSummary

# Retrieve available viruses in the filtered grid
con$mabGrid[, unique(virus)]

# Retrieve available clades for 1H9 mAb mixture in the filtered grid
con$mabGrid[mab_mixture == "1H9", unique(clade)]

# Create a DataSpaceMab object that contains the filtered mAb data
mab <- con$getMab()
mab

# Inspect the `nabMab` field
mab$nabMab

## End(Not run)

The DataSpaceStudy class

Description

The DataSpaceStudy class

Constructor

DataSpaceConnection$getStudy() DataSpaceConnection$getGroup()

Active bindings

study: A character. The study name.
config: A list. Stores configuration of the connection object such as URL, path and username.
availableDatasets: A data.table. The table of datasets available in the DataSpaceStudy object.
cache: A list. Stores the data to avoid downloading the same tables multiple times.
dataDir: A character. Default directory for storing nonstandard datasets. Set with setDataDir(dataDir).
treatmentArm: A data.table. The table of treatment arm information for the connected study. Not available for all study connection.
group: A character. The group name.
studyInfo: A list. Stores the information about the study.

Methods

Public methods

DataSpaceStudy$new()
DataSpaceStudy$print()
DataSpaceStudy$getDataset()
DataSpaceStudy$clearCache()
DataSpaceStudy$getDatasetDescription()
DataSpaceStudy$setDataDir()
DataSpaceStudy$refresh()
DataSpaceStudy$clone()

Method `new()`

Initialize DataSpaceStudy class. See DataSpaceConnection.

Usage

DataSpaceStudy$new(study = NULL, config = NULL, group = NULL, studyInfo = NULL)

Arguments

study: A character. Name of the study to retrieve.
config: A list. Stores configuration of the connection object such as URL, path and username.
group: An integer. ID of the group to retrieve.
studyInfo: A list. Stores the information about the study.

Method `print()`

Print DataSpaceStudy class.

Usage

DataSpaceStudy$print()

Method `getDataset()`

Get a dataset from the connection.

Usage

DataSpaceStudy$getDataset(
  datasetName,
  mergeExtra = FALSE,
  colFilter = NULL,
  reload = FALSE,
  outputDir = NULL,
  ...
)

Arguments

datasetName: A character. Name of the dataset to retrieve. Accepts the value in either the "name" or "label" field from availableDatasets.
mergeExtra: A logical. If set to TRUE, merge extra information. Ignored for non-integrated datasets.
colFilter: A matrix. A filter as returned by Rlabkey's makeFilter.
reload: A logical. If set to TRUE, download the dataset, whether a cached version exist or not.
outputDir: A character. Optional, specifies directory to download nonstandard datasets. If NULL, data will be downloaded to dataDir, set with setDataDir(dataDir). If dataDir is not set, and outputDir is NULL, a tmp directory will be used.
...: Extra arguments to be passed to labkey.selectRows

Method `clearCache()`

Clear cache. Remove downloaded datasets.

Usage

DataSpaceStudy$clearCache()

Method `getDatasetDescription()`

Get variable information.

Usage

DataSpaceStudy$getDatasetDescription(datasetName, outputDir = NULL)

Arguments

datasetName: A character. Name of the dataset to retrieve. Accepts the value in either the "name" or "label" field from availableDatasets.
outputDir: A character. Directory path.

Method `setDataDir()`

Set default directory to download non-integrated datasets. If no dataDir is set, a tmp directory will be used.

Usage

DataSpaceStudy$setDataDir(dataDir)

Arguments

dataDir: A character. Directory path.

Method `refresh()`

Refresh the study object to update available datasets and treatment info.

Usage

DataSpaceStudy$refresh()

Method `clone()`

The objects of this class are cloneable with this method.

Usage

DataSpaceStudy$clone(deep = FALSE)

Arguments

deep: Whether to make a deep clone.

Examples

## Not run: 
# Create a connection (Initiate a DataSpaceConnection object)
con <- connectDS()

# Connect to cvd408 (Initiate a DataSpaceStudy object)
# https://dataspace.cavd.org/cds/CAVD/app.view#learn/learn/Study/cvd408?q=408
cvd408 <- con$getStudy("cvd408")
cvd408

# Retrieve Neutralizing antibody dataset (NAb) for cvd408 from DataSpace
NAb <- cvd408$getDataset("NAb")

# Get variable information of the NAb dataset
cvd408$getDatasetDescription("NAb")

# Take a look at cvd408's treatment arm information
cvd408$treatmentArm

# Clear cache of a study object
cvd408$clearCache()

# Connect to the NYVAC durability comparison group
# https://dataspace.cavd.org/cds/CAVD/app.view#group/groupsummary/220
nyvac <- con$getGroup(220)

# Connect to all studies
cvd <- con$getStudy("")

# Refresh the study object to update available datasets and treatment info
cvd$refresh()

## End(Not run)

## Not run: 
# Create a connection (Initiate a DataSpaceConnection object)
con <- connectDS()

# Connect to cvd408 (Initiate a DataSpaceStudy object)
# https://dataspace.cavd.org/cds/CAVD/app.view#learn/learn/Study/cvd408?q=408
cvd408 <- con$getStudy("cvd408")
cvd408

# Retrieve Neutralizing antibody dataset (NAb) for cvd408 from DataSpace
NAb <- cvd408$getDataset("NAb")

# Get variable information of the NAb dataset
cvd408$getDatasetDescription("NAb")

# Take a look at cvd408's treatment arm information
cvd408$treatmentArm

# Clear cache of a study object
cvd408$clearCache()

# Connect to the NYVAC durability comparison group
# https://dataspace.cavd.org/cds/CAVD/app.view#group/groupsummary/220
nyvac <- con$getGroup(220)

# Connect to all studies
cvd <- con$getStudy("")

# Refresh the study object to update available datasets and treatment info
cvd$refresh()

## End(Not run)

Get a default netrc file path

Description

Get a default netrc file path

Usage

getNetrcPath()
getNetrcPath()

Value

A character vector containing the default netrc file path

Examples

getNetrcPath()
getNetrcPath()

Write a netrc file

Description

Write a netrc file that is valid for accessing DataSpace.

Usage

writeNetrc(
  login,
  password,
  netrcFile = NULL,
  onStaging = FALSE,
  overwrite = FALSE
)
writeNetrc(
  login,
  password,
  netrcFile = NULL,
  onStaging = FALSE,
  overwrite = FALSE
)

Arguments

`login`	A character. Email address used for logging in on DataSpace.
`password`	A character. Password associated with the login.
`netrcFile`	A character. Credentials will be written into that file. If left NULL, netrc will be written into a temporary file.
`onStaging`	A logical. Whether to connect to the staging server instead of the production server.
`overwrite`	A logical. Whether to overwrite the existing netrc file.

Details

The database is accessed with the user's credentials. A netrc file storing login and password information is required. See here for instruction on how to register and set DataSpace credential. By default curl will look for the file in your home directory.

Value

A character vector containing the netrc file path

Examples

# First, create an account in the DataSpace App and read the terms of use
# Next, create a netrc file using writeNetrc()
writeNetrc(
  login = "[email protected]",
  password = "yourSecretPassword"
)
# Specify `netrcFile = getNetrcPath()` to write netrc in the default path
# First, create an account in the DataSpace App and read the terms of use
# Next, create a netrc file using writeNetrc()
writeNetrc(
  login = "[email protected]",
  password = "yourSecretPassword"
)
# Specify `netrcFile = getNetrcPath()` to write netrc in the default path

Package 'DataSpaceR'

Help Index

DataSpaceR

Description

Details

Author(s)

See Also

Check netrc file

Description

Usage

Arguments

Value

See Also

Examples

Create a connection to DataSpace

Description

Usage

Arguments

Details

Value

See Also

Examples

The DataSpaceConnection class

Description

Constructor

Active bindings

Methods

Public methods

Method new()

Usage

Arguments

Returns

Method print()

Usage

Method getStudy()

Usage

Arguments

Method getGroup()

Usage

Arguments

Method filterMabGrid()

Usage

Arguments

Method resetMabGrid()

Usage

Method getMab()

Usage

Method downloadPublicationData()

Usage

Arguments

Method refresh()

Usage

Method clone()

Usage

Arguments

See Also

Examples

The DataSpaceMab class

Description

Constructor

Active bindings

Methods

Public methods

Method new()

Usage

Arguments

Method print()

Usage

Method refresh()

Usage

Method getLanlMetadata()

Usage

Method clone()

Usage

Arguments

See Also

Examples

The DataSpaceStudy class

Description

Constructor

Method `new()`

Method `print()`

Method `getStudy()`

Method `getGroup()`

Method `filterMabGrid()`

Method `resetMabGrid()`

Method `getMab()`

Method `downloadPublicationData()`

Method `refresh()`

Method `clone()`

Method `new()`

Method `print()`

Method `refresh()`

Method `getLanlMetadata()`

Method `clone()`

Method `new()`

Method `print()`

Method `getDataset()`

Method `clearCache()`

Method `getDatasetDescription()`

Method `setDataDir()`

Method `refresh()`

Method `clone()`