In benwhicks/retention.helpers: Munging, visualisation and analysis helper functions

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
library(tidyverse)
library(retention.helpers)

retention.helpers

The goal of retention.helpers is to provide a few functions to help working with the CSU Retention Team's data set, within the R environment.

``` {r echo = FALSE, message = FALSE, warning = FALSE, fig.height = 2} toy_academic_for_interventions |> inner_join( # only including subjects from the flags list toy_flags |> distinct(subject) ) |> left_join( toy_flags |> mutate(flagged = TRUE) ) |> mutate(flagged = replace_na(flagged, FALSE)) |> left_join(toy_interventions) |> mutate(grp = case_when( !flagged ~ "Engaged", intervention_result == "dialogue" ~ "Disengaged, with dialogue", intervention_result == "no dialogue" ~ "Disengaged, no dialogue") |> fct_relevel("Engaged", "Disengaged, with dialogue")) |> add_grade_helpers() |> filter(grade_substantive) |> ggplot(aes(x = grade, fill = grp, alpha = grade_success)) + geom_histogram(stat = "count") + coord_flip() + theme_minimal() + scale_fill_manual(values = csu_colours, guide = NULL) + scale_alpha_discrete(range = c(1, 0.5), guide = NULL) + facet_wrap(~grp, scales = "free")

## Installation

You can install the development version from [GitHub](https://github.com/) with:

``` r
# install.packages("devtools")
devtools::install_github("benwhicks/retention.helpers")

You should also have the tidyverse installed and loaded to get the most out of the package:

# install.packages("tidyverse")
library(tidyverse)

The best way to interface with the data is through the data.csu.retention package. This package is not shared publicly, so you will need to obtain a copy of the R Package itself and build the package yourself. This is done in RStudio using Ctrl-Shift-B or by going to the Build pane (usually in the top right along with Environment) and selecting Install and Restart.

Overview of functions

Most of the functions are split into groups based on their use and prefix. The main families are add_ and read_.

`add_*`

The add_ family of functions create new columns in a data frame based on data in that table only. This means they are the most broadly useful as the do not require retention.data loaded. For example if offering is in the data frame (in the form ABC123_201990_W_D) then we can extract the subject ABC123, session 201990 or year 2019.

See an example of using the add_* functions

``` {r add-example}

Given some data with offering

dat_with_offering <- tibble( offering = c("MTH100_189030_P_D", "PHL105_189060_B_I") )

dat_with_offering

Add in subject and year from offering

dat_with_offering %>% add_subject_from_offering() %>% add_year_from_offering()

</details>

### `read_*`

The `read_*` style functions operate in a similar fashion to `read_csv` in the tidyverse, expect they are designed to read particular commonly used files and clean them in the process. 


## Loading the Data

This package is designed to work _with_ the retention data set. 

```r
# ============================================= #
# Loading data via the retention.data package
# ============================================= #
library(data.csu.retention)

Toy data

There is also a sample of this data available (simulated and resampled from the original data, so it does not represent any actual student data). These tables are included in this package and all start with the prefix toy_.

glimpse(toy_academic)

There are two sets of tables that match. The first toy data set includes toy_academic, toy_enrolments and toy_student_course. The second set includes toy_academic_for_interventions, toy_flags and toy_interventions.