Skip to contents

Determine timely completion terms

Source: R/timely_term.R
timely_term.Rd

Determines the latest term by which program completion would be considered timely. Adds columns to the data frame that support the finding.

Usage

timely_term(dframe, midf_table = term, ..., span = NULL, sched_span = NULL)

Arguments

dframe

Data frame or data frame extension (e.g., data.table or tibble) with required variable {mcid}.

midf_table

term data frame with required variables {mcid, term, level}.

...

Not used for passing values; forces subsequent arguments to be referable only by name.

span

Integer scalar (default 6), number of years to define timely completion, typically 4, 6, or 8 years (100%, 150%, 200% respectively of sched_span).#'

sched_span

Integer scalar (default 4), the number of years an institution officially schedules for completing a program.

Value

Data frame with the following properties:

  • Data frame class is preserved. Groups and keys are not preserved.

  • Row order is preserved. Rows with NA values in any of the required variables are removed. Duplicated rows are removed.

  • New columns are added unless they are redundant (see Details). The new variables are:

    • entry_term   Character. Initial term of a student's longitudinal record, encoded YYYYT. Extracted from midf_table.

    • entry_level   Character. Student level (01 Freshman, 02 Sophomore, etc.) in their initial term. Extracted from midf_table.

    • adj_span   Numeric. Integer span of years for timely completion adjusted for a student's initial level.

    • timely_term   Character. Latest term by which program completion would be considered timely. Encoded YYYYT.

Details

Completing an academic program in a "timely" manner means that a student completes the requirements for a degree within a set time span, typically 4, 6, or 8 years after admission depending on the definition adopted in a particular study. The final term of that span is the timely completion term.

Our heuristic assigns a time span of 6 academic years for timely completion (other values can be assigned via the span argument). For students admitted at second-year level or higher, the span value is reduced by one academic year for each full year the student is assumed to have completed. The adjusted span is added to their initial term at an institution to create the timely_term value for each observation.

Redundant columns. To prevent overwriting, a variable such as timely_term is not added to the data frame if it duplicates an existing variable. The test for redundancy is managed internally by calling rm_redundant_cols() before the final data frame is returned. For documentation, see ?rm_redundant_cols.

Examples

# Assign toy data sets
student <- toy_student
term <- toy_term

# Start with a selected population
x <- student[c(9:11, 21:30, 344:345), .(mcid)]
x
#>               mcid
#>             <char>
#>  1: MCID3111169729
#>  2: MCID3111170852
#>  3: MCID3111173999
#>  4: MCID3111257807
#>  5: MCID3111258275
#>  6: MCID3111258347
#>  7: MCID3111259642
#>  8: MCID3111262210
#>  9: MCID3111265287
#> 10: MCID3111269576
#> 11: MCID3111272691
#> 12: MCID3111272880
#> 13: MCID3111277081
#> 14: MCID3112751130
#> 15: MCID3112754537

# Add timely term columns
x <- timely_term(x, midf_table = term)
x
#>               mcid entry_term   entry_level adj_span timely_term
#>             <char>     <char>        <char>    <num>      <char>
#>  1: MCID3111169729      19881 01 First-year        6       19933
#>  2: MCID3111170852      19881 01 First-year        6       19933
#>  3: MCID3111173999      19881 01 First-year        6       19933
#>  4: MCID3111257807      19901 01 First-year        6       19953
#>  5: MCID3111258275      19901 01 First-year        6       19953
#>  6: MCID3111258347      19901 01 First-year        6       19953
#>  7: MCID3111259642      19901 01 First-year        6       19953
#>  8: MCID3111262210      19901 01 First-year        6       19953
#>  9: MCID3111265287      19901 01 First-year        6       19953
#> 10: MCID3111269576      19901 01 First-year        6       19953
#> 11: MCID3111272691      19901 01 First-year        6       19953
#> 12: MCID3111272880      19901 01 First-year        6       19953
#> 13: MCID3111277081      19903 01 First-year        6       19961
#> 14: MCID3112751130      20151 01 First-year        6       20203
#> 15: MCID3112754537      20151 01 First-year        6       20203

# No change if added columns duplicate existing
y <- timely_term(x, midf_table = term)
check_equiv_frames(x, y)
#> [1] TRUE