% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/plotting-functions.R
\name{integration_alluvial_plot}
\alias{integration_alluvial_plot}
\title{Alluvial plots for IS distribution in time.}
\usage{
integration_alluvial_plot(
  x,
  group = c("SubjectID", "CellMarker", "Tissue"),
  plot_x = "TimePoint",
  plot_y = "fragmentEstimate_sum_PercAbundance",
  alluvia = mandatory_IS_vars(),
  alluvia_plot_y_threshold = 1,
  top_abundant_tbl = TRUE,
  ...
)
}
\arguments{
\item{x}{A data frame. See details.}

\item{group}{Character vector containing the column names that identify
unique groups.}

\item{plot_x}{Column name to plot on the x axis}

\item{plot_y}{Column name to plot on the y axis}

\item{alluvia}{Character vector of column names that uniquely identify
alluvia}

\item{alluvia_plot_y_threshold}{Numeric value. Everything below this
threshold on y will be plotted in grey and aggregated. See details.}

\item{top_abundant_tbl}{Logical. Produce the summary top abundant tables
via \link{top_abund_tableGrob}?}

\item{...}{Additional arguments to pass on to \link{top_abund_tableGrob}}
}
\value{
For each group a list with the associated plot and optionally
the summary tableGrob
}
\description{
\lifecycle{experimental}
Alluvial plots allow the visualization of integration sites distribution
in different points in time in the same group.
This functionality requires the suggested package
\href{https://corybrunson.github.io/ggalluvial/}{ggalluvial}.
}
\details{
\subsection{Input data frame}{

The input data frame must contain all the columns specified in the
arguments \code{group}, \code{plot_x}, \code{plot_y} and \code{alluvia}. The standard
input for this function is the data frame obtained via the
\link{compute_abundance} function.
}

\subsection{Plotting threshold on y}{

The plotting threshold on the quantification on the y axis has the
function to highlight only relevant information on the plot and reduce
computation time. The default value is 1, that acts on the default column
plotted on the y axis which holds a percentage value. This translates
in natural language roughly as "highlight with colors only those
integrations (alluvia) that at least in 1 point in time have an
abundance value >= 1 \%". The remaining integrations will be plotted
as transparent in the strata.
}
}
\examples{
data("integration_matrices", package = "ISAnalytics")
data("association_file", package = "ISAnalytics")
aggreg <- aggregate_values_by_key(
    x = integration_matrices,
    association_file = association_file,
    value_cols = c("seqCount", "fragmentEstimate")
)
abund <- compute_abundance(x = aggreg)
alluvial_plots <- integration_alluvial_plot(abund,
    alluvia_plot_y_threshold = 0.5
)
ex_plot <- alluvial_plots[[1]]$plot +
    ggplot2::labs(
        title = "IS distribution over time",
        subtitle = "Patient 1, MNC BM",
        y = "Abundance (\%)",
        x = "Time point (days after GT)"
    )
print(ex_plot)
}
\seealso{
Other Plotting functions: 
\code{\link{CIS_volcano_plot}()},
\code{\link{HSC_population_plot}()},
\code{\link{circos_genomic_density}()},
\code{\link{sharing_heatmap}()},
\code{\link{sharing_venn}()},
\code{\link{top_abund_tableGrob}()}
}
\concept{Plotting functions}
