% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/vizCirclize.R
\name{vizCirclize}
\alias{vizCirclize}
\title{Visualize Clonal Relationships as a Chord Diagram}
\usage{
vizCirclize(
  sc.data,
  clone.call = NULL,
  group.by = NULL,
  method = c("unique", "jaccard", "overlap"),
  proportion = FALSE,
  directional = FALSE,
  self.link = 1,
  include.self = TRUE,
  transparency = 0.5,
  link.visible = TRUE,
  annotate.sectors = TRUE,
  min.shared = 0,
  palette = "inferno",
  sector.colors = NULL,
  export.table = FALSE
)
}
\arguments{
\item{sc.data}{The single-cell object after \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{group.by}{A column header (or vector of column headers for hierarchical
grouping) in the metadata to group the analysis by.}

\item{method}{The method for calculating link values: \code{"unique"} (default) counts
unique shared clones, \code{"jaccard"} calculates Jaccard similarity,
\code{"overlap"} calculates overlap coefficient.}

\item{proportion}{Calculate the relationship by unique clones (\code{FALSE}, default)
or normalized by proportion (\code{TRUE}).}

\item{directional}{If \code{TRUE}, show directional arrows on chords. Default is \code{FALSE}.}

\item{self.link}{How to handle self-links. \code{1} = show as loops, \code{2} = show as
parallel lines. Default is \code{1}.}

\item{include.self}{Include self-links (clones within a single group). Default is \code{TRUE}.}

\item{transparency}{Transparency of the chord links (0-1). Default is \code{0.5}.}

\item{link.visible}{If \code{FALSE}, hide the chord links and show only sectors.}

\item{annotate.sectors}{If \code{TRUE} (default), display sector names.}

\item{min.shared}{Minimum number of shared clones to include a link (default 0).}

\item{palette}{Colors to use for sectors - input any \link[grDevices:palettes]{hcl.pals}.}

\item{sector.colors}{Named vector of colors for specific sectors. Overrides palette.}

\item{export.table}{If \code{TRUE}, returns the data instead of plotting.}
}
\value{
Invisibly returns the circlize data list. If circlize is not installed
or \code{export.table = TRUE}, returns the data that would be used for plotting.
}
\description{
This function creates a chord diagram visualization of shared clones between
groups using the circlize package. It provides a convenient wrapper around
\code{\link[=getCirclize]{getCirclize()}} that handles the circlize plotting code automatically.
}
\details{
This function requires the circlize package to be installed. If circlize is
not available, the function will return the data that would be used for plotting
and provide instructions for manual plotting.

The chord diagram shows relationships between groups (sectors) where the width
of each chord represents the number or proportion of shared clones between
the connected groups.
}
\examples{
\dontrun{
# Getting the combined contigs
combined <- combineTCR(contig_list,
                        samples = c("P17B", "P17L", "P18B", "P18L",
                                    "P19B","P19L", "P20B", "P20L"))

# Getting a sample of a Seurat object
scRep_example <- get(data("scRep_example"))
scRep_example <- combineExpression(combined,
                                   scRep_example)

# Simple chord diagram
vizCirclize(scRep_example, group.by = "seurat_clusters")

# Directional chord diagram with arrows
vizCirclize(scRep_example,
            group.by = "seurat_clusters",
            directional = TRUE)

# Multi-level grouping
scRep_example$Patient <- substring(scRep_example$orig.ident, 1, 3)
vizCirclize(scRep_example,
            group.by = c("Patient", "seurat_clusters"))
}

}
\seealso{
\code{\link[=getCirclize]{getCirclize()}} for generating the underlying data
}
\author{
Nick Borcherding
}
\concept{SC_Functions}
