---
title: "Additional-Workflows"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Additional-Workflows}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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


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


This vignette guides you through alternative workflows that might be applicable
if your data is not stored in lists or if you wish to experiment with an idmact-like
algorithm such as with functions other than the mean.

## Using df

The first example replicates the idmact_subj workflow from the README example,
but here we incorporate idmact_subj's df parameter. Start by setting up the data
frame for a scenario where the raw scores and the raw-to-scale map are all in the
same data frame.

```{r}
# Create 100 raw scores
set.seed(279)
raw_scores <- as.list(sample(1:100, 100, replace = TRUE))

# Map between raw scores and scale scores for each form

## Each form has scale scores ranging from 1 to 12
map_scale <- c(1:12)

## Each assessment has raw scores ranging from 1 - 100
map_raw_formA <- list(1:5, 6:20, 21:25, 26:40, 41:45, 46:50, 51:55,
                   56:75, 76:80, 81:85, 86:90, 91:100)

map_raw_formB <- list(1:10, 11:20, 21:30, 31:40, 41:50, 51:55, 56:65,
                   66:75, 76:85, 86:90, 91:95, 96:100)

formA <- map_elongate(map_raw = map_raw_formA,
                      map_scale = map_scale)

formB <- map_elongate(map_raw = map_raw_formB,
                      map_scale = map_scale)

df_A <- data.frame(raw = unlist(formA$map_raw),
                   scale = unlist(formA$map_scale),
                   scores = unlist(raw_scores))

df_B<- data.frame(raw = unlist(formB$map_raw),
                   scale = unlist(formB$map_scale),
                   scores = unlist(raw_scores))
```


Next, execute the subject-level algorithm as follows:

```{r}
resA <- idmact_subj(df = df_A,
                    raw = "scores",
                    map_raw = "raw",
                    map_scale = "scale")


resB <- idmact_subj(df = df_B,
                    raw = "scores",
                    map_raw = "raw",
                    map_scale = "scale")
```


Now, perform the comparison:

```{r}
cat("Form A subject level delta:", resA$deltas, "\n")
cat("Form B subject level delta:", resB$deltas)
```


## Using df and df_map

In some cases, it may make sense to use the workflow described above. However,
it's generally more useful to use both df and df_map. This example uses the same
raw data and maps as the previous example.

```{r}
# First make sure the information in map_raw_formA and map_raw_formB is the same
# length as the information in map_scale
map_raw_formA <- as.character(alist(1-5, 6-20, 21-25, 26-40, 41-45, 46-50, 51-55,
                   56-75, 76-80, 81-85, 86-90, 91-100))

map_raw_formB <- as.character(alist(1-10, 11-20, 21-30, 31-40, 41-50, 51-55, 56-65,
                   66-75, 76-85, 86-90, 91-95, 96-100))

# Then form the df_raw data frames
df_raw_A <- data.frame(raw = map_raw_formA,
                       scale = map_scale)
df_raw_A <- map_elongate_df(df_raw_A, "raw", "scale")

df_raw_B <- data.frame(raw = map_raw_formB,
                       scale = map_scale)
df_raw_B <- map_elongate_df(df_raw_B, "raw", "scale")

# Now the df data frame only needs to hold the raw scores
df <- data.frame(scores = unlist(raw_scores))
```


Next, execute the subject-level algorithm:

```{r}
resA <- idmact_subj(df = df,
                    df_map = df_raw_A,
                    raw = "scores",
                    map_raw = "raw",
                    map_scale = "scale")


resB <- idmact_subj(df = df,
                    df_map = df_raw_B,
                    raw = "scores",
                    map_raw = "raw",
                    map_scale = "scale")
```


Now, perform the comparison as before:

```{r}
cat("Form A subject level delta:", resA$deltas, "\n")
cat("Form B subject level delta:", resB$deltas)
```


## Custom Functions

As the name suggests, the Schiel (1998)
<https://www.act.org/content/dam/act/unsecured/documents/ACT_RR98-01.pdf> algorithm
for interpreting differences between mean ACT assessment scores focuses on the mean.
However, to facilitate development and experimentation, the functions in the
idmact package include parameters where the user can input anonymous functions
instead of using the defaults.

The example below showcases an implementation of the idmact algorithm focusing on
medians. In this example, we use the df, df_raw_A, and df_raw_B data frames from
the previous example.

First, run idmact_subj and switch the mcent_subj function to median:


```{r}
resA <- idmact_subj(df = df,
                    df_map = df_raw_A,
                    raw = "scores",
                    map_raw = "raw",
                    map_scale = "scale",
                    mcent_subj = function(x) median(x, na.rm = TRUE))


resB <- idmact_subj(df = df,
                    df_map = df_raw_B,
                    raw = "scores",
                    map_raw = "raw",
                    map_scale = "scale",
                    mcent_subj = function(x) median(x, na.rm = TRUE))
```


Finally, perform the comparisons:

```{r}
cat("Form A subject level delta:", resA$deltas, "\n")
cat("Form B subject level delta:", resB$deltas)
```
