% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/plot.microNetProps.R
\name{plot.microNetProps}
\alias{plot.microNetProps}
\alias{plot}
\title{Plot Method for microNetProps Objects}
\usage{
\method{plot}{microNetProps}(x,
  layout = "spring",
  sameLayout = FALSE,
  layoutGroup = "union",
  repulsion = 1,
  groupNames = NULL,
  groupsChanged = FALSE,
  labels = NULL,
  shortenLabels = "none",
  labelLength = 6L,
  labelPattern = c(5, "'", 3, "'", 3),
  charToRm = NULL,
  labelScale = TRUE,
  labelFont = 1,
  labelFile = NULL,

  # Nodes:
  nodeFilter = "none",
  nodeFilterPar = NULL,
  rmSingles = "none",
  nodeSize = "fix",
  normPar = NULL,
  nodeSizeSpread = 4,
  nodeColor = "cluster",
  colorVec = NULL,
  featVecCol = NULL,
  sameFeatCol = TRUE,
  sameClustCol = TRUE,
  sameColThresh = 2L,
  nodeShape = NULL,
  featVecShape = NULL,
  nodeTransp = 60,
  borderWidth = 1,
  borderCol = "gray80",

  # Hubs:
  highlightHubs = TRUE,
  hubTransp = NULL,
  hubLabelFont = NULL,
  hubBorderWidth = NULL,
  hubBorderCol = "black",

  # Edges:
  edgeFilter = "none",
  edgeFilterPar = NULL,
  edgeInvisFilter = "none",
  edgeInvisPar = NULL,
  edgeWidth = 1,
  negDiffCol = TRUE,
  posCol = NULL,
  negCol = NULL,
  cut = NULL,
  edgeTranspLow = 0,
  edgeTranspHigh = 0,

  # Additional arguments:
  cexNodes = 1,
  cexHubs = 1.2,
  cexLabels = 1,
  cexHubLabels = NULL,
  cexTitle = 1.2,
  showTitle = NULL,
  title1 = NULL,
  title2 = NULL,
  mar = c(1, 3, 3, 3),
  doPlot = TRUE,
  ...)
}
\arguments{
\item{x}{object of class \code{microNetProps}}

\item{layout}{indicates the layout used for defining node positions. Can be
a character with one of the layouts provided by
\code{\link[qgraph]{qgraph}}: \code{"spring"} (default), \code{"circle"},
or \code{"groups"}. Alternatively, the layouts provided by igraph (see
\code{\link[igraph:layout_]{layout\_}} are accepted (must be given as
character, e.g. \code{"layout_with_fr"}). Can also be a matrix with row
number equal to the number of nodes and two columns corresponding to the x
and y coordinate.}

\item{sameLayout}{logical. Indicates whether the same layout should be used
for both networks. Ignored if \code{x} contains only one network. See
argument \code{layoutGroup}.}

\item{layoutGroup}{numeric or character. Indicates the group, where the 
layout is taken from if argument \code{sameLayout} is \code{TRUE}. 
The layout is computed for group 1 (and adopted for group 2) if set to "1" 
and it is computed for group 2 if set to "2". Can alternatively be set to
"union" (default) to compute a union of both layouts, where the nodes are 
placed as optimal as possible equally for both networks.}

\item{repulsion}{positive numeric value indicating the strength of repulsive
forces in the "spring" layout. Nodes are placed closer together for smaller
values and further apart for higher values. See the \code{repulsion}
argument of \code{\link[qgraph]{qgraph}}.}

\item{groupNames}{character vector with two entries naming the groups to
which the networks belong. Defaults to the group names returned by 
\code{\link{netConstruct}}: If the data set is split according to a group
variable, its factor levels (in increasing order) are used. Ignored if
arguments \code{title1} and \code{title2} are set or if a single network is
plotted.}

\item{groupsChanged}{logical. Indicates the order in which the networks are
plotted. If \code{TRUE}, the order is exchanged. See details. Defaults to
\code{FALSE}.}

\item{labels}{defines the node labels. Can be a named character vector, which 
is used for both groups (then, the adjacency matrices in \code{x} must 
contain the same variables). 
Can also be a list with two named vectors (names must match the row/column 
names of the adjacency matrices). If \code{FALSE}, no labels are plotted. 
Defaults to the row/column names of the adjacency matrices.}

\item{shortenLabels}{character indicating how to shorten node labels. 
Ignored if node labels are defined via \code{labels}. NetCoMi's function 
\code{\link{editLabels}()} is used for label editing.
Available options are:
\describe{
\item{\code{"intelligent"}}{Elements of \code{charToRm} are removed,
labels are shortened to length \code{labelLength}, and duplicates are
removed using \code{labelPattern}.}
\item{\code{"simple"}}{Elements of \code{charToRm} are  removed and labels
are shortened to length \code{labelLength}.}
\item{\code{"none"}}{Default. Original dimnames of the adjacency matrices 
are used.} }}

\item{labelLength}{integer defining the length to which labels shall
be shortened if \code{shortenLabels} is set to \code{"simple"} or 
\code{"intelligent"}. Defaults to 6.}

\item{labelPattern}{vector of three or five elements, which is used if 
argument \code{shortenLabels} is set to \code{"intelligent"}. 
If cutting a label to length \code{labelLength} leads to duplicates, 
the label is shortened according to \code{labelPattern}, 
where the first entry gives the length of the first part, 
the second entry is used a separator, and the third entry
is the length of the third part. If \code{labelPattern} has five elements 
and the shortened labels are still not unique, 
the fourth element serves as further separator, and the fifth element gives
the length of the last label part. Defaults to c(5, "'", 3, "'", 3).
If the data contains, for example, three bacteria "Streptococcus1",
"Streptococcus2" and "Streptomyces", they are by default shortened to 
"Strep'coc'1", "Strep'coc'2", and "Strep'myc".}

\item{charToRm}{vector with characters to remove from node names. Ignored if
labels are given via \code{labels}.}

\item{labelScale}{logical. If \code{TRUE}, node labels are scaled according 
to node size}

\item{labelFont}{integer defining the font of node labels. Defaults to 1.}

\item{labelFile}{optional character of the form "<file name>.txt" naming a 
file where the original and renamed node labels are stored. The file is 
stored into the current working directory.}

\item{nodeFilter}{character indicating whether and how nodes should be
filtered. Possible values are:
\describe{
\item{\code{"none"}}{Default. All nodes are plotted.}
\item{\code{"highestConnect"}}{x nodes with highest connectivity (sum of
edge weights) are plotted.}
\item{\code{"highestDegree"}, \code{"highestBetween"}, 
\code{"highestClose"}, \code{"highestEigen"}}{x nodes with highest
degree/betweenness/closeness/eigenvector centrality are plotted.}
\item{\code{"clustTaxon"}}{Only nodes belonging the same cluster as to
variables that are given as character vector via  \code{nodeFilterPar}.}
\item{\code{"clustMin"}}{Plotted are only nodes belonging to clusters with
a minimum number of nodes of x.}
\item{\code{"names"}}{Character vector with variable names to be 
plotted}}\cr
Necessary parameters (e.g. "x") are given via the argument
\code{nodeFilterPar}.}

\item{nodeFilterPar}{parameters needed for the filtering method defined by
\code{nodeFilter}.}

\item{rmSingles}{character value indicating how to handle unconnected nodes.
Possible values are \code{"all"} (all single nodes are deleted),
\code{"inboth"} (only nodes that are unconnected in both networks are
removed) or \code{"none"} (default; no nodes are removed). Cannot be set to
\code{"all"}, if the same layout is used for both networks.}

\item{nodeSize}{character indicating how node sizes should be determined.
Possible values are: \describe{
\item{\code{"fix"}}{Default. All nodes have same size (hub size can be
defined separately via \code{cexHubs}).}
\item{\code{"degree"}, \code{"betweenness"}, \code{"closeness"},
\code{"eigenvector"}}{Size scaled according to node's centrality}
\item{\code{"counts"}}{Size scaled according to the sum of counts (of
microbes or samples, depending on what nodes express).}
\item{\code{"normCounts"}}{Size scaled according to the sum of normalized
counts (of microbes or samples), which are exported by
\code{netConstruct}.}
\item{\code{"TSS", "fractions", "CSS", "COM", "rarefy", "VST", "clr", 
"mclr"}}{Size scaled according to the sum of normalized
counts. Available are the same options as for \code{normMethod} in
\code{\link{netConstruct}}. Parameters are set via \code{normPar}.}
}}

\item{normPar}{list with parameters passed to the function for normalization
if \code{nodeSize} is set to a normalization method. Used analogously to
\code{normPar} of \code{\link{netConstruct}()}.}

\item{nodeSizeSpread}{positive numeric value indicating the spread of node
sizes. The smaller the value, the more similar are the node sizes. Node 
sizes are calculated by: (x - min(x)) / (max(x) - min(x)) * nodeSizeSpread 
+ cexNodes. For \code{nodeSizeSpread = 4} (default) and 
\code{cexNodes = 1}, node sizes range from 1 to 5.}

\item{nodeColor}{a character specifying the node colors. Possible values are
\code{"cluster"} (colors according to determined clusters),
\code{"feature"} (colors according to node's features defined by
\code{featVecCol}), \code{"colorVec"} (the vector \code{colorVec}). For the
former two cases, the colors can be specified via \code{colorVec}. If
\code{colorVec} is not defined, the \code{rainbow} function from
\code{grDevices} package  is used. Also accepted is a character value
defining a color, which is used for all nodes. If \code{NULL}, "grey40" is
used for all nodes.}

\item{colorVec}{a vector or list with two vectors used to specify node 
colors. Different usage depending on the "nodeColor" argument:
\describe{
\item{\code{nodeColor = "cluster"}}{\code{colorVec} must be a vector. 
Depending on the \code{sameClustCol} argument, the colors are used only in 
one or both networks. If the vector is not long enough, a warning is 
returned and colors from \code{rainbow()} are used for the remaining 
clusters.}
\item{\code{nodeColor = "feature"}}{Defines a color for each level of 
\code{featVecCol}. Can be a list with two vectors used for the two networks 
(for a single network, only the first element is used) or a vector, which 
is used for both groups if two networks are plotted.}
\item{\code{nodeColor = "colorVec"}}{\code{colorVec} defines a color for 
each node implying that its names must match the node's names (which is 
also ensured if names match the colnames of the original count matrix). 
Can be a list with two vectors used for the two networks (for a single 
network, only the first element is used) or a vector, which is used for 
both groups if two networks are plotted.}}}

\item{featVecCol}{a vector with a feature for each node. Used for coloring
nodes if \code{nodeColor} is set to \code{"feature"}. Is coerced to a
factor. If \code{colorVec} is given, its length must be larger than or
equal to the number of feature levels.}

\item{sameFeatCol}{logical indicating whether the same color should be used 
for same features in both networks (only used if two networks are plotted, 
\code{nodeColor = "feature"}, and no color vector/list is given (via 
\code{featVecCol})).}

\item{sameClustCol}{if TRUE (default) and two networks are plotted, clusters
having at least \code{sameColThresh} nodes in common have the same color.
Only used if \code{nodeColor} is set to \code{"cluster"}.}

\item{sameColThresh}{indicates how many nodes a cluster must have in common
in the two groups to have the same color. See argument \code{sameClustCol}.
Defaults to 2.}

\item{nodeShape}{character vector specifying node shapes. Possible values
are \code{"circle"} (default), \code{"square"}, \code{"triangle"}, and
\code{"diamond"}. If \code{featVecShape} is not \code{NULL}, the length of
\code{nodeShape} must equal the number of factor levels given by
\code{featVecShape}. Then, each shape is assigned to one factor level (in
increasing order). If \code{featVecShape} is \code{NULL}, the first shape
is used for all nodes. See the example.}

\item{featVecShape}{a vector with a feature for each node. If not \code{NULL},
a different node shape is used for each feature. Is coerced to factor mode.
The maximum number of factor levels is 4 corresponding to the four possible
shapes defined via \code{nodeShape}.}

\item{nodeTransp}{an integer between 0 and 100 indicating the transparency of
node colors. 0 means no transparency, 100 means full transparency. Defaults
to 60.}

\item{borderWidth}{numeric specifying the width of node borders. Defaults to
1.}

\item{borderCol}{character specifying the color of node borders. Defaults to
"gray80"}

\item{highlightHubs}{logical indicating if hubs should be highlighted. If
\code{TRUE}, the following features can be defined separately for hubs:
transparency (by \code{hubTransp}), label font (by \code{hubLabelFont}),
border width (by \code{hubBorderWidth}), and border color (by
\code{hubBorderCol}).}

\item{hubTransp}{numeric between 0 and 100 specifying the color transparency
of hub nodes. See argument \code{nodeTransp}. Defaults to
\code{0.5*nodeTransp}. Ignored if \code{highlightHubs} is \code{FALSE}.}

\item{hubLabelFont}{integer specifying the label font of hub nodes. Defaults
to \code{2*labelFont}. Ignored if \code{highlightHubs} is \code{FALSE}.}

\item{hubBorderWidth}{numeric specifying the border width of hub nodes.
Defaults to \code{2*borderWidth}. Ignored if \code{highlightHubs} is
\code{FALSE}.}

\item{hubBorderCol}{character specifying the border color of hub nodes.
Defaults to \code{"black"}. Ignored if \code{highlightHubs} is 
\code{FALSE}.}

\item{edgeFilter}{character specifying how edges are filtered. 
Possible values are:
\describe{
\item{\code{"none"}}{Default. All edges are plotted.}
\item{\code{"threshold"}}{For association networks, only edges 
corresponding to an absolute association >= x are plotted. For 
dissimilarity networks, only edges corresponding to a dissimilarity <= x 
are plotted. The behavior is similar to that of sparsification via threshold 
in netConstruct().}
\item{\code{"highestWeight"}}{The first x edges with highest edge weight 
are plotted.} 
}
x is defined by \code{edgeFilterPar}, respectively.}

\item{edgeFilterPar}{numeric specifying the "x" in \code{edgeFilter}.}

\item{edgeInvisFilter}{similar to \code{edgeFilter} but the edges are removed
only after computing the layout so that edge removal does not influence the
layout. Defaults to \code{"none"}.}

\item{edgeInvisPar}{numeric specifying the "x" in \code{edgeInvisFilter}.}

\item{edgeWidth}{numeric specifying the edge width. See argument
\code{"edge.width"} of \code{\link[qgraph]{qgraph}}.}

\item{negDiffCol}{logical indicating if edges with a negative corresponding
association should be colored different. If \code{TRUE} (default), argument
\code{posCol} is used for edges with positive association and \code{negCol}
for those with negative association. If \code{FALSE} and for dissimilarity
networks, only \code{posCol} is used.}

\item{posCol}{vector (character or numeric) with one or two elements
specifying the color of edges with positive weight and also for edges with
negative weight if \code{negDiffCol} is set to \code{FALSE}. The first
element is used for edges with weight below \code{cut} and the second for
edges with weight above \code{cut}. If a single value is given, it is used
for both cases. Defaults to \code{c("#009900", "darkgreen")}.}

\item{negCol}{vector (character or numeric) with one or two elements
specifying the color of edges with negative weight. The first
element is used for edges with absolute weight below \code{cut} and the
second for edges with absolute weight above \code{cut}. If a single value
is given, it is used for both cases. Ignored if \code{negDiffCol} is
\code{FALSE}. Defaults to \code{c("red", "#BF0000")}.}

\item{cut}{defines the \code{"cut"} parameter of 
\code{\link[qgraph]{qgraph}}. Can
be either a numeric value (is used for both groups if two networks are
plotted) or vector of length two. The default is set analogous to that in
\code{\link[qgraph]{qgraph}}: "0 for graphs with less then 20 nodes. For
larger graphs the cut value is automatically chosen to be equal to the
maximum of the 75th quantile of absolute edge strengths or the edge
strength corresponding to 2n-th edge strength (n being the number of
nodes.)" If two networks are plotted, the mean of the two determined cut 
parameters is used so that edge thicknesses are comparable.}

\item{edgeTranspLow}{numeric value between 0 and 100 specifying the
transparency of edges with weight below \code{cut}. The higher this value,
the higher the transparency.}

\item{edgeTranspHigh}{analogous to \code{edgeTranspLow}, but used for edges
with weight ABOVE \code{cut}.}

\item{cexNodes}{numeric scaling node sizes. Defaults to 1.}

\item{cexHubs}{numeric scaling hub sizes. Only used if \code{nodeSize} is set
to \code{"hubs"}.}

\item{cexLabels}{numeric scaling node labels. Defaults to 1. If set to 0, no
node labels are plotted.}

\item{cexHubLabels}{numeric scaling the node labels of hub nodes. Equals 
\code{cexLabels} by default. Ignored, if \code{highlightHubs = FALSE}.}

\item{cexTitle}{numeric scaling title(s). Defaults to 1.2.}

\item{showTitle}{if \code{TRUE}, a title is shown for each network, which is
either defined via \code{groupNames}, or \code{title1} and \code{title2}.
Defaults to \code{TRUE} if two networks are plotted and \code{FALSE} for
a single network.}

\item{title1}{character giving a title for the first network.}

\item{title2}{character giving a title for the second network (if existing).}

\item{mar}{a numeric vector of the form c(bottom, left, top, right) defining
the plot margins. Works similar to the \code{mar} argument in
\code{\link[graphics]{par}}. Defaults to c(1,3,3,3).}

\item{doPlot}{logical. If \code{FALSE}, the network plot is suppressed. 
Useful for saving the output (e.g., the layout) without plotting.}

\item{...}{further arguments being passed to \code{\link[qgraph]{qgraph}}, 
which is used for network plotting.}
}
\value{
Returns (invisibly) a list with the following elements: \tabular{ll}{
  \code{q1,q2}\tab the qgraph object(s)\cr
  \code{layout}\tab layout(s) specifying node positions\cr
  \code{nodecolor}\tab one or two vectors with node colors (one for each 
  group) \cr
  \code{labels}\tab one or two vectors with node labels}
}
\description{
Plotting objects of class \code{microNetProps}.
}
\examples{
# Load data sets from American Gut Project (from SpiecEasi package)
data("amgut1.filt")

# Network construction
amgut_net <- netConstruct(amgut1.filt, measure = "pearson",
                          filtTax = "highestVar",
                          filtTaxPar = list(highestVar = 50),
                          zeroMethod = "pseudoZO", normMethod = "clr",
                          sparsMethod = "threshold", thresh = 0.3)

# Network analysis
amgut_props <- netAnalyze(amgut_net)

### Network plots ###
# Clusters are used for node coloring: 
plot(amgut_props, 
     nodeColor = "cluster")

# Remove singletons
plot(amgut_props, 
     nodeColor = "cluster", 
     rmSingles = TRUE)

# A higher repulsion places nodes with high edge weight closer together
plot(amgut_props, 
     nodeColor = "cluster", 
     rmSingles = TRUE, 
     repulsion = 1.2)

# A feature vector is used for node coloring
# (this could be a vector with phylum names of the ASVs)
set.seed(123456)
featVec <- sample(1:5, nrow(amgut1.filt), replace = TRUE)

# Names must be equal to ASV names
names(featVec) <- colnames(amgut1.filt)

plot(amgut_props, 
     rmSingles = TRUE, 
     nodeColor = "feature", 
     featVecCol = featVec,
     colorVec = heat.colors(5))

# Use a further feature vector for node shapes
shapeVec <- sample(1:3, ncol(amgut1.filt), replace = TRUE)
names(shapeVec) <- colnames(amgut1.filt)

plot(amgut_props,
     rmSingles = TRUE,
     nodeColor = "feature",
     featVecCol = featVec,
     colorVec = heat.colors(5), 
     nodeShape = c("circle", "square", "diamond"),
     featVecShape = shapeVec, 
     highlightHubs = FALSE)

}
