@willwade/aac-processors 0.0.11 → 0.0.13

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

@@ -0,0 +1,147 @@
+/**
+ * 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.
+ */
+/**
+ * Constants for effort score calculation
+ * Values match the Ruby implementation exactly
+ */
+export declare const EFFORT_CONSTANTS: {
+    readonly SQRT2: number;
+    readonly BUTTON_SIZE_MULTIPLIER: 0.09;
+    readonly FIELD_SIZE_MULTIPLIER: 0.005;
+    readonly VISUAL_SCAN_MULTIPLIER: 0.015;
+    readonly BOARD_CHANGE_PROCESSING_EFFORT: 1;
+    readonly BOARD_HOME_EFFORT: 1;
+    readonly COMBINED_WORDS_REMEMBERING_EFFORT: 1;
+    readonly DISTANCE_MULTIPLIER: 0.4;
+    readonly DISTANCE_THRESHOLD_TO_SKIP_VISUAL_SCAN: 0.1;
+    readonly SKIPPED_VISUAL_SCAN_DISTANCE_MULTIPLIER: 0.5;
+    readonly SAME_LOCATION_AS_PRIOR_DISCOUNT: 0.1;
+    readonly RECOGNIZABLE_SEMANTIC_FROM_PRIOR_DISCOUNT: 0.5;
+    readonly RECOGNIZABLE_SEMANTIC_FROM_OTHER_DISCOUNT: 0.5;
+    readonly REUSED_SEMANTIC_FROM_OTHER_BONUS: 0.0025;
+    readonly RECOGNIZABLE_CLONE_FROM_PRIOR_DISCOUNT: 0.33;
+    readonly RECOGNIZABLE_CLONE_FROM_OTHER_DISCOUNT: 0.33;
+    readonly REUSED_CLONE_FROM_OTHER_BONUS: 0.005;
+    readonly SCAN_STEP_COST: 0.015;
+    readonly SCAN_SELECTION_COST: 0.1;
+};
+/**
+ * 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
+ */
+export declare function buttonSizeEffort(rows: number, cols: number): number;
+/**
+ * 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
+ */
+export declare function fieldSizeEffort(buttonCount: number): number;
+/**
+ * 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
+ */
+export declare function visualScanEffort(priorButtons: number): number;
+/**
+ * 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
+ */
+export declare function distanceEffort(x: number, y: number, entryX?: number, entryY?: number): number;
+/**
+ * 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
+ */
+export declare function spellingEffort(word: string): number;
+/**
+ * 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
+ */
+export declare function baseBoardEffort(rows: number, cols: number, buttonCount: number): number;
+/**
+ * Apply reuse discount based on semantic_id/clone_id frequency
+ *
+ * @param boardEffort - Current board effort
+ * @param reuseDiscount - Calculated reuse discount
+ * @returns Adjusted board effort
+ */
+export declare function applyReuseDiscount(boardEffort: number, reuseDiscount: number): number;
+/**
+ * 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
+ */
+export declare function calculateButtonEffort(baseEffort: number, boardPcts: {
+    [id: string]: number;
+}, button: {
+    semantic_id?: string;
+    clone_id?: string;
+}): number;
+/**
+ * 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
+ */
+export declare function calculateDistanceWithDiscounts(distance: number, boardPcts: {
+    [id: string]: number;
+}, button: {
+    semantic_id?: string;
+    clone_id?: string;
+}, setPcts: {
+    [id: string]: number;
+}): number;
+/**
+ * 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
+ */
+export declare function shouldSkipVisualScan(distance: number): boolean;
+/**
+ * Calculate local scan effort when buttons are close
+ *
+ * @param distance - Distance between buttons
+ * @returns Local scan effort
+ */
+export declare function localScanEffort(distance: number): number;
+/**
+ * Calculate effort for switch scanning
+ *
+ * @param steps - Number of scan steps to reach target
+ * @param selections - Number of switch selections required
+ * @returns Scanning effort score
+ */
+export declare function scanningEffort(steps: number, selections: number): number;

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

@@ -0,0 +1,211 @@
+"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;
+exports.scanningEffort = scanningEffort;
+/**
+ * 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,
+    SCAN_STEP_COST: 0.015, // Matches visual scan multiplier
+    SCAN_SELECTION_COST: 0.1, // Cost of a switch selection
+};
+/**
+ * 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;
+}
+/**
+ * Calculate effort for switch scanning
+ *
+ * @param steps - Number of scan steps to reach target
+ * @param selections - Number of switch selections required
+ * @returns Scanning effort score
+ */
+function scanningEffort(steps, selections) {
+    return (steps * exports.EFFORT_CONSTANTS.SCAN_STEP_COST + selections * exports.EFFORT_CONSTANTS.SCAN_SELECTION_COST);
+}

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/obl-types.d.ts

@@ -0,0 +1,93 @@
+/**
+ * .obl (Open Board Logging) File Format Types
+ *
+ * Based on the .obl specification for AAC logging.
+ */
+export interface OblAction {
+    action: string;
+    destination_board_id?: string;
+    text?: string;
+    modification_type?: string;
+    [key: string]: any;
+}
+export interface OblEventBase {
+    id: string;
+    timestamp: string;
+    type: 'button' | 'action' | 'utterance' | 'note' | 'other' | string;
+    locale?: string;
+    geo?: [number, number, number?];
+    location_id?: string;
+    modeling?: boolean;
+    system?: string;
+    window_width?: number;
+    window_height?: number;
+    percent_x?: number;
+    percent_y?: number;
+    [key: string]: any;
+}
+export interface OblButtonEvent extends OblEventBase {
+    type: 'button';
+    label: string;
+    spoken: boolean;
+    button_id?: string;
+    board_id?: string;
+    vocalization?: string;
+    image_url?: string;
+    actions?: OblAction[];
+}
+export interface OblActionEvent extends OblEventBase {
+    type: 'action';
+    action: string;
+    destination_board_id?: string;
+    text?: string;
+    modification_type?: string;
+}
+export interface OblUtteranceEvent extends OblEventBase {
+    type: 'utterance';
+    text: string;
+    buttons?: Array<{
+        id?: string;
+        label?: string;
+        board_id?: string;
+        vocalization?: string;
+        action?: string;
+        text?: string;
+    }>;
+}
+export interface OblNoteEvent extends OblEventBase {
+    type: 'note';
+    text: string;
+    author_name?: string;
+    author_email?: string;
+    author_url?: string;
+}
+export type OblEvent = OblButtonEvent | OblActionEvent | OblUtteranceEvent | OblNoteEvent | OblEventBase;
+export interface OblSession {
+    id: string;
+    type: 'log' | string;
+    started: string;
+    ended: string;
+    device_id?: string;
+    locale?: string;
+    anonymizations?: string[];
+    events: OblEvent[];
+    [key: string]: any;
+}
+export interface OblFile {
+    format: 'open-board-log-0.1' | string;
+    user_id: string;
+    user_name?: string;
+    source?: string;
+    locale?: string;
+    anonymized?: boolean;
+    license?: {
+        type: string;
+        copyright_notice_url?: string;
+        source_url?: string;
+        author_name?: string;
+        author_url?: string;
+        author_email?: string;
+    };
+    sessions: OblSession[];
+    [key: string]: any;
+}

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

@@ -0,0 +1,7 @@
+"use strict";
+/**
+ * .obl (Open Board Logging) File Format Types
+ *
+ * Based on the .obl specification for AAC logging.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -0,0 +1,40 @@
+import { OblFile } from './obl-types';
+import { HistoryEntry } from '../history';
+/**
+ * .obl (Open Board Logging) Utility
+ *
+ * Provides parsing and generation support for the .obl format.
+ */
+export declare class OblUtil {
+    /**
+     * Parse an OBL JSON string.
+     * Handles the optional /* notice * / at the start of the file.
+     */
+    static parse(json: string): OblFile;
+    /**
+     * Stringify an OBL file object.
+     * Optionally adds the recommended notice comment.
+     */
+    static stringify(obl: OblFile, includeNotice?: boolean): string;
+    /**
+     * Convert an OBL file to internal HistoryEntry format.
+     */
+    static toHistoryEntries(obl: OblFile): HistoryEntry[];
+    /**
+     * Convert HistoryEntries to an OBL file object.
+     */
+    static fromHistoryEntries(entries: HistoryEntry[], userId: string, source?: string): OblFile;
+}
+/**
+ * .obl Anonymization Utility
+ */
+export declare class OblAnonymizer {
+    /**
+     * Apply anonymization to an OBL file.
+     */
+    static anonymize(obl: OblFile, types: string[]): OblFile;
+    private static applyTimestampShift;
+    private static applyGeolocationMasking;
+    private static applyUrlStripping;
+    private static applyNameMasking;
+}