---
title: "GIMMEgVAR Vignette"
author: "Sandra Lee"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{GIMMEgVAR Vignette}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, echo= FALSE,include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

## GIMMEgVAR

The *GIMMEgVAR* package provides a data-driven approach for arriving at person-specific time series networks and network models for group relations that are generated via an idiographic approach using a Graphical Vector Autoregression (GVAR) framework.

**Model building proceeds as follows:** First, GVAR is fitted separately to each individuals' data. Next, relations that replicate across the majority of individuals are identified to detect signal from noise. These are considered group-level relations and are then used as a foundation for starting the search for final person-specific (or individual-level) relations. This is done by separately re-estimating GVAR on each individual's model with the group-level relations forced into each individual's network. Each individual's resulting network is considered their person-specific result. The final group-level model consists of paths present for the majority of individuals at the end of this process.

## Data Preparation

Data for *GIMMEgVAR* should be stored in a list which contains separate data frames for each individual. Each data frame should be arranged in long format (with one record per repeated measure per individual). Data should contain a unique identifier for each individual.

Below *GIMMEgVAR* is fitted using a simulated data set 'sampleData' that is included with the package. In this data set, there are no group-level relations in the contemporaneous (kappa) matrix; however there are group-level relations in the group-level temporal network (beta) matrix.

## Fitting GIMMEgVAR

The minimum required parameters needed to execute *GIMMEgVAR* are discussed below.

> `outputPath =` Creates a folder in the location specified by the user that holds all results, plots and logs from model fitting.
>
> `data =` Name of the list containing the data that will be used for analysis
>
> `gamma =` The EBIC hyper-parameter needed for GVAR estimation. Default is .50. Set to 0 to use regular BIC.
>
> `gimmeGVARThreshold =` The cutoff value for identifying group-level paths. Defaults to .50, indicating that a path must be non-zero across \>= .50 subjects to be included as a path in the group-level model.
>
> `variableNames =` The vector containing the name of variables to be analyzed.
>
> `idvar =` String indicating the subject ID.
>
> `mimic =` Determines which version of the R package *graphicalVAR* should be used when estimating GVAR. The recommendation is to use the "current" version.

In the example below, results from fitting *GIMMEgVAR* are saved to an object named 'res'. Doing so allows for plotting individual graphs and performing other post-hoc tasks.

```{r fitting GIMMEgVAR}

#load library
library("GIMMEgVAR")

#read in example data
data(sampleData)

#set ouptdirectory
outputDirectory <- getwd() 

#fit GIMMEgVAR and assign results to object named 'res' 
res <- GIMMEgVAR(outputPath = outputDirectory,
                 data = sampleData,
                 gamma = 0,
                 variableNames = c("V1","V2","V3","V4","V5"),
                 idvar = "Idnum",
                 gimmeGVARThreshold = .50,
                 mimic = "current")

```

## Network Plots

**Group-level relations:** The network plots are automatically produced for group-level results and can be found in the folder the user specified for `outputPath =`. Two group-level network graphs, one for the lagged (temporal) network and one for the contemporaneous networks are automatically generated. In group-level graphs, edges represent the presence of a relation and edge thickness represents the proportion of individuals with the edge present. Group-level edges are depicted as black, and person-specific edges are depicted as grey.

**Individual-level relations:** Syntax for obtaining individual level plots for the lagged (temporal) and contemporaneous networks are shown below. For individual network models, the partial directed correlations (lagged/temporal network graph) and partial correlation coefficients (contemporaneous network graph) are typically plotted in the GVAR framework. These graphs depict how two variables relate to each other given all other variables.

To obtain network graphs for person-specific results, each individuals' final lagged (temporal) and contemporaneous network graphs must be plotted using the syntax specified below.

```{r indivdual plot syntax}

#plot PDC (temporal/lagged network model for person 1)
plot(res[["resultsGIMMEgVAR"]][["01"]],"PDC", layout="circle")

#plot PCC (contemporaneous network model for person 1)
plot(res[["resultsGIMMEgVAR"]][["01"]],"PCC", layout="circle")

```