% 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 target variable}
\usage{
getTopRegions(
  signal,
  signalCoord,
  regionSet,
  signalCol = c("PC1", "PC2"),
  cutoff = 0.8,
  returnQuantile = TRUE
)
}
\arguments{
\item{signal}{Matrix of feature contribution scores (the contribution of 
each epigenetic feature to each target variable). One named column for each 
target variable.
One row for each original epigenetic feature (should be same order 
as original data/signalCoord). For (an unsupervised) example, if PCA was
done on epigenetic data and the
goal was to find region sets associated with the principal components, you 
could use the x$rotation output of prcomp(epigenetic data) as the
feature contribution scores/`signal` parameter.}

\item{signalCoord}{A GRanges object or data frame with coordinates 
for the genomic signal/original epigenetic data. 
Coordinates should be in the 
same order as the original data and the feature contribution scores 
(each item/row in signalCoord
corresponds to a row in signal). If a data.frame, 
must have chr and start columns (optionally can have end column, 
depending on the epigenetic data type).}

\item{regionSet}{A genomic ranges (GRanges) object with regions corresponding
to the same biological annotation.}

\item{signalCol}{A character vector with the names of the sample variables
of interest/target variables (e.g. PCs or sample phenotypes).}

\item{cutoff}{Numeric. Only regions with at least this value will be 
returned (either above this average `signal` value or above this quantile
if returnQuantile=TRUE).}

\item{returnQuantile}{Logical. 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 feature values in `signal` for
that `signalCol`.}
}
\value{
A GRanges object with region coordinates for regions with
scores/quantiles above "cutoff" for any target variable 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 feature contribution scores
for the regions or the quantile of the region's average
feature contribution score based on the 
distribution of all feature contribution scores for the target variable.
Returns average feature contribution score or quantile as GRanges metadata.
}
\examples{
data("brcaATACCoord1")
data("brcaATACData1")
data("esr1_chr1")
featureContributionScores <- prcomp(t(brcaATACData1))$rotation
topRegions <- getTopRegions(signal=featureContributionScores,
                            signalCoord=brcaATACCoord1,
                            regionSet=esr1_chr1,
                            returnQuantile = TRUE)
}