updating readme; adding doc to hpe

Author: stephaniehicks

.Rbuildignore

@@ -0,0 +1 @@
+^LICENSE\.md$

.gitignore

@@ -0,0 +1 @@
+inst/doc

DESCRIPTION

@@ -1,16 +1,26 @@
 Package: fasthplus
-Title: What the Package Does (One Line, Title Case)
+Title: Fast diconcordance estimation using percentiles.
 Version: 0.0.0.9000
-Authors@R: 
+Authors@R: c(
     person(given = "Nathan",
            family = "Dyjack",
            role = c("aut", "cre"),
            email = "ntdyjack@gmail.com",
-           comment = c(ORCID = "0000-0001-6944-6252"))
-Description: Fast diconcordance estimation using percentiles.
-License: `use_mit_license()`, `use_gpl3_license()` or friends to pick a
-    license
+           comment = c(ORCID = "0000-0001-6944-6252")), 
+    person(given = c("Stephanie", "C."), 
+           family = "Hicks", 
+           role = c("aut", "ctb"), 
+		       email = "shicks19@jhu.edu", 
+		       comment = c(ORCID = "0000-0002-7858-0231")))
+Description: This package contains a generalized disconcordance measure called H+ that is extended from G+ proposed by Rohlf in 1975. 
+License: CC BY 4.0
 Encoding: UTF-8
 LazyData: true
 Roxygen: list(markdown = TRUE)
 RoxygenNote: 7.1.1
+BugReports: https://github.com/ntdyjack/fasthplus/
+URL: https://github.com/ntdyjack/fasthplus/
+Suggests: 
+    knitr,
+    rmarkdown
+VignetteBuilder: knitr

DESCRIPTION~

@@ -1,81 +1,87 @@
-#' H+ Estimate
+#' @title H+ discordance metric
 #'
-#' Estimates H+ for two sets (vectors) A and B, or 
-#' a dissimilarity matrix D and a label vector L.
+#' @description Estimates the H+ discordance metric 
+#' for either (1) two sets (vectors) A and B, or 
+#' (2) a dissimilarity matrix D and a label vector L.
 #' Approximation is calculated using p+1 percentiles,
 #' with an accuracy bound of 1/p.
 #'
-#' @param A (numeric vector)
-#' @param B (numeric vector)
-#' @param D (dist, nxn)
-#' @param L (numeric or character vector, nx1)
-#' @param p (integer)
-#' @param alg (integer), Algorithm 1 or 2
-#' @return Estimated H+ (numeric)
+#' @param A numeric vector containing a set of length n
+#' @param B numeric vector containing a set of length n
+#' @param D distance matrix of dimension nxn
+#' @param L numeric or character vector of length n
+#' @param p integer representing the number of percentiles
+#' @param alg integer (1 or 2) representing the choice of algorithm used to estimate H+ (Algorithm 1 or 2)
+#' 
+#' @return A numeric returning the estimated value of H+. 
 #' @export
+#' 
 #' @examples
 #' a <- rnorm(n=500,mean=0)
-#' b <- rnorm(n=500,mean=1
-#' h <- hpe(a=a,b=b,p=101,alg=1)
+#' b <- rnorm(n=500,mean=1)
+#' h <- hpe(A=a,B=b,p=101,alg=1)
 #'
 #' a <- sapply(1:500, function(i) rnorm(n=50,mean=0))
 #' b <- sapply(1:500, function(i) rnorm(n=50,mean=0))
 #' x <- cbind(a,b)
 #' d <- dist(t(x))
 #' l <- c(rep(0,500),rep(1,500))
 #' h <- hpe(D=d,L=l,p=101,alg=1)
-hpe <- function(A,B,D,L,p=101,alg=1){
-  abflg<- missing(A) & missing(B)
+#' 
+hpe <- function(A, B, D, L, p = 101, alg = 1) {
+  abflg <- missing(A) & missing(B)
   dlflg <- missing(D) & missing(L)
-  if( abflg & dlflg){
+  if (abflg & dlflg) {
     stop("please provide either A B or D L")
-  } else if (!abflg){
+  } else if (!abflg) {
     nmflg <- (!is.numeric(A) & !is.numeric(A))
-    if(nmflg){
+    if (nmflg) {
       stop("please ensure A B are numeric")
     } else {
       print("Estimating H+ using A B formulation...")
     }
-  } else if(!dlflg){
-  #  tyflg <- !(class(D)=='dist' | (is.matrix(D) & isSymmetric(D)  & is.numeric(D)) )
-    tyflg <- !( class(D)=='dist' )
-    if(tyflg){
+  } else if (!dlflg) {
+    #  tyflg <- !(class(D)=='dist' | (is.matrix(D) & isSymmetric(D)  & is.numeric(D)) )
+    tyflg <- !(class(D) == 'dist')
+    if (tyflg) {
       stop("please ensure D is a dist objcect")
     }
     tyflg <- !(is.numeric(L) | is.character(L))
-    if(tyflg){
+    if (tyflg) {
       stop("please ensure L is numeric or character vector")
     }
     D <- as.matrix(D)
-    dmflg <- !( ncol(D) == nrow(D) & ncol(D) == length(L))
-    if(dmflg){
+    dmflg <- !(ncol(D) == nrow(D) & ncol(D) == length(L))
+    if (dmflg) {
       stop("Dimension mismatch for D and L")
     } else {
       print("Estimating H+ using D L formulation...")
     }
-    ind <- sapply(L, function(x) sapply(L, function(y) x==y))
+    ind <- sapply(L, function(x)
+      sapply(L, function(y)
+        x == y))
     ind <- ind[upper.tri(ind)]
     iw <- which(ind)
     ib <- which(!ind)
     D <- D[upper.tri(D)]
     A <- D[iw]
     B <- D[ib]
   }
-
-
-  ps <- seq(0,1,length.out=p)
+  
+  
+  ps <- seq(0, 1, length.out = p)
   qA <- quantile(A, probs = ps)
   qB <- quantile(B, probs = ps)
-
+  
   #call hp alg1 or 2
-  if(alg==1){
-    he <- alg1(qA,qB,p)  
-  }else if(alg==2){
-    he <- alg2(qA,qB,p)  
-  }else{
+  if (alg == 1) {
+    he <- alg1(qA, qB, p)
+  } else if (alg == 2) {
+    he <- alg2(qA, qB, p)
+  } else{
     stop("please specify a vaid algorithm (alg=1 or 2)")
   }
-
+  
   #return estimate
   return(he)
 }

LICENSE.md

@@ -1,34 +1,66 @@
 # fasthplus
 
-fasthplus provides fast approximations for the disconcordance of two sets.
-We present h+, a slight improvement modification of g+, a generalized disconcordance measure proposed by [Rohlf,1975] (https://www.annualreviews.org/doi/abs/10.1146/annurev.es.05.110174.000533).
-We present discorcodance in the sense of label fitness (clustering) for a generalized dissimilarity matrix or more generally for two arbitrary sets.
+fasthplus provides fast approximations for the discordance of two sets.
+We present H+, a slight improvement modification of G+, a generalized discordance measure proposed by [Rohlf, 1975] (https://www.annualreviews.org/doi/abs/10.1146/annurev.es.05.110174.000533).
+We present discordance in the sense of label fitness (clustering) for a generalized dissimilarity matrix or more generally for two arbitrary sets.
 
 
-# installation
+### Installing fasthplus
 
-At present, our package is available only via github installtion using the devtools package.
+At present, our package is available only via github installation using the `devtools` package.
 
-```R {cmd=false}
+```
 library(devtools)
 install_github(repo="ntdyjack/fasthplus", ref = "main")
+```
+
+After installation, the package can be loaded into R
+
+```
 library(fasthplus)
 ```
 
-# functions
+### Using fasthplus
+
+The main function in the **fasthplus** package is `hpe()`. 
+The `hpe()` function accepts either (1) two sets (`A` and `B`) or 
+(2) a distance matrix (`D`) and set of labels (`L`). 
+
+To provide a fast way to calculate H+, we provide an algorithm that approximates H+ using the number of percentiles (`p`), which is also an argument in the `hpe()` function. 
+
+To run the `hpe()` function with two sets (`A` and `B`) and the number of `p` + 1 percentiles: 
+
+```
+a <- rnorm(n=500,mean=0)
+b <- rnorm(n=500,mean=1)
+h <- hpe(A=a,B=b,p=101,alg=1)
+```
 
-##estimate h+ for a dissimilarity matrix and set of labels
-```R {cmd=false}
+To run the `hpe()` function with a dissimilarity matrix (`D`) and set of labels (`L`): 
+
+``` 
+# Two sets
 a <- sapply(1:100, function(i) rnorm(n=50,mean=0.0,sd=1))
 b <- sapply(1:100, function(i) rnorm(n=50,mean=0.0,sd=1))
 c <- cbind(a,b)
+
+# Create a set of labels
 l <- c(rep(0,100),rep(1,100))
+
+# Calculate a distance matrix
 d <- dist(t(c))
-h <- hp_estm(dis=d,lab=l,p=0.005)
+h <- hpe(D=d,L=l,p=0.005)
 ```
 
-##estimate h+ for two sets
-```R {cmd=false}
-h <- hp_estm(a=a,b=b)
-```
 
+### Issues and bug reports
+
+Please use https://github.com/ntdyjack/fasthplus/issues to submit issues, bug reports, and comments.
+
+### Contributors
+
+* [Nathan Dyjack](https://github.com/ntdyjack)
+* [Stephanie Hicks](https://github.com/stephaniehicks)
+
+
+