curatedTBData 1.0.0
if (!requireNamespace("BiocManager", quietly = TRUE))
install.packages("BiocManager")
BiocManager::install("curatedTBData")library(curatedTBData)
library(dplyr)
library(SummarizedExperiment)
library(sva)The DataSummary table summarized the list of available studies and
their metadata information contained in the curatedTBData package.
The table helps users to query avialable datasets quickly.
# Remove GeographicalRegion, Age, DiagnosisMethod, Notes, Tissue, HIVStatus for concise display
data("DataSummary", package = "curatedTBData")
DataSummary |>
dplyr::select(-c(GeographicalRegion, Age, DiagnosisMethod, Notes,
Tissue, HIVStatus)) |>
DT::datatable()Users can use curatedTBData() function to access data.
There are three arguments in the function.
The first argument study_name represents the names of the data that are used
to determine the resources of interests.
Users can find all available resource names from DataSummary$Study.
The second argument dry.run enables users to determine the resources’s
availability before actually downloading them.
When dry.run is set to TRUE, the output includes names of the resources.
The third argument curated.only allows the users to access
the curated ready-to-use data.
If curated.only is TRUE, the function only download the curated
gene expression profile and the clinical annotation of the corresponding data.
If curated.only is FALSE, the function downloads all available resources
for input studies.
curatedTBData("GSE19439", dry.run = TRUE, curated.only = FALSE)## snapshotDate(): 2021-10-18## dry.run = TRUE, listing dataset(s) to be downloaded
## Set dry.run = FALSE to download dataset(s).## Will download the following resources for GSE19439 from the ExperimentHub:
## GSE19439_assay_raw
## GSE19439_assay_curated
## GSE19439_column_data
## GSE19439_row_data
## GSE19439_meta_dataTo download complete data for a Microarry study (e.g. GSE19439),
we set dry.run = FALSE and curated.only = FALSE.
There are two experiments assay being included in the output Microarray studies.
The first experiment is assay_curated, which is a matrix that represents
normalized, curated version of the gene expression profile.
The second experiment is assay_raw, which is a
SummarziedExperiment object that contains the raw gene expression profile and information about probe features.
GSE19439 <- curatedTBData("GSE19439", dry.run = FALSE, curated.only = FALSE)## snapshotDate(): 2021-10-18## Downloading: GSE19439##
|
| | 0%
|
|============== | 20%
|
|============================ | 40%
|
|========================================== | 60%
|
|======================================================== | 80%
|
|======================================================================| 100%## Finished!GSE19439## $GSE19439
## A MultiAssayExperiment object of 2 listed
## experiments with user-defined names and respective classes.
## Containing an ExperimentList class object of length 2:
## [1] assay_curated: matrix with 25417 rows and 42 columns
## [2] object_raw: SummarizedExperiment with 48803 rows and 42 columns
## Functionality:
## experiments() - obtain the ExperimentList instance
## colData() - the primary/phenotype DataFrame
## sampleMap() - the sample coordination DataFrame
## `$`, `[`, `[[` - extract colData columns, subset, or experiment
## *Format() - convert into a long or wide DataFrame
## assays() - convert ExperimentList to a SimpleList of matrices
## exportClass() - save data to flat filesWhen accessing data for RNA sequencing studies, another assay called
assay_reprocess is included. This matrix represents the reprocessed version
of gene expression profile from the raw .fastq files using
Rsubread.
GSE79362 <- curatedTBData("GSE79362", dry.run = FALSE, curated.only = FALSE)## snapshotDate(): 2021-10-18## Downloading: GSE79362##
|
| | 0%
|
|============ | 17%
|
|======================= | 33%
|
|=================================== | 50%
|
|=============================================== | 67%
|
|========================================================== | 83%
|
|======================================================================| 100%## Finished!GSE79362## $GSE79362
## A MultiAssayExperiment object of 3 listed
## experiments with user-defined names and respective classes.
## Containing an ExperimentList class object of length 3:
## [1] assay_curated: matrix with 13419 rows and 355 columns
## [2] assay_reprocess_hg19: matrix with 25369 rows and 355 columns
## [3] object_raw: SummarizedExperiment with 134866 rows and 355 columns
## Functionality:
## experiments() - obtain the ExperimentList instance
## colData() - the primary/phenotype DataFrame
## sampleMap() - the sample coordination DataFrame
## `$`, `[`, `[[` - extract colData columns, subset, or experiment
## *Format() - convert into a long or wide DataFrame
## assays() - convert ExperimentList to a SimpleList of matrices
## exportClass() - save data to flat filesA list of MultiAssayExperiment objects is returned
when dry.run is FALSE.
To save running time, in the following example, we set the curated.only = TRUE
and selected five studies that belong to GSE19491
from the Gene Expression Omnibus.
myGEO <- c("GSE19435", "GSE19439", "GSE19442", "GSE19444", "GSE22098")
object_list <- curatedTBData(myGEO, dry.run = FALSE, curated.only = TRUE)## snapshotDate(): 2021-10-18## curated.only = TRUE. Download curated version.
## Set curated.only = FALSE if want to download both raw and curated data.## Downloading: GSE19435## Downloading: GSE19439## Downloading: GSE19442## Downloading: GSE19444## Downloading: GSE22098## Finished!object_list[1:2]## $GSE19435
## A MultiAssayExperiment object of 1 listed
## experiment with a user-defined name and respective class.
## Containing an ExperimentList class object of length 1:
## [1] assay_curated: matrix with 25417 rows and 33 columns
## Functionality:
## experiments() - obtain the ExperimentList instance
## colData() - the primary/phenotype DataFrame
## sampleMap() - the sample coordination DataFrame
## `$`, `[`, `[[` - extract colData columns, subset, or experiment
## *Format() - convert into a long or wide DataFrame
## assays() - convert ExperimentList to a SimpleList of matrices
## exportClass() - save data to flat files
##
## $GSE19439
## A MultiAssayExperiment object of 1 listed
## experiment with a user-defined name and respective class.
## Containing an ExperimentList class object of length 1:
## [1] assay_curated: matrix with 25417 rows and 42 columns
## Functionality:
## experiments() - obtain the ExperimentList instance
## colData() - the primary/phenotype DataFrame
## sampleMap() - the sample coordination DataFrame
## `$`, `[`, `[[` - extract colData columns, subset, or experiment
## *Format() - convert into a long or wide DataFrame
## assays() - convert ExperimentList to a SimpleList of matrices
## exportClass() - save data to flat filesA full version example for RNA sequencing data: GSE79362.
GSE79362 <- curatedTBData("GSE79362", dry.run = FALSE, curated.only = FALSE)## snapshotDate(): 2021-10-18## Downloading: GSE79362## Finished!GSE79362## $GSE79362
## A MultiAssayExperiment object of 3 listed
## experiments with user-defined names and respective classes.
## Containing an ExperimentList class object of length 3:
## [1] assay_curated: matrix with 13419 rows and 355 columns
## [2] assay_reprocess_hg19: matrix with 25369 rows and 355 columns
## [3] object_raw: SummarizedExperiment with 134866 rows and 355 columns
## Functionality:
## experiments() - obtain the ExperimentList instance
## colData() - the primary/phenotype DataFrame
## sampleMap() - the sample coordination DataFrame
## `$`, `[`, `[[` - extract colData columns, subset, or experiment
## *Format() - convert into a long or wide DataFrame
## assays() - convert ExperimentList to a SimpleList of matrices
## exportClass() - save data to flat filesThe major advantage of using MultiAssayExperiment
is the coordination of the meta-data and assays when sub-setting.
The MultiAssayExperiment object has built-in function for subsetting samples
based on column condition.
The following code shows how to select samples with only active TB.
GSE19439 <- object_list$GSE19439
GSE19439[, GSE19439$TBStatus == "PTB"]["assay_curated"] # 13 samples## A MultiAssayExperiment object of 1 listed
## experiment with a user-defined name and respective class.
## Containing an ExperimentList class object of length 1:
## [1] assay_curated: matrix with 0 rows and 13 columns
## Functionality:
## experiments() - obtain the ExperimentList instance
## colData() - the primary/phenotype DataFrame
## sampleMap() - the sample coordination DataFrame
## `$`, `[`, `[[` - extract colData columns, subset, or experiment
## *Format() - convert into a long or wide DataFrame
## assays() - convert ExperimentList to a SimpleList of matrices
## exportClass() - save data to flat filesThe following example shows how to subset patients with active TB and LTBI
GSE19439[, GSE19439$TBStatus %in% c("PTB", "LTBI")]["assay_curated"] # 30 samples## A MultiAssayExperiment object of 1 listed
## experiment with a user-defined name and respective class.
## Containing an ExperimentList class object of length 1:
## [1] assay_curated: matrix with 0 rows and 30 columns
## Functionality:
## experiments() - obtain the ExperimentList instance
## colData() - the primary/phenotype DataFrame
## sampleMap() - the sample coordination DataFrame
## `$`, `[`, `[[` - extract colData columns, subset, or experiment
## *Format() - convert into a long or wide DataFrame
## assays() - convert ExperimentList to a SimpleList of matrices
## exportClass() - save data to flat filesThe combine_objects() function provides an easy implementation for
combining different studies based on common gene symbols.
The function returns a SummarizedExperiment object that contains
the merged assay and associated clinical annotation. Noticed that GSE74092 is usually
removed from merging, because it used quantitative PCR,
which did not have enough coverage to capture all genes.
There are two arguments in the combine_objects() function.
The first one is object_list, which takes a list of
MultiAssayExperiment objects obtained from curatedTBData(). Notice that the names(object_list) should not be NULL
and must be unique for each object within the list,
so that we can keep track the original study after merging.
The second argument is experiment_name, which can be a string or vector of strings representing the name of the assay from the object.
GSE19491 <- combine_objects(object_list, experiment_name = "assay_curated",
update_genes = TRUE)## "update_genes" is TRUE, updating gene symbolsGSE19491## class: SummarizedExperiment
## dim: 25076 454
## metadata(0):
## assays(1): assay1
## rownames(25076): A1BG A1CF ... ZZZ3 dJ341D10.1
## rowData names(0):
## colnames(454): GSM484368 GSM484369 ... GSM550399 GSM550400
## colData names(32): Age Gender ... StaphStatus StrepStatusWhen the objects are merged, the original individual data tag can be found
in the Study section from the metadata.
unique(GSE19491$Study)## [1] "GSE19435" "GSE19439" "GSE19442" "GSE19444" "GSE22098"It is also possible to combine the given list of objects with
different experiment names. In this case, the experiment_name is a vector of
string that corresponds to each of object from the input list.
exp <- combine_objects(c(GSE79362[1], object_list[1]),
experiment_name = c("assay_reprocess_hg19",
"assay_curated"),
update_genes = TRUE)## Found more than one "experiment_name".## "update_genes" is TRUE, updating gene symbolsexp## class: SummarizedExperiment
## dim: 18939 388
## metadata(0):
## assays(1): assay1
## rownames(18939): A1BG A1CF ... ZZEF1 ZZZ3
## rowData names(0):
## colnames(388): GSM2092905 GSM2092906 ... GSM484399 GSM484400
## colData names(31): Age Gender ... DiabetesStatus TreatmentIf datasets are merged, it is typically recommended to
remove a very likely batch effect.
We use the ComBat() function from sva to remove
potential batch effect between studies.
In the following example, each study is viewed as one batch. The batch corrected
assay will be stored in a SummarizedExperiment object.
batch1 <- colData(GSE19491)$Study
combat_edata1 <- sva::ComBat(dat = assay(GSE19491), batch = batch1)
assays(GSE19491)[["Batch_corrected_assay"]] <- combat_edata1
GSE19491## class: SummarizedExperiment
## dim: 25076 454
## metadata(0):
## assays(2): assay1 Batch_corrected_assay
## rownames(25076): A1BG A1CF ... ZZZ3 dJ341D10.1
## rowData names(0):
## colnames(454): GSM484368 GSM484369 ... GSM550399 GSM550400
## colData names(32): Age Gender ... StaphStatus StrepStatusThe function subset_curatedTBData() allows the users to subset a list of
MultiAssayExperiment with the output contains
the exact conditions given by the annotationCondition.
With subset_curatedTBData(), users can quickly subset desired results
from curatedTBData database without checking individual object.
There are four arguments in this function.
The theObject represents a MultiAssayExperiment or
SummarizedExperiment object.
The annotationColName is a character that indicates the
column name in the metadata. The annotationCondition is a character or
vector of characters that the users intend to select.
In the following example, we call subset_curatedTBData() function to
subset samples with active TB (PTB) and latent TB infection (LTBI) for
binary classification.
multi_set_PTB_LTBI <- lapply(object_list, function(x)
subset_curatedTBData(x, annotationColName = "TBStatus",
annotationCondition = c("LTBI", "PTB"),
assayName = "assay_curated"))
# Remove NULL from the list
multi_set_PTB_LTBI <- multi_set_PTB_LTBI[!sapply(multi_set_PTB_LTBI, is.null)]
multi_set_PTB_LTBI[1:3]## $GSE19439
## class: SummarizedExperiment
## dim: 25417 30
## metadata(0):
## assays(1): assay1
## rownames(25417): 7A5 A1BG ... ZZEF1 ZZZ3
## rowData names(0):
## colnames(30): GSM484448 GSM484449 ... GSM484488 GSM484489
## colData names(24): Age Gender ... DiabetesStatus QFT_GIT
##
## $GSE19442
## class: SummarizedExperiment
## dim: 25417 51
## metadata(0):
## assays(1): assay1
## rownames(25417): 7A5 A1BG ... ZZEF1 ZZZ3
## rowData names(0):
## colnames(51): GSM484500 GSM484501 ... GSM484549 GSM484550
## colData names(23): Age Gender ... isolate_sensitivity DiabetesStatus
##
## $GSE19444
## class: SummarizedExperiment
## dim: 25417 42
## metadata(0):
## assays(1): assay1
## rownames(25417): 7A5 A1BG ... ZZEF1 ZZZ3
## rowData names(0):
## colnames(42): GSM484595 GSM484596 ... GSM484645 GSM484646
## colData names(24): Age Gender ... DiabetesStatus QFT_GITThe HIV status (HIVStatus) and diabetes status (DiabetesStatus) for each
subject were also recorded for each study in the curatedTBData.
In the following example, we select subjects with HIV positive from the input.
Users can also find HIV status information for each study by
looking at the column: HIVStatus from DataSummary.
When the the length of the annotationCondition equals to 1, we can subset using
either MultiAssayExperiment built-in procedure or subset_curatedTBData.
multi_set_HIV <- lapply(object_list, function(x)
subset_curatedTBData(x, annotationColName = "HIVStatus",
annotationCondition = "Negative",
assayName = "assay_curated"))
# Remove NULL from the list
multi_set_HIV <- multi_set_HIV[!vapply(multi_set_HIV, is.null, TRUE)]
multi_set_HIV[1:3]## $GSE19435
## class: SummarizedExperiment
## dim: 25417 33
## metadata(0):
## assays(1): assay1
## rownames(25417): 7A5 A1BG ... ZZEF1 ZZZ3
## rowData names(0):
## colnames(33): GSM484368 GSM484369 ... GSM484399 GSM484400
## colData names(24): Age Gender ... DiabetesStatus Treatment
##
## $GSE19439
## class: SummarizedExperiment
## dim: 25417 42
## metadata(0):
## assays(1): assay1
## rownames(25417): 7A5 A1BG ... ZZEF1 ZZZ3
## rowData names(0):
## colnames(42): GSM484448 GSM484449 ... GSM484488 GSM484489
## colData names(24): Age Gender ... DiabetesStatus QFT_GIT
##
## $GSE19442
## class: SummarizedExperiment
## dim: 25417 51
## metadata(0):
## assays(1): assay1
## rownames(25417): 7A5 A1BG ... ZZEF1 ZZZ3
## rowData names(0):
## colnames(51): GSM484500 GSM484501 ... GSM484549 GSM484550
## colData names(23): Age Gender ... isolate_sensitivity DiabetesStatussessionInfo()## R version 4.1.1 (2021-08-10)
## Platform: x86_64-pc-linux-gnu (64-bit)
## Running under: Ubuntu 20.04.3 LTS
##
## Matrix products: default
## BLAS: /home/biocbuild/bbs-3.14-bioc/R/lib/libRblas.so
## LAPACK: /home/biocbuild/bbs-3.14-bioc/R/lib/libRlapack.so
##
## locale:
## [1] LC_CTYPE=en_US.UTF-8 LC_NUMERIC=C
## [3] LC_TIME=en_GB 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] stats4 stats graphics grDevices utils datasets methods
## [8] base
##
## other attached packages:
## [1] sva_3.42.0 BiocParallel_1.28.0
## [3] genefilter_1.76.0 mgcv_1.8-38
## [5] nlme_3.1-153 SummarizedExperiment_1.24.0
## [7] Biobase_2.54.0 GenomicRanges_1.46.0
## [9] GenomeInfoDb_1.30.0 IRanges_2.28.0
## [11] S4Vectors_0.32.0 BiocGenerics_0.40.0
## [13] MatrixGenerics_1.6.0 matrixStats_0.61.0
## [15] dplyr_1.0.7 curatedTBData_1.0.0
## [17] BiocStyle_2.22.0
##
## loaded via a namespace (and not attached):
## [1] bitops_1.0-7 bit64_4.0.5
## [3] filelock_1.0.2 httr_1.4.2
## [5] tools_4.1.1 bslib_0.3.1
## [7] utf8_1.2.2 R6_2.5.1
## [9] DT_0.19 DBI_1.1.1
## [11] withr_2.4.2 tidyselect_1.1.1
## [13] bit_4.0.4 curl_4.3.2
## [15] compiler_4.1.1 DelayedArray_0.20.0
## [17] bookdown_0.24 sass_0.4.0
## [19] rappdirs_0.3.3 stringr_1.4.0
## [21] digest_0.6.28 rmarkdown_2.11
## [23] XVector_0.34.0 pkgconfig_2.0.3
## [25] htmltools_0.5.2 dbplyr_2.1.1
## [27] fastmap_1.1.0 limma_3.50.0
## [29] htmlwidgets_1.5.4 rlang_0.4.12
## [31] RSQLite_2.2.8 shiny_1.7.1
## [33] jquerylib_0.1.4 generics_0.1.1
## [35] jsonlite_1.7.2 crosstalk_1.1.1
## [37] RCurl_1.98-1.5 magrittr_2.0.1
## [39] GenomeInfoDbData_1.2.7 Matrix_1.3-4
## [41] Rcpp_1.0.7 fansi_0.5.0
## [43] lifecycle_1.0.1 stringi_1.7.5
## [45] yaml_2.2.1 edgeR_3.36.0
## [47] zlibbioc_1.40.0 BiocFileCache_2.2.0
## [49] AnnotationHub_3.2.0 grid_4.1.1
## [51] blob_1.2.2 parallel_4.1.1
## [53] promises_1.2.0.1 ExperimentHub_2.2.0
## [55] crayon_1.4.1 lattice_0.20-45
## [57] Biostrings_2.62.0 splines_4.1.1
## [59] annotate_1.72.0 KEGGREST_1.34.0
## [61] locfit_1.5-9.4 knitr_1.36
## [63] pillar_1.6.4 XML_3.99-0.8
## [65] glue_1.4.2 BiocVersion_3.14.0
## [67] evaluate_0.14 BiocManager_1.30.16
## [69] MultiAssayExperiment_1.20.0 png_0.1-7
## [71] vctrs_0.3.8 httpuv_1.6.3
## [73] purrr_0.3.4 assertthat_0.2.1
## [75] cachem_1.0.6 xfun_0.27
## [77] mime_0.12 xtable_1.8-4
## [79] later_1.3.0 survival_3.2-13
## [81] tibble_3.1.5 AnnotationDbi_1.56.1
## [83] memoise_2.0.0 HGNChelper_0.8.1
## [85] ellipsis_0.3.2 interactiveDisplayBase_1.32.0