Head Copy Lab Analytics Documentation

Quick Navigation

System Overview

Head Copy Lab analytics tracks advanced CW comprehension training at session and character levels, with dedicated lag-discipline metrics that measure how far behind the stream the operator can maintain typing.

Four Levels of Analytics

1. Session-level: item totals, accuracy, duration, assistance counts, lag aggregates.
2. Item-level (aggregated): per item/chunk accuracy and lag summary.
3. Character-level: typed-vs-expected errors with context and position.
4. Dashboard-level: trends, heat maps, substitution pairs, recent and best sessions.

Mode Tracking

• buffered - enforced word-lag typing
• chunking - chunk echo/build drills
• context - reserved for future context-primed stories
• shadow - reserved for future shadow copy

Database Schema

Primary tables used by Head Copy Lab analytics APIs.

head_copy_sessions

CREATE TABLE head_copy_sessions (
  id INT AUTO_INCREMENT PRIMARY KEY,
  username VARCHAR(255) NOT NULL,
  mode VARCHAR(30) NOT NULL,
  content_source VARCHAR(30) NOT NULL,
  language VARCHAR(50) DEFAULT NULL,
  buffer_target_words INT DEFAULT NULL,
  enforcement_mode VARCHAR(20) DEFAULT NULL,
  chunk_size_words INT DEFAULT NULL,
  chunk_strategy VARCHAR(30) DEFAULT NULL,
  items_total INT NOT NULL DEFAULT 0,
  items_correct INT NOT NULL DEFAULT 0,
  items_incorrect INT NOT NULL DEFAULT 0,
  accuracy_percentage DECIMAL(5,2) NOT NULL DEFAULT 0.00,
  avg_lag_words DECIMAL(6,2) DEFAULT NULL,
  min_lag_words DECIMAL(6,2) DEFAULT NULL,
  lag_compliance_percentage DECIMAL(5,2) DEFAULT NULL,
  session_duration_seconds INT NOT NULL DEFAULT 0,
  exact_speed_wpm INT DEFAULT NULL,
  effective_speed_wpm INT DEFAULT NULL,
  audio_profile VARCHAR(30) DEFAULT NULL,
  assisted_pause_count INT NOT NULL DEFAULT 0,
  assisted_replay_count INT NOT NULL DEFAULT 0,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  INDEX idx_user_date (username, created_at),
  INDEX idx_mode (mode),
  INDEX idx_source (content_source),
  INDEX idx_language (language)
);

head_copy_character_errors

CREATE TABLE head_copy_character_errors (
  id INT AUTO_INCREMENT PRIMARY KEY,
  username VARCHAR(255) NOT NULL,
  mode VARCHAR(30) NOT NULL,
  content_source VARCHAR(30) NOT NULL,
  language VARCHAR(50) DEFAULT NULL,
  expected_char CHAR(1) NOT NULL,
  received_char CHAR(1) NOT NULL,
  error_type VARCHAR(20) NOT NULL,
  context_text TEXT DEFAULT NULL,
  position_in_text INT DEFAULT NULL,
  text_length INT DEFAULT NULL,
  buffer_target_words INT DEFAULT NULL,
  chunk_size_words INT DEFAULT NULL,
  exact_speed_wpm INT DEFAULT NULL,
  effective_speed_wpm INT DEFAULT NULL,
  session_accuracy DECIMAL(5,2) DEFAULT NULL,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  INDEX idx_user_char (username, expected_char),
  INDEX idx_mode (mode),
  INDEX idx_error_type (error_type),
  INDEX idx_created_at (created_at)
);

Optional: head_copy_lag_events

CREATE TABLE head_copy_lag_events (
  id INT AUTO_INCREMENT PRIMARY KEY,
  username VARCHAR(255) NOT NULL,
  session_id INT NOT NULL,
  item_index INT NOT NULL,
  word_index INT NOT NULL,
  target_lag_words INT NOT NULL,
  observed_lag_words DECIMAL(6,2) NOT NULL,
  event_type VARCHAR(20) NOT NULL,
  event_time_ms INT NOT NULL,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  INDEX idx_session (session_id),
  INDEX idx_user_date (username, created_at)
);

API Endpoints

Implementation Details

• Character error detection: Levenshtein alignment with transposition support.
• Lag computation: compare committed word index against playback-complete word count at submit time.
• Lag aggregates: average lag, minimum lag, lag compliance percentage.
• Resilience: analytics API failures are caught on frontend and never break training flow.
• Auth model: APIs trust session username only; username from client payload is ignored.

Dashboard Features

• Filters by mode, content source, language, timeframe
• Overview cards for sessions, items, accuracy, lag, compliance, total practice time
• Charts for accuracy trend and lag compliance trend
• Problematic character heat map and substitution pair table
• Recent sessions and best sessions tables
• Clear analytics action with explicit confirmation phrase

Getting Started

1. Run Head Copy Lab sessions while signed in.
2. Finish at least one session to persist session + character analytics.
3. Open the analytics dashboard and apply mode/source/time filters.
4. Use character insights and lag trends to choose next drills.

Related pages: Head Copy Lab, Head Copy Analytics, Head Copy Help.