kollar-ts

TypeScript port of kollaR - Eye tracking data analysis library

Overview

kollar-ts is a TypeScript port of the R package kollaR by Johan Lundin Kleberg. It provides scientific algorithms for analyzing eye tracking data, including fixation detection, saccade analysis, and Area of Interest (AOI) analysis.

Features

• 4 Fixation Detection Algorithms:

  • I-VT: Velocity-based algorithm
  • I-DT: Dispersion-based algorithm
  • I2MC: Two-means clustering algorithm
  • Adaptive: Adaptive velocity threshold algorithm

• Preprocessing Pipeline:

  • Gap interpolation with margin-based approach
  • Moving average smoothing
  • RMS (precision) calculation
  • Downsampling for robustness

• Analysis Tools:

  • Area of Interest (AOI) testing
  • Sample-to-sample precision metrics (RMSD)
  • Velocity profile analysis
  • Fixation merging and trimming

• Full TypeScript Support:

  • Strict type checking
  • Comprehensive type definitions
  • IDE autocomplete support

⚠️ Important: Validation Status

This library is feature-complete and well-tested (257 tests, 91.64% coverage), but R validation has not yet been performed.

Use Cases

✅ Recommended for:

• Development and prototyping
• Learning eye tracking analysis algorithms
• Internal tools and demos
• Further testing and experimentation

❌ NOT recommended for (yet):

• Scientific publication
• Research use requiring validated results
• Claims of equivalence with R kollaR

Why This Matters

Scientific software requires proof that the TypeScript implementation produces equivalent results to the original R implementation. While all algorithms are comprehensively tested internally, we cannot claim scientific validity without comparing outputs with R.

Key Concerns:

1. ml-kmeans dependency (HIGH RISK): The I2MC algorithm uses the ml-kmeans library, which implements Lloyd's algorithm (kmeans++). The R kollaR package uses Hartigan-Wong algorithm. Different algorithms may produce different clustering results.
2. No R comparison tests: Need to verify that all algorithms produce equivalent results to R (within acceptable tolerance, typically < 0.1%).
3. Numerical precision: Floating-point behavior not validated against R.

Path to research-ready: Complete R validation (estimated 20-30 hours of work). See /evaluation/ directory for comprehensive audit.

Installation

npm install kollar-ts

Quick Start

import { preprocessGaze, calculateRMS } from 'kollar-ts';

// Your raw gaze data from eye tracker
const rawData = [
  { timestamp: 0, x: 512, y: 384 },
  { timestamp: 1.67, x: 513, y: 385 },
  // ... more samples
];

// Preprocess: interpolate gaps and smooth
const processed = preprocessGaze(rawData, {
  maxGapMs: 75,   // Interpolate gaps up to 75ms
  marginMs: 5,    // Use 5ms margin for interpolation
  filterMs: 15,   // 15ms moving average window
});

// Calculate precision metric
const rms = calculateRMS(processed, 'x', 'y', 40);
console.log(`Sample-to-sample precision: ${rms.toFixed(3)} degrees`);

Fixation Detection

import { algorithmIVT, algorithmIDT, algorithmI2MC, algorithmAdaptive } from 'kollar-ts';

// I-VT: Velocity-based detection
const ivtResult = algorithmIVT(processed, {
  velocityThreshold: 35, // degrees/second
  minFixationDuration: 40, // milliseconds
});

// I-DT: Dispersion-based detection
const idtResult = algorithmIDT(processed, {
  dispersionThreshold: 1.0, // degrees
  minDuration: 40, // milliseconds
});

// I2MC: Clustering-based detection (robust to noise)
const i2mcResult = algorithmI2MC(processed, {
  windowLengthMs: 200,
  downsamplingFactors: [2, 5, 10],
});

// Adaptive: Data-driven threshold
const adaptiveResult = algorithmAdaptive(processed, {
  onsetThresholdSd: 3,
  saveVelocityProfiles: true,
});

console.log(`Detected ${ivtResult.fixations.length} fixations`);

Development Status

Version 0.2.0 - ⚠️ Feature-complete, R validation pending

Current Status

✅ Ready for Development Use:

• All features implemented and tested (257 tests, 100% pass rate)
• 91.64% code coverage
• 7 working examples
• Complete documentation

⚠️ NOT Ready for Scientific Publication:

• R validation not yet performed
• ml-kmeans dependency unverified (HIGH RISK - uses different algorithm than R)
• Cannot claim scientific equivalence without validation

Estimated time to research-ready: 20-30 hours (R validation + dependency verification)

✅ Complete Features

• Type System: Full TypeScript support with strict mode
• Preprocessing Pipeline: Interpolation, smoothing, RMS calculation, downsampling
• Fixation Detection Algorithms:
  • I-VT (Velocity-based) - 16 tests ✅
  • I-DT (Dispersion-based) - 13 tests ✅
  • I2MC (Clustering-based) - 14 tests ✅ ⚠️ ml-kmeans unverified
  • Adaptive (Data-driven thresholds) - 17 tests ✅
• Fixation Utilities: Summarize, merge, trim - 18 tests ✅
• AOI Analysis: Classification, dwell time, latency, transitions - 28 tests ✅
• Comprehensive Testing: 257 tests with 91.64% coverage (100% pass rate)
• Integration Testing: Full pipeline validation - 16 tests ✅
• Working Examples: 7 complete examples demonstrating all features
• Documentation: Complete API documentation and usage guides

❌ Pending for Research Use

• R Validation: Compare outputs with R kollaR package (CRITICAL)
• ml-kmeans Verification: Verify I2MC against R's kmeans (HIGH RISK)
• Numerical Precision Testing: Validate floating-point behavior
• Performance Benchmarks: Compare speed with R implementation
• VALIDATION.md: Document validation results and tolerances

For comprehensive evaluation, see /evaluation/EXECUTIVE_SUMMARY.md

Project Structure

kollar-ts/
├── src/
│   ├── types/           # TypeScript type definitions
│   ├── utils/           # Utility functions (math, stats, RLE, rolling)
│   ├── preprocessing/   # Data preprocessing pipeline
│   ├── core/           # Core fixation detection algorithms
│   ├── analysis/       # AOI and analysis functions
│   └── index.ts        # Main exports
├── test/
│   ├── unit/          # Unit tests
│   ├── integration/   # Integration tests
│   └── validation/    # Validation against R
├── examples/          # Usage examples
├── docs/             # Documentation
├── LICENSE           # GPL-3.0 license
└── CITATION.md       # Citation information

Attribution

This TypeScript implementation is a port of the R package kollaR by Johan Lundin Kleberg.

Original R Package

• Author: Johan Lundin Kleberg
• Email: johan.lundin.kleberg@su.se
• Organization: Stockholm University
• Repository: https://github.com/drjohanlk/kollaR
• License: GPL-3.0

Research Citations

The algorithms in this library are based on peer-reviewed research:

I-VT and I-DT Algorithms

Salvucci, D. D., & Goldberg, J. H. (2000). Identifying fixations and saccades in eye-tracking protocols. Proceedings of the 2000 symposium on Eye tracking research & applications, 71-78. DOI: 10.1145/355017.355028

I2MC Algorithm

Hessels, R. S., Niehorster, D. C., Kemner, C., & Hooge, I. T. C. (2017). Noise-robust fixation detection in eye movement data: Identification by two-means clustering (I2MC). Behavior Research Methods, 49(5), 1802-1823. DOI: 10.3758/s13428-016-0822-1

Adaptive Velocity Threshold

Nyström, M., & Holmqvist, K. (2010). An adaptive algorithm for fixation, saccade, and glissade detection in eyetracking data. Behavior Research Methods, 42(1), 188-204. DOI: 10.3758/BRM.42.1.188

Please cite both the original R package and the relevant research papers when using this library.

See CITATION.md for complete citation information.

API Documentation

Preprocessing

import { preprocessGaze, calculateRMS } from 'kollar-ts';

// Main preprocessing pipeline
const processed = preprocessGaze(rawData, {
  maxGapMs: 75,      // Max gap to interpolate (ms)
  marginMs: 5,       // Margin for interpolation (ms)
  filterMs: 15,      // Moving average window (ms)
  xcol: 'x',         // X coordinate column name
  ycol: 'y',         // Y coordinate column name
  naIgnore: true,    // Ignore NAs when filtering
});

// Calculate precision (RMS)
const rms = calculateRMS(processed, 'x', 'y', 40);

Utilities

import { mean, median, sd, mad } from 'kollar-ts/utils';
import { rollmean, rollmedian } from 'kollar-ts/utils';
import { rle, findRuns } from 'kollar-ts/utils';

// Statistical functions
const m = mean([1, 2, 3, null, 4], true);  // true = remove NAs
const med = median([1, 2, 10, 4, 5], true);

// Rolling operations
const smoothed = rollmean(data, 5, 'center');  // 5-sample window

// Run-length encoding
const encoded = rle([1, 1, 2, 2, 2, 3]);
// { lengths: [2, 3, 1], values: [1, 2, 3] }

Examples

The examples/ directory contains complete, runnable examples demonstrating all features:

Algorithm Examples

• examples/i-vt.ts - I-VT velocity-based fixation detection
• examples/i-dt.ts - I-DT dispersion-based fixation detection
• examples/i2mc.ts - I2MC clustering-based algorithm (robust to noise)
• examples/adaptive.ts - Adaptive data-driven threshold algorithm
• examples/aoi-analysis.ts - Area of Interest (AOI) analysis and gaze transitions

Real Data Demo

examples/real-data-demo.ts - Complete pipeline demonstration using real eye tracking data

# Run the real data demo
npx tsx examples/real-data-demo.ts

This example shows:

• Loading real gaze data from JSON
• Preprocessing (interpolation, smoothing, RMS calculation)
• Running all 4 fixation detection algorithms
• Comparing algorithm results
• Performance analysis and spatial distribution

The demo uses sample data representative of Tobii Pro Spectrum recordings at 1200 Hz. For full datasets from the original R package, see examples/data/README.md for export instructions.

Development

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Watch mode for tests
npm run test:watch

# Type checking
npm run typecheck

# Linting
npm run lint

Contributing

Contributions are welcome! This project maintains scientific accuracy as its top priority. All algorithm implementations must match the R package behavior and be validated against R outputs.

Guidelines

1. Scientific Accuracy: All algorithms must be validated against R implementation
2. Testing: Comprehensive unit and validation tests required
3. Documentation: TSDoc comments for all public APIs
4. Type Safety: Strict TypeScript mode, no any types
5. Code Style: Follow existing patterns, use Prettier

License

GPL-3.0 - This project uses the same license as the original R package to ensure it remains open and accessible to the research community.

See LICENSE for full license text.

Roadmap

Phase 1: Foundation ✅ COMPLETE

• Project setup and configuration
• Type definitions
• Utility functions (95 tests ✅)
• Preprocessing pipeline (38 tests ✅)

Phase 2: Core Algorithms ✅ COMPLETE

• Fixation utility functions (18 tests ✅)
• I-DT algorithm (13 tests ✅)
• I-VT algorithm (16 tests ✅)
• I2MC algorithm (14 tests ✅)
• Adaptive algorithm (17 tests ✅)

Phase 3: Analysis & Validation ⚠️ PARTIALLY COMPLETE

• AOI analysis (28 tests ✅)
• Comprehensive unit tests (257 tests, 100% pass rate ✅)
• 91.64% test coverage ✅
• Integration testing (16 tests ✅)
• R validation ❌ (CRITICAL - required for research use)
• ml-kmeans verification ❌ (HIGH RISK)
• Numerical precision validation ❌
• Performance benchmarks ❌

Phase 4: Documentation & Examples ✅ COMPLETE

• Complete examples (7 working examples ✅)
• Usage guides ✅
• API documentation ✅
• README and guides ✅
• Comprehensive evaluation (/evaluation/ ✅)

Phase 5: Validation for Research Use ⚠️ TODO

Estimated time: 20-30 hours

Critical (BLOCKER for scientific publication):

• Run R validation script to generate fixture data
• Create R comparison tests
• Verify ml-kmeans produces same results as R
• Document validation results in VALIDATION.md
• Define and test acceptable tolerances

Important:

• Numerical precision testing
• Performance benchmarks vs R
• Update documentation with validation status

Optional:

• Algorithm-specific documentation pages
• Decision log (DECISIONS.md)

Phase 6: Publication 🚀 CONDITIONAL

Can publish now with disclaimer, OR wait for R validation

Option A: Publish with disclaimer

• npm publication with "R validation pending" notice
• GitHub release (v0.2.0-beta or similar)
• Clear documentation of limitations

Option B: Wait for validation (recommended)

• Complete Phase 5 (R validation)
• npm publication as research-ready
• GitHub release (v0.2.0)
• Research community announcement

Future Enhancements (Post validation)

• CI/CD pipeline (GitHub Actions)
• Additional algorithms
• Extended AOI analysis features
• Performance optimizations

Evaluation & Status

A comprehensive evaluation of kollar-ts has been completed. All documentation in this section is up-to-date as of October 23, 2025.

Overall Assessment

• Implementation Quality: 9.5/10 ✅
• Test Coverage: 9/10 ✅ (257 tests, 91.64% coverage)
• Documentation: 8/10 ✅
• Scientific Validation: 2/10 ❌ (R comparison not performed)
• Overall Score: 6.5/10 ⚠️ (would be 9/10 with R validation)

Evaluation Documents

For detailed analysis, see the /evaluation/ directory:

• EXECUTIVE_SUMMARY.md - Complete assessment and recommendations
• PRECISION_TEST_RESULTS.md - Test suite analysis
• DEPENDENCIES_ANALYSIS.md - ml-kmeans risk assessment
• README.md - Evaluation overview and navigation

Key Findings

✅ Strengths:

• Complete, well-tested implementation (257 tests, 100% pass rate)
• Excellent code quality (strict TypeScript, comprehensive types)
• All algorithms implemented with comprehensive edge case handling
• 91.64% test coverage
• Complete documentation and working examples

❌ Critical Gaps:

• R validation not performed (cannot prove scientific accuracy)
• ml-kmeans dependency unverified (HIGH RISK - uses different algorithm than R)
• No numerical precision validation against R

Verdict: ⚠️ CONDITIONAL - Ready for development use, needs R validation (20-30 hours) for research use.

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Original R Package: https://github.com/drjohanlk/kollaR
• Evaluation: See /evaluation/ for comprehensive audit

Citation

If you use kollar-ts in your research, please cite both this TypeScript implementation and the original R package. See CITATION.md for complete citation information.

⚠️ Important: Until R validation is complete, this library should be used for development/prototyping only, not for scientific publication.

Acknowledgments

This TypeScript port was created by H.Kaan Koyukan.

Special thanks to:

• Johan Lundin Kleberg for the original R implementation
• All researchers who developed and validated these eye tracking algorithms
• The eye tracking research community

---

Note: This is a scientific software project. Precision and accuracy are paramount. R validation is required before this implementation can be considered equivalent to the original R package. See /evaluation/ for comprehensive assessment.