#' Calculate Topic Cruciality
#'
#' Calculates the cruciality attributable to a particular course-code stem
#' within a plan of study. Topic cruciality is calculated as the sum of the
#' cruciality values for all courses in the plan of study whose course code
#' matches the specified course-code stem.
#'
#' This measure is generalized from the concept of math cruciality described
#' by Ryan (2026), which examines the contribution of required mathematics
#' courses to curriculum complexity. Rather than being restricted to
#' mathematics, this function can be used to calculate the cruciality of any
#' collection of courses that can be identified by a common course-code stem.
#'
#' @param plan_of_study A plan of study for which course crucialities can be
#'   calculated.
#' @param course_code_stem A character string identifying the course-code stem
#'   used to define the topic area. For example, `"MATH"` identifies all
#'   mathematics courses with the `"MATH"` course-code stem.
#' @param include_coreqs A logical value indicating whether corequisite
#' relationships should be included when calculating course crucialities.
#' Defaults to TRUE.
#'
#' @return The topic cruciality, calculated as the sum of the cruciality values
#'   for courses in the plan of study with the specified course-code stem.
#'
#' @references
#' Ryan, O. J. (2026). *The Role of Math Courses in Engineering Education:
#' Examining How Math Courses Shape First-Year Student Transition, Curriculum
#' Complexity, and Time-to-Degree* (Doctoral dissertation, Virginia Tech).
#' https://vtechworks.lib.vt.edu/items/4ddd7b33-8700-45d4-988d-2111a2970389


topic_cruciality <- function(plan_of_study, course_code_stem, include_coreqs = TRUE)
{
  crucialities <- structural_complexity(plan_of_study = plan_of_study, include_coreqs = include_coreqs)[[1]]$Cruciality
  all_courses <- V(plan_of_study)$name
  relevant_courses_index <- grepl(course_code_stem,all_courses)
  relevant_crucialities <- crucialities[relevant_courses_index]
  result <- sum(relevant_crucialities)
  return(result)
}

