% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/boot.ergoInfo.R
\name{boot.ergoInfo}
\alias{boot.ergoInfo}
\title{Bootstrap Test for the Ergodicity Information Index}
\usage{
boot.ergoInfo(
  dynEGA.object,
  EII,
  use = c("edge.list", "unweighted", "weighted"),
  shuffles = 5000,
  iter = 100,
  ncores,
  verbose = TRUE
)
}
\arguments{
\item{dynEGA.object}{A \code{\link[EGAnet]{dynEGA}} or a
\code{\link[EGAnet]{dynEGA.ind.pop}} object. If a \code{\link[EGAnet]{dynEGA}}
object, then \code{level = c("individual", "population")} is required}

\item{EII}{A \code{\link[EGAnet]{ergoInfo}} object
used to estimate the Empirical Ergodicity Information Index
or the estimated value of EII estimated using the \code{\link[EGAnet]{ergoInfo}}
function. Inherits \code{use} from \code{\link[EGAnet]{ergoInfo}}.
If no \code{\link[EGAnet]{ergoInfo}} object is provided, then it is estimated}

\item{use}{Character (length = 1).
A string indicating what network element will be used
to compute the algorithm complexity, the list of edges or the weights of the network.
Defaults to \code{use = "unweighted"}.
Current options are:

\itemize{

\item \code{"edge.list"} --- Calculates the algorithm complexity using the list of edges

\item \code{"unweighted"} --- Calculates the algorithm complexity using the binary weights of the encoded prime
transformed network. 0 = edge absent and 1 = edge present

\item \code{"weighted"} --- Calculates the algorithm complexity using the weights of encoded prime-weight transformed network

}}

\item{shuffles}{Numeric.
Number of shuffles used to compute the Kolmogorov complexity.
Defaults to \code{5000}}

\item{iter}{Numeric (length = 1).
Number of replica samples to generate from the bootstrap analysis.
Defaults to \code{100} (\code{1000} for robustness)}

\item{ncores}{Numeric (length = 1).
Number of cores to use in computing results.
Defaults to \code{ceiling(parallel::detectCores() / 2)} or half of your
computer's processing power.
Set to \code{1} to not use parallel computing

If you're unsure how many cores your computer has,
then type: \code{parallel::detectCores()}}

\item{verbose}{Boolean (length = 1).
Should progress be displayed?
Defaults to \code{TRUE}.
Set to \code{FALSE} to not display progress}
}
\value{
Returns a list containing:

\item{empirical.ergoInfo}{Empirical Ergodicity Information Index}

\item{boot.ergoInfo}{The values of the Ergodicity Information Index obtained in the bootstrap}

\item{p.value}{The two-sided \emph{p}-value of the bootstrap test for the Ergodicity Information Index.
The null hypothesis is that the empirical Ergodicity Information index is equal to or greater than the expected value of the EII
with small variation in the population structure}

\item{effect}{Indicates wheter the empirical EII is greater or less then the bootstrap distribution of EII.}

\item{interpretation}{How you can interpret the result of the test in plain English}
}
\description{
Tests the Ergodicity Information Index obtained in the
empirical sample with a distribution of EII obtained by a variant of
bootstrap sampling (see \strong{Details} for the procedure)
}
\details{
In traditional bootstrap sampling, individual participants are resampled
with replacement from the empirical sample. This process is time consuming
when carried out across \emph{v} number of variables, \emph{n} number of
participants, \emph{t} number of time points, and \emph{i} number of iterations.
Instead, \code{boot.ergoInfo} uses the premise of an ergodic process to
establish more efficient test that works directly on the sample's networks.

With an ergodic process, the expectation is that all individuals will have
a systematic relationship with the population. Destroying this relationship
should result in a significant loss of information. Following this conjecture,
\code{boot.ergoInfo} shuffles a random subset of edges that exist in the
\strong{population} that is \emph{equal} to the number of shared edges
it has with an individual. An individual's unique edges remain the same,
controlling for their unique information. The result is a replicate individual
that contains the same total number of edges as the actual individual but
its shared information with the population has been scrambled.

This process is repeated over each individual to create a replicate sample
and is repeated for \emph{X} iterations (e.g., 100). This approach creates
a sampling distribution that represents the expected information between
the population and individuals when a random process generates the shared
information between them. If the shared information between the population
and individuals in the empirical sample is sufficiently meaningful, then
this process should result in significant information loss.

How to interpret the results: the result of \code{boot.ergoInfo} is a sampling
distribution of EII values that would be expected if the process was random
(null distribution). If the empirical EII value is \emph{greater than} or
not significantly different from the null distribution, then the empirical
data can be expected to be generated from an nonergodic process and the
population structure is not sufficient to describe all individuals. If the
empirical EII value is significantly \emph{lower than} the null distribution,
then the empirical data can be described by the population structure -- the
population structure is sufficient to describe all individuals.
}
\examples{
# Obtain simulated data
sim.data <- sim.dynEGA

\dontrun{
# Dynamic EGA individual and population structures
dyn1 <- dynEGA.ind.pop(
  data = sim.dynEGA[,-26], n.embed = 5, tau = 1,
  delta = 1, id = 25, use.derivatives = 1,
  model = "glasso", ncores = 2, corr = "pearson"
)

# Empirical Ergodicity Information Index
eii1 <- ergoInfo(dynEGA.object = dyn1, use = "unweighted")

# Bootstrap Test for Ergodicity Information Index
testing.ergoinfo <- boot.ergoInfo(
  dynEGA.object = dyn1, EII = eii1,
  ncores = 2, use = "unweighted"
)

# Plot result
plot(testing.ergoinfo)

# Example using `dynEGA`
dyn2 <- dynEGA(
  data = sim.dynEGA, n.embed = 5, tau = 1,
  delta = 1, use.derivatives = 1, ncores = 2,
  level = c("individual", "population")
)

# Empirical Ergodicity Information Index
eii2 <- ergoInfo(dynEGA.object = dyn2, use = "unweighted")

# Bootstrap Test for Ergodicity Information Index
testing.ergoinfo2 <- boot.ergoInfo(
  dynEGA.object = dyn2, EII = eii2,
  ncores = 2
)

# Plot result
plot(testing.ergoinfo2)}

}
\references{
\strong{Original Implementation} \cr
Golino, H., Nesselroade, J. R., & Christensen, A. P. (2022).
Toward a psychology of individuals: The ergodicity information index and a bottom-up approach for finding generalizations.
\emph{PsyArXiv}.
}
\seealso{
\code{\link[EGAnet]{plot.EGAnet}} for plot usage in \code{\link{EGAnet}}
}
\author{
Hudson Golino <hfg9s at virginia.edu> & Alexander P. Christensen <alexander.christensen at Vanderbilt.Edu>
}
