ImmuneSpaceConnection: The ImmuneSpaceConnection class

In RGLab/ImmuneSpaceR: A Thin Wrapper around the ImmuneSpace Data and Tools Portal

The ImmuneSpaceConnection class

Description

A connection respresents a study or a set of studies available on ImmuneSpace. It provides function to download and display the data within these studies.

Details

The ImmuneSpaceConnection will initialize itself, and look for a .netrc file in "~/" the user's home directory. The .netrc file should contain a machine, login, and password entry to allow access to ImmuneSpace, where machine is the host name like "datatools.immunespace.org".

It can also use global variables labkey.url.base, and labkey.url.path, to access a study. labkey.url.base should be https://datatools.immunespace.org/. labkey.url.path should be /Studies/studyname, where 'studyname' is the accession number of the study.

Value

An instance of an ImmuneSpaceConnection for a study in labkey.url.path.

Constructor

CreateConnection

Fields

study

A character. The study accession number. Use an empty string ("") to create a connection at the project level.

availableDatasets

A data.table. The table of datasets available in the connection object.

cache

A list. Stores the data to avoid downloading the same tables multiple times.

config

A list. Stores configuration of the connection object such as URL, path and username.

Methods

initialize()

Initialize ImmuneSpaceConnection class. See CreateConnection.

print()

Print ImmuneSpaceConnection class.

listDatasets(output = c("datasets", "expression"))

Lists the datasets available in the study or studies of the connection.

listGEMatrices(verbose = FALSE, reload = FALSE, participantIds = NULL)

Lists available gene expression matrices for the connection.

verbose: A logical. If TRUE, whether to print the extra details for troubleshooting.

reload: A logical. If TRUE, retrieve the table of available gene expression matrices whether a cached version exist or not.

participantIds: A character vector of participant ids to filter by. Only matrices with data from participantIds will be returned. If NULL, all matrices are returned.

listGEAnalysis()

Lists available gene expression analysis for the connection.

listParticipantGroups()

Lists available participant groups on the ImmuneSpace portal.

listParticipantGEMatrices(group, verbose = FALSE)

Lists available gene expression matrices for participants in group.

group: A character or integer. Call con$listParticipantGroups() to see available participants groups. Use group_id or group_name as input.

verbose: A logical. If TRUE, whether to print the extra details for troubleshooting.

listWorkspaces(reload = FALSE)

Lists available workspaces for the connection.

reload: A logical. If TRUE, download the table whether a cached version exist or not.

listGatingSets(reload = FALSE)

Lists available gating sets for the connection.

reload: A logical. If TRUE, download the table whether a cached version exist or not.

summarizeCyto()

Prints a summary of cytometry data for the connection.

summarizeGatingSet(gatingSet)

Prints a summary of a gating set. Note that this method currently works only in the ImmuneSpace RStudio session.

gatingSet: A character. The name of the gating set to summarize.

loadGatingSet(gatingSet)

Loads a gating set via flowWorkspace::load_gs to the current environment. Note that this method currently works only in the ImmuneSpace RStudio Docker session.

gatingSet: A character. The name of the gating set to load.

getDataset(x, original_view = FALSE, reload = FALSE, colFilter = NULL, ...)

Get a dataset form the connection.

x: A character. The name of the dataset to download.

original_view: A logical. If TRUE, download the original ImmPort view; else, download the default grid view.

reload: A logical. If TRUE, download the dataset whether a cached version exist or not.

colFilter: A character. A filter as returned by Rlabkey's makeFilter function.

...: Extra arguments to be passed to labkey.selectRows.

getGEMatrix(matrixName = NULL, cohortType = NULL, outputType = "summary", annotation = "latest", reload = FALSE, verbose = FALSE)

Downloads a probe-level or gene-symbol summarized expression matrix from ImmuneSpace and constructs an ExpressionSet. Use experimentData() on the resulting ExpressionSet object to see version info for annotation.

matrixName: A character. The name of the gene expression matrix to download.

cohortType: A character. The name of a cohortType that has an associated gene expression matrix. Note that if this argument is not NULL, then matrixName is ignored. CohortType is a concatenation of "cohort" and "cell type" that allows the user to specify a matrix for the cell type subset of a cohort.

outputType: A character. one of 'raw', 'normalized' or 'summary'. If 'raw', returns an expression matrix of non-normalized values by probe. 'normalized' returns normalized values by probe. 'summary' returns normalized values averaged by gene symbol.

annotation: A character. one of 'default', 'latest', or 'ImmSig'. Determines which feature annotation set (FAS) is used. 'default' uses the FAS from when the matrix was generated. latest' uses a recently updated FAS based on the original. 'ImmSig' is specific to studies involved in the ImmuneSignatures project and uses the annotation from when the meta-study's manuscript was created.

reload: A logical. If set to TRUE, the matrix will be downloaded again, even if a cached copy exists in the ImmuneSpaceConnection object.

verbose: A logical. If set to TRUE, notes on how the expressionSet object was created will be printed, including normalization, summarization, feature_annotation_set, and alias2symbol mapping version of org.Hs.eg.db.

getGEAnalysis(...)

Downloads data from the gene expression analysis results table.

...: A list of arguments to be passed to labkey.selectRows.

getGEInputs()

Downloads data from the gene expression input samples table.

getParticipantData(group, dataType, original_view = FALSE, ...)

Returns a data.table with data subset by participant group.

group: A character or integer. Call con$listParticipantGroups() to see available participants groups. Use group_id or group_name as input.

dataType: A character. Use con$availableDatasets to see available dataset names.

getParticipantGEMatrix(group, outputType = "summary", annotation = "latest", reload = FALSE)

Downloads probe-level or gene-symbol summarized expression matrices for all participants within group from ImmuneSpace and constructs an ExpressionSet containing observations for each participant in group where gene expression data is available.

group: A character or integer. Call con$listParticipantGroups() to see available participants groups. Use group_id or group_name as input.

outputType: A character. one of 'raw', 'normalized' or 'summary'. If 'raw', returns an expression matrix of non-normalized values by probe. 'normalized' returns normalized values by probe. 'summary' returns normalized values averaged by gene symbol.

annotation: A character. one of 'default', 'latest', or 'ImmSig'. Determines which feature annotation set (FAS) is used. 'default' uses the FAS from when the matrix was generated. latest' uses a recently updated FAS based on the original. 'ImmSig' is specific to studies involved in the ImmuneSignatures project and uses the annotation from when the meta-study's manuscript was created.

reload: A logical. If set to TRUE, matrices will be downloaded again, even if a cached copy exists in the ImmuneSpaceConnection object.

downloadGEFiles(files, destdir = ".")

Downloads gene expression raw data files.

files: A character. Filenames as shown on the gene_expression_files dataset.

destdir: A character. The local path to store the downloaded files.

addTreatment(expressionSet)

Adds treatment information to the phenoData of an ExpressionSet.

expressionSet: An ExpressionSet. The ExpressionSet object that has been downloaded from the connection.

mapSampleNames(EM = NULL, colType = "participant_id")

Changes the sampleNames of an ExpressionSet fetched by getGEMatrix using the information in the phenodData slot.

EM: An ExpressionSet, as returned by getGEMatrix.

colType: A character. The type of column names. Valid options are 'expsample_accession' and 'participant_id'.

plot(...)

Visualizes a selected dataset. This method is used by the DataExplorer module on the ImmuneSpace portal.

dataset: A character. The name of the dataset to plot, as displayed by the listDataset method.

normalize_to_baseline: A logical. If TRUE, the values are plotted as log2 fold-change from baseline.

type: A character. The type of plot. Valid choices are 'auto', 'heatmap', 'boxplot', 'lineplot', 'violinplot'. If set to 'auto', the function will select an appropriate plot type for the selected data.

filter: A filter as created by the makeFilter function from Rlabkey.

facet: The facetting for ggplot2 based plots. Valid choices are 'grid' and 'wrap'.

text_size: The size of all text elements in the plot.

legend: A character. Columns of the dataset or demographics to be added as legend on the heatmap. This argument is ignored if the plot type isn't heatmap.

show_virus_strain: A logical. Should all the virus strains be shown or should the values be averaged. Only used when dataset = 'hai'.

interactive: A logical. If TRUE, an interactive plot will be created. The default is FALSE.

...: Extra argument to be passed to ggplot. e.g: shape = 'Age', color = 'Race'.

clearCache()

Clears the cache. Removes downloaded datasets and expression matrices.

Methods

Public methods

• ISCon$listWorkspaces()

• ISCon$listGatingSets()

• ISCon$summarizeCyto()

• ISCon$summarizeGatingSet()

• ISCon$loadGatingSet()

• ISCon$listDatasets()

• ISCon$getDataset()

• ISCon$listGEMatrices()

• ISCon$listGEAnalysis()

• ISCon$getGEMatrix()

• ISCon$getGEAnalysis()

• ISCon$getGEInputs()

• ISCon$getGEFiles()

• ISCon$downloadGEFiles()

• ISCon$addTreatment()

• ISCon$mapSampleNames()

• ISCon$listParticipantGroups()

• ISCon$getParticipantData()

• ISCon$listParticipantGEMatrices()

• ISCon$getParticipantGEMatrix()

• ISCon$plot()

• ISCon$print()

• ISCon$clearCache()

• ISCon$new()

• ISCon$clone()

---

Method listWorkspaces()

Usage

ISCon$listWorkspaces(reload = FALSE)

---

Method listGatingSets()

Usage

ISCon$listGatingSets(reload = FALSE)

---

Method summarizeCyto()

Usage

ISCon$summarizeCyto()

---

Method summarizeGatingSet()

Usage

ISCon$summarizeGatingSet(gatingSet)

---

Method loadGatingSet()

Usage

ISCon$loadGatingSet(gatingSet)

---

Method listDatasets()

Usage

ISCon$listDatasets(output = c("datasets", "expression"))

---

Method getDataset()

Usage

ISCon$getDataset(
  x,
  original_view = FALSE,
  reload = FALSE,
  colFilter = NULL,
  transformMethod = "none",
  ...
)

---

Method listGEMatrices()

Usage

ISCon$listGEMatrices(verbose = FALSE, reload = FALSE, participantIds = NULL)

---

Method listGEAnalysis()

Usage

ISCon$listGEAnalysis()

---

Method getGEMatrix()

Usage

ISCon$getGEMatrix(
  matrixName = NULL,
  cohortType = NULL,
  outputType = "summary",
  annotation = "latest",
  reload = FALSE,
  verbose = FALSE
)

---

Method getGEAnalysis()

Usage

ISCon$getGEAnalysis(...)

---

Method getGEInputs()

Usage

ISCon$getGEInputs()

---

Method getGEFiles()

Usage

ISCon$getGEFiles(files, destdir = ".", quiet = FALSE)

---

Method downloadGEFiles()

Usage

ISCon$downloadGEFiles(files, destdir = ".")

---

Method addTreatment()

Usage

ISCon$addTreatment(expressionSet)

---

Method mapSampleNames()

Usage

ISCon$mapSampleNames(EM = NULL, colType = "participant_id")

---

Method listParticipantGroups()

Usage

ISCon$listParticipantGroups()

---

Method getParticipantData()

Usage

ISCon$getParticipantData(
  group,
  dataType,
  original_view = FALSE,
  reload = FALSE,
  colFilter = NULL,
  transformMethod = "none",
  ...
)

---

Method listParticipantGEMatrices()

Usage

ISCon$listParticipantGEMatrices(group, verbose = FALSE)

---

Method getParticipantGEMatrix()

Usage

ISCon$getParticipantGEMatrix(
  group,
  outputType = "summary",
  annotation = "latest",
  reload = FALSE
)

---

Method plot()

Usage

ISCon$plot(...)

---

Method print()

Usage

ISCon$print()

---

Method clearCache()

Usage

ISCon$clearCache()

---

Method new()

Usage

ISCon$new(
  study = NULL,
  login = NULL,
  password = NULL,
  verbose = FALSE,
  onTest = FALSE
)

---

Method clone()

The objects of this class are cloneable with this method.

Usage

ISCon$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.

See Also

CreateConnection ImmuneSpaceR-package

Examples

## Not run: 
# Create a connection (Initiate a ImmuneSpaceConnection object)
sdy269 <- CreateConnection("SDY269")

# Print the connection object
sdy269

# Retrieve the HAI dataset
HAI <- sdy269$getDataset("hai")

# Fetch a summarized gene expresssion matrix with latest annotation
LAIV <- sdy269$getGEMatrix("LAIV_2008")

# Visualize the ELISA dataset
sdy269$plot("elisa")

## End(Not run)

sdy <- try(CreateConnection("SDY269"))
if (inherits(sdy, "try-error")) {
  warning("Read the Introduction vignette for more information on how to set
up a .netrc file.")
}

RGLab/ImmuneSpaceR documentation built on Jan. 5, 2023, 10:24 a.m.