Working-with-academic-data

library(retention.helpers)
library(tidyverse)

Leveraging the grade helper functions

There are a series of useful functions with the prefix add_grade_*. The function add_grade_helpers adds all of these to any data frame with grade as a field:

some_sample_grades <- 
    tibble(grade = c("FL", "FNS", "PS", "PS", "HD", "GP", "ZZ"))

some_sample_grades |> 
    add_grade_helpers()
#> # A tibble: 7 × 7
#>   grade grade_substantive grade_success grade_gpa grade_fail grade_zf grade_npe
#>   <chr> <lgl>             <lgl>         <lgl>     <lgl>      <lgl>    <lgl>    
#> 1 FL    TRUE              FALSE         TRUE      TRUE       FALSE    FALSE    
#> 2 FNS   TRUE              FALSE         TRUE      TRUE       TRUE     TRUE     
#> 3 PS    TRUE              TRUE          TRUE      FALSE      FALSE    FALSE    
#> 4 PS    TRUE              TRUE          TRUE      FALSE      FALSE    FALSE    
#> 5 HD    TRUE              TRUE          TRUE      FALSE      FALSE    FALSE    
#> 6 GP    FALSE             FALSE         FALSE     FALSE      FALSE    FALSE    
#> 7 ZZ    FALSE             FALSE         FALSE     FALSE      FALSE    FALSE

Note that grade_zf and grade_npe are identical. This is because sometimes we have used the term Zero-fail or Non-Participating Enrolment to indicate the same thing - a failing grade where the student also received a mark of 0 (FNS grade). To see how these are calculated refer to the table retention.helpers::grade_classifications.

If you only want a particular field appended to the data frame use add_grade_* instead:

some_sample_grades |> 
    add_grade_substantive() |> 
    add_grade_success()
#> # A tibble: 7 × 3
#>   grade grade_substantive grade_success
#>   <chr> <lgl>             <lgl>        
#> 1 FL    TRUE              FALSE        
#> 2 FNS   TRUE              FALSE        
#> 3 PS    TRUE              TRUE         
#> 4 PS    TRUE              TRUE         
#> 5 HD    TRUE              TRUE         
#> 6 GP    FALSE             FALSE        
#> 7 ZZ    FALSE             FALSE

For instance, you might want to count the grade distribution of only substantive (finalised and counting towards progress):

some_sample_grades |> 
    add_grade_helpers() |> 
    filter(grade_substantive) |> 
    count(grade)
#> # A tibble: 4 × 2
#>   grade     n
#>   <chr> <int>
#> 1 FL        1
#> 2 FNS       1
#> 3 HD        1
#> 4 PS        2

Summarising grade data

The helpers can be used to calculate aggregates of grades, such as progress rates and GPA (using the gpa function).

some_sample_grades |> 
    add_grade_helpers() |> 
    summarise(
        progress_rate = sum(grade_success) / sum(grade_substantive),
        gpa = gpa(grade)
    )
#> # A tibble: 1 × 2
#>   progress_rate   gpa
#>           <dbl> <dbl>
#> 1           0.6     5

Additionally, there is a function retention.helpers::summarise_academic() that aggregates a set of grades into two descriptions, result and result_long. This makes more sense to use with a grouped data frame.

tibble(
    student = c("A", "A", "A", "B", "B", "B"),
    grade = c("PS", "DI", "GP", "FNS", "FL", "PS")) |> 
    group_by(student) |> 
    summarise_academic()
#> # A tibble: 2 × 3
#>   student result_long       result    
#>   <chr>   <fct>             <fct>     
#> 1 A       Pass all          Pass      
#> 2 B       Failing (some ZF) Partial ZF

# additionally, there is an option to include the list of (substantive) grades
tibble(
    student = c("A", "A", "A", "B", "B", "B"),
    grade = c("PS", "DI", "GP", "FNS", "FL", "PS")) |> 
    group_by(student) |> 
    summarise_academic(include_grades = TRUE)
#> # A tibble: 2 × 4
#>   student grades      result_long       result    
#>   <chr>   <chr>       <fct>             <fct>     
#> 1 A       DI, PS      Pass all          Pass      
#> 2 B       FL, FNS, PS Failing (some ZF) Partial ZF

Additional summary functions can be included, if used like a normal dplyr::summarise function. These can leverage any of the extra fields added from retention.helpers::add_grade_helpers.

tibble(
    student = c("A", "A", "A", "B", "B", "B"),
    grade = c("PS", "DI", "GP", "FNS", "FL", "PS")) |> 
    group_by(student) |> 
    summarise_academic(
        n_substantive_grades = sum(grade_substantive),
        progress_rate = sum(grade_success) / sum(grade_substantive)
    )
#> # A tibble: 2 × 5
#>   student result_long       result     n_substantive_grades progress_rate
#>   <chr>   <fct>             <fct>                     <int>         <dbl>
#> 1 A       Pass all          Pass                          2         1    
#> 2 B       Failing (some ZF) Partial ZF                    3         0.333