add_timely_term {midfieldr}

Calculate a timely completion term for every student

Description

Add a column to a data frame of student-level records that indicates the latest term by which degree completion would be considered timely for every student.

Usage

add_timely_term(
  dframe,
  midfield_term = term,
  ...,
  span = NULL,
  sched_span = NULL
)

Arguments

dframe

Working data frame of student-level records to which timely-term columns are to be added. Required variable is mcid.

midfield_term

MIDFIELD term data table or equivalent with required variables mcid, term, and level.

...

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

span

Optional integer scalar, number of years to define timely completion. Commonly used values are are 100, 150, and 200 percent of sched_span. Default 6 years.

sched_span

Optional integer scalar, the number of years an institution officially schedules for completing a program. Default 4 years.

Details

By "completion" we mean an undergraduate earning their first baccalaureate degree (or degrees, for students earning more than one degree in the same term).

In many studies, students must complete their programs in a specified time span, for example 4-, 6-, or 8-years after admission. If they do, their completion is timely; if not, their completion is late and they are grouped with the non-completers when computing a metric such as graduation rate.

Our heuristic assigns span number of years (default is 6 years) to every student. For students admitted at second-year level or higher, the span is reduced by one year for each full year the student is assumed to have completed. For example, a student admitted at the second-year level is assumed to have completed one year of a program, so their span is reduced by one year.

The adjusted span is added to the initial term to create the timely completion term in the timely_term column.

Value

A data frame in data.table format with the following properties: rows are preserved; columns are preserved with the exception that columns added by the function overwrite existing columns of the same name (if any); grouping structures are not preserved. The added columns are:

term_i

Character. Initial term of a student's longitudinal record, encoded YYYYT

level_i

Character. Student level (01 Freshman, 02 Sophomore, etc.) in their initial term

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 for every student. Encoded YYYYT.

See Also

Other add_*: add_completion_status(), add_data_sufficiency()

Examples

# Start with an excerpt from the student data set 
dframe <- toy_student[1:10, .(mcid)]

# Add timely completion term column
add_timely_term(dframe, midfield_term = toy_term)

# Define timely completion as 200% of scheduled span (8 years)
add_timely_term(dframe, midfield_term = toy_term, span = 8)

# Existing timely_term column, if any, is overwritten
dframe[, timely_term := NA_character_]
add_timely_term(dframe, midfield_term = toy_term)