1 Introduction

orthosData is the companion database to the orthos software for mechanistic studies using differential gene expression experiments.

It currently encompasses data for over 100,000 differential gene expression mouse and human experiments distilled and compiled from the ARCHS4 database (Lachmann et al., 2018) of uniformly processed RNAseq experiments as well as associated pre-trained variational models.

Together with orthos it was developed to provide a better understanding of the effects of experimental treatments on gene expression and to help map treatments to mechanisms of action.

This vignette provides information on the orhosData functions for retrieval from ExperimentHub and local caching of the models and datasets used internally in orthos.

For more information on usage of these models and datasets for analysis purposes please refer to the orthos package documentation.

2 Installation and overview

orthosData is automatically installed as a dependency during orthos installation. orthosData can also be installed independently from Bioconductor using BiocManager::install():

if (!requireNamespace("BiocManager", quietly = TRUE))
    install.packages("BiocManager")
BiocManager::install("orthosData")
# or also...
BiocManager::install("orthosData", dependencies = TRUE)

After installation, the package can be loaded with:

library(orthosData)

3 Caching orthosData models with GetorthosModels()

GetorthosModels() is the function for local caching of orthosData Keras models for a given organism.

These are the models required to perform inference in orthos.

For each organism they are of three types:

  • ContextEncoder: The encoder component of a context Variational Autoencoder (VAE). Used to produce a latent encoding of a given gene expression profile (i.e context).

    • Input is a gene expression matrix (shape= M x N , where M is the number of condition and N is the number of orthos gene features) in the form of log2-transformed library normalized counts (log2 counts per million, log2CPMs).

    • Output is an M x d (where d=64) latent representation of the context.

  • DeltaEncoder: The encoder component of a contrast conditional Variational Autoencoder (cVAE). Used to produce a latent encoding of a contrast between two conditions (i.e delta).

    • Input is a matrix of gene expression contrasts (shape= M x N ) in the form of gene log2 CPM ratios (log2 fold changes, log2FCs), concatenated with the corresponding context encoding.

    • Output is an M x d (where d=512) latent representation of the contrast, conditioned on the context.

  • DeltaDecoder: The decoder component of the same cVAE as above. Used to produce the decoded version of the contrast between two conditions.

    • Input is the concatenated matrix (shape= M x (N+d) ) of the delta and context latent encodings.

    • Output is the decoded contrast matrix (shape= M x N), conditioned on the context.

For more details on model architecture and use of these models in orthos please refer to the orthos package vignette.

When called for a specific organism, GetorthosModels() downloads the corresponding set of models required for inference from ExperimentHub and caches them in the user ExperimentHub directory (see ExperimentHub::getExperimentHubOption("CACHE"))

# Check the path to the user's ExperimentHub directory:
ExperimentHub::getExperimentHubOption("CACHE")
# Download and cache the models for a specific organism:
GetorthosModels(organism = "Mouse")

4 Cache an orthosData contrast DB with GetorthosContrastDB()

The orthosData contrast database contains differential gene expression experiments compiled from the ARCHS4 database of publicly available expression data. Each entry in the database corresponds to a pair of RNAseq samples contrasting a treatment versus a control condition. A combination of metadata-semantic and quantitative analyses was used to determine the proper assignment of samples to such pairs in orthosData.

The database includes assays with the original contrasts in the form of gene expression log2 CPM ratios (i.e log2 fold changes, log2FCs), precalculated, decoded and residual components of those contrasts using the orthosData models as well as the gene expression context of those contrasts in the form of log2-transformed library normalized counts (i.e log2 counts per million, log2CPMs). It also contains extensive annotation on both the orthos feature genes and the contrasted conditions.

For each organism the DB has been compiled as an HDF5SummarizedExperiment with an HDF5 component that contains the gene assays and an rds component that contains gene annotation in the rowData and the contrast annotation in the colData.

Note that because of the way that HDF5 datasets and serialized SummarizedExperiments are linked in an HDF5SummarizedExperiment, the two components -although relocatable- need to have the exact same filenames as those used at creation time (see HDF5Array::saveHDF5SummarizedExperiment). In other words the files can be moved (or copied) to a different directory or to a different machine and they will retain functionality as long as both live in the same directory and are never renamed.

When GetorthosContrastDB() is called for a specific organism the corresponding HDF5SummarizedExperiment is downloaded from ExperimentHub and cached in the user ExperimentHub directory (see ExperimentHub::getExperimentHubOption("CACHE")).

# Check the path to the user's ExperimentHub directory:
ExperimentHub::getExperimentHubOption("CACHE")

# Download and cache the contrast database for a specific organism.
# Note: mode="DEMO" caches a small "toy" database for the queries for demonstration purposes 
# To download the full db use mode = "ANALYSIS" (this is time and space consuming)
GetorthosContrastDB(organism = "Mouse", mode="DEMO")

# Load the HDF5SummarizedExperiment: 
se <- HDF5Array::loadHDF5SummarizedExperiment(dir = ExperimentHub::getExperimentHubOption("CACHE"),
prefix = "mouse_v212_NDF_c100_DEMO")

Session information

sessionInfo()
#> R Under development (unstable) (2023-10-22 r85388)
#> Platform: x86_64-pc-linux-gnu
#> Running under: Ubuntu 22.04.3 LTS
#> 
#> Matrix products: default
#> BLAS:   /home/biocbuild/bbs-3.19-bioc/R/lib/libRblas.so 
#> LAPACK: /usr/lib/x86_64-linux-gnu/lapack/liblapack.so.3.10.0
#> 
#> 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       
#> 
#> time zone: America/New_York
#> tzcode source: system (glibc)
#> 
#> attached base packages:
#> [1] stats     graphics  grDevices utils     datasets  methods   base     
#> 
#> other attached packages:
#> [1] orthosData_1.1.0 knitr_1.44       BiocStyle_2.31.0
#> 
#> loaded via a namespace (and not attached):
#>  [1] tidyselect_1.2.0              dplyr_1.1.3                  
#>  [3] blob_1.2.4                    filelock_1.0.2               
#>  [5] Biostrings_2.71.1             bitops_1.0-7                 
#>  [7] fastmap_1.1.1                 RCurl_1.98-1.12              
#>  [9] BiocFileCache_2.11.0          promises_1.2.1               
#> [11] digest_0.6.33                 mime_0.12                    
#> [13] lifecycle_1.0.3               ellipsis_0.3.2               
#> [15] KEGGREST_1.43.0               interactiveDisplayBase_1.41.0
#> [17] RSQLite_2.3.1                 magrittr_2.0.3               
#> [19] compiler_4.4.0                rlang_1.1.1                  
#> [21] sass_0.4.7                    tools_4.4.0                  
#> [23] utf8_1.2.4                    yaml_2.3.7                   
#> [25] S4Arrays_1.3.0                bit_4.0.5                    
#> [27] curl_5.1.0                    DelayedArray_0.29.0          
#> [29] abind_1.4-5                   HDF5Array_1.31.0             
#> [31] BiocGenerics_0.49.0           grid_4.4.0                   
#> [33] stats4_4.4.0                  fansi_1.0.5                  
#> [35] ExperimentHub_2.11.0          xtable_1.8-4                 
#> [37] Rhdf5lib_1.25.0               SummarizedExperiment_1.33.0  
#> [39] cli_3.6.1                     rmarkdown_2.25               
#> [41] crayon_1.5.2                  generics_0.1.3               
#> [43] httr_1.4.7                    DBI_1.1.3                    
#> [45] cachem_1.0.8                  rhdf5_2.47.0                 
#> [47] stringr_1.5.0                 zlibbioc_1.49.0              
#> [49] AnnotationDbi_1.65.0          BiocManager_1.30.22          
#> [51] XVector_0.43.0                matrixStats_1.0.0            
#> [53] vctrs_0.6.4                   Matrix_1.6-1.1               
#> [55] jsonlite_1.8.7                bookdown_0.36                
#> [57] IRanges_2.37.0                S4Vectors_0.41.0             
#> [59] bit64_4.0.5                   fontawesome_0.5.2            
#> [61] jquerylib_0.1.4               glue_1.6.2                   
#> [63] stringi_1.7.12                BiocVersion_3.19.0           
#> [65] later_1.3.1                   GenomeInfoDb_1.39.0          
#> [67] GenomicRanges_1.55.0          tibble_3.2.1                 
#> [69] pillar_1.9.0                  rappdirs_0.3.3               
#> [71] htmltools_0.5.6.1             rhdf5filters_1.15.0          
#> [73] GenomeInfoDbData_1.2.11       R6_2.5.1                     
#> [75] dbplyr_2.4.0                  evaluate_0.22                
#> [77] shiny_1.7.5.1                 Biobase_2.63.0               
#> [79] lattice_0.22-5                AnnotationHub_3.11.0         
#> [81] png_0.1-8                     memoise_2.0.1                
#> [83] httpuv_1.6.12                 bslib_0.5.1                  
#> [85] Rcpp_1.0.11                   SparseArray_1.3.0            
#> [87] xfun_0.40                     MatrixGenerics_1.15.0        
#> [89] pkgconfig_2.0.3

5 References

Appendix

  1. Lachmann, Alexander, et al. “Massive mining of publicly available RNA-seq data from human and mouse.” Nature communications 9.1 (2018): 1366