# 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:

1. Regular teaching load = 12 credit hours

2. Courses with `ENRLD < 4` are excluded

3. Qualified credit hours beyond regular load are paid at `$2,500 / 3` per hour

4. For `ENRLD < 10`, pay is prorated:

   \[ \text{Compensation} = \left(\frac{\text{ENRLD}}{10}\right) \times \text{rate per CR} \times \text{qualified CR} \]

5. 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.

## 📨 Questions?

For questions or feedback, please open a GitHub issue or contact Dawit Aberra at dawit3000@fvsu.edu.