@willwade/aac-processors 0.0.10 → 0.0.12

package/dist/optional/analytics/metrics/effort.js

@@ -0,0 +1,198 @@
+"use strict";
+/**
+ * Effort Score Calculation Algorithms
+ *
+ * Implements the core effort calculation algorithms from the Ruby aac-metrics tool.
+ * These algorithms calculate how difficult it is to access each button based on
+ * distance, visual scanning, grid complexity, and motor planning support.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EFFORT_CONSTANTS = void 0;
+exports.buttonSizeEffort = buttonSizeEffort;
+exports.fieldSizeEffort = fieldSizeEffort;
+exports.visualScanEffort = visualScanEffort;
+exports.distanceEffort = distanceEffort;
+exports.spellingEffort = spellingEffort;
+exports.baseBoardEffort = baseBoardEffort;
+exports.applyReuseDiscount = applyReuseDiscount;
+exports.calculateButtonEffort = calculateButtonEffort;
+exports.calculateDistanceWithDiscounts = calculateDistanceWithDiscounts;
+exports.shouldSkipVisualScan = shouldSkipVisualScan;
+exports.localScanEffort = localScanEffort;
+/**
+ * Constants for effort score calculation
+ * Values match the Ruby implementation exactly
+ */
+exports.EFFORT_CONSTANTS = {
+    SQRT2: Math.sqrt(2),
+    BUTTON_SIZE_MULTIPLIER: 0.09,
+    FIELD_SIZE_MULTIPLIER: 0.005,
+    VISUAL_SCAN_MULTIPLIER: 0.015,
+    BOARD_CHANGE_PROCESSING_EFFORT: 1.0,
+    BOARD_HOME_EFFORT: 1.0,
+    COMBINED_WORDS_REMEMBERING_EFFORT: 1.0,
+    DISTANCE_MULTIPLIER: 0.4,
+    DISTANCE_THRESHOLD_TO_SKIP_VISUAL_SCAN: 0.1,
+    SKIPPED_VISUAL_SCAN_DISTANCE_MULTIPLIER: 0.5,
+    SAME_LOCATION_AS_PRIOR_DISCOUNT: 0.1,
+    RECOGNIZABLE_SEMANTIC_FROM_PRIOR_DISCOUNT: 0.5,
+    RECOGNIZABLE_SEMANTIC_FROM_OTHER_DISCOUNT: 0.5,
+    REUSED_SEMANTIC_FROM_OTHER_BONUS: 0.0025,
+    RECOGNIZABLE_CLONE_FROM_PRIOR_DISCOUNT: 0.33,
+    RECOGNIZABLE_CLONE_FROM_OTHER_DISCOUNT: 0.33,
+    REUSED_CLONE_FROM_OTHER_BONUS: 0.005,
+};
+/**
+ * Calculate button size effort based on grid dimensions
+ * Larger grids require more visual scanning and discrimination
+ *
+ * @param rows - Number of rows in the grid
+ * @param cols - Number of columns in the grid
+ * @returns Button size effort score
+ */
+function buttonSizeEffort(rows, cols) {
+    return exports.EFFORT_CONSTANTS.BUTTON_SIZE_MULTIPLIER * ((rows + cols) / 2);
+}
+/**
+ * Calculate field size effort based on number of visible buttons
+ * More buttons = more visual clutter = higher effort
+ *
+ * @param buttonCount - Number of visible buttons on the board
+ * @returns Field size effort score
+ */
+function fieldSizeEffort(buttonCount) {
+    return exports.EFFORT_CONSTANTS.FIELD_SIZE_MULTIPLIER * buttonCount;
+}
+/**
+ * Calculate visual scanning effort
+ * Effort increases with each button that must be scanned before reaching target
+ *
+ * @param priorButtons - Number of buttons visually scanned before target
+ * @returns Visual scan effort score
+ */
+function visualScanEffort(priorButtons) {
+    return priorButtons * exports.EFFORT_CONSTANTS.VISUAL_SCAN_MULTIPLIER;
+}
+/**
+ * Calculate distance effort from entry point to button center
+ * Uses Euclidean distance normalized by sqrt(2)
+ *
+ * @param x - Button center X coordinate (0-1 normalized)
+ * @param y - Button center Y coordinate (0-1 normalized)
+ * @param entryX - Entry point X coordinate (0-1 normalized, default 1.0 = bottom-right)
+ * @param entryY - Entry point Y coordinate (0-1 normalized, default 1.0 = bottom-right)
+ * @returns Distance effort score
+ */
+function distanceEffort(x, y, entryX = 1.0, entryY = 1.0) {
+    const distance = Math.sqrt(Math.pow(x - entryX, 2) + Math.pow(y - entryY, 2));
+    return (distance / exports.EFFORT_CONSTANTS.SQRT2) * exports.EFFORT_CONSTANTS.DISTANCE_MULTIPLIER;
+}
+/**
+ * Calculate spelling effort for words not available in the board set
+ * Base cost + per-letter cost
+ *
+ * @param word - The word to spell
+ * @returns Spelling effort score
+ */
+function spellingEffort(word) {
+    return 10 + word.length * 2.5;
+}
+/**
+ * Calculate base board effort
+ * Combines button size and field size efforts
+ *
+ * @param rows - Number of rows in the grid
+ * @param cols - Number of columns in the grid
+ * @param buttonCount - Number of visible buttons
+ * @returns Base board effort score
+ */
+function baseBoardEffort(rows, cols, buttonCount) {
+    const sizeEffort = buttonSizeEffort(rows, cols);
+    const fieldEffort = fieldSizeEffort(buttonCount);
+    return sizeEffort + fieldEffort;
+}
+/**
+ * Apply reuse discount based on semantic_id/clone_id frequency
+ *
+ * @param boardEffort - Current board effort
+ * @param reuseDiscount - Calculated reuse discount
+ * @returns Adjusted board effort
+ */
+function applyReuseDiscount(boardEffort, reuseDiscount) {
+    return Math.max(0, boardEffort - reuseDiscount);
+}
+/**
+ * Calculate button-level effort with motor planning discounts
+ *
+ * @param baseEffort - Base board effort
+ * @param boardPcts - Percentage of links matching semantic_id/clone_id
+ * @param button - Button data
+ * @returns Adjusted button effort
+ */
+function calculateButtonEffort(baseEffort, boardPcts, button) {
+    let buttonEffort = baseEffort;
+    // Apply discounts for semantic_id
+    if (button.semantic_id && boardPcts[button.semantic_id]) {
+        const discount = exports.EFFORT_CONSTANTS.SAME_LOCATION_AS_PRIOR_DISCOUNT / boardPcts[button.semantic_id];
+        buttonEffort = Math.min(buttonEffort, buttonEffort * discount);
+    }
+    // Apply discounts for clone_id
+    if (button.clone_id && boardPcts[button.clone_id]) {
+        const discount = exports.EFFORT_CONSTANTS.SAME_LOCATION_AS_PRIOR_DISCOUNT / boardPcts[button.clone_id];
+        buttonEffort = Math.min(buttonEffort, buttonEffort * discount);
+    }
+    return buttonEffort;
+}
+/**
+ * Calculate distance with motor planning discounts
+ *
+ * @param distance - Raw distance effort
+ * @param boardPcts - Percentage of links matching semantic_id/clone_id
+ * @param button - Button data
+ * @param setPcts - Percentage of boards containing semantic_id/clone_id
+ * @returns Adjusted distance effort
+ */
+function calculateDistanceWithDiscounts(distance, boardPcts, button, setPcts) {
+    let adjustedDistance = distance;
+    // Apply semantic_id discounts
+    if (button.semantic_id) {
+        if (boardPcts[button.semantic_id]) {
+            const discount = exports.EFFORT_CONSTANTS.SAME_LOCATION_AS_PRIOR_DISCOUNT / boardPcts[button.semantic_id];
+            adjustedDistance = Math.min(adjustedDistance, adjustedDistance * discount);
+        }
+        else if (setPcts[button.semantic_id]) {
+            const discount = exports.EFFORT_CONSTANTS.RECOGNIZABLE_SEMANTIC_FROM_OTHER_DISCOUNT / setPcts[button.semantic_id];
+            adjustedDistance = Math.min(adjustedDistance, adjustedDistance * discount);
+        }
+    }
+    // Apply clone_id discounts
+    if (button.clone_id) {
+        if (boardPcts[button.clone_id]) {
+            const discount = exports.EFFORT_CONSTANTS.SAME_LOCATION_AS_PRIOR_DISCOUNT / boardPcts[button.clone_id];
+            adjustedDistance = Math.min(adjustedDistance, adjustedDistance * discount);
+        }
+        else if (setPcts[button.clone_id]) {
+            const discount = exports.EFFORT_CONSTANTS.RECOGNIZABLE_CLONE_FROM_OTHER_DISCOUNT / setPcts[button.clone_id];
+            adjustedDistance = Math.min(adjustedDistance, adjustedDistance * discount);
+        }
+    }
+    return adjustedDistance;
+}
+/**
+ * Check if visual scan should be skipped (button close to previous)
+ *
+ * @param distance - Distance from previous button
+ * @returns True if close enough to skip full visual scan
+ */
+function shouldSkipVisualScan(distance) {
+    return distance < exports.EFFORT_CONSTANTS.DISTANCE_THRESHOLD_TO_SKIP_VISUAL_SCAN;
+}
+/**
+ * Calculate local scan effort when buttons are close
+ *
+ * @param distance - Distance between buttons
+ * @returns Local scan effort
+ */
+function localScanEffort(distance) {
+    return distance * exports.EFFORT_CONSTANTS.SKIPPED_VISUAL_SCAN_DISTANCE_MULTIPLIER;
+}

package/dist/optional/analytics/metrics/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * AAC Metrics Module
+ *
+ * Comprehensive metrics analysis for AAC board sets including:
+ * - Effort score calculation with motor planning
+ * - Vocabulary coverage analysis
+ * - Sentence construction evaluation
+ * - Comparative analysis between board sets
+ */
+export { MetricsCalculator } from './core';
+export { VocabularyAnalyzer } from './vocabulary';
+export { SentenceAnalyzer } from './sentence';
+export { ComparisonAnalyzer } from './comparison';
+export * from './types';
+export * from './effort';

package/dist/optional/analytics/metrics/index.js

@@ -0,0 +1,36 @@
+"use strict";
+/**
+ * AAC Metrics Module
+ *
+ * Comprehensive metrics analysis for AAC board sets including:
+ * - Effort score calculation with motor planning
+ * - Vocabulary coverage analysis
+ * - Sentence construction evaluation
+ * - Comparative analysis between board sets
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ComparisonAnalyzer = exports.SentenceAnalyzer = exports.VocabularyAnalyzer = exports.MetricsCalculator = void 0;
+var core_1 = require("./core");
+Object.defineProperty(exports, "MetricsCalculator", { enumerable: true, get: function () { return core_1.MetricsCalculator; } });
+var vocabulary_1 = require("./vocabulary");
+Object.defineProperty(exports, "VocabularyAnalyzer", { enumerable: true, get: function () { return vocabulary_1.VocabularyAnalyzer; } });
+var sentence_1 = require("./sentence");
+Object.defineProperty(exports, "SentenceAnalyzer", { enumerable: true, get: function () { return sentence_1.SentenceAnalyzer; } });
+var comparison_1 = require("./comparison");
+Object.defineProperty(exports, "ComparisonAnalyzer", { enumerable: true, get: function () { return comparison_1.ComparisonAnalyzer; } });
+__exportStar(require("./types"), exports);
+__exportStar(require("./effort"), exports);

package/dist/optional/analytics/metrics/sentence.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Sentence Construction Analysis
+ *
+ * Calculates the effort required to construct test sentences
+ * from the AAC board set, including spelling fallback for missing words.
+ */
+import { MetricsResult } from './types';
+export interface SentenceAnalysis {
+    sentence: string;
+    words: string[];
+    effort: number;
+    total_effort: number;
+    typing: boolean;
+    missing_words: string[];
+    word_efforts: Array<{
+        word: string;
+        effort: number;
+        typed: boolean;
+    }>;
+}
+export declare class SentenceAnalyzer {
+    /**
+     * Analyze effort to construct a set of test sentences
+     */
+    analyzeSentences(metrics: MetricsResult, sentences: string[][]): SentenceAnalysis[];
+    /**
+     * Analyze effort to construct a single sentence
+     */
+    analyzeSentence(metrics: MetricsResult, words: string[]): SentenceAnalysis;
+    /**
+     * Reconstruct sentence from word array
+     */
+    private reconstructSentence;
+    /**
+     * Calculate statistics across all sentences
+     */
+    calculateStatistics(analyses: SentenceAnalysis[]): {
+        total_sentences: number;
+        sentences_requiring_typing: number;
+        sentences_without_typing: number;
+        average_effort: number;
+        min_effort: number;
+        max_effort: number;
+        median_effort: number;
+        total_words: number;
+        words_requiring_typing: number;
+        typing_percent: number;
+    };
+}

package/dist/optional/analytics/metrics/sentence.js

@@ -0,0 +1,112 @@
+"use strict";
+/**
+ * Sentence Construction Analysis
+ *
+ * Calculates the effort required to construct test sentences
+ * from the AAC board set, including spelling fallback for missing words.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SentenceAnalyzer = void 0;
+const effort_1 = require("./effort");
+class SentenceAnalyzer {
+    /**
+     * Analyze effort to construct a set of test sentences
+     */
+    analyzeSentences(metrics, sentences) {
+        return sentences.map((words) => this.analyzeSentence(metrics, words));
+    }
+    /**
+     * Analyze effort to construct a single sentence
+     */
+    analyzeSentence(metrics, words) {
+        const wordEfforts = [];
+        let totalEffort = 0;
+        let typing = false;
+        const missingWords = [];
+        // Create word lookup map
+        const wordMap = new Map();
+        metrics.buttons.forEach((btn) => {
+            const existing = wordMap.get(btn.label.toLowerCase());
+            if (!existing || btn.effort < existing.effort) {
+                wordMap.set(btn.label.toLowerCase(), { effort: btn.effort });
+            }
+        });
+        // Calculate effort for each word
+        words.forEach((word) => {
+            const lowerWord = word.toLowerCase();
+            const found = wordMap.get(lowerWord);
+            if (found) {
+                wordEfforts.push({ word, effort: found.effort, typed: false });
+                totalEffort += found.effort;
+            }
+            else {
+                // Word not found - use spelling effort
+                const spellEffort = (0, effort_1.spellingEffort)(word);
+                wordEfforts.push({ word, effort: spellEffort, typed: true });
+                totalEffort += spellEffort;
+                typing = true;
+                missingWords.push(word);
+            }
+        });
+        const averageEffort = totalEffort / words.length;
+        // Reconstruct sentence for display
+        const sentence = this.reconstructSentence(words);
+        return {
+            sentence,
+            words,
+            effort: averageEffort,
+            total_effort: totalEffort,
+            typing,
+            missing_words: missingWords,
+            word_efforts: wordEfforts,
+        };
+    }
+    /**
+     * Reconstruct sentence from word array
+     */
+    reconstructSentence(words) {
+        return words
+            .map((word, idx) => {
+            // Capitalize first word
+            if (idx === 0) {
+                return word.charAt(0).toUpperCase() + word.slice(1).toLowerCase();
+            }
+            return word.toLowerCase();
+        })
+            .join(' ');
+    }
+    /**
+     * Calculate statistics across all sentences
+     */
+    calculateStatistics(analyses) {
+        const totalSentences = analyses.length;
+        const sentencesRequiringTyping = analyses.filter((a) => a.typing).length;
+        const sentencesWithoutTyping = totalSentences - sentencesRequiringTyping;
+        const efforts = analyses.map((a) => a.effort);
+        const averageEffort = efforts.reduce((sum, e) => sum + e, 0) / efforts.length;
+        const minEffort = Math.min(...efforts);
+        const maxEffort = Math.max(...efforts);
+        // Calculate median
+        const sortedEfforts = [...efforts].sort((a, b) => a - b);
+        const medianEffort = sortedEfforts.length % 2 === 0
+            ? (sortedEfforts[sortedEfforts.length / 2 - 1] + sortedEfforts[sortedEfforts.length / 2]) /
+                2
+            : sortedEfforts[Math.floor(sortedEfforts.length / 2)];
+        const totalWords = analyses.reduce((sum, a) => sum + a.words.length, 0);
+        const wordsRequiringTyping = analyses.reduce((sum, a) => sum + a.missing_words.length, 0);
+        const typingPercent = (wordsRequiringTyping / totalWords) * 100;
+        return {
+            total_sentences: totalSentences,
+            sentences_requiring_typing: sentencesRequiringTyping,
+            sentences_without_typing: sentencesWithoutTyping,
+            average_effort: averageEffort,
+            min_effort: minEffort,
+            max_effort: maxEffort,
+            median_effort: medianEffort,
+            total_words: totalWords,
+            words_requiring_typing: wordsRequiringTyping,
+            typing_percent: typingPercent,
+        };
+    }
+}
+exports.SentenceAnalyzer = SentenceAnalyzer;

package/dist/optional/analytics/metrics/types.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Metrics Types and Interfaces
+ *
+ * Defines the data structures used for AAC metrics analysis
+ */
+/**
+ * Button-level metrics result
+ */
+export interface ButtonMetrics {
+    id: string;
+    label: string;
+    level: number;
+    effort: number;
+    count?: number;
+    semantic_id?: string;
+    clone_id?: string;
+    temporary_home_id?: string;
+    comp_level?: number;
+    comp_effort?: number;
+}
+/**
+ * Board/page level analysis result
+ */
+export interface BoardAnalysis {
+    boardId: string;
+    level: number;
+    entryX: number;
+    entryY: number;
+    priorEffort?: number;
+    temporaryHomeId?: string;
+}
+/**
+ * Metrics analysis result
+ */
+export interface MetricsResult {
+    analysis_version: string;
+    locale: string;
+    total_boards: number;
+    total_buttons: number;
+    total_words: number;
+    reference_counts: {
+        [id: string]: number;
+    };
+    grid: {
+        rows: number;
+        columns: number;
+    };
+    buttons: ButtonMetrics[];
+    levels: {
+        [level: number]: ButtonMetrics[];
+    };
+    alternates?: {
+        [boardId: string]: AlternateBoardMetrics;
+    };
+    obfset?: any;
+}
+/**
+ * Alternate board metrics (for temporary home navigation)
+ */
+export interface AlternateBoardMetrics {
+    buttons: ButtonMetrics[];
+    levels: {
+        [level: number]: ButtonMetrics[];
+    };
+}
+/**
+ * Comparison result between two board sets
+ */
+export interface ComparisonResult extends MetricsResult {
+    target_effort_score: number;
+    comp_boards: number;
+    comp_buttons: number;
+    comp_words: number;
+    comp_grid: {
+        rows: number;
+        columns: number;
+    };
+    comp_effort_score: number;
+    missing_words: string[];
+    extra_words: string[];
+    overlapping_words: string[];
+    missing: {
+        [listId: string]: {
+            name: string;
+            list: string[];
+        };
+    };
+    high_effort_words: string[];
+    low_effort_words: string[];
+    cores: {
+        [listId: string]: {
+            name: string;
+            list: string[];
+            average_effort: number;
+            comp_effort: number;
+        };
+    };
+    care_components: {
+        core: number;
+        comp_core: number;
+        sentences: number;
+        comp_sentences: number;
+        fringe: number;
+        comp_fringe: number;
+        common_fringe: number;
+        comp_common_fringe: number;
+    };
+    sentences: SentenceAnalysis[];
+    fringe_words: FringeWord[];
+    common_fringe_words: FringeWord[];
+}
+/**
+ * Sentence construction analysis
+ */
+export interface SentenceAnalysis {
+    sentence: string;
+    words: string[];
+    effort: number;
+    typing: boolean;
+    comp_effort: number;
+    comp_typing: boolean;
+}
+/**
+ * Fringe vocabulary word analysis
+ */
+export interface FringeWord {
+    word: string;
+    effort: number;
+    comp_effort: number;
+}
+/**
+ * Core vocabulary list definition
+ */
+export interface CoreList {
+    id: string;
+    name: string;
+    url?: string;
+    locale: string;
+    words: string[];
+}
+/**
+ * Common words reference data
+ */
+export interface CommonWordsData {
+    version: string;
+    files: string[];
+    words: string[];
+    efforts: {
+        [word: string]: number;
+    };
+}
+/**
+ * Synonym mappings
+ */
+export interface SynonymsData {
+    [word: string]: string[];
+}

package/dist/optional/analytics/metrics/types.js

@@ -0,0 +1,7 @@
+"use strict";
+/**
+ * Metrics Types and Interfaces
+ *
+ * Defines the data structures used for AAC metrics analysis
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/optional/analytics/metrics/vocabulary.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Vocabulary Coverage Analysis
+ *
+ * Analyzes how well an AAC board set covers core vocabulary
+ * and identifies missing/extra words compared to reference lists.
+ */
+import { MetricsResult } from './types';
+import { ReferenceLoader } from '../reference/index';
+export interface VocabularyAnalysis {
+    core_coverage: {
+        [listId: string]: {
+            name: string;
+            total_words: number;
+            covered: number;
+            missing: number;
+            coverage_percent: number;
+            missing_words: string[];
+            average_effort: number;
+        };
+    };
+    total_unique_words: number;
+    words_with_effort: number;
+    words_requiring_spelling: number;
+    extra_words: string[];
+    high_effort_words: Array<{
+        word: string;
+        effort: number;
+    }>;
+    low_effort_words: Array<{
+        word: string;
+        effort: number;
+    }>;
+}
+export declare class VocabularyAnalyzer {
+    private referenceLoader;
+    constructor(referenceLoader?: ReferenceLoader);
+    /**
+     * Analyze vocabulary coverage against core lists
+     */
+    analyze(metrics: MetricsResult, options?: {
+        locale?: string;
+        highEffortThreshold?: number;
+        lowEffortThreshold?: number;
+    }): VocabularyAnalysis;
+    /**
+     * Analyze coverage for a single core list
+     */
+    private analyzeCoreList;
+    /**
+     * Calculate coverage percentage for a specific word list
+     */
+    calculateCoverage(wordList: string[], metrics: MetricsResult): {
+        covered: string[];
+        missing: string[];
+        coverage_percent: number;
+    };
+    /**
+     * Get effort for a word, or calculate spelling effort if missing
+     */
+    getWordEffort(word: string, metrics: MetricsResult): number;
+    /**
+     * Check if a word is in the board set
+     */
+    hasWord(word: string, metrics: MetricsResult): boolean;
+}