Downloading expression matrices using ImmuneSpaceR

Renan Sauteraud

2017-04-24

This vignette shows detailed examples for the getGEMatrix function.

Contents

  1. Connections
  2. List the expression matrices
  3. Download an expression matrix
  4. Summarized matrices
  5. Combining matrices
  6. Caching
  7. sessionInfo

Connections

As explained into the user guide vignette, datasets must be downloaded from ImmuneSpaceConnection objects. We must first instantiate a connection to the study or studies of interest. Throughout this vignette, we will use two connections, one to a single study, and one to to all available data.

library(ImmuneSpaceR)
sdy269 <- CreateConnection("SDY269")
all <- CreateConnection("")

List the expression matrices

Now that the connections have been instantiated, we can start downloading from them. But we need to figure out which processed matrices are available within our chosen studies.

On www.immunespace.org, in the study of interest or at the project level, the Gene expression matrices table will show the available runs.

Printing the connections will, among other information, list the datasets availables. The listDatasets method will only display the downloadable data. looking for. With which = "expression", the datasets wont be printed.

sdy269$listDatasets()
## datasets
##  cohort_membership
##  pcr
##  elisa
##  fcs_analyzed_result
##  fcs_sample_files
##  hai
##  elispot
##  demographics
##  gene_expression_files
## Expression Matrices
##  TIV_2008
##  LAIV_2008

Using wich = "expression", we can remove the datasets from the output.

all$listDatasets(which = "expression")
## Expression Matrices
##  TIV_older
##  SDY296_AIRFV_2011
##  LAIV_2008
##  TIV_2008
##  TIV_2007
##  pH1N1_2009
##  TIV_young
##  SDY63_older_PBMC_year1
##  SDY63_young_PBMC_year1
##  SDY404_older_PBMC_year2
##  SDY404_young_PBMC_year2
##  Cohort1_young
##  Cohort2_older
##  TIV_2011
##  Pneumovax23_group1
##  Fluzone_group1
##  Fluzone_group2
##  Pneumovax23_group2
##  Saline_group1
##  Saline_group2
##  VLminus
##  VLplus
##  TIV_2010
##  SDY301_AIRFV_2012

Naturally, all contains every processed matrices available on ImmuneSpace as it combines all available studies.

Back to top

Download

By run name

The getGEMatrix function will accept any of the run names listed in the connection.

TIV_2008 <- sdy269$getGEMatrix("TIV_2008")
## Downloading matrix..
## Downloading Features..
## Constructing ExpressionSet
TIV_2011 <- all$getGEMatrix(x = "TIV_2011")
## Downloading matrix..
## Downloading Features..
## Constructing ExpressionSet

The matrices are returned as ExpressionSet where the phenoData slot contains basic demographic information and the featureData slot shows a mapping of probe to official gene symbols.

TIV_2008
## ExpressionSet (storageMode: lockedEnvironment)
## assayData: 54715 features, 80 samples 
##   element names: exprs 
## protocolData: none
## phenoData
##   sampleNames: BS586131 BS586187 ... BS586267 (80 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:

By cohort

The cohort argument can be used in place of the run name (x). Likewise, the list of valid cohorts can be found in the Gene expression matrices table.

LAIV_2008 <- sdy269$getGEMatrix(cohort = "LAIV group 2008")
## Downloading matrix..
## Constructing ExpressionSet

Note that when cohort is used, x is ignored.

Back to top

Summarized matrices

By default, the returned ExpressionSets have probe names as features (or rows). However, multiple probes often match the same gene and merging experiments from different arrays is impossible at feature level. When they are available, the summary argument allows to return the matrices with gene symbols instead of probes.

TIV_2008_sum <- sdy269$getGEMatrix("TIV_2008", summary = TRUE)
## Downloading matrix..
## Constructing ExpressionSet

Probes that do not map to a unique gene are removed and expression is averaged by gene.

TIV_2008_sum
## ExpressionSet (storageMode: lockedEnvironment)
## assayData: 16910 features, 80 samples 
##   element names: exprs 
## protocolData: none
## phenoData
##   sampleNames: BS586131 BS586187 ... BS586267 (80 total)
##   varLabels: biosample_accession participant_id ...
##     study_time_collected_unit (5 total)
##   varMetadata: labelDescription
## featureData
##   featureNames: DDR1 RFC2 ... NUS1P3 (16910 total)
##   fvarLabels: FeatureId gene_symbol
##   fvarMetadata: labelDescription
## experimentData: use 'experimentData(object)'
## Annotation:

Back to top

Combining matrices

In order to faciliate analysis across experiments and studies, when multiple runs or cohorts are specified, getGEMatrix will attempt to combine the selected expression matrices into a single ExpressionSet.

To avoid returning an empty object, it is usually recommended to use the summarized version of the matrices, thus combining by genes. This is almost always necessary when combining data from multiple studies.

# Within a study
em269 <- sdy269$getGEMatrix(c("TIV_2008", "LAIV_2008"))
## Downloading matrix..
## Downloading matrix..
## Constructing ExpressionSet
## Constructing ExpressionSet
## Combining ExpressionSets
# Combining accross studies
TIV_seasons <- all$getGEMatrix(c("TIV_2008", "TIV_2011"), summary = TRUE)
## Downloading matrix..
## Downloading matrix..
## Constructing ExpressionSet
## Constructing ExpressionSet
## Combining ExpressionSets

Caching

As explained in the user guide, the ImmuneSpaceConnection class is a Reference class. It means its objects have fields accessed by reference. As a consequence, they can be modified without making a copy of the entire object. ImmuneSpaceR uses this feature to store downloaded datasets and expression matrices. Subsequent calls to getGEMatrix with the same input will be faster.

See ?setRefClass for more information about reference classes.

We can see a list of already downloaded runs and feature sets the data_cache field. This is not intended to be used for data manipulation and only displayed here to explain what gets cached.

names(sdy269$data_cache)
## [1] "GE_matrices"   "featureset_18" "TIV_2008_sum"  "TIV_2008"     
## [5] "LAIV_2008"

If, for any reason, a specific marix needs to be redownloaded, the reload argument will clear the cache for that specific getGEMatrix call and download the file and metadata again.

TIV_2008 <- sdy269$getGEMatrix("TIV_2008", reload = TRUE)
## Downloading matrix..
## Constructing ExpressionSet

Finally, it is possible to clear every cached expression matrix (and dataset).

sdy269$clear_cache()

Again, the data.cache field should never be modified manually. When in doubt, simply reload the expression matrix.

Back to top

sessionInfo()

sessionInfo()
## R version 3.4.0 (2017-04-21)
## Platform: x86_64-apple-darwin15.6.0 (64-bit)
## Running under: OS X El Capitan 10.11.6
## 
## Matrix products: default
## BLAS: /Library/Frameworks/R.framework/Versions/3.4/Resources/lib/libRblas.0.dylib
## LAPACK: /Library/Frameworks/R.framework/Versions/3.4/Resources/lib/libRlapack.dylib
## 
## locale:
## [1] C/en_US.UTF-8/en_US.UTF-8/C/en_US.UTF-8/en_US.UTF-8
## 
## attached base packages:
## [1] stats     graphics  grDevices utils     datasets  methods   base     
## 
## other attached packages:
## [1] Rlabkey_2.1.134    rjson_0.2.15       RCurl_1.95-4.8    
## [4] bitops_1.0-6       ImmuneSpaceR_1.4.0 rmarkdown_1.4     
## [7] knitr_1.15.1      
## 
## loaded via a namespace (and not attached):
##  [1] Biobase_2.36.0      viridis_0.4.0       httr_1.2.1         
##  [4] tidyr_0.6.1         jsonlite_1.4        viridisLite_0.2.0  
##  [7] foreach_1.4.3       gtools_3.5.0        assertthat_0.2.0   
## [10] stats4_3.4.0        yaml_2.1.14         robustbase_0.92-7  
## [13] backports_1.0.5     lattice_0.20-35     digest_0.6.12      
## [16] RColorBrewer_1.1-2  colorspace_1.3-2    htmltools_0.3.5    
## [19] plyr_1.8.4          pheatmap_1.0.8      purrr_0.2.2        
## [22] mvtnorm_1.0-6       scales_0.4.1        gdata_2.17.0       
## [25] whisker_0.3-2       tibble_1.3.0        ggplot2_2.2.1      
## [28] nnet_7.3-12         BiocGenerics_0.22.0 lazyeval_0.2.0     
## [31] magrittr_1.5        mclust_5.2.3        heatmaply_0.9.1    
## [34] evaluate_0.10       MASS_7.3-47         gplots_3.0.1       
## [37] class_7.3-14        tools_3.4.0         registry_0.3       
## [40] data.table_1.10.4   trimcluster_0.1-2   stringr_1.2.0      
## [43] plotly_4.5.6        kernlab_0.9-25      munsell_0.4.3      
## [46] cluster_2.0.6       fpc_2.1-10          compiler_3.4.0     
## [49] caTools_1.17.1      grid_3.4.0          iterators_1.0.8    
## [52] htmlwidgets_0.8     labeling_0.3        base64enc_0.1-3    
## [55] gtable_0.2.0        codetools_0.2-15    flexmix_2.3-13     
## [58] DBI_0.6-1           reshape2_1.4.2      TSP_1.1-5          
## [61] R6_2.2.0            seriation_1.2-1     gridExtra_2.2.1    
## [64] prabclus_2.2-6      dplyr_0.5.0         rprojroot_1.2      
## [67] KernSmooth_2.23-15  dendextend_1.5.2    modeltools_0.2-21  
## [70] stringi_1.1.5       parallel_3.4.0      Rcpp_0.12.10       
## [73] gclus_1.3.1         DEoptimR_1.0-8      diptest_0.75-7