---
title: "Core Workflows and Functions"
author: "engager package"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Core Workflows and Functions}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  message = FALSE,
  warning = FALSE
)
```

## Overview

This vignette demonstrates the supported v0.1.0 core using the package's public API:

- **Transcript Processing**: Loading and processing Zoom transcripts
- **Privacy-Supporting Workflows**: Applying structured-field masking and technical review
- **Analysis**: Core engagement metrics and analysis
- **Name Matching**: Reviewable exact student name matching workflows

## Supported Functions

The package exposes additional interactive guidance helpers, but the functions
below define the supported analysis workflow for v0.1.0:

```{r essential-functions, results='asis', echo=FALSE, message=FALSE, warning=FALSE}
library(engager)

essential_functions <- c(
  "basic_transcript_analysis",
  "quick_analysis",
  "batch_basic_analysis",
  "load_zoom_transcript",
  "process_zoom_transcript",
  "consolidate_transcript",
  "summarize_transcript_metrics",
  "summarize_transcript_files",
  "analyze_transcripts",
  "plot_users",
  "write_metrics",
  "load_roster",
  "detect_unmatched_names",
  "match_names_workflow",
  "write_unresolved",
  "ensure_privacy",
  "privacy_audit",
  "anonymize_educational_data",
  "validate_privacy_compliance",
  "review_privacy_risks",
  "generate_privacy_review_report"
)

stopifnot(all(essential_functions %in% getNamespaceExports("engager")))

# Emit a markdown list with autolinkable inline code items
cat("Supported workflow functions (", length(essential_functions), "):\n\n")
cat(paste0("- `", essential_functions, "()`"), sep = "\n")
```

## Core Workflow

### 1. Load and Process Transcript

```{r load-transcript}
# Load a sample transcript
transcript_file <- system.file("extdata/test_transcripts/intro_statistics_week1.vtt",
  package = "engager"
)

# Load the transcript
transcript <- load_zoom_transcript(transcript_file)
cat("Transcript loaded with", nrow(transcript), "comments\n")
```

### 2. Process and Summarize

```{r process-transcript}
# Process transcript with privacy defaults
processed <- process_zoom_transcript(
  transcript_df = transcript,
  add_dead_air = TRUE,
  consolidate_comments = TRUE
)

metrics <- summarize_transcript_metrics(
  transcript_df = processed,
  names_exclude = c("dead_air")
)

head(metrics)
```

### 3. Plot and Export

```{r plot-and-export}
engagement_plot <- plot_users(
  metrics,
  metric = "n",
  facet_by = "none",
  mask_by = "name"
)
print(engagement_plot)

output_file <- tempfile(fileext = ".csv")
write_metrics(
  metrics,
  what = "engagement",
  path = output_file,
  comments_policy = "omit"
)
stopifnot(file.exists(output_file))
unlink(output_file)
```

### 4. Run a Privacy Review

```{r privacy-compliance}
# Check privacy risk with synthetic data
synthetic_data <- data.frame(
  name = c("Student A", "Student B", "Instructor"),
  message = c("Hello", "Good morning", "Welcome to class"),
  timestamp = c("00:01:00", "00:02:00", "00:00:30")
)

# Privacy review helpers flag recognized identifier-like columns. They do not
# prove that a data set or free-text field contains no identifying information.
privacy_review <- review_privacy_risks(synthetic_data, audit_log = FALSE)
privacy_review$pii_detected
privacy_review$recommendations
```

## Function Categories

### Transcript Processing
- `load_zoom_transcript()` - Load Zoom transcript files
- `process_zoom_transcript()` - Process and clean transcripts
- `consolidate_transcript()` - Consolidate consecutive comments
- `summarize_transcript_files()` - Summarize transcripts at file level

### Analysis
- `analyze_transcripts()` - Main analysis function
- `summarize_transcript_metrics()` - Calculate engagement metrics

### Privacy Review
- `ensure_privacy()` - Mask recognized structured identifier columns
- `privacy_audit()` - Audit privacy risks
- `validate_privacy_compliance()` - Review privacy settings

### Name Matching
- `load_roster()` - Load a roster for matching
- `detect_unmatched_names()` - Identify speakers requiring review
- `match_names_workflow()` - Apply the supported exact matching workflow
- `write_unresolved()` - Write a privacy-supporting unresolved-name review file

### Utilities
- `plot_users()` - Plot user engagement
- `write_metrics()` - Export metrics

## Supported Boundaries

- Beginner and batch workflows produce per-session metrics, summaries, and plot
  objects.
- Exact name matching reports unresolved names instead of guessing.
- Output helpers mask recognized structured identifiers and omit raw comment
  text by default.
- Version 0.1.0 does not generate polished course-level engagement reports or
  support longitudinal individual-student reporting.

Users remain responsible for reviewing inputs, free text, outputs, sharing
decisions, and institutional requirements.