% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/permutation-testing.R
\name{cluster_permute_test}
\alias{cluster_permute_test}
\title{Tests for independence between labels and covariates using permutation of cells}
\usage{
cluster_permute_test(
  ccdb,
  cell_covariate_keys,
  cell_label_key = ccdb$cluster_pk,
  cell_stratify_keys,
  statistic,
  contrasts = NULL,
  n_perm,
  alternative = c("two.sided", "less", "greater"),
  sanity_check_strata = TRUE,
  ...
)
}
\arguments{
\item{ccdb}{\code{ContigCellDB}}

\item{cell_covariate_keys}{\code{character} naming fields in \code{ccdb$cell_tbl}}

\item{cell_label_key}{\code{character} naming a single field in \code{ccdb$cell_tbl}}

\item{cell_stratify_keys}{optional \code{character} naming fields in \code{ccdb$cell_tbl} under which permutations of \code{cell_label_key} will occur.
This means that the test will occur conditional on these covariates.
Must be disjoint from  \code{cell_covariate_keys}.}

\item{statistic}{function of label (vector) and covariate (data.frame).
If this returns a vector, then by default each level will be compared against each other, pairwise, but see the next section.}

\item{contrasts}{an optional list of numeric vectors.
Each will be dotted with the statistic, or optionally a matrix provided in which case each \strong{row} would be tested one-by-one.}

\item{n_perm}{number of permutations to run}

\item{alternative}{\code{character} naming the direction \code{statistic} should be fall under the alternative hypothesis}

\item{sanity_check_strata}{\code{logical}, should \code{cell_stratify_keys} be checked for sanity?}

\item{...}{passed to \code{statistic}}
}
\value{
a list containing the observed value of the statistic, the permuted values of the statistic, its expectation (under independence), a p-value, and the Monte Carlo standard error (of the expected value).
}
\description{
This tests a statistic for association between labels (for instance, cluster/clonal ID) and covariates (for instance, subject or treatment) by permuting the link between the two.
Each observation represents a cell.
\code{statistic} is any function of \code{labels}
}
\examples{
library(dplyr)
# covariate should name one or more columns in `cell_tbl`

cluster_idx = c(1, 1, 1, 2, 2, 3, 3)
subject = c('A', 'A', 'B', 'B', 'B', 'C', 'C')
contig_tbl = tibble(contig_pk = seq_along(cluster_idx), cluster_idx, subject)
ccdb_test = ContigCellDB(contig_tbl = contig_tbl, contig_pk = 'contig_pk',
cell_pk = c('contig_pk', 'subject', 'cluster_idx'), cluster_pk = 'cluster_idx')
ccdb_test$cell_tbl

clust_test = cluster_permute_test(ccdb_test, 'subject', 'cluster_idx',
statistic = purity, n_perm  = 50)
library(ggplot2)
plot_permute_test(perm_test = clust_test)
tidy.PermuteTest(clust_test)
}
\seealso{
\code{\link[=purity]{purity()}}
}
