% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/seqArchRplus_curate_clusters.R
\name{curate_clusters}
\alias{curate_clusters}
\title{Curate clusters from seqArchR result}
\usage{
curate_clusters(
  sname,
  use_aggl = "ward.D",
  use_dist = "euclid",
  seqArchR_result,
  iter,
  pos_lab = NULL,
  regularize = TRUE,
  topn = 50,
  use_cutk = 2,
  need_change = NULL,
  change_to = NULL,
  final = FALSE,
  dir_path = NULL
)
}
\arguments{
\item{sname}{The sample name}

\item{use_aggl}{The agglomeration method to be used for hierarchical
clustering. This is passed on to `seqArchR::collate_seqArchR_result`.
See argument `aggl_method` in \link[seqArchR]{collate_seqArchR_result}.}

\item{use_dist}{The distance method to be used for hierarchical clustering.
This is passed on to \code{\link[seqArchR]{collate_seqArchR_result}}.
See argument `dist_method` in \link[seqArchR]{collate_seqArchR_result}.}

\item{seqArchR_result}{The seqArchR result object.}

\item{iter}{Specify which iteration of the seqArchR result should be used
for obtaining clusters.}

\item{pos_lab}{The position labels}

\item{regularize}{Logical. Specify TRUE if the basis vector comparison
is to be regularized. Requires you to set \code{`topn`} which is set to 50 as
default. See argument `regularize` in
\code{\link[seqArchR]{collate_seqArchR_result}}.}

\item{topn}{Numeric. The top N features (nucleotide-position pairs)
that will be used for distance computation, rest will be ignored.
See argument `topn` in \code{\link[seqArchR]{collate_seqArchR_result}}.}

\item{use_cutk}{Value of K (number of clusters) for cutting the hierarchical
clustering tree.}

\item{need_change}{A list of elements (cluster IDs in the input clusters)
that need re-assignment. Elements}

\item{change_to}{A list of elements (cluster IDs in the input clusters)
to be assigned to those that need re-assignment. In case there is a candidate
that needs to be put into a new, independent cluster of itself, use
0 (as numeric). Both \code{`need_change`} and \code{`change_to`} should
be empty lists if no re-assignment is to be performed.}

\item{final}{Logical, set to TRUE or FALSE}

\item{dir_path}{The /path/to/the/directory where files will be written.
Default is NULL.}
}
\value{
This function returns a list holding (a) 'curation_plot': plot showing the
dendrogram + sequence logos, (b) 'clust_assignments': the
cluster (re-)assignments performed, and (c) 'clusters_list':
the sequence clusters as a list.

to help
perform curation and document it.


When `final = FALSE`, the `curation_plot' shows the dendrogram + sequence
logos of clusters (ordered by \code{hclust} ordering).
The 'clusters_list' holds the hclust ordered clusters.
If the `dir_path`
is specified, a PDF file showing the same figure is also written at the
location using the default filename
`<Sample_name>_dend_arch_list_reg_top50_euclid_complete_<K>clusters.pdf`.

When `final = TRUE`, 'clusters_list' holds the clusters with
re-assignments executed, and 'curation_plot' of dendrogram + sequence logos
now has an additional panel showing the sequence logos upon collation of
clusters as specified by the re-assignments.
Also the cluster IDs in the dendrograms have colors showing the
re-assignments, i.e., elements that were re-assigned to different clusters,
also have appropriate color changes reflected.

When `dir_path` is provided, the curation plot is written to disk using
the same filename as before except for suffix 'final' attched to it.
}
\description{
seqArchR result stores the clusters obtained at every iteration.
It is possible that the previously chosen agglomeration and/or distance
method used with hierarchical clustering does not yield reasonable
clusters. This function enables minor curation of the clusters obtained
from the hierarchical clustering step.
}
\details{
This function helps the user work through the curation in at most three
steps.

1. This function performs hierarchical clustering on the seqArchR clusters
(of the specified iteration) to obtain a clustering result.
The resulting clustering is visualized by a dendrogram, color-coded cluster
assignments, and corresponding sequence logos. Using this visualization,
the user can identify/estimate the (nearly right) number of clusters to cut
the dendrogram. The **first call** uses K = 2.

2. Visually examine and count the tentative number of clusters (K) deemed
right. Because these architectures are now arranged by the hierarchical
clustering order, identifying this tentative value of K is much easier.
Call the function this **second** time with the identified value of K.
Look at the visualization now generated to determine if it is good enough,
i.e., it requires only minor re-assignments.

3. Identify cases of cluster assignments that you wish to re-assign to
different clusters. These can be noted as a list and supplied in a
subsequent call to the function.

4. In the **final call** to the function, set `final = TRUE`, supply the re-
assignments as two lists `need_change` and `change_to`.

More on re-assignments using arguments \code{need_change} and
\code{change_to}: If any element is to be put into a new cluster, use a
numeral 0 in change_to. This can be done in either scenario: when any
element is re-assigned as a singleton cluster of itself, or as clustered
with some other element coming from some other existing cluster. Consider,
for instance, among some 33 clusters identified by seqArchR, the following
re-assignments are executed.

Original_clustering <- list(c(1), c(2,3), c(4,5), c(6, 7))
need_change <- list(c(5), c(2), c(3, 6))
change_to <- list(1, 0, 0)

In the above, element 5 is re-assigned to the cluster containing element 1.
Element 2 is re-assigned to a new, singleton cluster of itself, while
elements 3 and 6 (which initially can belong to same/any two clusters) are
collated together. Note that it is important to use \code{c()}.

Also see examples below.
}
\examples{


library(Biostrings)
raw_seqs <- Biostrings::readDNAStringSet(
                          filepath = system.file("extdata",
                            "example_promoters45.fa.gz",
                            package = "seqArchRplus",
                            mustWork = TRUE)
                        )

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

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

## The example seqArchR result generally holds the raw sequences, but in
## this case, the result object is devoid of them in order to reduce size of
## example data
if(!("rawSeqs" \%in\% names(seqArchR_result)))
    seqArchR_result$rawSeqs <- raw_seqs

use_aggl <- "complete"
use_dist <- "euclid"

## get seqArchR clusters custom curated
seqArchR_clusts <- seqArchRplus::curate_clusters(sname = "sample1",
    use_aggl = use_aggl, use_dist = use_dist,
    seqArchR_result = seqArchR_result, iter = 5,
    pos_lab = NULL, regularize = FALSE, topn = 50,
    use_cutk = 5, final = FALSE, dir_path = tempdir())

## Form the lists need_change and change_to for re-assignments
need_change <- list(c(2))
change_to <- list(c(1))

## This fetches us clusters with custom/curated collation in _arbitrary_
## order. See the next function call to order_clusters_iqw that orders
## these clusters by their median/mean IQW

seqArchR_clusts <- seqArchRplus::curate_clusters(sname = "sample1",
    use_aggl = use_aggl, use_dist = use_dist,
    seqArchR_result = seqArchR_result, iter = 5,
    pos_lab = NULL, regularize = FALSE, topn = 50,
    use_cutk = 5,
    need_change = need_change, change_to = change_to,
    final = TRUE, dir_path = tempdir())



}
\author{
Sarvesh Nikumbh
}
