---
title: "Intermediate SSM Analysis"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Intermediate SSM Analysis}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>")
library(ggplot2)
library(ggforce)
library(kableExtra)
set.seed(12345)
```

```{r setup}
library(circumplex)
```

## 1. Generalizing the basic analyses

### Generalizing to multiple means
We've already seen how adding the `measures` argument can change `ssm_analyze()` from analyzing means to analyzing correlations. Similarly, we can change it from analyzing all observations as a single group to analyzing subgroups separately. This is done using the `grouping` argument. This argument needs to contain a single variable (name or column number) that specifies each observation's group. For instance, the `Gender` variable in the `jz2017` dataset is a factor with two levels: Female and Male. To analyze each gender separately, we need to add the `grouping = "Gender"` argument to the function call.

```{r group}
data("jz2017")
results <- ssm_analyze(
  data = jz2017, 
  scales = PANO(), 
  angles = octants(), 
  grouping = "Gender"
)
summary(results)
```

Note that the output of `summary()` looks the same as previous mean-based analyses except that there are now two Profile blocks: one for Female and one for Male. A similar modification will occur if we generate a table and figure.

```r
ssm_table(results)
```

```{r group_table, echo = FALSE}
ssm_table(results, render = FALSE) %>% 
  knitr::kable(caption = circumplex:::dcaption(results)) %>% 
  kableExtra::kable_styling(full_width = TRUE, font_size = 12)
```

```{r group_plot, fig.width = 7.5, fig.height = 4, out.width = "100%"}
ssm_plot_circle(results)
```

```{r group_plot2, fig.width = 7.5, fig.height = 4, out.width = "100%"}
ssm_plot_curve(results)
```

Any number of groups can be analyzed in this way, and the output will contain additional profile blocks, the table will contain additional rows, and the figures will contain additional points or curves. The grouping variable just needs to contain more than one level (i.e., unique value).

### Generalizing to multiple measures
Similarly, we can analyze multiple external measures in a single function call by providing a vector of variables to the `measures` argument instead of a single variable. This can be done by wrapping the variable names or column numbers with the `c()` or, if they are adjacent columns, with the column numbers and the `:` shortcut. The package functions were written to analyze all measures and groups within a single bootstrapping, so adding additional measures and groups should still be fast.

```{r measures}
results2 <- ssm_analyze(
  data = jz2017, 
  scales = PANO(), 
  angles = octants(),
  measures = c("NARPD", "ASPD")
)
summary(results2)
```

```r
ssm_table(results2)
```

```{r measures_table, echo = FALSE}
ssm_table(results2, render = FALSE) %>% 
  knitr::kable(caption = circumplex:::dcaption(results2)) %>% 
  kableExtra::kable_styling(full_width = TRUE, font_size = 12)
```

```{r measures_plot, fig.width = 7.5, fig.height = 4, out.width = "100%"}
ssm_plot_circle(results2)
```

```{r measures_plot2, fig.width = 7.5, fig.height = 4, out.width = "100%"}
ssm_plot_curve(results2)
```

### Generalizing to multiple groups and multiple measures
Finally, it is possible to analyze multiple measures within multiple groups. As you might expect, this requires providing both the `measures` and `grouping` arguments to the same function call. Again, any number of measures and groups is possible. The profiles in such an analysis will be named "Measure: Group" as below.

```{r general}
results3 <- ssm_analyze(
  data = jz2017, 
  scales = PANO(), 
  angles = octants(), 
  grouping = "Gender", 
  measures = 10:12)
summary(results3)
```

```r
ssm_table(results3)
```

```{r general_table, echo = FALSE}
ssm_table(results3, render = FALSE) %>% 
  knitr::kable(caption = circumplex:::dcaption(results3)) %>% 
  kableExtra::kable_styling(full_width = TRUE, font_size = 12)
```

```{r general_plot, fig.width = 7.5, fig.height = 4, out.width = "100%"}
ssm_plot_circle(results3)
```

Note that the borders for the "PARDPD: Male" and "SZTPD: Male" blocks are dashed instead of solid. This indicates that these profiles have low fit (i.e., $R^2<.7$). We could alternatively hide these such profiles by adding `lowfit = FALSE` as below (noting that the color guide may change as profiles are dropped).

```{r general_plot2, fig.width = 7.5, fig.height = 4, out.width = "100%"}
ssm_plot_circle(results3, drop_lowfit = TRUE)
```

```{r general_plot3, fig.width = 7.5, fig.height = 4, out.width = "100%"}
ssm_plot_curve(results3)
```

```{r general_plot4, fig.width = 7.5, fig.height = 4, out.width = "100%"}
ssm_plot_curve(results3, drop_lowfit = TRUE)
```

## 2. Contrast analyses
The final argument to master in this vignette is `contrast`, which allows us to compare two groups or measures. Setting this argument to TRUE will first generate scores for each group (or measure), then estimate SSM parameters for these scores, and finally calculate the difference between the parameters. To keep the code simpler and to discourage "fishing expeditions," only two groups or measures can be compared at a time.

### Contrasts between groups' means
To compare the mean profiles for females and males, we can start with the same syntax we had before and then add a `contrast` argument.

```{r model_contrast}
results4 <- ssm_analyze(
  data = jz2017, 
  scales = PANO(), 
  angles = octants(), 
  grouping = "Gender", 
  contrast = TRUE
)
summary(results4)
```

Note that we have the profile blocks for each group as well as a contrast block. The contrast is made by subtracting the first level of the grouping variable from the second level (e.g., Male - Female). This provides an indication of the direction of the contrast. We can again generate a table and figure to display the results.

```r
ssm_table(results4)
```

```{r model_table, echo = FALSE}
ssm_table(results4, render = FALSE) %>% 
  knitr::kable(caption = circumplex:::dcaption(results4)) %>% 
  kableExtra::kable_styling(full_width = TRUE, font_size = 12)
```

```{r model_plot, fig.width = 7.5, fig.height = 4, out.width = "100%"}
ssm_plot_contrast(results4)
```

### Contrasts between measures in a group
Comparing measures in a group is very similar. Again, all we need to do is add the `contrast` argument to the function call containing `measures`. Here we will use a parameter contrast to see what they look like.

```{r measure_contrast}
results5 <- ssm_analyze(
  data = jz2017, 
  scales = PANO(), 
  angles = octants(), 
  measures = c("NARPD", "ASPD"),
  contrast = TRUE
)
summary(results5)
```

```r
ssm_table(results5)
```

```{r measure_contrast_table, echo = FALSE, results = "asis"}
ssm_table(results5, render = FALSE) %>% 
  knitr::kable(caption = circumplex:::dcaption(results5)) %>% 
  kableExtra::kable_styling(full_width = TRUE, font_size = 12)
```

```{r measure_contrast_plot, fig.width = 7.5, fig.height = 4, out.width = "100%"}
ssm_plot_contrast(results5)
```

Here, instead of a circle plot, we see a contrast plot showing the difference between the two measures' SSM parameters and their 95% confidence intervals. Because the confidence interval for the elevation parameter does not include zero, this parameter is significantly different between the measures.

### Contrasts between groups' correlations
Finally, we might want to compare a single measure's profiles in two different groups. To do so, we need to specify the `measures`, the `grouping` variable, and the type of `contrast`. In this case, we need to ensure that we are providing only a single measure and a grouping variable with just two levels (as again only two things can be contrasted at a time). Note that the contrast name in this case will take the form of "Measure: Group2 - Group1".

```{r group_contrast}
results6 <- ssm_analyze(
  data = jz2017, 
  scales = PANO(), 
  angles = octants(), 
  measures = "BORPD", 
  grouping = "Gender", 
  contrast = TRUE
)
summary(results6)
```

```r
ssm_table(results6)
```

```{r group_contrast_table, echo = FALSE, results = "asis"}
ssm_table(results6, render = FALSE) %>% 
  knitr::kable(caption = circumplex:::dcaption(results6)) %>% 
  kableExtra::kable_styling(full_width = TRUE, font_size = 12)
```

```{r group_contrast_plot, fig.width = 7.5, fig.height = 4, out.width = "100%"}
ssm_plot_contrast(results6)
```

## 3. Taxonomy of analysis types
Although all SSM analyses are based on the idea of decomposing circumplex scores into the parameters of a cosine curve, there are actually many different ways to implement it. Each of these implementations allows different questions to be explored. In the table below, a list of the SSM analysis types that are currently implemented in the `circumplex` package is provided. This table also provides the specific combination of arguments needed to implement each analysis using the `ssm_analyze()` function. Specifying which analysis to run is simply a matter of providing the correct arguments to the function; this allows a single function to essentially do the work of seven and makes for a more intuitive user experience.

```{r taxonomy, echo = FALSE}
msr <- c("FALSE", "FALSE", "FALSE", "TRUE",  "TRUE",  "TRUE",  "TRUE")
grp <- c("FALSE", "TRUE",  "TRUE",  "FALSE", "FALSE", "TRUE",  "TRUE")
ctr <- c("FALSE", "FALSE", "TRUE",  "FALSE", "TRUE",  "FALSE", "TRUE")
tab <- data.frame(
  Usage = c(
    "Examine overall mean profile",
    "Examine groups' mean profiles",
    "Compare groups' mean profiles",
    "Examine variables' correlation profiles",
    "Compare variables' correlation profiles",
    "Examine groups' correlation profiles",
    "Compare groups' correlation profiles"
  ),
  measures = msr,
  grouping = grp,
  contrast = ctr
)
knitr::kable(tab, escape = FALSE) %>% 
  column_spec(1, width = "3in") %>% 
  add_header_above(c("", "Arguments Needed" = 3))
```

The three main questions to ask when conducting a new SSM analysis are:

1. **Do we want to project non-circumplex measures into the circumplex space?**
If yes, we must specify one or more `measures`, and the scores that get modeled using SSM will be the correlations between the circumplex scales and these measures. If no, we must omit the `measures` argument, and the scores that get modeled using SSM will be the mean scores on the circumplex scales.

1. **Do we want to perform analyses separately for groups within the dataset?**
If yes, we must specify a `grouping` variable, and the output will contain results for each group (i.e., unique value of this variable). If no, we must omit the `grouping` argument, and a single set of results for all data will be output.

1. **Do we want to contrast/compare two sets of results?** If yes, we must specify `contrast` as TRUE and ensure that we are only requesting two sets of results (i.e., two groups or two measures). If no, we must omit the `contrast` argument or set it to FALSE, and the results themselves will be output, rather than their contrast.

## 4. Working with SSM tables

### Basic customizations of tables
Additional arguments to the `ssm_table()` function can be explored using the `?ssm_table` command. Two useful options are the `drop_xy` argument, which shows or hides the x-value and y-value columns, and the `caption` argument which allows a custom string to be printed above the table. Note as well that the return object of this function is just a data frame, which can be easily edited to add, change, or remove text. To change the formatting of the table, see the `htmlTable` or `kableExtra` packages.

## 5. Working with SSM figures

### Exporting figures as files
All SSM plots are created using the `ggplot2` package, which is incredibly flexible and powerful. It also offers the `ggsave()` function to export figures to external files of various types. See the documentation for this function (`?ggsave`) to learn more, but some useful arguments are `filename`, `plot`, `width`, `height`, and `units`. We can save the figure as a raster image file (e.g., "png", "jpeg", "tiff"), a vector image file (e.g., "svg"), or a portable document (e.g., "pdf" or "tex"). We can also control the exact width and height of the image in different units (i.e., "in", "cm", or "mm"). Because the underlying graphics are vectorized in R, they can be easily scaled to any size without loss of quality and used in manuscripts, presentations, or posters.

```r
ssm_plot(results6)
ggsave("bordpd_gender.png", width = 7.5, height = 4, units = "in")
```

## Wrap-up
In this vignette, we learned how to generalize the SSM analyses to multiple groups and measures, how to conduct contrast analyses, how to make basic customizations to tables and figures, and how to export tables and figures to external files. In the next vignette, "Advanced Circumplex Visualization," we will learn more advanced customization options for the SSM figures and other circumplex visualizations. (Note that the next vignette is still in progress.)

## References
* Gurtman, M. B. (1992). Construct validity of interpersonal personality measures: The interpersonal circumplex as a nomological net. _Journal of Personality and Social Psychology, 63_(1), 105–118.

* Gurtman, M. B., & Pincus, A. L. (2003). The circumplex model: Methods and research applications. In J. A. Schinka & W. F. Velicer (Eds.), _Handbook of psychology. Volume 2: Research methods in psychology_ (pp. 407–428). Hoboken, NJ: John Wiley & Sons, Inc.

* Wright, A. G. C., Pincus, A. L., Conroy, D. E., & Hilsenroth, M. J. (2009). Integrating methods to optimize circumplex description and comparison of groups. _Journal of Personality Assessment, 91_(4), 311–322.

* Zimmermann, J., & Wright, A. G. C. (2017). Beyond description in interpersonal construct validation: Methodological advances in the circumplex Structural Summary Approach. _Assessment, 24_(1), 3–23.
