-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathREADME.Rmd
188 lines (144 loc) · 8.55 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r setup, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
```
# ReducedExperiment
<!-- <img src="inst/ReducedExperiment_hex.png" align="right" height="174" width="150" /> -->
<!-- badges: start -->
[](https://github.com/jackgisby/ReducedExperiment/actions/workflows/build-test-deploy.yml)
[](https://codecov.io/gh/jackgisby/ReducedExperiment)
[](https://github.com/jackgisby/ReducedExperiment/issues)
[](https://github.com/jackgisby/ReducedExperiment/pulls)
[](https://lifecycle.r-lib.org/articles/stages.html#experimental)
<!-- [](https://github.com/jackgisby/ReducedExperiment/actions/workflows/check-bioc.yml) -->
<!-- [](https://bioconductor.org/checkResults/release/bioc-LATEST/ReducedExperiment) -->
<!-- [](https://bioconductor.org/checkResults/devel/bioc-LATEST/ReducedExperiment) -->
<!-- [](http://bioconductor.org/packages/stats/bioc/ReducedExperiment/) -->
<!-- [](https://support.bioconductor.org/tag/ReducedExperiment) -->
<!-- [](https://bioconductor.org/packages/release/bioc/html/ReducedExperiment.html#since) -->
<!-- [](http://bioconductor.org/checkResults/devel/bioc-LATEST/ReducedExperiment/) -->
<!-- [](https://bioconductor.org/packages/release/bioc/html/ReducedExperiment.html#since) -->
<!-- badges: end -->
ReducedExperiment provides containers for storing and
manipulating dimensionally-reduced assay data. The ReducedExperiment
classes allow users to simultaneously manipulate their original dataset
and their decomposed data, in addition to other method-specific outputs
like pathway analysis. Implements utilities and specialised classes for the
application of stabilised independent component analysis (sICA) and
weighted gene correlation network analysis (WGCNA).
## Installation
Get the latest stable `R` release from [CRAN](http://cran.r-project.org/).
Then install `ReducedExperiment` from
[Bioconductor](https://bioconductor.org/packages/release/bioc/html/ReducedExperiment.html)
using the following code:
```{r install, eval = FALSE}
if (!requireNamespace("BiocManager", quietly = TRUE)) {
install.packages("BiocManager")
}
BiocManager::install("ReducedExperiment")
```
Alternatively, the development version of `ReducedExperiment` is available from
[Bioconductor](https://bioconductor.org/packages/devel/bioc/html/ReducedExperiment.html)
or [GitHub](https://github.com/jackgisby/ReducedExperiment) with:
```{r install_dev, eval = FALSE}
BiocManager::install("ReducedExperiment", version = "devel")
devtools::install_github("jackgisby/ReducedExperiment")
```
The development version of the package is also available as a container on [DockerHub](https://hub.docker.com/repository/docker/jackgisby/reducedexperiment/).
## Usage
`ReducedExperiment` objects are derived from `SummarizedExperiment` objects, with
additional slots designed to store and manipulate the outputs of common
dimensionality reduction techniques.
As an example, the `SummarizedExperiment` described below contains gene
expression data from individuals with COVID-19. It contains the following slots:
* `assays` - A features by samples matrix containing the expression data.
* `colData` - Contains a row for each sample containing phenotype data.
* `rowData` - Contains a row for each feature containing gene IDs.
The `SummarizedExperiment` objects are convenient
because, when we slice the rows or columns of the expression matrix, the
metadata for the rows and columns are sliced accordingly.
```{r show_se, eval=requireNamespace('SummarizedExperiment'), message=FALSE, warning=FALSE}
library("SummarizedExperiment")
se <- readRDS(system.file(
"extdata",
"wave1.rds",
package = "ReducedExperiment"
))
se
```
The `SummarizedExperiment` has two dimensions, representing the features (2,184)
and samples (234).
We can perform a factor analysis on these data, the result of which is a set
of reduced components and feature loadings.
```{r estimateFactors, eval=requireNamespace('ReducedExperiment'), message=FALSE, warning=FALSE}
library("ReducedExperiment")
fe <- estimateFactors(se, nc = 35)
fe
```
This `FactorisedExperiment` object has an additional dimension representing the
35 factors. It also has additional slots, including:
* `reduced` - A samples by factors matrix containing the dimensionally-reduced
data.
* `loadings` - Contains a features by factors matrix containing the loadings.
The `ReducedExperiment` objects allow users to simultaneously slice and modify the
`assays`, `rowData`, `colData`, `reduced` and `loadings` matrices. Here, we
provided a `SummarizedExperiment` object to `estimateFactors`, but we could
just have easily provided a simple expression matrix.
Alternatively, you may have already applied dimensionality reduction to your
data and simply wish to package it into a `ReducedExperiment` container. For
instance, below we apply principal components analysis, and construct a
`FactorisedExperiment` object from the results.
```{r fe_from_prcomp, eval=requireNamespace('ReducedExperiment'), message=FALSE, warning=FALSE}
prcomp_res <- stats::prcomp(t(assay(se)), center = TRUE, scale. = TRUE)
fe_prcomp <- FactorisedExperiment(
se,
reduced = prcomp_res$x,
loadings = prcomp_res$rotation,
stability = prcomp_res$sdev,
center = prcomp_res$center,
scale = prcomp_res$scale
)
fe_prcomp
```
## Functionality
The package currently provides three types of container:
* `ReducedExperiment` - A basic container that can store dimensionally-reduced
components.
* `FactorisedExperiment` - A container based on `ReducedExperiment` designed for
working with the results of factor analysis. It can contain feature loadings
and factor stability values.
* `ModularExperiment` - A container based on `ReducedExperiment` designed for
working with modules of features (usually genes), as is produced by the
popular Weighted Gene Correlation Network Analysis (WGCNA) approach. It
contains the mapping of features to modules
Various tools are provided by the package for applying dimensionality reduction
and manipulating their results. These include:
* Workflows for applying independent component analysis (ICA) and
WGCNA. We additionally developed an R implementation of the stabilised ICA
algorithm.
* Methods for applying pathway enrichment analysis to factors and modules.
* Functions for identifying associations between factors/modules and
sample-level variables.
* Methods for applying identified factors or modules to new datasets.
* Other approach-specific plots and utilities, such as factor stability plots
and module preservation plots.
Many of these are demonstrated in more detail in the [package's vignette](https://jackgisby.github.io/ReducedExperiment/articles/ReducedExperiment.html).
The containers implemented in `ReducedExperiment` are designed to be extensible.
We encourage the development of children classes with additional, or
alternative, slots and methods.
## Citation
Below is the citation output from using `citation('ReducedExperiment')` in R.
```{r 'citation', eval = requireNamespace('ReducedExperiment')}
print(citation("ReducedExperiment"), bibtex = TRUE)
```
The `ReducedExperiment` package relies on many software packages and development
tools. The packages used are listed in the vignette and relevant papers are
cited.