% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/clonalBin.R
\name{clonalBin}
\alias{clonalBin}
\title{Bin Clones by Frequency or Proportion}
\usage{
clonalBin(
  input.data,
  clone.call = NULL,
  chain = "both",
  group.by = NULL,
  proportion = TRUE,
  clone.size = NULL,
  cloneCall = NULL,
  cloneSize = NULL
)
}
\arguments{
\item{input.data}{The product of \code{\link[=combineTCR]{combineTCR()}}, \code{\link[=combineBCR]{combineBCR()}}, or
\code{\link[=combineExpression]{combineExpression()}}.}

\item{clone.call}{Defines the clonal sequence grouping. Accepted values
are: \code{gene} (VDJC genes), \code{nt} (CDR3 nucleotide sequence), \code{aa} (CDR3 amino
acid sequence), or \code{strict} (VDJC + nt). A custom column header can also be used.}

\item{chain}{The TCR/BCR chain to use. Use \code{both} to include both chains
(e.g., TRA/TRB). Accepted values: \code{TRA}, \code{TRB}, \code{TRG}, \code{TRD}, \code{IGH}, \code{IGL}
(for both light chains), \code{both}.}

\item{group.by}{A column header in the metadata to group the analysis
by (e.g., "sample", "treatment"). If \code{NULL}, data will be analyzed
by list element.}

\item{proportion}{Whether to use proportion (\code{TRUE}) or total
frequency (\code{FALSE}) of the clone for binning.}

\item{clone.size}{The bins for the grouping based on proportion or frequency.
If proportion is \code{FALSE} and the clone.size values are not set high enough
based on frequency, the upper limit of clone.size will be automatically
updated.}

\item{cloneCall}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Use \code{clone.call} instead.}

\item{cloneSize}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Use \code{clone.size} instead.}
}
\value{
A list of data frames with clonal frequency, clonal proportion,
and cloneSize columns added.
}
\description{
This function adds a clonal grouping variable (\code{cloneSize}) to the output
of \code{\link[=combineTCR]{combineTCR()}}, \code{\link[=combineBCR]{combineBCR()}}, or \code{\link[=combineExpression]{combineExpression()}}. It calculates
the clonal frequency and proportion, then bins clones into categories based
on customizable thresholds. This is useful for categorizing clones prior to
downstream analysis or visualization.
}
\examples{
# Getting the combined contigs
combined <- combineTCR(contig_list,
                        samples = c("P17B", "P17L", "P18B", "P18L",
                                    "P19B","P19L", "P20B", "P20L"))

# Adding clonal bins with default settings (proportion-based)
combined <- clonalBin(combined)

# Adding clonal bins based on frequency
combined <- clonalBin(combined,
                      proportion = FALSE,
                      clone.size = c(Rare = 1, Small = 5, Medium = 20,
                                     Large = 100, Hyperexpanded = 500))

# Using a custom grouping variable
combined <- addVariable(combined,
                        variable.name = "Type",
                        variables = rep(c("B", "L"), 4))
combined <- clonalBin(combined, group.by = "Type")

}
\author{
Nick Borcherding
}
\concept{Clonal_Analysis}
