Package {engager}

engager: Student Engagement Analysis Package

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

Pipe operator

Description

See magrittr::%>% for details.

Error handling helpers

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

Add Dead Air Rows

Description

Take a tibble containing the comments from a Zoom recording transcript and return a tibble that adds rows for any time between transcribed comments, labeled with the dead_air_name provided (or the default value of 'dead_air'). The resulting tibble will have rows accounting for the time from the beginning of the first comment to the end of the last one.

Usage

add_dead_air_rows(df = NULL, dead_air_name = "dead_air")

Arguments

Value

A tibble with rows added for dead air periods

Convert aliases list column to long form (internal)

Description

Convert aliases list column to long form (internal)

Usage

aliases_long(roster_df)

Experimental Multi-Session Attendance Patterns

Description

Internal prototype for a possible v0.1.1 workflow. Its roster, unmatched-name, threshold, and reporting semantics are not part of the v0.1.0 public API. Analyzes attendance patterns across multiple Zoom sessions, tracking who attended which sessions and identifying participation patterns while applying the selected package masking controls.

Usage

analyze_multi_session_attendance(
  transcript_files = NULL,
  roster_data = NULL,
  data_folder = ".",
  transcripts_folder = "transcripts",
  unmatched_names_action = c("stop", "warn"),
  privacy_level = c("privacy_strict", "privacy_standard", "mask", "none"),
  min_attendance_threshold = 0.5
)

Arguments

Value

List containing:

• attendance_matrix: Data frame with participants as rows and sessions as columns

• attendance_summary: Summary statistics for each participant

• session_summary: Summary statistics for each session

• participation_patterns: Analysis of participation patterns

• privacy_compliant: Backward-compatible Boolean indicating whether the package's technical privacy checks completed without an error. This is not a legal or institutional compliance determination.

Analyze Transcripts (High-level orchestration)

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.

Anonymize Educational Data

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)

Apply Name Matching

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

Apply Privacy-Aware Name Matching

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

Audit Ethical Usage Patterns

Description

Analyzes usage patterns to detect potential ethical concerns and provides recommendations for improvement.

Usage

audit_ethical_usage(
  function_calls = NULL,
  data_sizes = NULL,
  privacy_settings = NULL,
  time_period = 30
)

Arguments

Value

Audit report with ethical usage analysis

Basic Analysis Workflow for New Users

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)

Batch analysis for multiple transcript files

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)

Build match audit structure

Description

Build match audit structure

Usage

build_match_audit(roster_spec, hmac_used, icu_version, algo = "sha256")

Build a mapping from name_hash to unique student_id (or mark collision)

Description

Returns a tibble with columns: name_hash, student_id, collision where collision is TRUE if the hash corresponds to multiple students.

Usage

build_roster_hash_index(roster_df)

Calculate Content Similarity Between Two Transcripts

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

Review a Configured Data Retention Period

Description

Compares configured date fields with a selected period to support local records review. It does not determine or enforce institutional policy.

Usage

check_data_retention_policy(
  data = NULL,
  retention_period = c("academic_year", "semester", "quarter", "custom"),
  custom_retention_days = NULL,
  date_column = NULL,
  current_date = Sys.Date()
)

Arguments

Value

List containing review status and retention analysis. The passed field is the preferred status name; compliant is retained as a backward-compatible alias.

Consolidate Transcript

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.

Convert technical error to user-friendly message

Description

Converts technical error messages to helpful, actionable guidance

Usage

convert_error_to_user_friendly(error_message, context)

Arguments

Value

User-friendly error message

Package Data Documentation

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.

Derive a 'speaker' column from common alternatives

Description

Derive a 'speaker' column from common alternatives

Usage

derive_speaker_column(df)

Detect Duplicate Transcripts

Description

Identifies and analyzes duplicate Zoom transcript files using multiple detection methods. This function helps clean up transcript datasets by finding files that contain similar or identical content, which can occur when multiple transcript formats are generated for the same recording session.

Usage

detect_duplicate_transcripts(
  transcript_list = NULL,
  data_folder = ".",
  transcripts_folder = "transcripts",
  similarity_threshold = 0.95,
  method = c("hybrid", "content", "metadata"),
  names_to_exclude = c("dead_air")
)

Arguments

Value

List containing duplicate groups, similarity matrix, and recommendations

See Also

process_zoom_transcript for processing individual transcripts, summarize_transcript_metrics for analyzing transcript content

Detect unmatched names from transcripts against a roster

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()

Ensure Privacy for Outputs

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)

Ethical Review Functions

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.

Interactive Help System

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")

Experimental Attendance Report

Description

Internal prototype for a possible v0.1.1 reporting workflow. Chart and threshold semantics are not part of the v0.1.0 public API.

Usage

generate_attendance_report(
  analysis_results = NULL,
  output_file = NULL,
  include_charts = FALSE
)

Arguments

Value

Report content as character vector

Generate a Privacy Review Report

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.

Get next UX level

Description

Get next UX level

Usage

get_next_level(current_level)

Arguments

Value

Next UX level

Smart function recommendations

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")

Get current user experience level

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()

Function Visibility Management System

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")

Hash a canonicalized name using SHA-256 or HMAC-SHA-256

Description

Returns lowercase hex string. Uses openssl for both plain and HMAC.

Usage

hash_canonical_name(canonical_name, key = NULL, algo = "sha256")

Arguments

Load a roster file

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)

Load Zoom Transcript

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)

Lookup Merge Utilities (Safe, Transactional, UTF-8)

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)

Make Cancelled Classes Tibble This function creates an empty tibble for recording of cancelled class sessions for scheduled classes where a Zoom recording is not expected.

Description

where a zoom recording is not expected.

Usage

make_blank_cancelled_classes_df()

Create Blank Section Names Lookup Template

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()

Perform exact matching by name_hash against roster index Returns list(transcripts_with_ids, unresolved)

Description

Perform exact matching by name_hash against roster index Returns list(transcripts_with_ids, unresolved)

Usage

match_names_exact(prepped_transcripts, roster_index, include_name_hash = FALSE)

Fuzzy matching stub (not implemented)

Description

Accepts the same inputs as future implementation but aborts with a clear message. This keeps the API future-proof without enabling behavior now.

Usage

match_names_fuzzy(...)

Match names workflow with privacy-supporting defaults

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()

Null-coalescing helper

Description

Null-coalescing helper

Usage

normalize_name(x)

Plot Users

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.

Prepare transcript names: normalize and hash speaker names Expects column 'speaker'. Optional 'timestamp'.

Description

Prepare transcript names: normalize and hash speaker names Expects column 'speaker'. Optional 'timestamp'.

Usage

prepare_transcript_names(transcripts_df, key = NULL)

Privacy Audit

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.

Privacy Review Functions

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.

Process Zoom Transcript

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)

Quick analysis for single 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)

Resolve the name hash key using precedence

Description

Precedence: explicit function argument > Sys.getenv("ENGAGER_NAME_HASH_KEY") > getOption("engager.name_hash_key", NULL)

Usage

resolve_name_hash_key(key)

Review Data for Privacy Risks

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.

Safe Name Matching Workflow

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

Schema validators and contracts

Description

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

Set user experience level

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)

Show functions available at current 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")

Show error recovery suggestions

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")

Show function categories and counts

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()

Show help for specific function

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")

User Guidance and Help System

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()

Show privacy and ethics guidance

Description

Show privacy and ethics guidance

Usage

show_privacy_guidance()

Value

Invisibly NULL; called for its formatted console guide.

Examples

show_privacy_guidance()

Show troubleshooting guide

Description

Show troubleshooting guide

Usage

show_troubleshooting()

Value

Invisibly NULL; called for its formatted console guide.

Examples

show_troubleshooting()

Show workflow help and templates

Description

Show workflow help and templates

Usage

show_workflow_help()

Value

Invisibly NULL; called for its formatted console guide.

Examples

show_workflow_help()

Summarize Transcript Files

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 = "."
)

Summarize Transcript Metrics

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)

User-Friendly Error Handling System

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")

Validate directory argument with user-friendly errors

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

Validate function arguments with user-friendly errors

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

Validate Privacy Compliance

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)

Write Metrics

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.

Write unresolved matches to disk with privacy guardrails

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()

Canonical schemas used in pipelines

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.