% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/viewClusterCy.R
\name{viewClusterCy}
\alias{viewClusterCy}
\title{Visualise Clustered MetaPathNet Networks in Cytoscape}
\usage{
viewClusterCy(
  cluster_matrix,
  label = c("none", "all", "non_background"),
  category = TRUE,
  network_title = "",
  collection_title = ""
)
}
\arguments{
\item{cluster_matrix}{A matrix or data.frame with at least five columns:
\code{source}, \code{target}, \code{interaction_type},
\code{source_cluster}, and \code{target_cluster}. Typically the direct
output of \code{clusterNetwork()}.}

\item{label}{Character; controls KEGG-based node labelling. One of:
\itemize{
\item \code{"none"} – no labels are shown on the Cytoscape network.
\item \code{"all"} – convert KEGG IDs to biological names and label all nodes.
\item \code{"non_background"} – convert and label only nodes in non-background
clusters. The background cluster is defined as the largest
community and is left unlabelled to reduce KEGG REST calls and visual clutter.
}}

\item{category}{Logical. If \code{TRUE}, node shapes are mapped to
basic categories: \code{"Compound"}, \code{"KO"}, \code{"Contextual"}.
If \code{FALSE}, all nodes use the same shape (ellipse).}

\item{network_title}{Character. Cytoscape network title. If empty or
\code{NULL}, defaults to \code{"cluster_network"}.}

\item{collection_title}{Character. Cytoscape collection title. If empty or
\code{NULL}, defaults to \code{"cluster_collection"}.}
}
\value{
Invisibly returns \code{NULL}. The function acts via side effects in
Cytoscape, creating and styling a new network.
}
\description{
Sends a cluster-annotated MetaPathNet network (typically the output of
\code{clusterNetwork()}) to Cytoscape for interactive exploration.
Nodes are coloured by community (cluster), optionally shaped by category
(compound / KO / contextual), and can be labelled with KEGG-derived names.
}
\details{
Cytoscape (version \strong{>= 3.9.0}) must be running and reachable via
\pkg{RCy3} before calling this function.

The function reconstructs node-level cluster membership from the
\code{source_cluster} and \code{target_cluster} columns, identifies the
largest community as a background cluster (for \code{label = "non_background"}),
optionally converts KEGG IDs to names via \pkg{KEGGREST}, and then creates a
Cytoscape network via \pkg{RCy3} with:
\itemize{
\item colour mapping by cluster,
\item shape mapping by node type (if \code{category = TRUE}),
\item node labels from the chosen \code{label} mode.
}

KEGG name conversion can be slow on large networks, especially with
\code{label = "all"}. For big MetaPathNet networks, \code{label = "non_background"}
is often a good compromise.
}
\examples{
## 1) Load the precomputed example network; see buildKeggNetwork() for its construction
data(MetaPathNet_example_network)

net_trp <- MetaPathNet_example_network

## 2) Detect communities on the full network graph
net_trp_clusters <- clusterNetwork(
  network_table = net_trp,
  method        = "leiden",
  resolution    = 0.01
)

\dontrun{
## Requires a running Cytoscape session for network layout and rendering
## 3) Recommended: full cluster-aware visualisation in Cytoscape
viewClusterCy(
  cluster_matrix    = net_trp_clusters,
  label             = "all",   # convert KEGG IDs to biological names and label all nodes
  category          = TRUE,    # shape by node type (Compound / KO / Contextual)
  network_title     = "Example network clusters",
  collection_title  = "MetaPathNet_Examples"
)

## 4) Faster option for larger networks: label only non-background clusters
viewClusterCy(
  cluster_matrix    = net_trp_clusters,
  label             = "non_background",
  category          = TRUE,
  network_title     = "Example network clusters (foreground labels)",
  collection_title  = "MetaPathNet_Examples"
)
}

}
\seealso{
\code{\link{clusterNetwork}} for community detection, and
\code{\link{viewNetworkCy}} for non-clustered KEGG network visualisation.
}
