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

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

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

This document presents the example application of the rMOST package. Please refer to Study 3 of Zhang et al. (in press) for a complete guideline on adopting multi-objective optimization for personnel selection.

# Prepare inputs

Note that different input parameters are required for different types of optimization problems. Below are the inputs needed for an example multi-objective optimization problem with 5 predictors.

```{r}
## Input ##

# Predictor intercorrelation matrix
Rx <- matrix(c(  1,  .37, .51, .16, .25,
               .37,   1, .03, .31, .02,
               .51, .03,   1, .13, .34,
               .16, .31, .13,   1,-.02,
               .25, .02, .34,-.02,   1), 5, 5)

# Criterion validity of the predictors
Rxy1 <- c(.32, .52, .22, .48, .20) 
Rxy2 <- c(.30, .35, .15, .25, .10)
Rxy3 <- c(.15, .25, .30, .35, .10)

# Overall selection ratio
sr <- 0.15

# Proportion of minority applicants
prop_b <- 1/8 # Proportion of Black applicants (i.e., (# of Black applicants)/(# of all applicants))
prop_h <- 1/6 # Proportion of Hispanic applicants

# Predictor subgroup d
d_wb <- c(.39, .72, -.09, .39, .04) # White-Black subgroup difference
d_wh <- c(.17, .79, .08, .04, -.14) # White-Hispanic subgroup difference
```

# Obtain MOO solutions

## 3 Non-adverse impact objectives

An example of such a MOO problem is when an organization seeks to optimize job performance, retention, and organizational commitment.

```{r}
# Example: 3 non-adverse impact objectives
out_3C = MOST(optProb = "3C", 
              # predictor intercorrelations
              Rx = Rx, 
              # predictor - objective relations
              Rxy1 = Rxy1, # non-AI objective 1
              Rxy2 = Rxy2, # non-AI objective 2
              Rxy3 = Rxy3, # non-AI objective 3
              Spac = 10)

# The first few solutions
head(out_3C)
```

## 2 Non-adverse impact objectives and 1 adverse-impact objective

An example of such a MOO problem is when an organization seeks to optimize job performance, retention, and Black-white adverse impact ratio.

```{r}
# Example: 2 non-adverse impact objectives & 1 adverse impact objective 
out_2C_1AI = MOST(optProb = "2C_1AI", 
                  # predictor intercorrelations
                  Rx = Rx, 
                  # predictor - objective relations
                  Rxy1 = Rxy1, # non-AI objective 1
                  Rxy2 = Rxy2, # non-AI objective 2
                  d1 = d_wb, # subgroup difference for minority 1
                  # selection ratio
                  sr = sr, 
                  # proportion of minority
                  prop1 = prop_b, # minority 1
                  Spac = 10)

# The first few solutions
head(out_2C_1AI)
```

## 1 Non-adverse impact objectives and 2 adverse-impact objectives

An example of such a MOO problem is when an organization seeks to optimize job performance, Black-white adverse impact ratio, and Hispanic-white adverse impact ratio. Note that the 2 adverse-impact objectives should have the same reference group. For example, the objectives can be Black-white adverse impact ratio and Hispanic-white adverse impact ratio. The objectives cannot be Black-white adverse impact ratio and female-male adverse impact ratio.

```{r}
# Example: 1 non-adverse impact objective & 2 adverse impact objectives 
out_1C_2AI = MOST(optProb = "1C_2AI",
                  # predictor intercorrelations
                  Rx = Rx, 
                  # predictor - objective relations
                  Rxy1 = Rxy1, # non-AI objective 1
                  d1 = d_wb, # subgroup difference for minority 1
                  d2 = d_wh, # subgroup difference for minority 2
                  # selection ratio
                  sr = sr, 
                  # proportion of minority 
                  prop1 = prop_b, # minority 1
                  prop2 = prop_h, # minority 2
                  Spac = 10)

# The first few solutions
head(out_1C_2AI)
```

# Understand and use the results

Each row of the output corresponds to a set of predictor weights and the corresponding outcome for each of the three objectives.   
* Columns 3 - 5: the expected outcome values for each objective  
* Columns 6 -  : the weights assigned to each predictor  

Given the output of rMOST::MOST(), users can select a final solution (i.e., a final set of predictor weights) based on their goal. Predictor weights of the final solution could be used to create a predictor composite to be used in selection.

Take solution 1 in an optimization problem with 3 non-adverse impact objectives as an example. This solution assigns the weight of `r out_3C[1, 6]` to predictor P1, `r out_3C[1, 7]` to predictor P2, `r out_3C[1, 8]` to predictor P3, `r out_3C[1, 9]` to predictor P4, and `r out_3C[1, 10]` to predictor P5.

```{r}
out_3C[1, 6:ncol(out_3C)]
```

Assuming a top-down selection, a predictor composite created with these weights would result in the following outcomes. The predictor composite would have a validity of `r out_3C[1, 3]` for objective C1, `r out_3C[1, 4]` for objective C2, and `r out_3C[1, 5]` for objective C3.

```{r}
out_3C[1, 3:5]
```