Merge pull request #17 from KrishnaswamyLab/dev

phateR v0.2.8

.travis.yml

@@ -13,6 +13,8 @@ r:
   - release
   - devel
 
+cache: packages
+
 env:
   global:
     - PATH="$HOME/miniconda/bin:$PATH"

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: phateR
 Title: PHATE - Potential of Heat-Diffusion for Affinity-Based Transition Embedding
-Version: 0.2.7
+Version: 0.2.8
 Authors@R: c(person("Krishnan", "Srinivasan", email = "[email protected]", role = c("aut")),
              person(given = 'Scott', family = 'Gigante', email = '[email protected]', role = 'cre', comment = c(ORCID = '0000-0002-4544-2764')))
 Description: PHATE is a tool for visualizing high dimensional single-cell data

R/phate.R

@@ -17,17 +17,24 @@
 #' If NULL, alpha decaying kernel is not used
 #' @param n.landmark int, optional, default: 2000
 #' number of landmarks to use in fast PHATE
-#' @param potential.method string, optional, default: 'log'
-#' choose from 'log' and 'sqrt'
-#' which transformation of the diffusional operator is used
-#' to compute the diffusion potential
+#' @param gamma float, optional, default: 1
+#' Informational distance constant between -1 and 1.
+#' `gamma=1` gives the PHATE log potential, `gamma=0` gives
+#' a square root potential.
 #' @param t int, optional, default: 'auto'
 #' power to which the diffusion operator is powered
 #' sets the level of diffusion
 #' @param knn.dist.method string, optional, default: 'euclidean'.
-#' The desired distance function for calculating pairwise distances on the data.
-#' If 'precomputed', `data` is treated as a
-#' (n_samples, n_samples) distance or affinity matrix
+#' recommended values: 'euclidean', 'cosine', 'precomputed'
+#' Any metric from `scipy.spatial.distance` can be used
+#' distance metric for building kNN graph. If 'precomputed',
+#' `data` should be an n_samples x n_samples distance or
+#' affinity matrix. Distance matrices are assumed to have zeros
+#' down the diagonal, while affinity matrices are assumed to have
+#' non-zero values down the diagonal. This is detected automatically using
+#' `data[0,0]`. You can override this detection with
+#' `knn.dist.method='precomputed_distance'` or
+#' `knn.dist.method='precomputed_affinity'`.
 #' @param init phate object, optional
 #' object to use for initialization. Avoids recomputing
 #' intermediate steps if parameters are the same.
@@ -55,8 +62,9 @@
 #' For n_jobs below -1, (n.cpus + 1 + n.jobs) are used. Thus for
 #' n_jobs = -2, all CPUs but one are used
 #' @param seed int or `NULL`, random state (default: `NULL`)
-#' @param use.alpha boolean, default: NULL
-#' Deprecated. To disable alpha decay, use `alpha=NULL`
+#' @param potential.method Deprecated.
+#' @param use.alpha Deprecated
+#' To disable alpha decay, use `alpha=NULL`
 #' @param n.svd Deprecated.
 #' @param pca.method Deprecated.
 #' @param g.kernel Deprecated.
@@ -105,12 +113,13 @@
 #' @export
 phate <- function(data, ndim = 2, k = 5,
                   alpha = 15,
-                  n.landmark=2000, potential.method = "log",
+                  n.landmark=2000, gamma=1,
                   t = "auto", knn.dist.method = "euclidean",
                   init=NULL,
                   mds.method = "metric", mds.dist.method = "euclidean",
                   t.max=100, npca = 100, plot.optimal.t=FALSE,
                   verbose=1, n.jobs=1, seed=NULL,
+                  potential.method = NULL,
                   # deprecated args, remove in v3
                   use.alpha=NULL,
                   n.svd = NULL,
@@ -127,6 +136,18 @@ phate <- function(data, ndim = 2, k = 5,
     message("Argument dist.method is deprecated. Using knn.dist.method instead.")
     knn.dist.method <- dist.method
   }
+  if (!is.null(potential.method)) {
+    if (potential.method == 'log') {
+      gamma <- 1
+    } else if (potential.method == 'sqrt') {
+      gamma <- 0
+    } else {
+      stop(paste0("potential.method ", potential.method, " not recognized. ",
+                  "Please use -1 <= gamma <= 1 instead."))
+    }
+    message(paste0("Argument potential_method is deprecated. Setting gamma to ",
+                   gamma, " to achieve ", potential.method, " transformation."))
+  }
   if (!is.null(n.svd)) {
     message("Setting n.svd is currently not supported. Using n.svd=100")
   }
@@ -208,8 +229,8 @@ phate <- function(data, ndim = 2, k = 5,
 
   # store parameters
   params <- list("data" = data, "k" = k, "alpha" = alpha, "t" = t,
-                 "n.landmark" = n.landmark, "ndim" = ndim,
-                 "potential.method" = potential.method,
+                 "n.landmark" = n.landmark, "gamma" = gamma,
+                 "ndim" = ndim,
                  "npca" = npca, "mds.method" = mds.method,
                  "knn.dist.method" = knn.dist.method,
                  "mds.dist.method" = mds.dist.method)
@@ -226,7 +247,7 @@ phate <- function(data, ndim = 2, k = 5,
                           t = t,
                           alpha_decay = use.alpha,
                           n_landmark = n.landmark,
-                          potential_method = potential.method,
+                          gamma = gamma,
                           n_pca = npca,
                           mds = mds.method,
                           mds_dist = mds.dist.method,
@@ -243,7 +264,7 @@ phate <- function(data, ndim = 2, k = 5,
                               t = t,
                               alpha_decay = use.alpha,
                               n_landmark = n.landmark,
-                              potential_method = potential.method,
+                              gamma = gamma,
                               n_pca = npca,
                               mds = mds.method,
                               mds_dist = mds.dist.method,
@@ -314,7 +335,7 @@ plot.phate <- function(x, ...) {
 #' ## $embedding : (3000, 2)
 #' ## $operator : Python PHATE operator
 #' ## $params : list with elements (data, k, alpha, t, n.landmark, ndim,
-#' ##                               potential.method, npca, mds.method,
+#' ##                               gamma, npca, mds.method,
 #' ##                               knn.dist.method, mds.dist.method)
 #'
 #' }

R/utils.R

@@ -31,6 +31,7 @@ load_pyphate <- function() {
 #' is not available on Windows.
 #' @param conda Path to conda executable (or "auto" to find conda using the PATH
 #'  and other conventional install locations).
+#' @param pip Install from pip, if possible.
 #' @param ... Additional arguments passed to conda_install() or
 #' virtualenv_install().
 #'

README.Rmd

@@ -1,5 +1,5 @@
 ---
-title : phateR v0.2.7
+title : phateR v0.2.8
 output: github_document
 ---
 
@@ -42,6 +42,8 @@ For our Python and Matlab implementations, please see [KrishnaswamyLab/PHATE](ht
 
 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
 
 Install `phateR` from CRAN by running the following code in R:
@@ -56,8 +58,6 @@ Install `phate` in Python by running the following code from a terminal:
 pip install --user phate
 ```
 
-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 with `devtools` and `reticulate`
 
 The development version of PHATE can be installed directly from R with `devtools`:
@@ -80,7 +80,7 @@ reticulate::py_install("phate", pip=TRUE)
 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/SmitaKrishnaswamy/PHATE.git
+git clone --recursive git://github.com/KrishnaswamyLab/PHATE.git
 cd PHATE/phateR
 R CMD INSTALL
 cd ../Python
@@ -126,11 +126,11 @@ 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. 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.
+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, potential.method='sqrt', t=120, init=tree.phate)
+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)
@@ -147,4 +147,5 @@ ggplot(tree.phate, aes(x=PHATE1, y=PHATE2, color=tree.data$branches)) +
 
 ## Issues
 
-Please let us know of any issues at the [GitHub repo](https://github.com/KrishnaswamyLab/phateR/issues)
+Please let us know of any issues at the [GitHub repo](https://github.com/KrishnaswamyLab/phateR/issues). If you have any questions or require assistance using MAGIC, please contact us at <https://krishnaswamylab.org/get-help>.
+

README.md

@@ -1,4 +1,4 @@
-phateR v0.2.7
+phateR v0.2.8
 ================
 
 <!-- README.md is generated from README.Rmd. Please edit that file -->
@@ -43,6 +43,11 @@ For our Python and Matlab implementations, please see
 
 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
 
 Install `phateR` from CRAN by running the following code in R:
@@ -57,8 +62,6 @@ Install `phate` in Python by running the following code from a terminal:
 pip install --user phate
 ```
 
-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 with `devtools` and `reticulate`
 
 The development version of PHATE can be installed directly from R with
@@ -83,7 +86,7 @@ The latest source version of PHATE can be accessed by running the
 following in a terminal:
 
 ``` bash
-git clone --recursive git://github.com/SmitaKrishnaswamy/PHATE.git
+git clone --recursive git://github.com/KrishnaswamyLab/PHATE.git
 cd PHATE/phateR
 R CMD INSTALL
 cd ../Python
@@ -113,7 +116,6 @@ PCA.
 ``` r
 library(phateR)
 #> Loading required package: Matrix
-#> Warning: package 'Matrix' was built under R version 3.4.4
 data(tree.data)
 plot(prcomp(tree.data$data)$x, col=tree.data$branches)
 ```
@@ -145,17 +147,17 @@ 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. 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.
+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
 # runs phate with different parameters
-tree.phate <- phate(tree.data$data, potential.method='sqrt', t=120, init=tree.phate)
+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)
@@ -177,4 +179,7 @@ ggplot(tree.phate, aes(x=PHATE1, y=PHATE2, color=tree.data$branches)) +
 ## Issues
 
 Please let us know of any issues at the [GitHub
-repo](https://github.com/KrishnaswamyLab/phateR/issues)
+repo](https://github.com/KrishnaswamyLab/phateR/issues).
+If you have any questions or require assistance using PHATE,
+please contact us at <https://krishnaswamylab.org/get-help>.
+