v5.2.2

jsCAT v5.2.2 Release Notes

We're excited to announce the release of jsCAT v5.2.2, a major milestone that represents significant improvements to our JavaScript library for IRT-based computer adaptive testing. This release introduces substantial enhancements to algorithm accuracy, API flexibility, and overall robustness. We're also setting this version tag as the first GitHub release.

🚀 What's New

Enhanced EAP Estimation Algorithm

• Fixed Critical Bug: Resolved likelihood function initialization issue that was affecting EAP calculations
• Improved Accuracy: EAP estimates are now more reliable and mathematically sound

Flexible Prior Distribution Support

• Multiple Distribution Types: Support for both normal ('norm') and uniform ('unif') prior distributions
• Dynamic Configuration: Prior distributions are now constructed dynamically based on method and parameters
• Better Validation: Comprehensive prior validation with clear error messages

Enhanced Item Selection Methods

• New 'Fixed' Selection: Added support for 'fixed' item selection method for deterministic item ordering
• Improved MFI Algorithm: Maximum Fisher Information selection now uses standardized parameter handling
• Robust Parameter Defaults: Automatic filling of missing item parameters with sensible defaults

Modernized Type System

• Flexible Zeta Interface: Support for both symbolic (a, b, c, d) and semantic (discrimination, difficulty, guessing, slipping) parameter names
• Optional Properties: More flexible stimulus definitions with optional parameters
• Better Type Safety: Enhanced TypeScript support with improved type definitions

Advanced Multi-CAT Support with Clowder

• Centralized Management: The new Clowder class enables management of multiple CAT instances simultaneously
• Corpus Management: Sophisticated handling of validated and unvalidated items across multiple CATs
• Early Stopping: Configurable stopping criteria including item count, SE measurement thresholds, and plateau detection
• Multi-Zeta Stimuli: Support for stimuli with different parameters for different CAT instances

🔧 Technical Improvements

Robust Parameter Validation

• Comprehensive validation for all zeta parameters
• Automatic conversion between symbolic and semantic parameter formats
• Clear error messages for invalid configurations

Optimized Dependencies

• Switched to specific lodash function imports for better tree-shaking
• Reduced bundle size and improved performance
• Updated to modern import patterns

Enhanced Testing Framework

• Extensive ground truth validation tests
• Support for multiple participants with separate CSV files
• Async testing with Promise.all for parallel validation
• Comprehensive test coverage for all estimation methods

Getting Started

Installation

npm install @bdelab/jscat@5.2.2

Quick Example

import { Cat } from '@bdelab/jscat';

// Create a Cat with EAP estimation and normal prior
const cat = new Cat({
  method: 'eap',
  itemSelect: 'MFI',
  priorDist: 'norm',
  priorPar: [0, 1],
  minTheta: -6,
  maxTheta: 6
});

// Use flexible parameter format
const items = [
  { discrimination: 1.2, difficulty: 0.5, guessing: 0.2 },
  { a: 1.5, b: -0.3, c: 0.1, d: 1.0 }
];

const responses = [1, 0];
cat.updateAbilityEstimate(items, responses);

Migration Information

Some users will have trouble switching from jsCat v4.0.0 to this current version. To help, in this section we analyze the breaking changes in the Cat object between v4.0.0 and the current version of jsCAT library.

🏗️ Structural Changes

File Location Change

• v4.0.0: Cat class was in src/index.ts
• Current: Cat class moved to src/cat.ts and exported from src/index.ts
• 🎇 Impact: Direct imports from ./index may still work, but internal file structure has changed. Confirm that import statements reference the correct path.

Constructor Interface Changes

• CatInput Interface Changes:

  // v4.0.0
  export interface CatInput {
    prior?: number[][];  // Direct prior distribution array
    // Missing priorDist and priorPar
  }
  
  // Current
  export interface CatInput {
    priorDist?: string;     // NEW: Prior distribution type
    priorPar?: number[];    // NEW: Prior distribution parameters  
    // prior property removed from interface
  }

• Constructor Parameter Changes:

  • v4.0.0: prior = abilityPrior (direct array)
  • Current: priorDist = 'norm' and priorPar = [0, 1] (separate type and parameters)

• 🎇 Impact: If you're using a custom prior, you will need to update to the new input interfaces.

Property Access Changes

• Removed Properties:

  • v4.0.0: private _nItems: number property existed
  • Current: _nItems property removed, nItems getter now returns this._resps.length
  • 🎇 Impact: Remove any references to _nItems. References to nItems will still work.

• New Properties:

  • Current: public priorDist: string (NEW)
  • Current: public priorPar: number[] (NEW)
  • Current: private _prior: [number, number][] (NEW - computed from priorDist/priorPar)

• Changed Property Types:

  • v4.0.0: public prior: number[][]
  • Current: private _prior: [number, number][] with public get prior()
  • 🎇 Impact: Remove any references to the prior property.

Validation Method Changes

• validateItemSelect Method:

  // v4.0.0
  const validItemSelect: Array<string> = ['mfi', 'random', 'closest'];
  
  // Current  
  const validItemSelect: Array<string> = ['mfi', 'random', 'closest', 'fixed'];

  • Breaking: Added 'fixed' as valid item selection method
  • 🎇 Impact: Low

• validateStartSelect Method:

  // v4.0.0
  const validStartSelect: Array<string> = ['random', 'middle'];
  
  // Current
  const validStartSelect: Array<string> = ['random', 'middle', 'fixed'];

  • Breaking: Added 'fixed' as valid start selection method
  • 🎇 Impact: Low

EAP Estimation Changes

// v4.0.0 - estimateAbilityEAP()
const like = this.likelihood(theta);  // Direct likelihood

// Current - estimateAbilityEAP()  
const like = Math.exp(this.likelihood(theta)); // Convert back from log-likelihood

• Breaking: EAP now converts log-likelihood back to probability using Math.exp()
• 🎇 Impact: High. EAP estimates are now correct. No changes in user code should be needed.

Type System Changes

Zeta Type Definition Changes

// v4.0.0
export type Zeta = { a: number; b: number; c: number; d: number };

// Current
export interface Zeta {
  a?: number; b?: number; c?: number; d?: number;  // Optional symbolic
  discrimination?: number; difficulty?: number;     // Optional semantic  
  guessing?: number; slipping?: number;
}

• Breaking: Zeta changed from required properties to optional with semantic alternatives

Stimulus Type Changes

// v4.0.0
export interface Stimulus {
  difficulty: number;  // Required
  [key: string]: any;
}

// Current  
export interface Stimulus extends Zeta {  // Now extends Zeta
  [key: string]: any;
}

• Breaking: Stimulus now extends Zeta interface, difficulty no longer explicitly required

Prior Distribution Construction

// v4.0.0
export const abilityPrior = normal();  // Global constant
// Constructor: prior = abilityPrior

// Current
// Constructor: this._prior = this.method === 'eap' ? Cat.validatePrior(priorDist, priorPar, minTheta, maxTheta) : [];

• Breaking: Prior distribution now constructed dynamically based on method and parameters
• Breaking: Removed global abilityPrior constant

Summary of Highest Impact Breaking Changes

• Constructor interface completely changed (prior → priorDist/priorPar)

  // v4.0.0
  const cat = new Cat({
    prior: customPriorArray  // number[][]
  });
  
  // Current - BREAKING CHANGE
  const cat = new Cat({
    priorDist: 'norm',      // 'norm' or 'unif'
    priorPar: [0, 1]        // [mean, sd] for norm, [min, max] for unif
  });

• Zeta/Stimulus type definitions changed from required to optional properties

  // v4.0.0 - All properties required
  const zeta: Zeta = { a: 1, b: 0, c: 0, d: 1 };
  
  // Current - Properties optional, semantic names supported
  const zeta: Zeta = { discrimination: 1, difficulty: 0 }; // ✅ Valid
  const zeta: Zeta = { a: 1, b: 0 }; // ✅ Also valid (defaults applied)

• EAP estimation algorithm changed (affects numerical results)

Issues & Support: Please report any issues on our GitHub repository.

Citation: If you use jsCAT in your research, please cite our paper: Ma, W. A., et al. (2025). ROAR-CAT: Rapid Online Assessment of Reading ability with Computerized Adaptive Testing. Behavior Research Methods, 57(1), 1-17.