---
title: "Group Iterative Multiple Model Estimation (GIMME)"
author: "KM Gates"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{GIMME}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

# **The Basics**


* GIMME can be used to estimate the unified SEM, Vector Autoregressive (VAR), and hybrid-VAR models.

* Missing data is not a problem. 

* Heterogeneous data is not a problem: 
  
    * No "group" or "common" structure will be forced unless it truly describes the majority. 
      
    * Individual-level nuances will surface after a group or common structure is fit (provided one exists).
    
    * If desired, subgroups of individuals with similar patterns of effects will be generated to aid the researcher in finding similar patterns among the varied individual models. 
 
* Works well with as little as 3 or as many as 20 variables.
  
* Can be freely downloaded by installing the package "gimme" in R.
 
# **Running GIMME**
 
__1. Extract the time series for your variables__

  * Create a data frame for each person. Have each variable be a column, with the rows being the observation across time (e.g., scans in fMRI or days in daily diary studies).
  
  * Make sure you don't have any constants, such as ID number. All variables must vary across time for each individual. 
  
  * Substitute NA for missing values.
  
  * Either put the data frames in an R list object, where each slice is a different person's data frame or save the individuals' time series as separate files (i.e., each person has a file) and put them in a folder. Do not put anything else in this folder.
  
  * Files must be either comma, space, or tab delimited.

__3. Installing gimme with R__

  * Open an R script and enter into the console: `install.packages("gimme")`
  
  * Once gimme has been installed, you will need to load the package by entering: `library(gimme)`
  
__4. Running gimme__
   The *gimme* (or equivelently, *gimmeSEM*) function requires that you input:
   1. Data object (if you put your individual data frames in a list) or source directory (if you saved them as seperate files)
   2. If you stored them in a folder: How data are separated (e..g, comma-separated values) and if there is a header
   
   All other fields are optional and will go to defaults if no user input is provided. If no output directory is indicated, all information    is stored as R objects (see tutorial linked above for details).
```{r, eval = FALSE}
gimme(                  # can use "gimme" or "gimmeSEM"
    data = '',          # list object or source directory where your data are 
    out = '',           # output directory where you'd like your output to go
    sep = "",           # how data are separated. "" for space; "," for comma, "/t" for tab-delimited
    header = ,          # TRUE or FALSE, is there a header
    ar = TRUE,          # TRUE (default) or FALSE, start with autoregressive paths open
    plot = TRUE,        # TRUE (default) or FALSE, generate plots
    subgroup = FALSE,   # TRUE or FALSE (default), cluster individuals based on similarities in effects
    paths = NULL,       # option to list paths that will be group-level (semi-confirmatory)
    groupcutoff = .75,  # the proportion that is considered the majority at the group level
    subcutoff = .75,     # the proportion that is considered the majority at the subgroup level
    stop_crit = "standard", # "standard", "model fit", or "significance"
    VAR       = FALSE,  # TRUE or FALSE (default), option to use VAR model instead of uSEM
    hybrid    = FALSE   # TRUE or FALSE (default), option to use hybrid-VAR model instead of uSEM
    )        
```
`stop_crit` controls when the individual-level search ends. `"standard"` uses the default behavior and stops once model fit is adequate or no significant paths remain. `"model fit"` keeps adding the path with the largest modification index until fit is adequate, even when that path is not significant. `"significance"` keeps adding significant paths even after model fit is adequate.
While *gimme* is running you will see information iterate in the command window. The algorithm will tell you when it is finished.

# **Output**

* The output directory will contain:

    * __indivPathEstimates__: Contains estimate, standard error, p-value, and z-value for each path and each individual 
  
    * __summaryFit__: Contains model fit information for individual-level models. If subgroups are requested, this file also indicates the subgroup membership for each individual.
  
    * __summaryPathCountMatrix__: Contains counts of total number of paths, both contemporaneous and lagged, estimated for the sample. The row variable is the outcome and the column variable is the predictor variable.
  
    * __summaryPathCounts__: Contains summary count information for paths identified at the group-, subgroup (if subgroup = TRUE), and individual-level.
  
    * __summaryPathPlots__: Produced if plot = TRUE. Contains figure with group, subgroup (if subgroup = TRUE), and individual-level paths for the sample. Black paths are group-level, green paths are subgroup-level, and grey paths are individual-level, where the thickness of the line represents the count.
  
* The subgroup output directory (if subgroup = TRUE) will contain:

    * __subgroup*k*PathCounts__: Contains counts of relations among lagged and contemporaneous variables for the **k**th subgroup
  
    * __subgroup*k*Plot__: Contains plot of group, subgroup, and individual level paths for the **k**th subgroup. Black represents group-level paths, grey represents individual-level paths, and green represents subgroup-level paths.
    
    * *Note: if a subgroup of size n = 1 is discovered, subgroup-level output is not produced. Subgroups of size one can be considered outlier cases* 

* In individual output directory (*where id represents the original file name for each individual*):

    * __*id*Betas__: Contains individual-level estimates of each path for each individual.
    
    * __*id*StdErrors__: Contains individual-level standard errors for each path for each individual.
    
    * __*id*Plot__: Contains individual-level plots. Red paths represent positive weights and blue paths represent negative weights.

# **FAQ**

**How many time points do I need?**
This is a difficult question since it will be related to the number of variables you are using. Rules of thumb for any analysis can generally be used: the more the better! Having at lest 100 time points is recommended, but adequate results have been obtained in simulation studies with only T = 60. 

**Do all individuals have to have the same number of observations (T)?**
No. 

**How many people do I need in my sample?**
For regular *gimmme*, reliable results are obtained with as few as 10 participants. Remember that in this context, power to detect effects is determined by the number of time points rather than the number of individuals. Still, having at least 10 individuals helps *gimme* to detect signal from noise by looking for effects that consistently occur. 

**What do I do if I obtain an error?**
Do some initial trouble-shooting. 
1. Ensure that all of your individuals have the same number of variables (columns) in their data sets. 
2. Ensure that all variables have variability (i.e., are not constant). *gimme* will let you know if this is the case. 
3. Ensure your path directories are correct. 
4. Ensure that the columns are variables and the rows contain the observations across time. 
5. Ensure that variables aren't perfectly correlated (or nearly perfectly correlated) for all individuals. 
6. If all this is correct, please email the error you received, code used to run *gimme*, and the data (we promise not to use it or share it) to: echo gimme@unc.edu. 
