-
Notifications
You must be signed in to change notification settings - Fork 2
/
README.Rmd
183 lines (130 loc) · 7.11 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
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
```
# mxnorm: An R package to normalize multiplexed imaging data.
<!-- badges: start -->
[](https://cran.r-project.org/package=mxnorm)
[](https://cran.r-project.org/package=mxnorm)
[](https://joss.theoj.org/papers/10.21105/joss.04180)
[](https://github.com/ColemanRHarris/mxnorm/actions)
[](https://app.codecov.io/gh/ColemanRHarris/mxnorm?branch=main)
<!-- badges: end -->
A package designed to handle multiplexed imaging data in R, implementing normalization methods and quality metrics detailed in our paper [here](https://doi.org/10.1101/2021.07.16.452359). Further information about the package, usage, the vignettes, and more can be found on [CRAN](https://cran.r-project.org/package=mxnorm).
# Installation
To install from `CRAN`, use:
``` r
install.packages("mxnorm")
```
You can install the development version from [GitHub](https://github.com/) with:
``` r
# install.packages("devtools")
devtools::install_github("ColemanRHarris/mxnorm")
```
## Dependencies
This package imports `lme4` (and its dependency `nloptr`) which use `CMake` to build the packages. To install `CMake`, please see [here](https://cmake.org/install/) or select from the following:
```
- yum install cmake (Fedora/CentOS; inside a terminal)
- apt install cmake (Debian/Ubuntu; inside a terminal).
- pacman -S cmake (Arch Linux; inside a terminal).
- brew install cmake (MacOS; inside a terminal with Homebrew)
- port install cmake (MacOS; inside a terminal with MacPorts)
```
This package also uses the `reticulate` package to interface with the `scikit-learn` Python package. Depending on the user's environment, sometimes Python/`conda`/`Miniconda` is not detected, producing an option like the following:
```
No non-system installation of Python could be found.
Would you like to download and install Miniconda?
Miniconda is an open source environment management system for Python.
See https://docs.conda.io/en/latest/miniconda.html for more details.
Would you like to install Miniconda? [Y/n]:
```
In this case, installing Miniconda within the R environment will ensure that both Python and the `scikit-image` package are properly installed. However, if you want to use a separate Python installation, please respond `N` to this prompt and use `reticulate::py_config()` to setup your Python environment. Please also ensure that `scikit-image` is installed in your desired Python environment via `pip install scikit-image`.
# Community Guidelines
Please report any issues, bugs, or problems with the software here: https://github.com/ColemanRHarris/mxnorm/issues. For any contributions, feel free to fork the package repository on GitHub or submit pull requests. Any other contribution questions and requests for support can be directed to the package maintainer Coleman Harris (coleman.r.harris@vanderbilt.edu).
# Analysis Example
This is a basic example using the `mx_sample` dataset, which is simulated data to demonstrate the package's functionality with slide effects.
```{r sample}
library(mxnorm)
head(mx_sample)
```
## `mx_dataset` objects
How to build the `mx_dataset` object with `mx_sample` data in the `mxnorm` package:
```{r example}
mx_dataset = mx_dataset(data=mx_sample,
slide_id="slide_id",
image_id="image_id",
marker_cols=c("marker1_vals","marker2_vals","marker3_vals"),
metadata_cols=c("metadata1_vals"))
```
We can use the built-in `summary()` function to observe `mx_dataset` object:
```{r ex_str}
summary(mx_dataset)
```
## Normalization with `mx_normalize()`
And now we can normalize this data using the `mx_normalize()` function:
```{r norm}
mx_norm = mx_normalize(mx_data = mx_dataset,
transform = "log10_mean_divide",
method="None")
```
And we again use `summary()` to capture the following attributes for the `mx_dataset` object:
```{r norm_str, warning=FALSE}
summary(mx_norm)
```
## Otsu discordance scores with `run_otsu_discordance()`
Using the above normalized data, we can run an Otsu discordance score analysis to determine how well our normalization method performs (here, we look for lower discordance scores to distinguish better performing methods):
```{r otsu}
mx_otsu = run_otsu_discordance(mx_norm,
table="both",
threshold_override = NULL,
plot_out = FALSE)
```
We can also begin to visualize these results using some of `mxnorm`'s plotting features built using `ggplot2`.
First, we can visualize the densities of the marker values as follows:
```{r mx_dens}
plot_mx_density(mx_otsu)
```
We can also visualize the results of the Otsu misclassification analysis stratified by slide and marker:
```{r mx_misc}
plot_mx_discordance(mx_otsu)
```
## UMAP dimension reduction with `run_reduce_umap()`
We can also use the UMAP algorithm to reduce the dimensions of our markers in the dataset as follows, using the `metadata_col` parameter for later (e.g., similar to a tissue type in practice with multiplexed data):
```{r umap}
mx_umap = run_reduce_umap(mx_otsu,
table="both",
marker_list = c("marker1_vals","marker2_vals","marker3_vals"),
downsample_pct = 0.8,
metadata_col = "metadata1_vals")
```
We can further visualize the results of the UMAP dimension reduction as follows:
```{r mx_umap}
plot_mx_umap(mx_umap,metadata_col = "metadata1_vals")
```
Note that since the sample data is simulated, we don't see separation of the groups like we would expect with biological samples that have some underlying correlation. What we can observe, however, is the separation of slides in the `raw` data and subsequent mixing of these slides in the `normalized` data:
```{r mx_umap_slide}
plot_mx_umap(mx_umap,metadata_col = "slide_id")
```
## Variance components analysis with `run_var_proportions()`
We can also leverage `lmer()` from the `lme4` package to perform random effect modeling on the data to determine how much variance is present at the slide level, as follows:
```{r var,warnings=FALSE,message=FALSE}
mx_var = run_var_proportions(mx_umap,
table="both",
metadata_cols = "metadata1_vals")
```
And we can use `summary()` to capture the following attributes for the `mx_dataset` object:
```{r var_str}
summary(mx_var)
```
And we can also visualize the results of the variance proportions after normalization:
```{r mx_var}
plot_mx_proportions(mx_var)
```