% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/gimme.R
\name{gimmeSEM}
\alias{gimmeSEM}
\alias{gimme}
\title{Group iterative multiple model estimation.}
\usage{
gimmeSEM(data        = NULL,
         out         = NULL,
         sep         = NULL,
         header      = NULL,
         ar          = TRUE,
         plot        = TRUE,
         subgroup    = FALSE,
         sub_feature = "lag & contemp",
         sub_method = "Walktrap",
         sub_sim_thresh    = "lowest", 
         confirm_subgroup = NULL,
         paths       = NULL,
         exogenous = NULL,
         outcome   = NULL,
         conv_vars   = NULL,
         conv_length = 16, 
         conv_interval = 1,
         mult_vars   = NULL,
         mean_center_mult = FALSE,
         standardize = FALSE,
         groupcutoff = .75,
         subcutoff   = .75,
         diagnos     = FALSE, 
         ms_allow         = FALSE,
         ms_tol           = 1e-5,
         lv_model         = NULL, 
         lv_estimator     = "miiv",     
         lv_scores        = "regression",       
         lv_miiv_scaling  = "first.indicator", 
         lv_final_estimator = "miiv",
         lasso_model_crit    = NULL, 
         hybrid = FALSE,
         VAR = FALSE,
         dir_prop_cutoff =0,
         ordered = NULL,
         group_correct = "Bonferroni Group",
         indiv_correct = "Bonferroni",
         alpha = .05,
         stop_crit = "model fit",
           rmsea_cutoff = .05,
           srmr_cutoff = .05,
           nnfi_cutoff = .95,
           cfi_cutoff = .95,
           n_excellent = 2)
}
\arguments{
\item{data}{The path to the directory where the data files are located,
or the name of the list containing each individual's time series. Each file
or matrix must contain one matrix for each individual containing a T (time)
by p (number of variables) matrix where the columns represent variables and
the rows represent time. Individuals must have the same variables (p)
but can have different lengths of observations (T).}

\item{out}{The path to the directory where the results will be stored
(optional). If specified,
a copy of output files will be replaced in directory. If directory at
specified path does not exist, it will be created.}

\item{sep}{The spacing of the data files. Follows R convention.
"" indicates space-delimited, backslash 
"t" indicates tab-delimited, "," indicates comma delimited. Only necessary
to specify if reading data in from physical directory.}

\item{header}{Logical. Indicate TRUE for data files with a header. Only
necessary to specify if reading data in from physical directory.}

\item{ar}{Logical. If TRUE, begins search for group model with
autoregressive (AR) paths freed for estimation. If ms_allow=TRUE, it is recommended
to set ar=FALSE.  Multiple solutions are unlikely to be found when ar=TRUE.  Defaults to TRUE.}

\item{plot}{Logical. If TRUE, graphs depicting relations among variables
of interest will automatically be 
created. Solid lines represent contemporaneous relations (lag 0) and dashed lines reflect 
lagged relations (lag 1). For individual-level plots, red paths represent positive weights
and blue paths represent negative weights. Width of paths corresponds to estimated path weight.
For the group-level plot, black represents group-level paths, grey represents
individual-level paths, and (if subgroup = TRUE)
green represents subgroup-level paths. For the group-level plot,
the width of the edge corresponds to the count. Defaults to TRUE.}

\item{subgroup}{Logical. If TRUE, subgroups are generated based on
similarities in model features using the \code{walktrap.community}
function from the \code{igraph} package. When ms_allow=TRUE, subgroup
should be set to FALSE.  Defaults to FALSE.}

\item{sub_feature}{Option to indicate feature(s) used to subgroup individuals. Defaults to
"lag & contemp" for lagged and contemporaneous, which is the original method. Can use 
"lagged" or "contemp" to subgroup solely on features related to lagged and contemporaneous 
relations, respectively.}

\item{sub_method}{Community detection method used to cluster individuals into subgroups. Options align 
with those available in the igraph package: "Walktrap" (default), "Infomap", "Louvain", "Edge Betweenness", 
"Label Prop", "Fast Greedy", "Leading Eigen", and "Spinglass".}

\item{sub_sim_thresh}{Threshold for inducing sparsity in similarity matrix. Options are: the percent of edges 
in the similarity matrix to set to zero (e.g., .25 would set the lower quartile), "lowest" (default) subtracts 
the minimum value from all values, and "search" searches across thresholds to arrive at one providing highest modularity.}

\item{confirm_subgroup}{Dataframe. Option only available when subgroup = TRUE. Dataframe should contain two columns. The first
column should specify file labels (the name of the data files without file extension), 
and the second should contain integer values (beginning at 1) 
specifying the subgroup membership for each individual.
function from the \code{igraph} package. Defaults to TRUE.}

\item{paths}{\code{lavaan}-style syntax containing paths with which
to begin model estimation (optional). That is, Y~X indicates that Y
is regressed on X, or X predicts Y. Paths can also be set to a specific value for estimation using \code{lavaan}-style syntax 
(e.g., 'V4 ~ 0.5*V3'), or set to 0 so that they will not be estimated 
(e.g., 'V4 ~ 0*V3'). If no header is used, then variables should be referred to with V followed (with no separation)
by the column number. If a header is used, variables should be referred to using variable names.
To reference lag variables, "lag" should be added to the end of the variable
name with no separation. Defaults to NULL.}

\item{exogenous}{Vector of variable names to be treated as exogenous (optional).
That is, exogenous variable X can predict Y but cannot be predicted by Y.
If no header is used, then variables should be referred to with V followed
(with no separation) by the column number.  If a header is used, variables should be referred 
to using variable names. The default for exogenous variables is that lagged effects of the exogenous 
variables are not included in the model search.  If lagged paths are wanted, "&lag" should be added to the end of the variable
name with no separation. Defaults to NULL.}

\item{outcome}{Vector of variable names to be treated as outcome (optional). This is a variable
that can be predicted by others but cannot predict. If no header is used, then variables should be referred to with V followed
(with no separation) by the column number.  If a header is used, variables should be referred 
to using variable names.}

\item{conv_vars}{Vector of variable names to be convolved via smoothed Finite Impulse 
Response (sFIR). Note, conv_vars are not not automatically considered exogenous variables.
To treat conv_vars as exogenous use the exogenous argument. Variables listed in conv_vars 
must be binary variables. You cannot do lagged variables. If there is missing data in the endogenous variables their values 
will be imputed for the convolution operation only. Defaults to NULL.}

\item{conv_length}{Expected response length in seconds. For functional MRI BOLD, 16 seconds (default) is typical
for the hemodynamic response function.}

\item{conv_interval}{Interval between data acquisition. Currently conv_length/conv_interval must be an integer. For 
fMRI studies, this is the repetition time. Defaults to 1.}

\item{mult_vars}{Vector of variable names to be multiplied to explore bilinear/modulatory
effects (optional). All multiplied variables will be treated as exogenous (X can predict
Y but cannot be predicted by Y). Within the vector, multiplication of two variables should be
indicated with an asterik (e.g. V1*V2). If no header is used, variables should be referred to with 
V followed by the column number (with no separation). If a header is used, each variable should be
referred to using variable names. If multiplication with the lag 1 of a variable is desired, the 
variable name should be followed by "lag" with no separation (e.g. V1*V2lag).}

\item{mean_center_mult}{Logical. If TRUE, the variables indicated in mult_vars will be mean-centered
before being multiplied together. Defaults to FALSE.}

\item{standardize}{Logical. If TRUE, all variables will be standardized to have a mean of zero and a
standard deviation of one. Defaults to FALSE}

\item{groupcutoff}{Cutoff value for group-level paths. Defaults to .75,
indicating that a path must be significant across 75\% of individuals to be
included as a group-level path.}

\item{subcutoff}{Cutoff value for subgroup- level paths. Defaults to .75,
indicating that a path must be significant across at least 75\% of the
individuals in a subgroup to be considered a subgroup-level path.}

\item{diagnos}{Logical. If TRUE provides internal output for diagnostic purposes. Defaults to FALSE.}

\item{ms_allow}{Logical. If TRUE provides multiple solutions when more than one path has identical 
modification index values.  When ms_allow=TRUE, it is recommended
to set ar=FALSE.  Multiple solutions are unlikely to be found when ar=TRUE.  Additionally,
subgroup should be set to FALSE.  Output files for individuals with multiple solutions will represent the last solution 
found for the individual, not necessarily the best solution for the individual.}

\item{ms_tol}{Precision used when evaluating similarity of modification indices when ms_allow = TRUE.  We recommend
that ms_tol not be greater than the default, especially when standardize=TRUE.     
Defaults to 1e-5.}

\item{lv_model}{Invoke latent variable modeling by providing the measurement model syntax here. lavaan
conventions are used for relating observed variables to factors. Defaults to NULL.}

\item{lv_estimator}{Estimator used for factor analysis. Options are "miiv" (default), "pml" (pseudo-ML) or "svd".}

\item{lv_scores}{Method used for estimating latent variable scores from parameters obtained from the factor analysis 
when lv_model is not NULL. Options are: "regression" (Default), "bartlett".}

\item{lv_miiv_scaling}{Type of scaling indicator to use when "miiv" selected for lv_estimator. Options are
"first.indicator" (Default; the first observed variable in the measurement equation is used), "group" 
(best one for the group), or "individual" (each individual has the best one for them according to R2).}

\item{lv_final_estimator}{Estimator for final estimations. "miiv" (Default) or "pml" (pseudo-ML).}

\item{lasso_model_crit}{When not null, invokes multiLASSO approach for the GIMME model search procedure. Arguments 
indicate the model selection criterion to use for model selection: 'bic' (select on BIC), 'aic', 'aicc', 'hqc', 'cv' (cross-validation).}

\item{hybrid}{Logical. If TRUE, enables hybrid-VAR models where both directed contemporaneous paths and contemporaneous
covariances among residuals are candidate relations in the search space. Defaults to FALSE.}

\item{VAR}{Logical.  If true, VAR models where contemporaneous covariances among residuals are candidate relations in the 
search space.  Defaults to FALSE.}

\item{dir_prop_cutoff}{Option to require that the directionality of a relation has to be higher than the reverse direction for a prespecified proportion of indivdiuals.}

\item{ordered}{A character vector containing the names of all ordered categorical variables in the model.}

\item{group_correct}{Indicate how to correct for multiple testing at the group level.
"Bonferroni Group" (Default) corrects alpha for the number of people (N) in the sample;
"Bonferroni Paths" corrects alpha for the number of eligible paths;
a numeric value between 0 and 1 sets the alpha level directly;
"fdr" applies a Benjamini-Hochberg false discovery rate correction.}

\item{indiv_correct}{Indicate how to correct for multiple comparisons at the individual level.
"Bonferroni" (Default) applies a Bonferroni correction dividing alpha by the number of eligible paths;
"fdr" applies a Benjamini-Hochberg false discovery rate correction.}

\item{alpha}{The base alpha level used for significance testing in all searches (group and individual).
Defaults to .05.}

\item{stop_crit}{Stopping criterion for the individual-level search.
"standard" stops when either fit is adequate or no significant
paths remain. "model fit" (default) continues adding the paths until fit
is adequate regardless of significance of those paths. "significance"
continues adding significant paths even after fit is adequate.}

\item{rmsea_cutoff}{Cutoff for RMSEA for an individual model(default is .05; must be between 0.0 and 1.0).}

\item{srmr_cutoff}{Cutoff for SRMR for an individual model (default is .05; must be between 0.0 and 1.0).}

\item{nnfi_cutoff}{Cutoff for NNFI for an individual model (default is .95; must be between 0.0 and 1.0).}

\item{cfi_cutoff}{Cutoff for CFI for an individual model (default is .95; must be between 0.0 and 1.0).}

\item{n_excellent}{Number of fit indices needed to surpass their cutoffs for an
individual model to be considered excellent. Default is 2. Max is 4.}
}
\value{
A list with the following components: 
\itemize{
\item{data: list of data used in analyses. Contains lagged variables and any data manipulations done within gimme.}
\item{path_est_mats: N matrices of individual-level coefficient estimates for directed paths.}
\item{varnames: Variable names in order of data.} 
\item{n_vars_total: total number of variables.}
\item{n_lagged: total nubmer of lagged varaibles.}
\item{n_endog: total number of endogenous variables. }
\item{fit: Final fit indices, R-squared for each variable, convergence status, subgroup membership (if applicable), and modularity (if applicable).}
\item{path_se_est: Matrix of all individuals' unstandardized & standardized coefficient estimates, standard errors, level of each relation (e.g., "group"), and subgroup membership.}
\item{plots: If number of variables >3, N individual-level plots of directed lagged and contemporaneous relations among variables. Red = high / hot / positive values; Blue = low / cold / negative values.  Line width corresponds with absolute value of beta estimate. Use plot() function.}  
\item{plots_cov: If number of variables >3 and hybrid = TRUE or VAR = TRUE, N plots of contemporaneous covariances among residuals.}
\item{group_plot_paths: If number of variables >3, aggregated plot of directed relations. Black = group-level, Green = subgroup level, Grey = individual level. Line width corresponds with percent of individuals who have that path estimated.} 
\item{group_plot_cov: If number of variables >3 and hybrid = TRUE or VAR = TRUE, aggregated plot of covariances among residuals.} 
\item{sub_plots_paths: Aggregated directed subgroup plots for K subgroups if applicable.}
\item{sub_plots_cov: Aggregated covariance subgroup plots for K subgroups if applicable.}
\item{path_counts: Matrix containing counts of the number of people for whom a given directed relation is estimated.}
\item{path_counts_sub: K matrices containing counts of the number of people within that subgroup for whom a given directed relation is estimated.}
\item{cov_counts: Matrix containing counts of the number of people for whom a given covariance relation is estimated.}
\item{cov_counts_sub: K matrices containing counts of the number of people within that subgroup for whom a given covariance relation is estimated.}
\item{vcov: N matrices containing the estimated covariance matrix of paramaters of interest in gimme.}
\item{vcovfull: N matrices of the full estimated covariance matrix of parameters.}
\item{psi: N standardized residual covariance matrices.}  
\item{ps_unstd: N unstandardied residual covariance matrices.}
\item{sim_matrix: If subgroup = TRUE, similarity count matrix of how many edges are in commong among each pair of individuals after the group-level search (also considers individual-level paths that may be added later via the EPC).}
\item{syntax: N individual slices containing lavaan-style syntax.}
\item{lvgimme: If provided, the latent variable model syntax (also included in the above).}
\item{rf_est: If variables to convolve are provided in conv_vars, the N response function estimates for individuals.}
\item{arguments: List of arguments provided by the user.}
}
}
\description{
This function identifies structural equation models for each
individual that consist of both group-level and individual-level paths.
}
\details{
gimmeSEM is a data-driven method for identifying structural equation models for each individual that consist of both group-level and individual-level paths. 
The group-level search identifies paths that are significant across a prespecified proportion of individuals in the sample (e.g., 75\%). 
The optional subgrouping stage identifies subgroups of individuals with similar model features (e.g., similar patterns of lagged and contemporaneous relations among variables). 
The individual-level search then adds paths to each individual's model until fit is adequate or no significant paths remain.
 Output is a list of results if saved as an object and/or files printed to a directory if the "out" argument is used.
}
\examples{
 \dontrun{
paths <- 'V2 ~ V1
          V3 ~ V4lag'

fit <- gimmeSEM(data     = simData,
                out      = "C:/simData_out",
                subgroup = TRUE, 
                paths    = paths)

print(fit, mean = TRUE)
print(fit, subgroup = 1, mean = TRUE)
print(fit, file = "group_1_1", estimates = TRUE)
print(fit, subgroup = 2, fitMeasures = TRUE)
plot(fit, file = "group_1_1")
 }
}
\references{
Gates, K.M. & Molenaar, P.C.M. (2012). Group search algorithm
recovers effective connectivity maps for individuals
in homogeneous and heterogeneous samples. NeuroImage, 63, 310-319.

Lane, S.T. & Gates, K.M. (2017). Automated selection of robust
individual-level structural equation models for time series data.
Structural Equation Modeling.

Adriene M. Beltz & Peter C. M. Molenaar (2016) Dealing 
with Multiple Solutions in Structural Vector Autoregressive Models, 
Multivariate Behavioral Research, 51:2-3, 357-373.
}
\author{
Zachary Fisher, Kathleen Gates, & Stephanie Lane
}
\keyword{gimmeSEM}
