% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/cluster-testing.R
\name{cluster_test_by}
\alias{cluster_test_by}
\alias{cluster_logistic_test}
\title{Test clusters for differential usage}
\usage{
cluster_test_by(ccdb, fields = "chain", tbl = "cluster_tbl", ...)

cluster_logistic_test(
  formula,
  ccdb,
  filterset = cluster_filterset(),
  contig_filter_args = TRUE,
  tie_break_keys = c("umis", "reads"),
  add_cluster_tbl = FALSE,
  keep_fit = FALSE,
  fitter = glm_glmer,
  silent = FALSE
)
}
\arguments{
\item{ccdb}{\code{\link[=ContigCellDB]{ContigCellDB()}}}

\item{fields}{\code{character} naming fields in \code{tbl}}

\item{tbl}{one of \code{contig_tbl}, \code{cell_tbl} or \code{cluster_tbl}}

\item{...}{passed to \code{cluster_logistic_test}}

\item{formula}{the \strong{right-hand side} of a glmer or glm-style formula.}

\item{filterset}{a call to \code{\link[=cluster_filterset]{cluster_filterset()}} that will be used to subset clusters.}

\item{contig_filter_args}{an expression passed to \code{\link[dplyr:filter]{dplyr::filter()}}.
Unlike \code{filter}, multiple criteria must be \code{&} together, rather than using
commas to separate. These act on \code{ccdb$contig_tbl}}

\item{tie_break_keys}{(optional) \code{character} naming fields in \code{contig_tbl}
that are used sort the contig table in descending order.
Used to break ties if \code{contig_filter_args} does not return a unique contig
for each cluster}

\item{add_cluster_tbl}{\code{logical} should the output be joined to the \code{cluster_tbl}?}

\item{keep_fit}{\code{logical} as to whether the fit objects should be returned as a list column}

\item{fitter}{a function taking arguments \code{formula}, \code{data}, \code{is_mixed} and \code{keep_fit} that is run on each cluster.  Should return a \code{tibble} or \code{data.frame}}

\item{silent}{\code{logical}. Should warnings from fitting functions should be suppressed?}
}
\value{
table with one row per cluster/term.
}
\description{
Typically one will want to stratify by chain by calling \code{cluster_test_by}, as this will calculate the number of cell "trials" separately depending on the chain recovered.
}
\section{Functions}{
\itemize{
\item \code{cluster_test_by}: split \code{ccdb} and conduct tests within strata
}}

\examples{
library(dplyr)
data(ccdb_ex)
ccdb_ex = cluster_germline(ccdb_ex)
trav1 = filter(ccdb_ex$cluster_tbl, v_gene == 'TRAV1')
cluster_logistic_test(~pop + (1|sample), ccdb_ex,
filterset = cluster_filterset(white_list= trav1))
# Fixed effect analysis of each cluster, by chain
prev4 = ccdb_ex$contig_tbl \%>\% group_by(cluster_idx) \%>\%
summarize(n()) \%>\% filter(`n()`>= 4)
cluster_test_by(ccdb = ccdb_ex, fields = 'chain',
tbl = 'cluster_tbl', formula = ~ pop, filterset = cluster_filterset(white_list= prev4))
}
