Package 'engager'

Description

Tools for processing Zoom transcripts, matching names with rosters, computing engagement metrics, and creating privacy-aware visualizations and reports. The package emphasizes privacy-supporting defaults, privacy review helpers, and masked outputs by default.

Author(s)

Maintainer: Conor Healy conorhealy@berkeley.edu

See Also

Useful links:

• https://github.com/revgizmo/engager

• https://revgizmo.github.io/engager/

• Report bugs at https://github.com/revgizmo/engager/issues

Description

See magrittr::%>% for details.

Description

Provides a small wrapper around rlang::abort() to standardize error classes within the package for precise testing and user handling.

Usage

abort_zse(message, class = character())

Arguments

Value

No return value, throws an error

Description

Convenience wrapper to process a set of .transcript.vtt files from a folder, compute engagement metrics, and optionally write outputs.

Usage

analyze_transcripts(
  transcripts_folder = NULL,
  names_to_exclude = c("dead_air"),
  write = FALSE,
  output_path = NULL
)

Arguments

Value

A tibble with speaker-level engagement metrics for the discovered transcript files. When write = TRUE, the same metrics are also written to output_path after export privacy policies are applied.

Description

Advanced anonymization for educational data that preserves data utility while supporting privacy review.

Usage

anonymize_educational_data(
  data = NULL,
  method = c("mask", "hash", "pseudonymize"),
  preserve_columns = NULL,
  hash_salt = NULL,
  aggregation_level = c("individual", "section", "course", "institution")
)

Arguments

Value

A data frame of the same row shape as data, with recognized structured identifier columns transformed by the selected method. Missing and blank identifiers remain missing or blank. These transformations do not inspect free text and do not establish that a data set is anonymous or compliant with legal or institutional requirements.

Anonymize sample data

sample_data <- tibble::tibble( student_id = c("12345", "67890"), preferred_name = c("Alice Johnson", "Bob Smith"), section = c("A", "B"), participation_score = c(85, 92) )

Mask method (default)

anonymized <- anonymize_educational_data(sample_data, method = "mask")

Hash method requires a caller-provided salt

hashed <- anonymize_educational_data(sample_data, method = "hash", hash_salt = "my_salt")

Examples

sample_data <- tibble::tibble(
  student_id = c("12345", "67890"),
  preferred_name = c("Alice Johnson", "Bob Smith"),
  section = c("A", "B"),
  participation_score = c(85, 92)
)
anonymize_educational_data(sample_data)

Description

Internal function to apply name matching to transcript data.

Usage

apply_name_matching(transcript_data, name_lookup, roster_data)

Arguments

Value

Matched transcript data

Description

Internal function to apply privacy-aware name matching using consistent hashing. This function enhances the existing matching logic with privacy-supporting design.

Usage

apply_privacy_aware_matching(result, section_names_lookup, privacy_level)

Arguments

Value

Enhanced matching results with privacy-aware processing

Description

Simplified workflow that guides new users through basic analysis of Zoom transcripts with minimal complexity. Complete basic transcript analysis workflow

This is the main function for new users. It performs a complete analysis workflow in five simple steps: load, process, analyze, visualize, and either return results in memory or export to an explicit directory.

Usage

basic_transcript_analysis(
  transcript_file,
  output_dir = NULL,
  privacy_level = "high"
)

Arguments

Value

A named list with analysis (a tibble of speaker metrics), plots (a ggplot object), output_dir (the explicit output directory or NULL), transcript_file, and privacy_level.

Examples

transcript_file <- system.file(
  "extdata/test_transcripts/ideal_course_session1.vtt",
  package = "engager"
)
results <- basic_transcript_analysis(transcript_file)

Description

Process multiple transcript files in one workflow

Usage

batch_basic_analysis(
  transcript_files,
  output_dir = NULL,
  privacy_level = "high"
)

Arguments

Value

A named list keyed by transcript basename. Each element is the analysis list returned by basic_transcript_analysis() or a list with an error message when that file could not be processed.

Examples

transcript_dir <- system.file("extdata/test_transcripts", package = "engager")
files <- file.path(transcript_dir, c(
  "ideal_course_session1.vtt", "ideal_course_session2.vtt"
))
results <- batch_basic_analysis(files)

Description

This function calculates the similarity between two transcript data frames based on various metrics including speaker overlap, duration, word count, comment count, and content similarity.

Usage

calculate_content_similarity(
  transcript1 = NULL,
  transcript2 = NULL,
  names_to_exclude = c("dead_air")
)

Arguments

Value

Similarity score between 0 and 1

Description

Take a tibble containing the comments from a Zoom recording transcript and return a tibble that consolidates all consecutive comments from the same speaker where the time between the end of the first comment and start of the second comment is less than max_pause_sec seconds. This function addresses an issue with the Zoom transcript where the speaker is speaking a continuous sentence, but the Zoom transcript will cut the comment into two lines. For example, a comment of "This should be a single sentence." is often split into "This should be" and "a single sentence". This function stitches those together into "This should be a single sentence." where the start time of the consolidated comment will be the beginning of the first row and the end time of the consolidated comment will be the ending of the last row.

Usage

consolidate_transcript(df = NULL, max_pause_sec = 1)

Arguments

Value

A tibble with consecutive comments consolidated by speaker and pause threshold, including name, comment, start, end, duration, and wordcount columns. Returns NULL when df is not a tibble.

Description

Converts technical error messages to helpful, actionable guidance

Usage

convert_error_to_user_friendly(error_message, context)

Arguments

Value

User-friendly error message

Description

User-provided data and bundled synthetic fixtures.

Details

The package is designed to analyze user-provided WebVTT transcripts and related institutional data. It does not bundle real course or student data. Synthetic transcript and roster fixtures are included under inst/extdata/test_transcripts for runnable examples and package validation. They must not be interpreted as institutional records.

See also: load_zoom_transcript() for loading transcript data and write_metrics() for exporting analysis results.

Description

Detect unmatched names from transcripts against a roster

Usage

detect_unmatched_names(transcripts_df, roster_df, options = list())

Arguments

Value

Tibble with columns: name_hash, occurrence_n, first_seen_at, reason, guidance. name_hash omitted unless include_name_hash = TRUE.

See Also

Other name-matching: match_names_workflow(), write_unresolved()

Description

Applies privacy rules to objects before they are returned, written, or plotted. By default, masks personally identifiable information in tabular data to privacy-supporting placeholders.

Usage

ensure_privacy(
  x = NULL,
  privacy_level = getOption("engager.privacy_level", "mask"),
  id_columns = c("preferred_name", "name", "first_last", "name_raw", "student_id",
    "email", "transcript_name", "formal_name", "user_name", "speaker"),
  audit_log = TRUE
)

Arguments

Details

CRITICAL ETHICAL USE: This function is designed to promote participation equity and educational improvement, NOT surveillance. Outputs are masked by default to support student privacy review; institutional compliance review remains the user's responsibility.

The default behavior is controlled by the global option engager.privacy_level, which is set to "mask" on package load. Pass privacy_level explicitly for one call, or set the engager.privacy_level option for the current R session.

Value

For tabular input, an object with the same data-frame class as x and configured identifier columns transformed according to privacy_level. Non-tabular input is returned unchanged. This is a technical masking result, not a legal or institutional compliance determination.

Examples

df <- tibble::tibble(
  section = c("A", "A", "B"),
  preferred_name = c("Alice Johnson", "Bob Lee", "Cara Diaz"),
  session_ct = c(3, 5, 2)
)
ensure_privacy(df)

Description

Internal technical prompts for reviewing educational data-analysis use. These helpers do not determine whether a workflow is ethically approved or compliant with institutional requirements.

Description

Provides interactive help and function discovery to help users find the right functions for their specific tasks. Interactive function discovery

Helps users find the right function based on what they want to do

Usage

find_function_for_task(task)

Arguments

Value

Invisibly NULL; called for its function suggestions printed to the console.

Examples

find_function_for_task("load transcript file")
find_function_for_task("create visualizations")
find_function_for_task("export results")

Description

Generates a lightweight report from review_privacy_risks(). The report is intended to support local review and documentation; it does not certify legal compliance.

Usage

generate_privacy_review_report(
  data = NULL,
  output_file = NULL,
  report_format = c("text", "html", "json"),
  include_audit_trail = TRUE,
  institution_info = NULL,
  institution_type = c("educational", "research", "mixed")
)

Arguments

Value

A named list containing report metadata, a summary, the underlying technical review results, and recommendations. When output_file is supplied, the same report is also serialized there.

Description

Get next UX level

Usage

get_next_level(current_level)

Arguments

Value

Next UX level

Description

Provides intelligent function recommendations based on user context

Usage

get_smart_recommendations(context)

Arguments

Value

Invisibly NULL; called for its recommendations printed to the console.

Examples

get_smart_recommendations("new user")
get_smart_recommendations("batch processing")
get_smart_recommendations("privacy concerns")

Description

Get current user experience level

Usage

get_ux_level()

Value

A character scalar containing the configured experience level, or "basic" when no level has been configured. This function takes no arguments.

Examples

current_level <- get_ux_level()

Description

Manages which functions are visible to users based on experience level to implement progressive disclosure and simplify the user interface. Get visible functions for user experience level

Usage

get_visible_functions(level = "basic")

Arguments

Value

A character vector of exported function names visible at level.

Examples

# Get functions visible to basic users
basic_functions <- get_visible_functions("basic")

# Get functions visible to intermediate users
intermediate_functions <- get_visible_functions("intermediate")

Description

Load a roster file

Usage

load_roster(
  data_folder = ".",
  roster_file = "roster.csv",
  strict_errors = FALSE
)

Arguments

Value

A tibble containing the roster rows. When an enrolled column is present, only rows where it is TRUE are returned. A missing file returns an empty tibble unless strict_errors = TRUE.

Examples

roster_path <- tempfile(fileext = ".csv")
readr::write_csv(
  tibble::tibble(student_id = "S001", preferred_name = "Student One"),
  roster_path
)
roster <- load_roster(roster_path)
unlink(roster_path)

Description

Load a Zoom recording transcript and return tibble containing the comments from a Zoom recording transcript

Usage

load_zoom_transcript(transcript_file_path = NULL)

Arguments

Details

Original code posted by Conor Healy: https://ucbischool.slack.com/archives/C02A36407K9/p1631855705002000 Addition of wordcount by Brooks Ambrose: https://gist.github.com/brooksambrose/1a8a673eb3bf884c1868ad4d80f08246

Value

A tibble with one row per parsed WebVTT cue and columns describing speaker name, cue text, start and end times, duration, word count, and source transcript. Returns NULL when the file is empty.

Examples

# Load a sample transcript from the package's extdata directory
transcript_file <- system.file("extdata/test_transcripts/intro_statistics_week1.vtt",
  package = "engager"
)
load_zoom_transcript(transcript_file_path = transcript_file)

Description

Utilities to safely read, merge, and write the participant lookup configuration (section_names_lookup.csv). All operations are read-then-merge in memory; writes are opt-in and transactional with timestamped backups to prevent accidental data loss.

Details

Expected columns in lookup data frame:

• transcript_name

• preferred_name

• formal_name

• participant_type (e.g., instructor, enrolled_student, guest, unknown)

• student_id

• notes (optional)

Description

where a zoom recording is not expected.

Usage

make_blank_cancelled_classes_df()

Description

Creates an empty tibble template for customizing student names by section. This function generates a properly structured data frame that can be filled in to map between different name formats (preferred names, formal names, transcript names) for students across different course sections.

Usage

make_blank_section_names_lookup_csv()

Description

Returns an object of class 'engager_match' with redacted print/summary.

Usage

match_names_workflow(transcripts_df, roster_df, options = list())

Arguments

Value

A list with elements transcripts_with_ids, unresolved, and audit. Returns an object of class 'engager_match' with redacted print() and summary() methods.

See Also

Other name-matching: detect_unmatched_names(), write_unresolved()

Description

Unified plotting function for engagement metrics with privacy-aware options.

Usage

plot_users(
  data = NULL,
  metric = "session_ct",
  student_col = "name",
  facet_by = c("section", "transcript_file", "none"),
  mask_by = c("name", "rank"),
  privacy_level = getOption("engager.privacy_level", "mask"),
  metrics_lookup_df = NULL
)

Arguments

Value

A ggplot object whose data contains the selected metric and the configured privacy-processed participant labels, ready to print or modify.

Description

Summarize which identifier columns were present and how many values were masked.

Usage

privacy_audit(
  data = NULL,
  id_columns = c("preferred_name", "name", "first_last", "name_raw", "student_id",
    "email")
)

Arguments

Value

A tibble with one row per detected identifier column and the fields column, values, non_empty, and masked_estimate, summarizing the technical masking state of the supplied data.

Description

Functions to support institutional privacy review for educational data. These helpers do not guarantee legal compliance; institutions remain responsible for policy review and authorization.

Description

Process a Zoom recording transcript with given parameters and return tibble containing the consolidated and annotated comments.

Usage

process_zoom_transcript(
  transcript_file_path = "",
  consolidate_comments = TRUE,
  max_pause_sec = 1,
  add_dead_air = TRUE,
  dead_air_name = "dead_air",
  na_name = "unknown",
  transcript_df = NULL
)

Arguments

Details

Original code posted by Conor Healy: https://ucbischool.slack.com/archives/C02A36407K9/p1631855705002000 Addition of wordcount, wordcount_perc, and wpm by Brooks Ambrose: https://gist.github.com/brooksambrose/1a8a673eb3bf884c1868ad4d80f08246

Value

A tibble of processed transcript cues with normalized speaker, comment, timing, duration, word-count, and source-file fields. Depending on the arguments, adjacent cues may be consolidated and dead-air rows added.

Examples

# Load a sample transcript from the package's extdata directory
transcript_file <- system.file("extdata/test_transcripts/intro_statistics_week1.vtt",
  package = "engager"
)
process_zoom_transcript(transcript_file_path = transcript_file)

Description

Simplified version for users who just want quick results

Usage

quick_analysis(transcript_file, output_dir = NULL)

Arguments

Value

The named analysis list returned by basic_transcript_analysis().

Examples

transcript_file <- system.file(
  "extdata/test_transcripts/ideal_course_session1.vtt",
  package = "engager"
)
results <- quick_analysis(transcript_file)

Description

Performs a technical privacy review of a data frame by looking for common identifier columns, optional retention concerns, and institution-specific review prompts. This is a screening helper, not a legal compliance determination.

Usage

review_privacy_risks(
  data = NULL,
  institution_type = c("educational", "research", "mixed"),
  check_retention = TRUE,
  retention_period = c("academic_year", "semester", "quarter", "custom"),
  custom_retention_days = NULL,
  audit_log = TRUE
)

Arguments

Value

A named list containing the logical technical review status, detected identifier fields, recommendations, retention-review details, and institutional review prompts.

Description

Main workflow function for privacy-supporting name matching. Implements two-stage processing: Stage 1 (unmasked matching in memory) and Stage 2 (privacy masking for outputs). Provides configuration-driven behavior for unmatched names.

Usage

safe_name_matching_workflow(
  transcript_file_path = NULL,
  roster_data = NULL,
  privacy_level = getOption("engager.privacy_level", "mask"),
  unmatched_names_action = getOption("engager.unmatched_names_action", "stop"),
  data_folder = NULL,
  section_names_lookup_file = "section_names_lookup.csv",
  write_lookup = FALSE
)

Arguments

Value

Processed transcript data with privacy-aware name matching applied

Description

Defines simple schema validation helpers and canonical schemas used throughout the package. Keep this intentionally lightweight to avoid dependency bloat.

Description

Set user experience level

Usage

set_ux_level(level = "basic")

Arguments

Value

Invisibly, the selected experience level as a character scalar.

Examples

old_ux_level <- getOption("zoomstudentengagement.ux_level")
# Set to basic level (5 essential functions)
set_ux_level("basic")

# Set to intermediate level (15 functions)
set_ux_level("intermediate")
options(zoomstudentengagement.ux_level = old_ux_level)

Description

Show functions available at current UX level

Usage

show_available_functions(level = NULL)

Arguments

Value

Invisibly NULL; called for its formatted console output.

Examples

# Show functions at current level
show_available_functions()

# Show functions at specific level
show_available_functions("intermediate")

Description

Provides specific recovery suggestions based on error type

Usage

show_error_recovery(error_type)

Arguments

Value

Invisibly NULL; called for its recovery guidance printed to the console.

Examples

show_error_recovery("file_not_found")
show_error_recovery("permission_denied")

Description

Show function categories and counts

Usage

show_function_categories()

Value

Invisibly NULL; called for its category summary printed to the console.

Examples

show_function_categories()

Description

Show help for specific function

Usage

show_function_help(function_name)

Arguments

Value

Invisibly NULL; called for its formatted console help.

Examples

show_function_help("load_zoom_transcript")
show_function_help("basic_transcript_analysis")

Description

Provides contextual help and guidance for users to navigate the package effectively and find the right functions for their tasks. Show getting started guide

Displays a comprehensive getting started guide for new users

Usage

show_getting_started()

Value

Invisibly NULL; called for its formatted console guide.

Examples

show_getting_started()

Description

Show privacy and ethics guidance

Usage

show_privacy_guidance()

Value

Invisibly NULL; called for its formatted console guide.

Examples

show_privacy_guidance()

Description

Show troubleshooting guide

Usage

show_troubleshooting()

Value

Invisibly NULL; called for its formatted console guide.

Examples

show_troubleshooting()

Description

Show workflow help and templates

Usage

show_workflow_help()

Value

Invisibly NULL; called for its formatted console guide.

Examples

show_workflow_help()

Description

Summarize multiple transcript files and return aggregated metrics. If a tibble with additional columns beyond 'transcript_file' is provided, all metadata columns will be preserved in the output.

Usage

summarize_transcript_files(
  transcript_file_names = NULL,
  data_folder = ".",
  transcripts_folder = "transcripts",
  names_to_exclude = NULL,
  deduplicate_content = FALSE,
  similarity_threshold = 0.95,
  duplicate_method = c("hybrid", "content", "metadata")
)

Arguments

Value

A tibble of speaker-level metrics combined across the requested transcript files. Metadata columns supplied with transcript_file_names are retained in the result.

Examples

transcript_dir <- system.file("extdata/test_transcripts", package = "engager")
transcript_files <- c(
  "ideal_course_session1.vtt",
  "ideal_course_session2.vtt"
)
summary <- summarize_transcript_files(
  transcript_file_names = transcript_files,
  data_folder = transcript_dir,
  transcripts_folder = "."
)

Description

Process a Zoom recording transcript and return summary metrics by speaker

Usage

summarize_transcript_metrics(
  transcript_file_path = "",
  names_exclude = c("dead_air"),
  consolidate_comments = TRUE,
  max_pause_sec = 1,
  add_dead_air = TRUE,
  dead_air_name = "dead_air",
  na_name = "unknown",
  transcript_df = NULL,
  comments_format = c("list", "text", "count")
)

Arguments

Details

Original code posted by Conor Healy: https://ucbischool.slack.com/archives/C02A36407K9/p1631855705002000 Addition of wordcount, wordcount_perc, and wpm by Brooks Ambrose: https://gist.github.com/brooksambrose/1a8a673eb3bf884c1868ad4d80f08246

This function preserves in-memory comment data for analysis compatibility. Use write_metrics() for privacy-safe CSV exports. The privacy helpers mask structured identifier columns, but they do not redact identifiers embedded in free transcript text.

Value

A tibble with one row per speaker (and source transcript when present), containing participation totals such as duration, word count, session count, and the configured comment representation.

Examples

# Load a sample transcript from the package's extdata directory
transcript_file <- system.file("extdata/test_transcripts/intro_statistics_week1.vtt",
  package = "engager"
)
summarize_transcript_metrics(transcript_file_path = transcript_file)

Description

Provides helpful error messages and recovery guidance to help users understand and resolve issues quickly. User-friendly error wrapper

Wraps expressions with user-friendly error handling

Usage

user_friendly_error(expr, context = "operation")

Arguments

Value

The value of expr unchanged when evaluation succeeds. On failure, the function raises a rewritten error with recovery guidance.

Examples

result <- user_friendly_error(1 + 1, "adding values")

Description

Validates directory arguments and provides helpful error messages

Usage

validate_directory_argument(
  dir_path,
  context = "directory operation",
  create_if_missing = TRUE
)

Arguments

Value

TRUE if valid, stops with user-friendly error if invalid

Description

Validates function arguments and provides helpful error messages

Usage

validate_file_argument(file_path, context = "file operation")

Arguments

Value

TRUE if valid, stops with user-friendly error if invalid

Description

Scans data objects for possible real names when package masking is enabled. This is an exact-match technical check, not a legal or institutional compliance determination. It stops processing when configured names are found.

Usage

validate_privacy_compliance(
  data = NULL,
  privacy_level = getOption("engager.privacy_level", "mask"),
  real_names = NULL,
  stop_on_violation = TRUE
)

Arguments

Value

The logical scalar TRUE when the technical check finds no configured real names. The function raises an error instead when a blocking exposure is found.

Examples

# Validate privacy compliance
df <- tibble::tibble(
  name = c("Student_01", "Student_02"),
  score = c(85, 92)
)
validate_privacy_compliance(df)

# Check with specific real names
real_names <- c("John Smith", "Jane Doe")
validate_privacy_compliance(df, real_names = real_names)

Description

Unified writer for engagement-related outputs with privacy enforcement. Parent directories are created if they do not exist.

Usage

write_metrics(
  data = NULL,
  what = c("engagement", "summary", "session_summary"),
  path,
  comments_format = NULL,
  privacy_level = getOption("engager.privacy_level", "mask"),
  comments_policy = c("auto", "omit", "count", "text")
)

Arguments

Details

write_metrics() is the privacy-safe CSV export path. It applies structured identifier masking with ensure_privacy() and then omits raw free-text comments by default. ensure_privacy() does not redact identifiers embedded inside comment text.

Value

Invisibly returns the exported tibble after privacy and export policies are applied.

Description

By default, writes only hashed columns (no raw names). To include raw names, both conditions must be met: include_raw = TRUE and options(engager.allow_raw_name_exports = TRUE) is set. Otherwise, the function aborts with class engager_privacy_error.

Usage

write_unresolved(unresolved_tbl, path, include_raw = FALSE, overwrite = FALSE)

Arguments

Value

Invisibly, a character scalar containing the path that was written.

See Also

Other name-matching: detect_unmatched_names(), match_names_workflow()

Description

These are documented here for reference and to be used by callers/tests. Keep them minimal; adjust as the package evolves.

Usage

zse_schema

Format

An object of class list of length 2.