catool: Walkthrough

🔍 Introduction

This vignette demonstrates how to use the catool R package to calculate fair and transparent overload compensation for college instructors, based on institutional course schedules and compensation policies.

The package supports analysis for both individual instructors and full teaching schedules using well-defined eligibility and proration rules based on enrollment and credit hour thresholds.

🏫 Prepare Your Schedule Data

To use catool, your schedule data must include at minimum:

INSTRUCTOR: Instructor name (e.g., “Baker, Danielle”)
ENRLD: Enrollment count for each course
HRS: Credit hours for each course

📂 Sample input:

The schedule.csv file from the “inst/extdata” folder provides a realistic example of course schedule data used by the package. It includes columns such as SUBJ, CRN, INSTRUCTOR,DEPARTMENT and COLLEGE fields.

schedule <- data.frame(
  INSTRUCTOR = c("Lalau-Hitchcock, Diksha", "Lalau-Hitchcock, Diksha", "Brown, Cecily"),
  ENRLD = c(12, 7, 4),
  HRS = c(3, 3, 3),
  stringsAsFactors = FALSE
)

If you have extended data including subject codes, departments, colleges, and programs, make sure those columns are labeled as SUBJ, DEPARTMENT, COLLEGE, and PROGRAM respectively.

🔎 Filter Schedules with `filter_schedule()`

You can filter a schedule using subject codes, instructor names, department, college, or program using pattern matching.

# Filter by subject pattern
filter_schedule(schedule, subject_pattern = "MATH|CSCI")

# Filter by instructor
filter_schedule(schedule, instructor_pattern = "Armbruster|al-Abdul")

# Filter by department
filter_schedule(schedule, department_pattern = "Business Administration")

# Filter by college
filter_schedule(schedule, college_pattern = "arts")

# Filter by program
filter_schedule(schedule, program_pattern = "computation")

👤 Analyze One Instructor

# Filter by instructor name (case-insensitive)
inst_schedule <- get_instructor_schedule("Lalau-Hitchcock", schedule)

# Calculate overload compensation using default policy
ol_comp(inst_schedule)

# You can also apply custom policy parameters
ol_comp(inst_schedule, L = 4, U = 8, reg_load = 9, rate_per_cr = 5000 / 3)

# Compare institutional vs instructor interest
ol_comp(inst_schedule, favor_institution = TRUE)  # Less pay
ol_comp(inst_schedule, favor_institution = FALSE) # More pay

👥 See All Instructors in the Schedule

get_unique_instructors(schedule)

🔢 Analyze by Instructor Index

# Get summary for a specific instructor by index
ol_comp_byindex(1, schedule_df = schedule)

# With custom policy
ol_comp_byindex(1, schedule_df = schedule, L = 4, U = 9, reg_load = 12, rate_per_cr = 2500 / 3)

📋 Summarize All Instructors

The ol_comp_summary() function generates a comprehensive compensation report for all instructors in the schedule.

Purpose:

Aggregate overload pay calculations for payroll or administration
Enforce consistent application of institutional policy
Return a tidy summary table with all instructors and their compensation lines

Default usage:

ol_comp_summary(schedule)

Custom policy parameters:

ol_comp_summary(schedule, L = 4, U = 9, reg_load = 12, rate_per_cr = 2500 / 3)

Compare strategies for all instructors:

# Favoring institution (less total pay)
ol_comp_summary(schedule, favor_institution = TRUE)

# Favoring instructor (more total pay)
ol_comp_summary(schedule, favor_institution = FALSE)

📊 Output Format

The output returned by ol_comp_summary() includes:

Column	Description
`SUBJ`	Course subject (if provided)
`INSTR`	Instructor name
`HRS`	Credit hours for the course
`ENRLD`	Enrollment count
`QHRS`	Qualified credit hours eligible for compensation
`TYPE`	`PRO` if proration applies (ENRLD < U), `TOT` for total rows
`PAY`	Dollar amount for that row, rounded to two decimal places
`SUMMARY`	Contains instructor name, policy notes, or total lines

Note:

Compensation is calculated based only on qualified credit hours
Courses with ENRLD < 4 are excluded
Compensation is prorated when ENRLD < 10 (based on threshold U)
Total overload amounts appear in the SUMMARY column as: "TOTAL OVERLOAD: $6,833.33" (rounded to two decimal places)

⚖️ Policy Logic

Default institutional policy:

Regular teaching load = 12 credit hours
Courses with ENRLD < 4 are excluded
Qualified credit hours beyond regular load are paid at $2,500 / 3 per hour
For ENRLD < 10, pay is prorated:

\[ \text{Compensation} = \left(\frac{\text{ENRLD}}{10}\right) \times \text{rate per CR} \times \text{qualified CR} \]
Overload hours are assigned based on the favor_institution strategy:
- If favor_institution = TRUE, least-enrolled eligible courses are counted toward overload
- If favor_institution = FALSE, most-enrolled eligible courses are preserved for compensation

🧭 Instructor vs Institutional Interest Inclination Strategy

You can specify how regular teaching load is assigned when determining overload pay:

favor_institution = TRUE → Favor institutional interest → Assign high-enrollment courses to regular load first → Leaves low-enrollment courses for compensation → Results in less total pay
favor_institution = FALSE → Favor instructor interest → Assign low-enrollment courses to regular load first → Leaves high-enrollment courses for compensation → Results in more total pay

This option is supported in both ol_comp() and ol_comp_summary() functions.