feat: functions to retrieve all Analytics from canvas LMS

NAMESPACE

@@ -9,6 +9,7 @@ export(create_folder)
 export(create_group_category)
 export(create_page)
 export(download_course_file)
+export(get_accounts)
 export(get_all_courses)
 export(get_assignment_data)
 export(get_assignment_details)
@@ -26,6 +27,10 @@ export(get_course_quizzes)
 export(get_course_sections)
 export(get_course_students)
 export(get_courses)
+export(get_department_grade_data)
+export(get_department_participation_data)
+export(get_department_statistics)
+export(get_department_statistics_by_subaccount)
 export(get_discussions)
 export(get_group_categories)
 export(get_group_info)
@@ -35,6 +40,9 @@ export(get_module_items)
 export(get_modules)
 export(get_page_content)
 export(get_student_summaries)
+export(get_user_course_assignment_data)
+export(get_user_course_messaging_data)
+export(get_user_course_participation_data)
 export(post_new_discussion)
 importFrom(magrittr,"%>%")
 importFrom(rlang,.data)

R/get_accounts.R

@@ -0,0 +1,44 @@
+#' Get a list of accounts from the Canvas LMS API
+#'
+#' Retrieves a paginated list of accounts that the current user can view or manage.
+#'
+#' @param canvas A list containing the 'api_key' and 'base_url' for authentication.
+#' @param include A vector of additional information to include. Default is NULL.
+#' @param per_page Number of accounts to retrieve per page. Default is 100.
+#'
+#' @return A list of accounts retrieved from the Canvas LMS API.
+#' @export
+get_accounts <- function(canvas, include = NULL, per_page = 100) {
+  # Define the legal values for the 'include' parameter
+  legal_values <- c("lti_guid", "registration_settings", "services")
+
+  # Check that the 'include' parameter uses legal values
+  if (!is.null(include)) {
+    if (any(!include %in% legal_values)) {
+      stop("The 'include' parameter must use legal values: 'lti_guid', 'registration_settings', 'services'.")
+    }
+  }
+
+  # Construct the API endpoint URL
+  url <- paste0(canvas$base_url, "/api/v1/accounts?per_page=", per_page)
+
+  # Add the 'include' parameter to the URL if it's not NULL
+  if (!is.null(include)) {
+    url <- paste0(url, "&include[]=", paste(include, collapse = "&include[]="))
+  }
+
+  # Make the API request
+  response <- httr::GET(url, httr::add_headers(Authorization = paste("Bearer", canvas$api_key)))
+
+  # Check the response status code
+  if (httr::status_code(response) != 200) {
+    stop("Failed to retrieve the list of accounts. Please check your authentication and API endpoint.")
+  }
+
+  # Parse the response as JSON
+  accounts <- httr::content(response, "text", encoding = "UTF-8") %>%
+    jsonlite::fromJSON(flatten = TRUE)
+
+  # Return the list of accounts
+  return(accounts)
+}

R/get_department_grade_data.R

@@ -0,0 +1,43 @@
+#' Get department-level grade data from the Canvas LMS API
+#'
+#' Retrieves the department-level grade data for a specific account and term from the Canvas LMS API.
+#'
+#' @param canvas A list containing the 'api_key' and 'base_url' for authentication.
+#' @param account_id The ID of the account for which to retrieve the grade data.
+#' @param type The type of courses to include in the data. Can be 'current', 'completed', or 'term'.
+#' @param term_id The ID of the term for which to retrieve the grade data. Only used when type is 'terms/<term_id>'.
+#' @param per_page Number of grade data to retrieve per page. Default is 100.
+#'
+#' @return A data frame of grade data retrieved from the Canvas LMS API.
+#' @export
+get_department_grade_data <- function(canvas, account_id, type = "current", term_id = NULL, per_page = 100) {
+  # Define the allowed values for the 'type' parameter
+  allowed_values <- c("current", "completed", "term")
+
+  # Check that the 'type' parameter uses allowed values
+  if (!type %in% allowed_values) {
+    stop("The 'type' parameter must use allowed values: 'current', 'completed', 'terms/<term_id>'.")
+  }
+
+  # Construct the API endpoint URL
+  if (type == "term>") {
+    url <- paste0(canvas$base_url, "/api/v1/accounts/", account_id, "/analytics/terms/", term_id, "/grades?per_page=", per_page)
+  } else {
+    url <- paste0(canvas$base_url, "/api/v1/accounts/", account_id, "/analytics/", type, "/grades?per_page=", per_page)
+  }
+
+  # Make the API request
+  response <- httr::GET(url, httr::add_headers(Authorization = paste("Bearer", canvas$api_key)))
+
+  # Check the response status code
+  if (httr::status_code(response) != 200) {
+    stop("Failed to retrieve department-level grade data. Please check your authentication and API endpoint.")
+  }
+
+  # Parse the response as JSON
+  grade_data <- httr::content(response, "text", encoding = "UTF-8") %>%
+    jsonlite::fromJSON(flatten = TRUE)
+
+  # Return the grade data as a data frame
+  return(grade_data)
+}

R/get_department_participation_data.R

@@ -0,0 +1,43 @@
+#' Get department-level participation data from the Canvas LMS API
+#'
+#' Retrieves the department-level participation data for a specific account and term from the Canvas LMS API.
+#'
+#' @param canvas A list containing the 'api_key' and 'base_url' for authentication.
+#' @param account_id The ID of the account for which to retrieve the participation data.
+#' @param type The type of courses to include in the data. Can be 'current', 'completed', or 'term'.
+#' @param term_id The ID of the term for which to retrieve the participation data. Only used when type is 'terms/<term_id>'.
+#' @param per_page Number of participation data to retrieve per page. Default is 100.
+#'
+#' @return A data frame of participation data retrieved from the Canvas LMS API.
+#' @export
+get_department_participation_data <- function(canvas, account_id, type = "current", term_id = NULL, per_page = 100) {
+  # Define the allowed values for the 'type' parameter
+  allowed_values <- c("current", "completed", "term")
+
+  # Check that the 'type' parameter uses allowed values
+  if (!type %in% allowed_values) {
+    stop("The 'type' parameter must use allowed values: 'current', 'completed', 'terms'.")
+  }
+
+  # Construct the API endpoint URL
+  if (type == "term") {
+    url <- paste0(canvas$base_url, "/api/v1/accounts/", account_id, "/analytics/terms/", term_id, "/activity?per_page=", per_page)
+  } else {
+    url <- paste0(canvas$base_url, "/api/v1/accounts/", account_id, "/analytics/", type, "/activity?per_page=", per_page)
+  }
+
+  # Make the API request
+  response <- httr::GET(url, httr::add_headers(Authorization = paste("Bearer", canvas$api_key)))
+
+  # Check the response status code
+  if (httr::status_code(response) != 200) {
+    stop("Failed to retrieve department-level participation data. Please check your authentication and API endpoint.")
+  }
+
+  # Parse the response as JSON
+  participation_data <- httr::content(response, "text", encoding = "UTF-8") %>%
+    jsonlite::fromJSON(flatten = TRUE)
+
+  # Return the participation data as a data frame
+  return(participation_data)
+}

R/get_department_statistics.R

@@ -0,0 +1,42 @@
+#' Get department-level statistics from the Canvas LMS API
+#'
+#' Retrieves department-level statistics for a specific account and term from the Canvas LMS API.
+#'
+#' @param canvas A list containing the 'api_key' and 'base_url' for authentication.
+#' @param account_id The ID of the account for which to retrieve the statistics.
+#' @param type The type of courses to include in the data. Can be 'current', 'completed', or 'term'.
+#' @param term_id The ID of the term for which to retrieve the statistics. Only used when type is 'terms/<term_id>'.
+#'
+#' @return A list of department-level statistics retrieved from the Canvas LMS API.
+#' @export
+get_department_statistics <- function(canvas, account_id, type = "current", term_id = NULL) {
+  # Define the allowed values for the 'type' parameter
+  allowed_values <- c("current", "completed", "term")
+
+  # Check that the 'type' parameter uses allowed values
+  if (!type %in% allowed_values) {
+    stop("The 'type' parameter must use allowed values: 'current', 'completed', 'term'.")
+  }
+
+  # Construct the API endpoint URL
+  if (type == "term") {
+    url <- paste0(canvas$base_url, "/api/v1/accounts/", account_id, "/analytics/terms/", term_id, "/statistics")
+  } else {
+    url <- paste0(canvas$base_url, "/api/v1/accounts/", account_id, "/analytics/", type, "/statistics")
+  }
+
+  # Make the API request
+  response <- httr::GET(url, httr::add_headers(Authorization = paste("Bearer", canvas$api_key)))
+
+  # Check the response status code
+  if (httr::status_code(response) != 200) {
+    stop("Failed to retrieve department-level statistics. Please check your authentication and API endpoint.")
+  }
+
+  # Parse the response as JSON
+  statistics <- httr::content(response, "text", encoding = "UTF-8") %>%
+    jsonlite::fromJSON(flatten = TRUE)
+
+  # Return the statistics
+  return(statistics)
+}

R/get_department_statistics_by_subaccount.R

@@ -0,0 +1,42 @@
+#' Get department-level statistics by subaccount from the Canvas LMS API
+#'
+#' Retrieves department-level statistics for a specific account and term from the Canvas LMS API.
+#'
+#' @param canvas A list containing the 'api_key' and 'base_url' for authentication.
+#' @param account_id The ID of the account for which to retrieve the statistics.
+#' @param type The type of courses to include in the data. Can be 'current', 'completed', or 'term'.
+#' @param term_id The ID of the term for which to retrieve the statistics. Only used when type is 'terms/<term_id>'.
+#'
+#' @return A list of department-level statistics retrieved from the Canvas LMS API.
+#' @export
+get_department_statistics_by_subaccount <- function(canvas, account_id, type = "current", term_id = NULL) {
+  # Define the allowed values for the 'type' parameter
+  allowed_values <- c("current", "completed", "term")
+
+  # Check that the 'type' parameter uses allowed values
+  if (!type %in% allowed_values) {
+    stop("The 'type' parameter must use allowed values: 'current', 'completed', 'term>'.")
+  }
+
+  # Construct the API endpoint URL
+  if (type == "term") {
+    url <- paste0(canvas$base_url, "/api/v1/accounts/", account_id, "/analytics/terms/", term_id, "/statistics_by_subaccount")
+  } else {
+    url <- paste0(canvas$base_url, "/api/v1/accounts/", account_id, "/analytics/", type, "/statistics_by_subaccount")
+  }
+
+  # Make the API request
+  response <- httr::GET(url, httr::add_headers(Authorization = paste("Bearer", canvas$api_key)))
+
+  # Check the response status code
+  if (httr::status_code(response) != 200) {
+    stop("Failed to retrieve department-level statistics. Please check your authentication and API endpoint.")
+  }
+
+  # Parse the response as JSON
+  statistics <- httr::content(response, "text", encoding = "UTF-8") %>%
+    jsonlite::fromJSON(flatten = TRUE)
+
+  # Return the statistics
+  return(statistics)
+}

R/get_user_course_assignment_data.R

@@ -0,0 +1,29 @@
+#' Get user-in-a-course-level assignment data from the Canvas LMS API
+#'
+#' Retrieves user-in-a-course-level assignment data for a specific course and student from the Canvas LMS API.
+#'
+#' @param canvas A list containing the 'api_key' and 'base_url' for authentication.
+#' @param course_id The ID of the course for which to retrieve the assignment data.
+#' @param student_id The ID of the student for which to retrieve the assignment data.
+#'
+#' @return A list of user-in-a-course-level assignment data retrieved from the Canvas LMS API.
+#' @export
+get_user_course_assignment_data <- function(canvas, course_id, student_id) {
+  # Construct the API endpoint URL
+  url <- paste0(canvas$base_url, "/api/v1/courses/", course_id, "/analytics/users/", student_id, "/assignments")
+
+  # Make the API request
+  response <- httr::GET(url, httr::add_headers(Authorization = paste("Bearer", canvas$api_key)))
+
+  # Check the response status code
+  if (httr::status_code(response) != 200) {
+    stop("Failed to retrieve user-in-a-course-level assignment data. Please check your authentication and API endpoint.")
+  }
+
+  # Parse the response as JSON
+  assignment_data <- httr::content(response, "text", encoding = "UTF-8") %>%
+    jsonlite::fromJSON(flatten = TRUE)
+
+  # Return the assignment data
+  return(assignment_data)
+}

R/get_user_course_messaging_data.R

@@ -0,0 +1,29 @@
+#' Get user-in-a-course-level messaging data from the Canvas LMS API
+#'
+#' Retrieves user-in-a-course-level messaging data for a specific course and student from the Canvas LMS API.
+#'
+#' @param canvas A list containing the 'api_key' and 'base_url' for authentication.
+#' @param course_id The ID of the course for which to retrieve the messaging data.
+#' @param student_id The ID of the student for which to retrieve the messaging data.
+#'
+#' @return A list of user-in-a-course-level messaging data retrieved from the Canvas LMS API.
+#' @export
+get_user_course_messaging_data <- function(canvas, course_id, student_id) {
+  # Construct the API endpoint URL
+  url <- paste0(canvas$base_url, "/api/v1/courses/", course_id, "/analytics/users/", student_id, "/communication")
+
+  # Make the API request
+  response <- httr::GET(url, httr::add_headers(Authorization = paste("Bearer", canvas$api_key)))
+
+  # Check the response status code
+  if (httr::status_code(response) != 200) {
+    stop("Failed to retrieve user-in-a-course-level messaging data. Please check your authentication and API endpoint.")
+  }
+
+  # Parse the response as JSON
+  messaging_data <- httr::content(response, "text", encoding = "UTF-8") %>%
+    jsonlite::fromJSON(flatten = TRUE)
+
+  # Return the messaging data
+  return(messaging_data)
+}

R/get_user_course_participation_data.R

@@ -0,0 +1,29 @@
+#' Get user-in-a-course-level participation data from the Canvas LMS API
+#'
+#' Retrieves user-in-a-course-level participation data for a specific course and student from the Canvas LMS API.
+#'
+#' @param canvas A list containing the 'api_key' and 'base_url' for authentication.
+#' @param course_id The ID of the course for which to retrieve the participation data.
+#' @param student_id The ID of the student for which to retrieve the participation data.
+#'
+#' @return A list of user-in-a-course-level participation data retrieved from the Canvas LMS API.
+#' @export
+get_user_course_participation_data <- function(canvas, course_id, student_id) {
+  # Construct the API endpoint URL
+  url <- paste0(canvas$base_url, "/api/v1/courses/", course_id, "/analytics/users/", student_id, "/activity")
+
+  # Make the API request
+  response <- httr::GET(url, httr::add_headers(Authorization = paste("Bearer", canvas$api_key)))
+
+  # Check the response status code
+  if (httr::status_code(response) != 200) {
+    stop("Failed to retrieve user-in-a-course-level participation data. Please check your authentication and API endpoint.")
+  }
+
+  # Parse the response as JSON
+  participation_data <- httr::content(response, "text", encoding = "UTF-8") %>%
+    jsonlite::fromJSON(flatten = TRUE)
+
+  # Return the participation data
+  return(participation_data)
+}