% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/createAssoPerm.R
\name{createAssoPerm}
\alias{createAssoPerm}
\title{Create and store association matrices for permuted data}
\usage{
createAssoPerm(
  x,
  computeAsso = TRUE,
  nPerm = 1000L,
  cores = 1L,
  seed = NULL,
  permGroupMat = NULL,
  fileStoreAssoPerm = "assoPerm",
  append = TRUE,
  storeCountsPerm = FALSE,
  fileStoreCountsPerm = c("countsPerm1", "countsPerm2"),
  logFile = NULL,
  verbose = TRUE
)
}
\arguments{
\item{x}{object of class \code{"microNet"} or \code{"microNetProps"} 
(returned by \code{\link[NetCoMi]{netConstruct}} or 
\code{\link[NetCoMi]{netAnalyze}}).}

\item{computeAsso}{logical indicating whether the association matrices should
be computed. If \code{FALSE}, only the permuted group labels are computed 
and returned.}

\item{nPerm}{integer indicating the number of permutations.}

\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{seed}{integer giving a seed for reproducibility of the results.}

\item{permGroupMat}{an optional matrix with permuted group labels 
(with nPerm rows and n1+n2 columns).}

\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{append}{logical indicating whether existing files (given by 
fileStoreAssoPerm and fileStoreCountsPerm) should be extended. 
If \code{TRUE}, a new file is created only if the file is not existing. 
If \code{FALSE}, a new file is created in any case.}

\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{logFile}{character string naming the log file to which the current 
iteration number is written. Defaults
to \code{NULL} so that no log file is generated.}

\item{verbose}{logical. If \code{TRUE} (default), status messages are shown.}
}
\value{
Invisible object: Matrix with permuted group labels.
}
\description{
The function creates and returns a matrix with permuted group 
  labels and saves association matrices computed for the permuted data to 
  an external file.
}
\examples{
\donttest{
  # Load data sets from American Gut Project (from SpiecEasi package)
  data("amgut1.filt")

  # Generate a random group vector
  set.seed(123456)
  group <- sample(1:2, nrow(amgut1.filt), replace = TRUE)

  # Network construction:
  amgut_net <- netConstruct(amgut1.filt, group = group,
                            measure = "pearson",
                            filtTax = "highestVar",
                            filtTaxPar = list(highestVar = 30),
                            zeroMethod = "pseudoZO", normMethod = "clr")

  # Network analysis:
  amgut_props <- netAnalyze(amgut_net, clustMethod = "cluster_fast_greedy")

  # Use 'createAssoPerm' to create "permuted" count and association matrices,
  # which can be reused by netCompare() and diffNet()
  # Note: 
  # createAssoPerm() accepts objects 'amgut_net' and 'amgut_props' as input
  
  createAssoPerm(amgut_props, nPerm = 100L, 
                 computeAsso = TRUE,
                 fileStoreAssoPerm = "assoPerm",
                 storeCountsPerm = TRUE, 
                 fileStoreCountsPerm = c("countsPerm1", "countsPerm2"),
                 append = FALSE, seed = 123456)
  
  # Run netcompare using the stored permutation count matrices 
  # (association matrices are still computed within netCompare):
  amgut_comp1 <- netCompare(amgut_props, permTest = TRUE, nPerm = 100L, 
                            fileLoadCountsPerm = c("countsPerm1", 
                                                   "countsPerm2"),
                            seed = 123456)
                            
  # Run netcompare using the stored permutation association matrices:
  amgut_comp2 <- netCompare(amgut_props, permTest = TRUE, nPerm = 100L, 
                            fileLoadAssoPerm = "assoPerm")
  
  summary(amgut_comp1)
  summary(amgut_comp2)
  all.equal(amgut_comp1$properties, amgut_comp2$properties)
  
  # Run diffnet using the stored permutation count matrices in diffnet()
  diff1 <- diffnet(amgut_net, diffMethod = "permute", nPerm = 100L, 
                  fileLoadCountsPerm = c("countsPerm1", "countsPerm2"))
                  
  # Run diffnet using the stored permutation association matrices 
  diff2 <- diffnet(amgut_net, diffMethod = "permute", nPerm = 100L, 
                  fileLoadAssoPerm = "assoPerm")
                 
 #plot(diff1)
 #plot(diff2)
 # Note: Networks are empty (no significantly different associations) 
 # for only 100 permutations
}
}
