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

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.width = 7,
  fig.height = 5
)
```

```{r setup}
library(engager)
library(dplyr)
library(ggplot2)
```

# Getting Started with engager

The `engager` package helps instructors analyze student engagement from Zoom transcripts, with a particular focus on participation equity. This vignette will get you started with the basic workflow.

## Installation

Install the package from GitHub:

```{r eval = FALSE}
devtools::install_github("revgizmo/engager")
```

## Quick Start

The beginner workflow loads, processes, summarizes, plots, and exports one
transcript with privacy-supporting defaults:

```{r quick-start}
transcript_file <- system.file(
  "extdata/test_transcripts/intro_statistics_week1.vtt",
  package = "engager"
)

results <- basic_transcript_analysis(
  transcript_file,
  output_dir = tempfile("engager-getting-started-")
)
head(results$analysis)
print(results$plots)
```

For explicit control, compose the public processing functions and pass the
processed object forward instead of re-reading the file:

```{r composable-workflow}
transcript <- load_zoom_transcript(transcript_file)
processed <- process_zoom_transcript(
  transcript_df = transcript,
  consolidate_comments = TRUE,
  add_dead_air = TRUE
)
summary_metrics <- summarize_transcript_metrics(
  transcript_df = processed,
  names_exclude = c("dead_air")
)

# View the results (recognized structured identifiers are masked by default)
head(summary_metrics)

# Run a technical privacy review
privacy_result <- privacy_audit(summary_metrics)
cat(
  "Privacy review:",
  ifelse(nrow(privacy_result) == 0, "No recognized issues flagged", "Review flags returned"),
  "\n"
)
```

## What the Package Does
The `engager` package provides tools for:

1. **Loading and Processing Zoom Transcripts**: Convert Zoom VTT files into analyzable data
2. **Calculating Engagement Metrics**: Measure participation by speaker/student
3. **Name Matching and Cleaning**: Match transcript names to student rosters
4. **Visualization**: Create plots to analyze participation patterns
5. **Exporting**: Write privacy-supporting participation metrics and summaries
6. **Privacy Review**: Support technical review and institutional oversight
7. **Masking and Data Transformation**: Reduce exposure of recognized structured identifiers

## Basic Workflow

The typical workflow involves:

1. **Setup**: Configure your analysis parameters and privacy settings
2. **Load Transcripts**: Import and process Zoom transcript files
3. **Load Roster**: Import student enrollment data
4. **Clean Names**: Match transcript names to student records
5. **Analyze**: Calculate metrics and create visualizations
6. **Review Privacy**: Review outputs and apply masking or other transformations where needed
7. **Export**: Write privacy-supporting metrics and summaries; save returned plot objects explicitly

Version 0.1.0 provides per-session metrics, summaries, and plot objects. It does
not generate a polished course-level engagement report or support longitudinal
individual-student reporting.

## Exact Name Matching

`match_names_workflow()` compares normalized transcript speakers with roster
names and aliases. Version 0.1.0 supports exact matching only and reports
unresolved speakers instead of guessing.

```{r name-matching-example}
roster <- tibble::tibble(
  preferred_name = c("Alice Smith", "Bob Jones"),
  student_id = c("S1", "S2"),
  aliases = c("A Smith; Alice S", NA_character_)
)

transcripts <- tibble::tibble(
  speaker = c("alice smith", "carol"),
  timestamp = as.POSIXct(
    c("2025-01-01 10:00:00", "2025-01-01 10:01:00"),
    tz = "UTC"
  )
)

matching <- match_names_workflow(
  transcripts,
  roster,
  options = list(match_strategy = "exact")
)

matching
matching$unresolved
```

Review unresolved speakers locally before deciding whether to add an authorized
roster alias or leave the speaker unresolved. See `?write_unresolved` for the
privacy-supporting unresolved-name export.

### Getting Help

For detailed troubleshooting guidance:
- **Check the package documentation**: `?match_names_workflow`
- **Find unmatched names before matching**: `?detect_unmatched_names`
- **Review the supported workflow**: See `?match_names_workflow` and `?write_unresolved`

## Next Steps

- **For visualization**: see `vignette("plotting")`
- **For exported function coverage**: see `vignette("essential-functions")`
- **For privacy, ethics, and institutional review considerations**: see `vignette("privacy-ethics-review")`

## Getting Help

- Check package documentation with `help(package = "engager")`
- Open vignettes with `browseVignettes(package = "engager")`
- Report issues on GitHub at `https://github.com/revgizmo/engager/issues`