@@ -1,3 +1,4 @@

 ^.*\.Rproj$

 ^\.Rproj\.user$

 ^\.travis\.yml$

+^man-roxygen

\ No newline at end of file

@@ -1,7 +1,10 @@

 # Generated by roxygen2: do not edit by hand

 export(aggregateSignal)

+export(convertToFromNullDist)

+export(getGammaPVal)

 export(getMetaRegionProfile)

+export(getPermStat)

 export(regionQuantileByPC)

 export(rsRankingIndex)

 export(rsScoreHeatmap)

@@ -58,6 +61,7 @@ importFrom(grid,unit)

 importFrom(grid,viewport)

 importFrom(methods,hasArg)

 importFrom(methods,is)

+importFrom(ppcor,pcor)

 importFrom(simpleCache,simpleCache)

 importFrom(stats,coefficients)

 importFrom(stats,ecdf)

@@ -50,6 +50,10 @@

 #' @importFrom fitdistrplus fitdist

 #' @importFrom simpleCache simpleCache

 #' @importFrom ppcor pcor

+#' @eval addParamDocs <- function(signal=FALSE, signalCoord=FALSE, 

+#' signalCoordType=FALSE, GRList=FALSE, 

+#' regionSet=FALSE, signalCol=FALSE, 

+#' scoringMetric=FALSE, verbose=FALSE, absVal=FALSE ) { x +100}

 NULL

 # now package lists GenomicRanges in "Depends" instead of "Imports" in 

@@ -80,18 +84,12 @@ if (getRversion() >= "2.15.1") {

 #' Then the loadings are used to score the region set 

 #' according to the `scoringMetric` parameter.  

 #' 

+#' @eval print("@param testP my test param ")

 #' @param signal matrix of loadings (the coefficients of 

 #' the linear combination that defines each PC). One named column for each PC.

 #' One row for each original dimension/variable (should be same order 

 #' as original data/signalCoord). The x$rotation output of prcomp().

-#' @param signalCoord a GRanges object or data frame with coordinates 

-#' for the genomic signal/original data (e.g. DNA methylation) 

-#' included in the PCA. Coordinates should be in the 

-#' same order as the original data and the loadings 

-#' (each item/row in signalCoord

-#' corresponds to a row in `signal`). If a data.frame, 

-#' must have chr and start columns. If end is included, start 

-#' and end should be the same. Start coordinate will be used for calculations.

+#' @template signalCoord

 #' @param signalCoordType character. Can be "default", "singleBase", or 

 #' "multiBase". This describes whether the coordinates for `signal` 

 #' (`signalCoord`) are each a single base (e.g. as for DNA methylation)

@@ -518,7 +516,7 @@ aggregateSignal <- function(signal,

 #' the linear combination that defines each PC). One named column for each PC.

 #' One row for each original dimension/variable (should be same order 

 #' as original data/signalCoord). The x$rotation output of prcomp().

-#' @param signalCoord a GRanges object or data frame with coordinates 

+#' @param signalCoord a GRanges object or data.frame with coordinates 

 #' for the genomic signal/original data (eg DNA methylation) 

 #' included in the PCA. Coordinates should be in the 

 #' same order as the original data and the loadings 

@@ -535,8 +533,8 @@ aggregateSignal <- function(signal,

 #' will be used. Otherwise, "multiBase" will be used. 

 #' @param GRList GRangesList object. Each list item is 

 #' a distinct region set to test (region set: regions that correspond to 

-#' the same biological annotation). The region set database.

-#' Must be from the same reference genome

+#' the same biological annotation). The region set database

+#' must be from the same reference genome

 #' as the coordinates for the actual data/samples (signalCoord).

 #' @param signalCol A character vector with principal components to  

 #' include. eg c("PC1", "PC2") These should be column names of signal.

@@ -788,8 +786,7 @@ createCorFeatureMat <- function(dataMat, featureMat,

         featureMat = as.matrix(featureMat)

     }

-    #remove this line

-    # dataMat = data.table::copy(as.data.frame(t(dataMat)))

+    # avoid this copy and/or delay transpose until after calculating correlation?

     dataMat = as.data.frame(t(dataMat))

@@ -862,7 +859,7 @@ createCorFeatureMat <- function(dataMat, featureMat,

 #' the linear combination that defines each PC). One named column for each PC.

 #' One row for each original dimension/variable (should be same order 

 #' as original data/signalCoord). Given by prcomp(x)$rotation.

-#' @param signalCoord a GRanges object or data frame with coordinates 

+#' @param signalCoord a GRanges object or data.frame with coordinates 

 #' for the genomic signal/original data (eg DNA methylation) 

 #' included in the PCA. Coordinates should be in the 

 #' same order as the original data and the loadings 

@@ -1203,7 +1200,7 @@ BSBinAggregate <- function(BSDT, rangeDT, binCount,

 # the linear combination that defines each PC). One named column for each PC.

 # One row for each original dimension/variable (should be same order 

 # as original data/signalCoord). The x$rotation output of prcomp().

-# @param signalCoord a GRanges object or data frame with coordinates 

+# @param signalCoord a GRanges object or data.frame with coordinates 

 # for the genomic signal/original data (eg DNA methylation) 

 # included in the PCA. Coordinates should be in the 

 # same order as the original data and the loadings 

@@ -1389,42 +1386,43 @@ weightedAvePerRegion <- function(signalDT,

-# Get regions that are most associated with PCs of interest

-#

-# Get a GRanges with top regions from the region set based on average

-# loadings for the regions or the quantile of the region's loading.

-# Returns average loading or quantile as GRanges metadata.

-# 

-# @param signal matrix of loadings (the coefficients of 

-# the linear combination that defines each PC). One named column for each PC.

-# One row for each original dimension/variable (should be same order 

-# as original data/signalCoord). The x$rotation output of prcomp().

-# @param signalCoord a GRanges object or data frame with coordinates 

-# for the genomic signal/original data (eg DNA methylation) 

-# included in the PCA. Coordinates should be in the 

-# same order as the original data and the loadings 

-# (each item/row in signalCoord

-# corresponds to a row in `signal`). If a data.frame, 

-# must have chr and start columns. If end is included, start 

-# and end should be the same. Start coordinate will be used for calculations.

-# @param regionSet A GRanges object with regions corresponding

-# to the same biological annotation.

-# @param signalCol A character vector with principal components to  

-# include. eg c("PC1", "PC2") These should be column names of signal.

-# @param returnQuantile "logical" object. If FALSE, return region averages. If TRUE,

-# for each region, return the quantile of that region's average value

-# based on the distribution of individual genomic signal/feature values

-# @return a GRanges object with region coordinates for regions with

-# scores/quantiles above "cutoff" for any PC in signalCol. The scores/quantiles

-# for signalCol are given as metadata in the GRanges.

+#' Get regions that are most associated with PCs of interest

+#'

+#' Get a GRanges with top regions from the region set based on average

+#' loadings for the regions or the quantile of the region's loading.

+#' Returns average loading or quantile as GRanges metadata.

+#' 

+#' @param signal matrix of loadings (the coefficients of 

+#' the linear combination that defines each PC). One named column for each PC.

+#' One row for each original dimension/variable (should be same order 

+#' as original data/signalCoord). The x$rotation output of prcomp().

+#' @param signalCoord a GRanges object or data.frame with coordinates 

+#' for the genomic signal/original data (eg DNA methylation) 

+#' included in the PCA. Coordinates should be in the 

+#' same order as the original data and the loadings 

+#' (each item/row in signalCoord

+#' corresponds to a row in `signal`). If a data.frame, 

+#' must have chr and start columns. If end is included, start 

+#' and end should be the same. Start coordinate will be used for calculations.

+#' @param regionSet A GRanges object with regions corresponding

+#' to the same biological annotation.

+#' @param signalCol A character vector with principal components to  

+#' include. eg c("PC1", "PC2") These should be column names of signal.

+#' @param returnQuantile "logical" object. If FALSE, return region averages. If TRUE,

+#' for each region, return the quantile of that region's average value

+#' based on the distribution of individual genomic signal/feature values

+#' @return a GRanges object with region coordinates for regions with

+#' scores/quantiles above "cutoff" for any PC in signalCol. The scores/quantiles

+#' for signalCol are given as metadata in the GRanges.

 # Are regions in order along the rows of the data.table?

 #

-# @examples data("brcaLoadings1")

-# data("brcaMCoord1")

-# data("esr1_chr1")

-# COCOA:::getTopRegions(signal=brcaLoadings1,

-# signalCoord=brcaMCoord1, regionSet=esr1_chr1, returnQuantile = TRUE)

+#' @examples 

+#' data("brcaLoadings1")

+#' data("brcaMCoord1")

+#' data("esr1_chr1")

+#' getTopRegions(signal=brcaLoadings1,

+#' signalCoord=brcaMCoord1, regionSet=esr1_chr1, returnQuantile = TRUE)

 getTopRegions <- function(signal, 

                           signalCoord, 

@@ -344,8 +344,7 @@ corPerm <- function(randomInd, genomicSignal,

 #' with one row for each region set (e.g. a data.frame with results for

 #' a single COCOA permutation).

 #' 

-#' @example 

-#' 

+#' @examples

 #' # six region sets (rows), 2 signals (columns)

 #' fakePermScores = data.frame(abs(rnorm(6)), abs(rnorm(6)))

 #' fakePermScores2 = data.frame(abs(rnorm(6)), abs(rnorm(6)))

new file mode 100755

@@ -0,0 +1,8 @@

+#' @param signalCoord a GRanges object or data.frame with coordinates 

+#' for the genomic signal/original data (e.g. DNA methylation) 

+#' included in the PCA. Coordinates should be in the 

+#' same order as the original data and the loadings 

+#' (each item/row in signalCoord

+#' corresponds to a row in `signal`). If a data.frame, 

+#' must have chr and start columns. If end is included, start 

+#' and end should be the same. Start coordinate will be used for calculations.

\ No newline at end of file

@@ -14,7 +14,7 @@ the linear combination that defines each PC). One named column for each PC.

 One row for each original dimension/variable (should be same order 

 as original data/signalCoord). The x$rotation output of prcomp().}

-\item{signalCoord}{a GRanges object or data frame with coordinates 

+\item{signalCoord}{a GRanges object or data.frame with coordinates 

 for the genomic signal/original data (e.g. DNA methylation) 

 included in the PCA. Coordinates should be in the 

 same order as the original data and the loadings 

@@ -93,6 +93,8 @@ will decrease (if there may be anticorrelation between

 regions in a region set). Choose FALSE if you expect regions in a 

 given region set to all change in the same direction (all be positively

 correlated with each other).}

+

+\item{testP}{my test param}

 }

 \value{

 a data.frame with one row and the following 

new file mode 100755

@@ -0,0 +1,42 @@

+% Generated by roxygen2: do not edit by hand

+% Please edit documentation in R/permutation.R

+\name{convertToFromNullDist}

+\alias{convertToFromNullDist}

+\title{Converts COCOA permutation results to null distributions and vice versa}

+\usage{

+convertToFromNullDist(resultsList)

+}

+\arguments{

+\item{resultsList}{each item in the list is a data.frame, one item for

+each permutation with the results of that permutation. Each row in the 

+data.frame is a region set. All data.frames should be the same size and

+each data.frame's rows should be in the same order}

+}

+\value{

+a list of data.frames. If given a list where each item is 

+a data.frame with results from one COCOA permutation, this function

+will return a list of data.frames where each data.frame contains the

+null distributions for a single region set. The output data.frames will

+have the same columns as the input data.frames. If given a list where each

+item is a data.frame with the null distribution/s for a single region

+set, this function will return a list where each item is a data.frame

+with one row for each region set (e.g. a data.frame with results for

+a single COCOA permutation).

+}

+\description{

+This function will take a list of results of permutation tests that included

+many region sets and return a list of data.frames where each data.frame

+contains the null distribution for a single region set.

+The function can 

+also convert in the reverse order from a list of null distributions to a 

+list of COCOA results.

+}

+\examples{

+# six region sets (rows), 2 signals (columns)

+fakePermScores = data.frame(abs(rnorm(6)), abs(rnorm(6)))

+fakePermScores2 = data.frame(abs(rnorm(6)), abs(rnorm(6)))

+# 2 fake COCOA results (i.e. nPerm=2)

+permRSScores = list(fakePermScores, fakePermScores2)

+convertToFromNullDist(permRSScores)

+

+}

new file mode 100755

@@ -0,0 +1,17 @@

+% Generated by roxygen2: do not edit by hand

+% Please edit documentation in R/permutation.R

+\name{fitGammaNullDist}

+\alias{fitGammaNullDist}

+\title{signalCoord=brcaMCoord1, 

+                                 GRList=GRangesList(esr1_chr1), 

+                                 signalCol=c("PC1", "PC2"), 

+                                 scoringMetric="regionMean")}

+\usage{

+fitGammaNullDist(nullDistDF, method = "mme", force = FALSE)

+}

+\description{

+signalCoord=brcaMCoord1, 

+                                 GRList=GRangesList(esr1_chr1), 

+                                 signalCol=c("PC1", "PC2"), 

+                                 scoringMetric="regionMean")

+}

@@ -4,22 +4,31 @@

 \alias{getGammaPVal}

 \title{Get p value after fitting a gamma distribution to the null distribution}

 \usage{

-getGammaPVal(scores, nullDistList, method = "mme",

-  realScoreInDist = FALSE, force = FALSE)

+getGammaPVal(scores, nullDistList, calcCols, method = "mme",

+  realScoreInDist = TRUE, force = FALSE)

 }

 \arguments{

 \item{scores}{a data.frame. Has same columns as nullDistDF. One row per

 region set (should be in same order as nullDistDF) The scores

 that will be used to get p values.}

-\item{nullDistList}{list of a data.frame. Each list item 

+\item{nullDistList}{list of data.frames. Each list item 

 has null distributions for a single 

 region set. Each column corresponds to a null distribution for that 

 region set for a given variable/sample attribute.}

+\item{calcCols}{character.}

+

+\item{method}{character. Has the method to use to fit the gamma 

+distribution to the null distribution. See ?fitdistrplus::fitdist() for

+available options and meaning. The default method "mme" is the 

+"moment matching estimation"}

+

 \item{realScoreInDist}{logical. Should the actual score (from 

 test with no permutations) be included in the null distribution 

 when fitting the gamma distribution}

+

+\item{force}{logical.}

 }

 \value{

 Returns a data.frame with p values, one column for each col in

@@ -28,3 +37,13 @@ scores and nullDistDF

 \description{

 Get p value after fitting a gamma distribution to the null distribution

 }

+\examples{

+fakeOriginalScores = data.frame(PC1=abs(rnorm(6)), PC2=abs(rnorm(6)))

+fakePermScores = data.frame(PC1=abs(rnorm(6)), PC2=abs(rnorm(6)))

+fakePermScores2 = data.frame(PC1=abs(rnorm(6)), PC2=abs(rnorm(6)))

+fakePermScores3 = data.frame(PC1=abs(rnorm(6)), PC2=abs(rnorm(6)))

+permRSScores = list(fakePermScores, fakePermScores2, fakePermScores3)

+nullDistList = convertToFromNullDist(permRSScores)

+getGammaPVal(scores=fakeOriginalScores, nullDistList=nullDistList, calcCols=c("PC1", "PC2")) 

+

+}

@@ -14,7 +14,7 @@ the linear combination that defines each PC). One named column for each PC.

 One row for each original dimension/variable (should be same order 

 as original data/signalCoord). Given by prcomp(x)$rotation.}

-\item{signalCoord}{a GRanges object or data frame with coordinates 

+\item{signalCoord}{a GRanges object or data.frame with coordinates 

 for the genomic signal/original data (eg DNA methylation) 

 included in the PCA. Coordinates should be in the 

 same order as the original data and the loadings 

new file mode 100755

@@ -0,0 +1,51 @@

+% Generated by roxygen2: do not edit by hand

+% Please edit documentation in R/COCOA.R

+\name{getTopRegions}

+\alias{getTopRegions}

+\title{Get regions that are most associated with PCs of interest}

+\usage{

+getTopRegions(signal, signalCoord, regionSet, signalCol = c("PC1",

+  "PC2"), cutoff = 0.8, returnQuantile = TRUE)

+}

+\arguments{

+\item{signal}{matrix of loadings (the coefficients of 

+the linear combination that defines each PC). One named column for each PC.

+One row for each original dimension/variable (should be same order 

+as original data/signalCoord). The x$rotation output of prcomp().}

+

+\item{signalCoord}{a GRanges object or data.frame with coordinates 

+for the genomic signal/original data (eg DNA methylation) 

+included in the PCA. Coordinates should be in the 

+same order as the original data and the loadings 

+(each item/row in signalCoord

+corresponds to a row in `signal`). If a data.frame, 

+must have chr and start columns. If end is included, start 

+and end should be the same. Start coordinate will be used for calculations.}

+

+\item{regionSet}{A GRanges object with regions corresponding

+to the same biological annotation.}

+

+\item{signalCol}{A character vector with principal components to

+include. eg c("PC1", "PC2") These should be column names of signal.}

+

+\item{returnQuantile}{"logical" object. If FALSE, return region averages. If TRUE,

+for each region, return the quantile of that region's average value

+based on the distribution of individual genomic signal/feature values}

+}

+\value{

+a GRanges object with region coordinates for regions with

+scores/quantiles above "cutoff" for any PC in signalCol. The scores/quantiles

+for signalCol are given as metadata in the GRanges.

+}

+\description{

+Get a GRanges with top regions from the region set based on average

+loadings for the regions or the quantile of the region's loading.

+Returns average loading or quantile as GRanges metadata.

+}

+\examples{

+data("brcaLoadings1")

+data("brcaMCoord1")

+data("esr1_chr1")

+getTopRegions(signal=brcaLoadings1,

+signalCoord=brcaMCoord1, regionSet=esr1_chr1, returnQuantile = TRUE)

+}

@@ -14,7 +14,7 @@ the linear combination that defines each PC). One named column for each PC.

 One row for each original dimension/variable (should be same order 

 as original data/signalCoord). The x$rotation output of prcomp().}

-\item{signalCoord}{a GRanges object or data frame with coordinates 

+\item{signalCoord}{a GRanges object or data.frame with coordinates 

 for the genomic signal/original data (eg DNA methylation) 

 included in the PCA. Coordinates should be in the 

 same order as the original data and the loadings 

@@ -24,8 +24,8 @@ If end is not included, start coordinate will be used for calculations.}

 \item{GRList}{GRangesList object. Each list item is 

 a distinct region set to test (region set: regions that correspond to 

-the same biological annotation). The region set database.

-Must be from the same reference genome

+the same biological annotation). The region set database

+must be from the same reference genome

 as the coordinates for the actual data/samples (signalCoord).}

 \item{signalCol}{A character vector with principal components to

@@ -2,7 +2,7 @@

 % Please edit documentation in R/permutation.R

 \name{runCOCOAPerm}

 \alias{runCOCOAPerm}

-\title{permutation test by shuffling sample labels}

+\title{Run COCOA permutations to get p-values}

 \usage{

 runCOCOAPerm(genomicSignal, signalCoord, GRList, realRSScores,

   sampleLabels, signalCol = c("PC1", "PC2"),

@@ -11,22 +11,31 @@ runCOCOAPerm(genomicSignal, signalCoord, GRList, realRSScores,

   cacheDir = getwd(), dataID = "tmp", correctionMethod = "BH", ...)

 }

 \arguments{

+\item{realRSScores}{data.frame. A data.frame with region set

+scores. The output of the 'runCOCOA' function.

+Rows should be in the same order as the region sets in GRList. 

+Must include columns with names given by 'colsToAnnotate'.}

+

 \item{sampleLabels}{data.frame/matrix. Sample labels/values that 

 you are running COCOA to find region sets associated with. These 

 values will be shuffled for the permutation test. Rows are samples.

 Each column is a sample label.}

-\item{variationMetric}{character. Either "cor" (correlation), "pcor" (partial

-correlation), or "cov" (covariation)}

+\item{variationMetric}{character. Either "cor" (Pearson correlation), 

+"pcor" (partial correlation), "spearmanCor (Spearman correlation) 

+or "cov" (covariation).}

 \item{nPerm}{numeric. The number of permutations to do.}

-\item{useSimpleCache}{logical.}

+\item{useSimpleCache}{logical. Whether to use save caches. Caches

+will be created for each permutation so that if the function is disrupted

+it can restart where it left off. The final results are also saved 

+as a cache.}

 \item{cacheDir}{character.}

 \item{dataID}{character. A unique identifier for this dataset 

-(for saving results)}

+(for saving results with simpleCache)}

 \item{correctionMethod}{character. P value correction method. Default

 is "BH" for Benjamini and Hochberg false discovery rate. For acceptable 

@@ -35,7 +44,7 @@ arguments and more info see ?stats::p.adjust() (method parameter)}

 \item{...}{character. Optional additional arguments for simpleCache}

 \item{colsToAnnotate}{character. The column names of `sampleLabels` that

-you want to test.}

+you want to test. These must also be columns in realRSScores.}

 \item{resultType}{character. "pval" or "zscore"}

 }

@@ -44,5 +53,40 @@ Returns a list where each item is a data.frame of COCOA results

 from a separate permutation

 }

 \description{

+This is a convenience function that runs multiple steps of the 

+permutation process together: it runs COCOA permutations, converts these

+to null distributions, gets the empirical p value (which is limited by the

+number of permutations), gets z scores, and fits a gamma distribution 

+to each null distribution to estimate p values (not limited by the 

+number of permutations),

+Requires that the user has previously calculated the real COCOA scores. 

+See these individual functions for more info on each step: corPerm, 

+convertToFromNullDist, getPermStat, and getGammaPVal.

+}

+\details{

 For reproducibility, set seed with 'set.seed()' function before running.

 }

+\examples{

+data("brcaMCoord1")

+data("brcaLoadings1")

+data("esr1_chr1")

+data("nrf1_chr1")

+data("brcaMethylData1")

+data("brcaPCScores657")

+pcCor = corFeature

+sampleLabels <- brcaPCScores657[colnames(brcaMethylData1), ]

+sampleLabels$ER_Status <- scale(as.numeric(sampleLabels$ER_Status), 

+                               center=TRUE, scale=FALSE)

+# give the actual order of samples to randomInd to get the real scores

+realRSScores <- corPerm(randomInd=1:4, genomicSignal=brcaMethylData1, 

+        signalCoord=brcaMCoord1, GRList=GRangesList(esr1_chr1, nrf1_chr1),

+        calcCols=c("PC1", "PC2"), sampleLabels=sampleLabels, 

+        variationMetric="cor")

+

+a=runCOCOAPerm(genomicSignal=brcaMethylData1, 

+        signalCoord=brcaMCoord1, GRList=GRangesList(esr1_chr1, nrf1_chr1),

+        realRSScores=realRSScores, 

+        sampleLabels=sampleLabels, signalCol=c("PC1", "PC2"),

+        variationMetric="cor", nPerm = 10, useSimpleCache=FALSE)

+

+}