% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/netCompare.R
\name{netCompare}
\alias{netCompare}
\title{Group Comparison of Network Properties}
\usage{
netCompare(
  x,
  permTest = FALSE,
  jaccQuant = 0.75,
  lnormFit = NULL,
  testRand = TRUE,
  nPermRand = 1000L,
  gcd = TRUE,
  gcdOrb = c(0, 2, 5, 7, 8, 10, 11, 6, 9, 4, 1),
  verbose = TRUE,
  nPerm = 1000L,
  adjust = "adaptBH",
  trueNullMethod = "convest",
  cores = 1L,
  logFile = NULL,
  seed = NULL,
  fileLoadAssoPerm = NULL,
  fileLoadCountsPerm = NULL,
  storeAssoPerm = FALSE,
  fileStoreAssoPerm = "assoPerm",
  storeCountsPerm = FALSE,
  fileStoreCountsPerm = c("countsPerm1", "countsPerm2"),
  returnPermProps = FALSE,
  returnPermCentr = FALSE,
  assoPerm = NULL,
  dissPerm = NULL
)
}
\arguments{
\item{x}{object of class \code{microNetProps} (returned by 
\code{\link[NetCoMi]{netAnalyze}}).}

\item{permTest}{logical. If \code{TRUE}, a permutation test is conducted 
to test centrality measures and global network properties for group
differences. Defaults to \code{FALSE}. May lead to a considerably increased
execution time!}

\item{jaccQuant}{numeric value between 0 and 1 specifying the quantile 
used as threshold to identify the most central nodes for each centrality
measure. The resulting sets of nodes are used to calculate Jaccard's index
(see details). Default is 0.75.}

\item{lnormFit}{logical indicating whether a log-normal distribution should
be fitted to the calculated centrality values for determining Jaccard's
index (see details). If \code{NULL} (default), the value is adopted
from the input, i.e., equals the method used for determining hub nodes.}

\item{testRand}{logical. If \code{TRUE}, a permutation test is conducted 
for the adjusted Rand index (with H0: ARI = 0). Execution time may be 
increased for large networks.}

\item{nPermRand}{integer giving the number of permutations used for testing 
the adjusted Rand index for being significantly different from zero. 
Ignored if \code{testRand = FALSE}. Defaults to 1000L.}

\item{gcd}{logical. If \code{TRUE} (default), the Graphlet Correlation 
Distance (GCD) is computed.}

\item{gcdOrb}{numeric vector with integers from 0 to 14 defining the orbits 
used for calculating the GCD. Minimum length is 2. 
Defaults to c(0, 1, 2, 4, 5, 6, 7, 8, 9, 10, 11), 
thus excluding redundant orbits such as the orbit o3.}

\item{verbose}{logical. If \code{TRUE} (default), status messages are shown.}

\item{nPerm}{integer giving the number of permutations if 
\code{permTest = TRUE}. Default is 1000L.}

\item{adjust}{character indicating the method used for multiple testing
adjustment of the permutation p-values. Possible values are \code{"lfdr"}
(default) for local false discovery rate correction (via
\code{\link[fdrtool]{fdrtool}}), \code{"adaptBH"} for the adaptive
Benjamini-Hochberg method \cite{(Benjamini and Hochberg, 2000)},  or one of
the methods provided by \code{\link[stats]{p.adjust}} (see
\code{p.adjust.methods()}).}

\item{trueNullMethod}{character indicating the method used for estimating the
proportion of true null hypotheses from a vector of p-values. Used for the
adaptive Benjamini-Hochberg method for multiple testing adjustment (chosen
by \code{adjust = "adaptBH"}). Accepts the provided options of the
\code{method} argument of \code{\link[limma]{propTrueNull}}:
\code{"convest"}(default), \code{"lfdr"}, \code{"mean"}, and \code{"hist"}.
Can alternatively be \code{"farco"} for the "iterative plug-in method"
proposed by \cite{Farcomeni (2007)}.}

\item{cores}{integer indicating the number of CPU cores used for
permutation tests. If cores > 1, the tests are performed in parallel.
Is limited to the number of available CPU cores determined by
\code{\link[parallel]{detectCores}}. Defaults to 1L (no parallelization).}

\item{logFile}{character string naming the log file to which the current 
iteration number is written (if permutation tests are performed). Defaults
to \code{NULL} so that no log file is generated.}

\item{seed}{integer giving a seed for reproducibility of the results.}

\item{fileLoadAssoPerm}{character giving the name or path (without file 
extension)  of the file containing the "permuted" association/dissimilarity 
matrices that was generated by setting \code{storeAssoPerm} to 
\code{TRUE}. Only used for permutation tests. If \code{NULL}, no 
existing associations are used.}

\item{fileLoadCountsPerm}{character giving the name or path (without file 
extension)  of the file containing the "permuted" count matrices that was 
generated by setting \code{storeCountsPerm} to \code{TRUE}. 
Only used for permutation tests, and if \code{fileLoadAssoPerm = NULL}. 
If \code{NULL}, no existing count matrices are used.}

\item{storeAssoPerm}{logical indicating whether the association/dissimilarity 
matrices for the permuted data should be saved to a file.
The file name is given via \code{fileStoreAssoPerm}. If \code{TRUE}, 
the computed "permutation" association/dissimilarity matrices can be reused
via \code{fileLoadAssoPerm} to save runtime. Defaults to \code{FALSE}.
Ignored if \code{fileLoadAssoPerm} is not \code{NULL}.}

\item{fileStoreAssoPerm}{character giving the name of a file to which the 
matrix with associations/dissimilarities of the permuted data is saved. 
Can also be a path.}

\item{storeCountsPerm}{logical indicating whether the permuted count matrices
should be saved to an external file. Defaults to \code{FALSE}.
Ignored if \code{fileLoadCountsPerm} is not \code{NULL}.}

\item{fileStoreCountsPerm}{character vector with two elements giving the 
names of two files storing the permuted count matrices belonging to the 
two groups.}

\item{returnPermProps}{logical. If \code{TRUE}, the global properties and 
their absolute differences for the permuted data are returned.}

\item{returnPermCentr}{logical. If \code{TRUE}, the centralities and 
their absolute differences for the permuted data are returned.}

\item{assoPerm}{only needed for output generated with NetCoMi v1.0.1! A list 
with two elements used for the permutation procedure.
Each entry must contain association matrices for \code{"nPerm"}
permutations. This can be the \code{"assoPerm"} value as part of the
output either returned by \code{diffnet} or \code{\link{netCompare}}.}

\item{dissPerm}{only needed for output generated with NetCoMi v1.0.1! 
Usage analog to \code{assoPerm} if a dissimilarity measure has been used 
for network construction.}
}
\value{
Object of class \code{microNetComp} with the following
  elements:\cr
  \tabular{ll}{
  \code{jaccDeg,jaccBetw,jaccClose,jaccEigen}\tab Values of Jaccard's index
  for the centrality measures\cr
  \code{jaccHub}\tab Jaccard index for the sets of hub nodes\cr
  \code{randInd}\tab Adjusted Rand index\cr
  \code{randIndLCC}\tab Adjusted Rand index for the largest connected 
  component (LCC)\cr
  \code{gcd}\tab Graphlet Correlation Distance (object of class \code{gcd} 
  returned by \code{\link{calcGCD}})\cr
  \code{gcdLCC}\tab Graphlet Correlation Distance for the LCC\cr
  \code{properties}\tab List with calculated network properties\cr
  \code{propertiesLCC}\tab List with calculated network properties of the 
  LCC\cr
  \code{diffGlobal}\tab Vectors with differences of global properties\cr
  \code{diffGlobalLCC}\tab Vectors with differences of global properties for
  the LCC\cr
  \code{diffCent}\tab Vectors with differences of the centrality values\cr
  \code{countMatrices}\tab The two count matrices returned
  by \code{netConstruct}\cr
  \code{assoMatrices}\tab The two association matrices returned
  by \code{netConstruct}\cr
  \code{dissMatrices}\tab The two dissimilarity matrices returned
  by \code{netConstruct}\cr
  \code{adjaMatrices}\tab The two adjacency matrices returned
  by \code{netConstruct}\cr
  \code{groups}\tab Group names returned by \code{netConstruct}\cr
  \code{paramsProperties}\tab Parameters used for network analysis
  }
  \strong{Additional output if permutation tests are conducted:}
 \tabular{ll}{
 \code{pvalDiffGlobal}\tab P-values of the tests for differential global
 properties\cr
 \code{pvalDiffGlobalLCC}\tab P-values of the tests for differential
 global properties in the LCC\cr
 \code{pvalDiffCentr}\tab P-values of the tests for differential centrality
 values\cr
 \code{pvalDiffCentrAdjust}\tab Adjusted p-values of the tests for
 differential centrality values\cr
 \code{permDiffGlobal}\tab \code{nPerm} x 10 matrix containing the absolute 
 differences of the ten global network properties (computed for the whole 
 network) for all \code{nPerm} permutations\cr
 \code{permDiffGlobalLCC}\tab \code{nPerm} x 11 matrix containing the 
 absolute differences of the eleven global network properties (computed for 
 the LCC) for all \code{nPerm} permutations\cr
 \code{permDiffCentr}\tab List with absolute differences of the four 
 centrality measures for all \code{nPerm} permutations. Each list contains 
 a \code{nPerm} x \code{nNodes} matrix.
 }
}
\description{
Calculate and compare network properties for microbial networks
  using Jaccard's index, the Rand index, the Graphlet Correlation Distance, 
  and permutation tests.
}
\details{
\strong{Permutation procedure:}\cr
  Used for testing centrality measures and global network properties for
  group differences.\cr
  The null hypothesis of the tests is defined as
  \deqn{H_0: c1_i - c2_i = 0,} where \eqn{c1_i} and
  \eqn{c2_i} denote the centrality values of taxon i in group 1 and 2,
  respectively.\cr
  To generate a sampling distribution of the differences under \eqn{H_0},
  the group labels are randomly reassigned to the samples while the group
  sizes are kept. The associations are then re-estimated for each permuted
  data set. The p-values are calculated as the proportion of
  "permutation-differences" being larger than or equal to the observed 
  difference. In non-exact tests, a pseudo-count is added to the numerator 
  and denominator to avoid p-values of zero. Several methods for adjusting 
  the p-values for multiplicity are available.

  \strong{Jaccard's index:}\cr
  Jaccard's index expresses for each centrality measure how equal the sets of
  most central nodes are among the two networks.\cr
  These sets are defined as nodes with a centrality value above a defined
  quantile (via \code{jaccQuant}) either of the empirical distribution of the
  centrality values (\code{lnormFit = FALSE}) or of a fitted log-normal
  distribution (\code{lnormFit = TRUE}).\cr
  The index ranges from 0 to 1, where 1 means the sets of most central nodes
  are exactly equal in both networks and 0 indicates that the
  most central nodes are completely different.\cr
  The index is calculated as suggested by \cite{Real and Vargas (1996)}.
  \cr\cr
  \strong{Rand index:}\cr
  The Rand index is used to express whether the determined clusterings are
  equal in both groups. The adjusted Rand index (ARI) ranges from -1 to 1,
  where 1 indicates that the two clusterings are exactly equal. The expected
  index value for two random clusterings is 0. The implemented test procedure
  is in accordance with the explanations in \cite{Qannari et al. (2014)},
  where a p-value below the alpha levels means that ARI is significantly
  higher than expected for two random clusterings.
  \cr\cr
  \strong{Graphlet Correlation Distance:}\cr
  A graphlet-based distance measure, which is defined as the Euclidean 
  distance of the upper triangle values of the Graphlet Correlation 
  Matrices (GCM) of two networks \cite{(Yaveroglu et al., 2014)}.
  The GCM of a network is a matrix with Spearman's correlations between the 
  network's node orbits \cite{(Hocevar and Demsar, 2016)}.
  See \code{\link{calcGCD}} for details.
}
\examples{

# Load data sets from American Gut Project (from SpiecEasi package)
data("amgut2.filt.phy")

# Split data into two groups: with and without seasonal allergies
amgut_season_yes <- phyloseq::subset_samples(amgut2.filt.phy, 
                                      SEASONAL_ALLERGIES == "yes")
amgut_season_no <- phyloseq::subset_samples(amgut2.filt.phy, 
                                     SEASONAL_ALLERGIES == "no")

amgut_season_yes
amgut_season_no

# Filter the 121 samples (sample size of the smaller group) with highest 
# frequency to make the sample sizes equal and thus ensure comparability.
n_yes <- phyloseq::nsamples(amgut_season_yes)

# Network construction
amgut_net <- netConstruct(data = amgut_season_yes,
                          data2 = amgut_season_no,
                          measure = "pearson",
                          filtSamp = "highestFreq",
                          filtSampPar = list(highestFreq = n_yes),
                          filtTax = "highestVar",
                          filtTaxPar = list(highestVar = 30),
                          zeroMethod = "pseudoZO", normMethod = "clr")

# Network analysis
# Note: Please zoom into the GCM plot or open a new window using:
# x11(width = 10, height = 10)
amgut_props <- netAnalyze(amgut_net, clustMethod = "cluster_fast_greedy")

# Network plot
plot(amgut_props,
     sameLayout = TRUE,
     title1 = "Seasonal allergies",
     title2 = "No seasonal allergies")

#--------------------------
# Network comparison

# Without permutation tests
amgut_comp1 <- netCompare(amgut_props, permTest = FALSE)
summary(amgut_comp1)

\donttest{
  # With permutation tests (with only 100 permutations to decrease runtime)
  amgut_comp2 <- netCompare(amgut_props,
                            permTest = TRUE,
                            nPerm = 100L,
                            cores = 1L,
                            storeCountsPerm = TRUE,
                            fileStoreCountsPerm = c("countsPerm1",
                                                    "countsPerm2"),
                            storeAssoPerm = TRUE,
                            fileStoreAssoPerm = "assoPerm",
                            seed = 123456)

# Rerun with a different adjustment method ...
# ... using the stored permutation count matrices
amgut_comp3 <- netCompare(amgut_props, adjust = "BH",
                          permTest = TRUE, nPerm = 100L,
                          fileLoadCountsPerm = c("countsPerm1",
                                                 "countsPerm2"),
                          seed = 123456)

# ... using the stored permutation association matrices
amgut_comp4 <- netCompare(amgut_props, adjust = "BH",
                          permTest = TRUE, nPerm = 100L, 
                          fileLoadAssoPerm = "assoPerm",
                          seed = 123456)
  
# amgut_comp3 and amgut_comp4 should be equal
all.equal(amgut_comp3$adjaMatrices, amgut_comp4$adjaMatrices)
all.equal(amgut_comp3$properties, amgut_comp4$properties)

summary(amgut_comp2)
summary(amgut_comp3)
summary(amgut_comp4)

#--------------------------
# Use 'createAssoPerm' to create "permuted" count and association matrices
createAssoPerm(amgut_props, nPerm = 100, 
               computeAsso = TRUE,
               fileStoreAssoPerm = "assoPerm",
               storeCountsPerm = TRUE, 
               fileStoreCountsPerm = c("countsPerm1", "countsPerm2"),
               append = FALSE, seed = 123456)

amgut_comp5 <- netCompare(amgut_props, permTest = TRUE, nPerm = 100L, 
                          fileLoadAssoPerm = "assoPerm")

all.equal(amgut_comp3$properties, amgut_comp5$properties)

summary(amgut_comp5)
}

}
\references{
\insertRef{benjamini2000adaptive}{NetCoMi} \cr\cr
  \insertRef{farcomeni2007some}{NetCoMi} \cr\cr
  \insertRef{gill2010statistical}{NetCoMi} \cr\cr
  \insertRef{hocevar2016computation}{NetCoMi}\cr\cr
  \insertRef{qannari2014significance}{NetCoMi}\cr\cr
  \insertRef{real1996probabilistic}{NetCoMi}\cr\cr
  \insertRef{yaveroglu2014revealing}{NetCoMi}
}
\seealso{
\code{\link{summary.microNetComp}}, \code{\link{netConstruct}},
  \code{\link{netAnalyze}}
}
