/
README.Rmd
182 lines (128 loc) · 7.18 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
---
title : phateR
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%"
)
```
[](https://pypi.org/project/phate/)
[](https://cran.r-project.org/package=phateR)
[](https://travis-ci.com/KrishnaswamyLab/phateR)
[](https://phate.readthedocs.io/)
[](https://www.nature.com/articles/s41587-019-0336-3)
[](https://twitter.com/KrishnaswamyLab)
[](https://github.com/KrishnaswamyLab/PHATE/)
This R package provides an implementation of the [PHATE dimensionality reduction and visualization method](https://www.nature.com/articles/s41587-019-0336-3).
For a thorough overview of the PHATE visualization method, please see the [Nature Biotechnology publication](https://www.nature.com/articles/s41587-019-0336-3).
For our Python and Matlab implementations, please see [KrishnaswamyLab/PHATE](https://github.com/KrishnaswamyLab/PHATE).
## Table of Contents
* [Installation](#installation)
* [Installation from CRAN and PyPi](#installation-from-cran-and-pypi)
* [Installation with devtools and <code>reticulate</code>](#installation-with-devtools-and-reticulate)
* [Installation from source](#installation-from-source)
* [Quick Start](#quick-start)
* [Tutorial](#tutorial)
* [Issues](#issues)
* [FAQ](#faq)
* [Help](#help)
## Installation
In order to use PHATE in R, you must also install the Python package.
If `python` or `pip` are not installed, you will need to install them. We recommend [Miniconda3](https://conda.io/miniconda.html) to install Python and `pip` together, or otherwise you can install `pip` from https://pip.pypa.io/en/stable/installing/.
#### Installation from CRAN and PyPi
First install `phate` in Python by running the following code from a terminal:
```{bash pypi-install, eval = FALSE}
pip install --user phate
```
Then install `phateR` from CRAN by running the following code in R:
```{r cran-install, eval = FALSE}
install.packages("phateR")
```
#### Installation with `devtools` and `reticulate`
The development version of PHATE can be installed directly from R with `devtools`:
```{r github-install, eval = FALSE}
if (!suppressWarnings(require(devtools))) install.packages("devtools")
reticulate::py_install("phate", pip=TRUE)
devtools::install_github("KrishnaswamyLab/phateR")
```
#### Installation from source
The latest source version of PHATE can be accessed by running the following in a terminal:
```{bash install-source, eval=FALSE}
git clone --recursive git://github.com/KrishnaswamyLab/PHATE.git
cd PHATE/Python
python setup.py install --user
cd ../phateR
R CMD INSTALL
```
If the `phateR` folder is empty, you have may forgotten to use the `--recursive` option for `git clone`. You can rectify this by running the following in a terminal:
```{bash fix-submodule, eval=FALSE}
cd PHATE
git submodule init
git submodule update
cd Python
python setup.py install --user
cd ../phateR
R CMD INSTALL
```
## Quick Start
If you have loaded a data matrix `data` in R (cells on rows, genes on columns) you can run PHATE as follows:
```{r quick start, eval=FALSE}
library(phateR)
data_phate <- phate(data)
```
phateR accepts R matrices, `Matrix` sparse matrices, `data.frame`s, and any other data type that can be converted to a matrix with the function `as.matrix`.
## Tutorial
This is a basic example running `phate` on a highly branched example
dataset that is included with the package. You can read a tutorial
on running PHATE on single-cell RNA-seq at
<http://htmlpreview.github.io/?https://github.com/KrishnaswamyLab/phateR/blob/master/inst/examples/bonemarrow_tutorial.html>
or in `inst/examples`. Running this tutorial from start to finish should take approximately 3 minutes.
First, let's load the tree data and examine it with PCA.
```{r example-data}
library(phateR)
data(tree.data)
plot(prcomp(tree.data$data)$x, col=tree.data$branches)
```
Now we run PHATE on the data. We'll just go ahead and try with the default parameters.
```{r run-phate}
# runs phate
tree.phate <- phate(tree.data$data)
summary(tree.phate)
```
Let's plot the results.
```{r plot-results}
# plot embedding
palette(rainbow(10))
plot(tree.phate, col = tree.data$branches)
```
Good news! Our branches separate nicely. However, most of the interesting activity seems to be concentrated into one region of the plot - in this case we should try the square root potential instead by using `gamma=0`. We can also try increasing `t` to make the structure a little clearer - in this case, because synthetic data in unusually structured, we can use a very large value, like 120, but in biological data the automatic `t` selection is generally very close to ideal. Note here that if we pass our previous result in with the argument `init`, we won't have to recompute the diffusion operator.
```{r adjust-parameters}
# runs phate with different parameters
tree.phate <- phate(tree.data$data, gamma=0, t=120, init=tree.phate)
# plot embedding
palette(rainbow(10))
plot(tree.phate, col = tree.data$branches)
```
We can also pass the PHATE object directly to `ggplot`, if it is installed.
```{r ggplot}
library(ggplot2)
ggplot(tree.phate, aes(x=PHATE1, y=PHATE2, color=tree.data$branches)) +
geom_point()
```
## Issues
### FAQ
* **Should genes (features) by rows or columns?**
To be consistent with common dimensionality reductions such as PCA (`stats::prcomp`) and t-SNE (`Rtsne::Rtsne`), we require that cells (observations) be rows and genes (features) be columns of your input data.
- **Can I run PHATE with Seurat?**
PHATE was removed from Seurat in version 3. You can install a version of Seurat with `RunPHATE` included by following the instructions at <https://github.com/satijalab/seurat/pull/1172#issuecomment-564782167>.
* **I have installed PHATE in Python, but phateR says it is not installed!**
Check your `reticulate::py_discover_config("phate")` and compare it to the version of Python in which you installed PHATE (run `which python` and `which pip` in a terminal.) Chances are `reticulate` can't find the right version of Python; you can fix this by adding the following line to your `~/.Renviron`:
```PATH=/path/to/my/python```
You can read more about `Renviron` at <https://CRAN.R-project.org/package=startup/vignettes/startup-intro.html>.
### Help
Please let us know of any issues at the [GitHub repository](https://github.com/KrishnaswamyLab/phateR/issues). If you have any questions or require assistance using PHATE, please read the documentation at <https://CRAN.R-project.org/package=phateR/phateR.pdf> or by running `help(phateR::phate)` or contact us at <https://krishnaswamylab.org/get-help>.