\name{eqsens_dt}
\alias{eqsens_dt}
\alias{plotsens}
\alias{filtgen.maf.dist}
\alias{update_fdr_filt}

%- Also NEED an '\alias' for EACH other topic documented here.
\title{
support for sensitivity analyses related to eQTL enumerations
}
\description{
support for sensitivity analyses related to eQTL enumerations
}
\usage{
eqsens_dt(dtab, filtgen = filtgen.maf.dist, by = c("pairs", "snps", "probes")[1], 
	targfdrs = c(0.05, 0.01, 0.005), 
	parmslist = list(mafs = c(0.025, 0.05, 0.075, 0.1, 0.125), 
		dists = c(1000, 5000, 10000, 25000, 50000, 1e+05)),
                renameChisq = TRUE)
filtgen.maf.dist (maf.dist, validate.tab = function(tab) all(c("mindist", 
    "MAF", "score") \%in\% colnames(tab))) 
update_fdr_filt(tab, filt = function(x) x, by = c("pairs", "snps", 
    "probes")[1]) 
plotsens(eqsout, ylab = "count of eQTL at given FDR", 
     title = "cis radius in bp")
}

\arguments{
  \item{dtab}{
data.table instance as generated by converting a \code{\link{cisScores}}
GRanges.  In general it will need to have column names score, MAF, mindist,
and columns with names permScore_1, ....
}
  \item{filtgen}{
a function that generates a closure.  The function returned
by \code{filtgen} will be a function of one argument that filters
an input data.table.  The environment of the returned function
will possess bindings used to define the filtering operation.
\code{filtgen.maf.dist}, documented here, is a working example.
}
  \item{by}{
character atom describing the level of aggregation for sensitivity
analysis.  eQTl searches generally involve cartesian products
of sets of SNPs and sets of genes, and if all elements of these products
are of interest, set \code{by} to \code{"pairs"}.  For sensitivity
analysis in which per-SNP associations are measured by choosing the
maximum association statistic for all genes cis to the SNP, set
\code{by} to \code{"snps"}.  For per-gene associations, with
scores maximized over all SNPs cis to genes, use \code{"probes"}.
}
  \item{targfdrs}{
numeric vector of FDR levels for which enumerations are performed.
}
  \item{parmslist}{
list of numeric vectors giving thresholds for use in filtering
tests using \code{filtgen}
}
 \item{maf.dist}{numeric vector of length two giving thresholding
values for MAF and cis distance for filtering association tests}
 \item{validate.tab}{function of one argument, assumed to be
a data.table instance, that can be used to check whether filtering
conditions are feasible before attempting to filter; should return
TRUE if they are, FALSE otherwise.}
 \item{tab}{data.table instance as generated by 
     converting a \code{\link{cisScores}}}
 \item{filt}{function of one argument that operates on a data.table
instance to reduce the rows to a desired set; parameters of
filtering task are established in the environment of \code{filt}}
  \item{eqsout}{
matrix as output by \code{eqsens\_dt}
}
  \item{ylab}{
text string to be used to label Y axis on the left
}
  \item{title}{
text string to label top of plot
}
  \item{renameChisq}{Some utilities fail to generate 'score' for
observed association statistic, but report as 'chisq'.  If TRUE
and such a column name is found in dtab, setnames will be run
to rename to 'score'.}
}
\details{
The objective is to generate data for tabulation or visualization
of sensitivity analyses, and the scope of sensitivity analysis
can be established in various ways.  This software is mostly intended
as a framework.
}
\value{
\code{eqsens_dt} returns a data.frame instance with enumerations
of eQTL at various FDR thresholds for various settings of tuning
parameters

\code{update_fdr_filt} revises (using \code{\link{pifdr}}) the \code{fdr} field of an input
data.table instance using variable
\code{score} as observed value, and permuted
values furnished by the variables named with \code{permScore} as
leading substring 
}
%\references{
%% ~put references to the literature/web site here ~
%}
\author{
VJ Carey <stvjc@channing.harvard.edu>
}
\note{
To do: allow filtering on the number of permutations to be used
in FDR calculation.
}

%% ~Make other sections like Warning with \section{Warning }{....} ~

%\seealso{
%% ~~objects to See Also as \code{\link{help}}, ~~~
%}
\examples{
   \dontrun{
   example(cisScores) # would generate f1
   names(f1) = NULL
   eqsens_dt( data.table(as(f1, "data.frame")) )
   }
}
% Add one or more standard keywords, see file 'KEYWORDS' in the
% R documentation directory.
\keyword{ models }
