% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/seqArchRplus_cluster_annotations.R
\name{per_cluster_annotations}
\alias{per_cluster_annotations}
\title{per_cluster_annotations}
\usage{
per_cluster_annotations(
  sname = NULL,
  clusts = NULL,
  tc_gr = NULL,
  cager_obj = NULL,
  qLow = 0.1,
  qUp = 0.9,
  txdb_obj = NULL,
  tss_region = NULL,
  orgdb_obj = NULL,
  one_plot = TRUE,
  dir_path = NULL,
  txt_size = 12,
  use_suffix = NULL,
  use_prefix = "C",
  n_cores = 1
)
}
\arguments{
\item{sname}{Sample name. Default is NULL. This is a required argument
if the CAGEexp object is provided. See `cager_obj` argument}

\item{clusts}{List of sequence IDs in each cluster. This can be NULL only
when a BED file is passed to the argument `tc_gr`}

\item{tc_gr}{Tag clusters as \code{\link[GenomicRanges]{GRanges}} or a
BED file (specify filename with path). If `cager_obj` is not provided (i.e.,
 it is NULL), this argument is required. It will be ignored only if
 `cager_obj` is provided. Default is NULL}

\item{cager_obj}{A CAGEexp object obtained from the CAGEr package, if and
when CAGEr was used to process the raw CAGE data}

\item{qLow, qUp}{The interquantile boundaries to be considered for obtaining
tag clusters from the CAGEexp object. See \code{\link[CAGEr]{tagClusters}}}

\item{txdb_obj}{A TxDb object storing transcript metadata}

\item{tss_region}{For ChIPseeker}

\item{orgdb_obj}{Organism-level annotation package}

\item{one_plot}{Logical. Default is TRUE. If set to FALSE the barplots of
annotations per cluster are returned as a list, else all are condensed into
single plot}

\item{dir_path}{Specify the /path/to/directory to store results}

\item{txt_size}{Adjust text size for the plots}

\item{use_suffix, use_prefix}{Character. Specify any suffix and/or prefix
you wish to add to the cluster labels}

\item{n_cores}{Numeric. If you wish to parallelize annotation of peaks,
specify the number of cores. Default is 1 (serial)}
}
\value{
When `one_plot = TRUE`, a single plot where annotation barplots for each
cluster are put together (ordered as per the clusters in `clusts`).
Otherwise, a list of annotation barplots is returned (again ordered by
the clusters in `clusts`).
}
\description{
This function helps annotate the genomic regions specified in
`tc_gr` with features, namely, promoter-TSS (transcription start site),
exons, 5'UTR, 3'UTR, introns and (distal) intergenic regions. This requires
that the annotations are available as a TxDb object. The selected genomic
regions can be specified as a single GenomicRanges object. These regions
can be specified directly as a BED file (when available) or select specific
regions from a larger set of regions based on some clustering.

When working with CAGE data, if the CAGEr package was used and the
corresponding CAGEexp object is available, it can also be used -- see
`cager_obj` argument.
}
\details{
When annotations for only selected clusters are required, alter
the `clusts` argument to specify only those selected clusters. Because
the `clusts` list holds the IDs of sequences belonging to each cluster, the
corresponding records are selected from the `tc_gr` GRanges object. This
approach requires that sequence IDs in `clusts` are directly associated with
the ranges in `tc_gr`. Also, see examples.
}
\examples{

## Need the TxDb object to run these examples
if(require("TxDb.Dmelanogaster.UCSC.dm6.ensGene")){

library(GenomicRanges)
library(TxDb.Dmelanogaster.UCSC.dm6.ensGene)
library(ChIPseeker)

bed_fname <- system.file("extdata", "example_info_df.bed.gz",
         package = "seqArchRplus", mustWork = TRUE)

info_df <- read.delim(file = bed_fname,
         sep = "\t", header = TRUE)

tc_gr_from_df <- GenomicRanges::makeGRangesFromDataFrame(info_df,
                                                  keep.extra.columns = TRUE)

tc_gr <- readRDS(system.file("extdata", "example_tc_gr.rds",
         package = "seqArchRplus", mustWork = TRUE))

use_clusts <- readRDS(system.file("extdata", "example_clust_info.rds",
         package = "seqArchRplus", mustWork = TRUE))

tdir <- tempdir()

# Get annotations for all clusters in use_clusts
annotations_pl <- per_cluster_annotations(sname = "sample1",
                         clusts = use_clusts,
                         tc_gr = tc_gr_from_df,
                         txdb_obj = TxDb.Dmelanogaster.UCSC.dm6.ensGene,
                         one_plot = FALSE,
                         dir_path = tdir,
                         tss_region = c(-500,100))

# Get annotations for selected clusters in use_clusts
# -- First two clusters
selected_clusts <- lapply(seq(2), function(x) use_clusts[[x]])
# OR
# -- Mixed set of clusters, say 1 and 3 out of total 3
selected_clusts <- lapply(c(1,3), function(x) use_clusts[[x]])
#
annotations_pl <- per_cluster_annotations(sname = "sample1",
                         clusts = selected_clusts,
                         tc_gr = tc_gr,
                         txdb_obj = TxDb.Dmelanogaster.UCSC.dm6.ensGene,
                         one_plot = FALSE,
                         dir_path = tdir,
                         tss_region = c(-500,100))

# Alternatively, you can also directly specify a BED file to the `tc_gr`
# argument. This is useful when one may not have access to the CAGEexp
# object, but only clusters' information is available in a BED file.
#

annotations_pl <- per_cluster_annotations(sname = "sample1",
                         clusts = NULL,
                         tc_gr = bed_fname,
                         txdb_obj = TxDb.Dmelanogaster.UCSC.dm6.ensGene,
                         one_plot = FALSE,
                         dir_path = tdir,
                         tss_region = c(-500,100))
}

}
\author{
Sarvesh Nikumbh
}
