---
title: "siren Vignette"
author: "David Navarro-Gonzalez, Pere Joan Ferrando, Fabia Morales-Vives and Ana Hernandez-Dorado "
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{siren Vignette}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

This vignette ilustrates siren functions using the provided example dataset.

## Overview

siren performs an hybrid multi-stage factor analytic procedure for controlling the effects of Acquiescence (ACQ) in multidimensional questionnaires for which a restricted factorial solution (Ferrando & Lorenzo-Seva, 2000) can be specified. In the first stage, an ACQ factor is estimated and its effects are partialled-out from the inter-item correlations. In the second, a specified CFA solution is fitted to the cleaned matrix. This solution can be specified in two ways: (a) using the cleaned correlation matrix as input, or (b) specifying a full solution which has fixed loadings on the ACQ factor. The use of the program allows (a) the structural properties of the questionnaire to be assessed and (b) unbiased factor score estimates to be obtained for each respondent.

## Usage

    acquihybrid(x, content_factors, target, corr = "Pearson", raw_data=TRUE,
       method = "fixed", display = TRUE)

The complete description of the arguments can be found in the function documentation:

```{r, eval=FALSE}
?acquihybrid
```
    
The minimum required arguments are: the raw sample scores (x), the content factors to be retained (content_factors) and the target matrix (target), which provides the direction of each item in their corresponding factor.

In the next section we will provide an empirical example, describing all the used input arguments.

## Example

To illustrate how siren works, we have used an existing dataset of 1309 participants (55.8% females) between 14 and 19 years old (M = 16.4, S.D. = 1.1) from three previous studies (Morales-Vives & Dueñas, 2018; Morales-Vives et al., 2020; Morales-Vives et al., in press.

All participants answered the Psychological Maturity Assessment Scale questionnaire (PSYMAS; Morales-Vives et al., 2013), which assesses the psychological maturity of adolescents, understood as the ability to take responsibility for one's own obligations, taking into account one's own characteristics and needs, without showing excessive dependence on others. It consists of 27 items with a five-point response format (1 = Completely disagree, 5 = Completely agree) and it assesses the following factors: work orientation, self-reliance, and identity.

In the current analysis, we have only used ten items from two of the subscales of this questionnaire (four items of self-reliance subscale and six items of identity subscale) so that within each subscale half of the items were in one direction (lack of maturity) and the other half in the opposite direction (high maturity). Self-reliance refers to willingness to take the initiative without allowing others to exercise excessive control, and Identity refers to knowledge about own’s characteristics and needs.

The complete dataset is available through `siren::psymas`. For illustrative purposes, the first 10 responders' scores are:

```{r, echo=FALSE, results='asis'}
knitr::kable(cbind(paste0("responder", 1:10),head(siren::psymas, 10)), col.names = c("Responder","I1 ","I2 ","I3 ","I4 ","I5 ","I6 ","I7 ","I8 ","I9 ","I10"))
```

As mentioned, the `content factors` to be retained in this case will be 2 (Self-reliance and identity).

Finally, the `target_matrix` of the 10 items is a matrix composed by 0 (the item does not measure this factor), -9 or 9, when the item measures the item, in reverse or direct way.

    psymas_target=cbind(c(-9,-9,0,0,0,9,0,0,9,0),c(0,0,-9,9,-9,0,9,-9,0,9))

Which reads as:

```{r, echo=FALSE, results='asis'}
knitr::kable(cbind(c("I1","I2","I3","I4","I5","I6","I7","I8","I9","I10"),c(-9,-9,0,0,0,9,0,0,9,0),c(0,0,-9,9,-9,0,9,-9,0,9)), col.names = c("Item","F1","F2"))
```

Finally, the example can be computed using the following code:

    acquihybrid(psymas, content_factors = 2, target = psymas_target, corr = "Polychoric")

```{r, include = FALSE}
library(siren)
psymas_target=cbind(c(-9,-9,0,0,0,9,0,0,9,0),c(0,0,-9,9,-9,0,9,-9,0,9))
results = acquihybrid(psymas,content_factors=2,target = psymas_target, corr = "Polychoric")
psymas_loadings = results$loadings
fit_indices = results$fit_indices
psymas_pfactors = results$pfactors
```

The factor loadings scores are:

```{r, echo=FALSE, results='asis'}
rownames(psymas_loadings) <- c("I1", "I2", "I6", "I9", "I3", "I4", "I5", "I7", "I8", "I10")
knitr::kable(psymas_loadings, col.names = c("Item", "F1", "F2", "ACQ"))
```

The fit indices scores are: GFI = `r round(fit_indices$gfi,3)`, SRMR = `r round(fit_indices$srmr,3)`, RMSEA = `r round(fit_indices$rmsea,3)`, and CFI = `r round(fit_indices$cfi,3)`.


Finally, the individual factor scores are computed. Here are the factor scores of the first 10 responders:

```{r, echo=FALSE, results='asis'}
knitr::kable(cbind(paste0("responder", 1:10),head(round(psymas_pfactors,3), 10)), col.names = c("Responder","F1", "F2", "ACQ"))
```

## References

Ferrando, P. J., & Lorenzo-Seva, U. (2000). Unrestricted versus restricted factor analysis of multidimensional test items: Some aspects of the problem and some suggestions. Psicológica, 21(2), 301-323.

Ferrando, P. J., & Lorenzo-Seva, U. (2010). Unrestricted item factor analysis and some relations with item response theory. Technical report, Department of Psychology, Universitat Rovira i Virgili, Tarragona.http://psico.fcep.urv.es/utilitats/factor. 

Ferrando, P. J., Lorenzo-Seva, U., & Chico, E. (2003). Unrestricted factor analytic procedures for assessing acquiescent responding in balanced, theoretically unidimensional personality scales. Multivariate Behavioral Research, 3(38):353–374, doi:10.1207/S15327906MBR3803_04

Morales-Vives, F., Camps, E., & Lorenzo-Seva, U. (2012). Manual del Cuestionario de Madurez Psicológica PSYMAS. TEA Ediciones, S.A. 

Morales-Vives, F., Camps, E., & Lorenzo-Seva, U. (2013). Development and validation of the psychological maturity assessment scale (PSYMAS). European Journal of Psychological Assessment. doi:10.1027/1015-5759/a000115
