This package provides a thin wrapper around Rlabkey
and connects to the ImmuneSpace database, making it easier to fetch datasets, including gene expression data, hai, and so forth, from specific studies.
In order to connect to ImmuneSpace, you will need a .netrc
file in your home directory that will contain a machine
name (hostname of ImmuneSpace), and login
and password
. See here for more information.
A netrc file may look like this:
machine www.immunespace.org
login myuser@domain.com
password supersecretpassword
Put it in your home directory. If you type:
ls ~/.netrc
at the command prompt, you should see it there. If it’s not there, create one now. Make sure you have a valid login and password. If you don’t have one, go to ImmuneSpace now and set yourself up with an account.
We’ll be looking at study SDY269
. If you want to use a different study, change that string. The connections have state, so you can instantiate multiple connections to different studies simultaneously.
library(ImmuneSpaceR)
sdy269 <- CreateConnection(study = "SDY269")
sdy269
## Immunespace Connection to study SDY269
## URL: https://www.immunespace.org/Studies/SDY269
## User: unknown_user at not_a_domain.com
## Available datasets
## demographics
## pcr
## cohort_membership
## elisa
## elispot
## hai
## gene_expression_files
## fcs_analyzed_result
## fcs_sample_files
## Expression Matrices
## TIV_2008
## LAIV_2008
The call to CreateConnection
instantiates the connection Printing the object shows where it’s connected, to what study, and the available data sets and gene expression matrices.
Note that when a script is running on ImmuneSpace, some variables set in the global environments will automatically indicate which study should be used and the study
argument can be skipped.
We can grab any of the datasets listed in the connection.
sdy269$getDataset("hai")
## participant_id age_reported gender race cohort
## 1: SUB112847.269 24 Male White TIV Group 2008
## 2: SUB112860.269 32 Female White LAIV group 2008
## 3: SUB112842.269 28 Male White TIV Group 2008
## 4: SUB112859.269 32 Male White LAIV group 2008
## 5: SUB112878.269 28 Female White TIV Group 2008
## ---
## 332: SUB112866.269 34 Male White LAIV group 2008
## 333: SUB112867.269 37 Male White LAIV group 2008
## 334: SUB112883.269 23 Female Asian LAIV group 2008
## 335: SUB112848.269 39 Female White TIV Group 2008
## 336: SUB112850.269 41 Male White LAIV group 2008
## study_time_collected study_time_collected_unit
## 1: 28 Days
## 2: 0 Days
## 3: 28 Days
## 4: 0 Days
## 5: 28 Days
## ---
## 332: 0 Days
## 333: 0 Days
## 334: 28 Days
## 335: 0 Days
## 336: 28 Days
## virus value_reported
## 1: A/Uruguay/716/2007 NYMC X-175C (H3N2) 320
## 2: A/South Dakota/6/2007 (H1N1) 40
## 3: B/Brisbane/3/2007 80
## 4: A/South Dakota/6/2007 (H1N1) 5
## 5: A/Uruguay/716/2007 NYMC X-175C (H3N2) 160
## ---
## 332: A/South Dakota/6/2007 (H1N1) 40
## 333: B/Florida/4/2006 5
## 334: A/South Dakota/6/2007 (H1N1) 20
## 335: A/Brisbane/59/2007 (H1N1) 640
## 336: B/Florida/4/2006 5
The sdy269 object is an R5 class, so it behaves like a true object. Functions (like getDataset
) are members of the object, thus the $
semantics to access member functions.
The first time you retrieve a data set, it will contact the database. The data is cached locally, so the next time you call getDataset
on the same dataset, it will retrieve the cached local copy. This is much faster.
To get only a subset of the data and speed up the download, filters can be passed to getDataset
. The filters are created using the makeFilter
function of the Rlabkey
package.
library(Rlabkey)
myFilter <- makeFilter(c("gender", "EQUAL", "Female"))
hai <- sdy269$getDataset("hai", colFilter = myFilter)
See ?makeFilter
for more information on the syntax.
For more information about getDataset
’s options, refer to the dedicated vignette.
We can also grab a gene expression matrix
sdy269$getGEMatrix("LAIV_2008")
## Downloading matrix..
## Downloading Features..
## Constructing ExpressionSet
## ExpressionSet (storageMode: lockedEnvironment)
## assayData: 54715 features, 83 samples
## element names: exprs
## protocolData: none
## phenoData
## sampleNames: BS586216 BS586160 ... BS586111 (83 total)
## varLabels: biosample_accession participant_id ...
## study_time_collected_unit (5 total)
## varMetadata: labelDescription
## featureData
## featureNames: 1007_PM_s_at 1053_PM_at ... AFFX-r2-TagQ-5_at
## (54715 total)
## fvarLabels: FeatureId gene_symbol
## fvarMetadata: labelDescription
## experimentData: use 'experimentData(object)'
## Annotation:
The object contacts the DB and downloads the matrix file. This is stored and cached locally as a data.table
. The next time you access it, it will be much faster since it won’t need to contact the database again.
It is also possible to call this function using multiple matrix names. In this case, all the matrices are downloaded and combined into a single ExpressionSet
.
sdy269$getGEMatrix(c("TIV_2008", "LAIV_2008"))
## Downloading matrix..
## Downloading matrix..
## Constructing ExpressionSet
## Constructing ExpressionSet
## Combining ExpressionSets
## ExpressionSet (storageMode: lockedEnvironment)
## assayData: 54715 features, 163 samples
## element names: exprs
## protocolData: none
## phenoData
## sampleNames: BS586131 BS586187 ... BS586111 (163 total)
## varLabels: biosample_accession participant_id ...
## study_time_collected_unit (5 total)
## varMetadata: labelDescription
## featureData
## featureNames: 1 2 ... 54715 (54715 total)
## fvarLabels: FeatureId gene_symbol
## fvarMetadata: labelDescription
## experimentData: use 'experimentData(object)'
## Annotation:
Finally, the summary argument will let you download the matrix with gene symbols in place of priobe ids.
gs <- sdy269$getGEMatrix("TIV_2008", summary = TRUE)
## Downloading matrix..
## Constructing ExpressionSet
If the connection was created with verbose = TRUE
, some functions will display additional informations such as the valid dataset names.
A quick plot of a data set can be generated using the quick_plot
function.
quick_plot
automatically chooses the type of plot depending on the selected dataset.
sdy269$quick_plot("hai")
sdy269$quick_plot("elisa")
However, the type
argument can be used to manually select from “boxplot”, “heatmap”, “violin” and “line”.
To fetch data from multiple studies, simply create a connection at the project level.
con <- CreateConnection("")
This will instantiate a connection at the Studies
level. Most functions work cross study connections just like they do on single studies.
You can get a list of datasets and gene expression matrices available accross all studies.
con
## Immunespace Connection to study Studies
## URL: https://www.immunespace.org/Studies/
## User: unknown_user at not_a_domain.com
## Available datasets
## elispot
## mbaa
## hai
## elisa
## pcr
## neut_ab_titer
## fcs_analyzed_result
## gene_expression_files
## fcs_sample_files
## fcs_control_files
## cohort_membership
## demographics
## Expression Matrices
## VLplus
## Cohort2_older
## Fluzone_group1
## TIV_2007
## Fluzone_group2
## TIV_2011
## TIV_older
## Cohort1_young
## Saline_group2
## older_PBMC_year2
## TIV_2008
## TIV_young
## young_PBMC_year1
## VLminus
## pH1N1_2009
## Pneumovax23_group1
## older_PBMC_year1
## Pneumovax23_group2
## LAIV_2008
## TIV_2010
## Saline_group1
## young_PBMC_year2
In cross-study connections, getDataset
and getGEMatrix
will combine the requested datasets or expression matrices. See the dedicated vignettes for more information.
Likewise, quick_plot
will plot accross studies. Note that in most cases the datasets will have too many cohorts/subjects, making the filtering of the data a necessity. The colFilter
argument can be used here, as described in the getDataset
section.
plotFilter <- makeFilter(c("cohort", "IN", "TIV 2010;TIV Group 2008"))
con$quick_plot("elispot", filter = plotFilter)
The figure above shows the ELISPOT results for two different years of TIV vaccine cohorts from two different studies.
sessionInfo()
## R version 3.3.0 (2016-05-03)
## Platform: x86_64-pc-linux-gnu (64-bit)
## Running under: Ubuntu 14.04.4 LTS
##
## locale:
## [1] LC_CTYPE=en_US.UTF-8 LC_NUMERIC=C
## [3] LC_TIME=en_US.UTF-8 LC_COLLATE=C
## [5] LC_MONETARY=en_US.UTF-8 LC_MESSAGES=en_US.UTF-8
## [7] LC_PAPER=en_US.UTF-8 LC_NAME=C
## [9] LC_ADDRESS=C LC_TELEPHONE=C
## [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C
##
## attached base packages:
## [1] stats graphics grDevices utils datasets methods base
##
## other attached packages:
## [1] Rlabkey_2.1.129 rjson_0.2.15 RCurl_1.95-4.8
## [4] bitops_1.0-6 ImmuneSpaceR_1.0.2 rmarkdown_0.9.6
## [7] knitr_1.13
##
## loaded via a namespace (and not attached):
## [1] Rcpp_0.12.5 magrittr_1.5 BiocGenerics_0.18.0
## [4] munsell_0.4.3 colorspace_1.2-6 plyr_1.8.3
## [7] stringr_1.0.0 caTools_1.17.1 tools_3.3.0
## [10] parallel_3.3.0 grid_3.3.0 Biobase_2.32.0
## [13] data.table_1.9.6 gtable_0.2.0 KernSmooth_2.23-15
## [16] gtools_3.5.0 htmltools_0.3.5 yaml_2.1.13
## [19] digest_0.6.9 reshape2_1.4.1 RColorBrewer_1.1-2
## [22] ggplot2_2.1.0 formatR_1.4 evaluate_0.9
## [25] labeling_0.3 pheatmap_1.0.8 gdata_2.17.0
## [28] stringi_1.0-1 gplots_3.0.1 scales_0.4.0
## [31] chron_2.3-47