% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/plotSoilRelationGraph.R
\name{plotSoilRelationGraph}
\alias{plotSoilRelationGraph}
\title{Plot a component relation graph}
\usage{
plotSoilRelationGraph(
  m,
  s = "",
  plot.style = c("network", "dendrogram", "none"),
  graph.mode = "upper",
  spanning.tree = NULL,
  del.edges = NULL,
  vertex.scaling.method = "degree",
  vertex.scaling.factor = 2,
  edge.scaling.factor = 1,
  vertex.alpha = 0.65,
  edge.transparency = 1,
  edge.col = grey(0.5),
  edge.highlight.col = "royalblue",
  g.layout = igraph::layout_with_fr,
  vertex.label.color = "black",
  delete.singletons = FALSE,
  ...
)
}
\arguments{
\item{m}{adjacency matrix}

\item{s}{central component; an empty character string is interpreted as no central component}

\item{plot.style}{plot style ('network', or 'dendrogram'), or 'none' for no graphical output}

\item{graph.mode}{interpretation of adjacency matrix: 'upper' or 'directed', see details}

\item{spanning.tree}{plot the minimum or maximum spanning tree ('min', 'max'), or, max spanning tree plus edges with weight greater than the n-th quantile specified in \code{spanning.tree}. See details and examples.}

\item{del.edges}{optionally delete edges with weights less than the specified quantile (0-1)}

\item{vertex.scaling.method}{'degree' (default) or 'distance', see details}

\item{vertex.scaling.factor}{scaling factor applied to vertex size}

\item{edge.scaling.factor}{optional scaling factor applied to edge width}

\item{vertex.alpha}{optional transparency setting for vertices (0-1)}

\item{edge.transparency}{optional transparency setting for edges (0-1)}

\item{edge.col}{edge color, applied to all edges}

\item{edge.highlight.col}{edge color applied to all edges connecting to component named in \code{s}}

\item{g.layout}{an igraph layout function, defaults to \code{igraph::layout_with_fr}}

\item{vertex.label.color}{vertex label color}

\item{delete.singletons}{optionally delete vertices with no edges (\code{degree == 0})}

\item{...}{further arguments passed to plotting function}
}
\value{
an igraph \code{graph} object is invisibly returned
}
\description{
Plot a component relation graph based on an adjacency or similarity matrix.
}
\details{
Vertex size is based on a normalized index of connectivity:
\itemize{
\item "degree" size = \code{sqrt(igraph::degree(g) / max(igraph::degree(g))) * scaling.factor}
\item "distance" size = \code{sqrt(igraph::distance(V -> s) / max(igraph::distance(V -> s))) * scaling.factor}, where distance(V->s) is the distance from all nodes to the named series, \code{s}.
}

Edge width can be optionally scaled by edge weight by specifying an \code{edge.scaling.factor} value. The maximum spanning tree represents a sub-graph where the sum of edge weights are maximized. The minimum spanning tree represents a sub-graph where the sum of edge weights are minimized. The maximum spanning tree is likely a more useful simplification of the full graph, in which only the strongest relationships (e.g. most common co-occurrences) are preserved.

The maximum spanning tree + edges with weights > n-th quantile is an experimental hybrid. The 'backbone' of the graph is created by the maximum spanning tree, and augmented by 'strong' auxiliary edges--defined by a value between 0 and 1.

The \code{graph.mode} argument is passed to \code{igraph::graph_from_adjacency_matrix()} and determines how vertex relationships are coded in the adjacency matrix \code{m}. Typically, the default value of 'upper' (the upper triangle of \code{m} contains adjacency information) is the desired mode. If \code{m} contains directional information, set \code{graph.mode} to 'directed'. This has the side-effect of altering the default community detection algorithm from \code{igraph::cluster_fast_greedy} to \code{igraph::cluster_walktrap}.
}
\note{
The default output for \code{plot.style=network} is nondeterministic when using most igraph layouts, including the default \code{igraph::layour_with_fr}. Previous versions of sharpshootR hard-coded a random seed via \code{set.seed(1010101)}. Consider adding this if you are trying to recreate previous output.
}
\examples{

# consider setting a random seed for consistent output from run to run
# prior releases of sharpshootR used:
# set.seed(1010101)

if (requireNamespace("igraph") && requireNamespace("vegan")) {
  # load sample data set
  data(amador)

  # create weighted adjacency matrix (see ?component.adj.matrix for details)
  m <- component.adj.matrix(amador)

  # plot network diagram, with Amador soil highlighted
  plotSoilRelationGraph(m, s='amador')

  # dendrogram representation
  plotSoilRelationGraph(m, s='amador', plot.style='dendrogram')

  # compare methods
  m.o <- component.adj.matrix(amador, method='occurrence')

  op <- par(no.readonly = TRUE)

  par(mfcol=c(1,2))
  plotSoilRelationGraph(m, s='amador', plot.style='dendrogram')
  title('community matrix')
  plotSoilRelationGraph(m.o, s='amador', plot.style='dendrogram')
  title('occurence')

  # investigate max spanning tree
  plotSoilRelationGraph(m, spanning.tree='max')

  # investigate max spanning tree + edges with weights > 75-th pctile
  plotSoilRelationGraph(m, spanning.tree=0.75)

  par(op)

  \donttest{
  
    if(requireNamespace("curl") &
       curl::has_internet() &
       require(soilDB)) {
    
      # get similar data from soilweb, for the Pardee series
      s <- 'pardee'
      d <- siblings(s, component.data = TRUE)
    
      # normalize component names
      d$sib.data$compname <- tolower(d$sib.data$compname)
    
      # keep only major components
      d$sib.data <- subset(d$sib.data, subset=compkind == 'Series')
    
      # build adj. matrix and plot
      m <- component.adj.matrix(d$sib.data)
      plotSoilRelationGraph(m, s=s, plot.style='dendrogram')
    
      # alter plotting style, see ?plot.phylo
      plotSoilRelationGraph(m, s=s, plot.style='dendrogram', type='fan')
      plotSoilRelationGraph(m, s=s, plot.style='dendrogram', 
                            type='unrooted', use.edge.length=FALSE) 
    
    }
  }
}
}
\author{
D.E. Beaudette
}
\keyword{hplot}
