@bdelab/jscat/lib/clowder.d.ts

A library to support IRT-based computer adaptive testing in JavaScript

/// <reference types="lodash" />
import { Cat, CatInput } from './cat';
import { CatMap, MultiZetaStimulus, Stimulus, Zeta } from './type';
import { EarlyStopping } from './stopping';
export interface ClowderInput {
    /**
     * An object containing Cat configurations for each Cat instance.
     * Keys correspond to Cat names, while values correspond to Cat configurations.
     */
    cats: CatMap<CatInput>;
    /**
     * An object containing arrays of stimuli for each corpus.
     */
    corpus: MultiZetaStimulus[];
    /**
     * A random seed for reproducibility. If not provided, a random seed will be generated.
     */
    randomSeed?: string | null;
    /**
     * An optional EarlyStopping instance to use for early stopping.
     */
    earlyStopping?: EarlyStopping;
}
/**
 * The Clowder class is responsible for managing a collection of Cat instances
 * along with a corpus of stimuli.  It maintains a list of named Cat instances
 * and a corpus where each item in the coprpus may have IRT parameters
 * corresponding to each named Cat. Clowder provides methods for updating the
 * ability estimates of each of its Cats, and selecting the next item to present
 * to the participant.
 */
export declare class Clowder {
    private _cats;
    private _corpus;
    private _remainingItems;
    private _seenItems;
    private _earlyStopping?;
    private readonly _rng;
    private _stoppingReason;
    /**
     * Create a Clowder object.
     *
     * @param {ClowderInput} input - An object containing arrays of Cat configurations and corpora.
     * @param {CatMap<CatInput>} input.cats - An object containing Cat configurations for each Cat instance.
     * @param {MultiZetaStimulus[]} input.corpus - An array of stimuli representing each corpus.
     *
     * @throws {Error} - Throws an error if any item in the corpus has duplicated IRT parameters for any Cat name.
     */
    constructor({ cats, corpus, randomSeed, earlyStopping }: ClowderInput);
    /**
     * Validate the provided Cat name against the existing Cat instances.
     * Throw an error if the Cat name is not found.
     *
     * @param {string} catName - The name of the Cat instance to validate.
     * @param {boolean} allowUnvalidated - Whether to allow the reserved 'unvalidated' name.
     *
     * @throws {Error} - Throws an error if the provided Cat name is not found among the existing Cat instances.
     */
    private _validateCatName;
    /**
     * The named Cat instances that this Clowder manages.
     */
    get cats(): import("lodash").Omit<CatMap<Cat>, "unvalidated">;
    /**
     * The corpus that was provided to this Clowder when it was created.
     */
    get corpus(): MultiZetaStimulus[];
    /**
     * The subset of the input corpus that this Clowder has not yet "seen".
     */
    get remainingItems(): MultiZetaStimulus[];
    /**
     * The subset of the input corpus that this Clowder has "seen" so far.
     */
    get seenItems(): Stimulus[];
    /**
     * The theta estimates for each Cat instance.
     */
    get theta(): {
        [x: string]: number;
        [x: number]: number;
    };
    /**
     * The standard error of measurement estimates for each Cat instance.
     */
    get seMeasurement(): {
        [x: string]: number;
        [x: number]: number;
    };
    /**
     * The number of items presented to each Cat instance.
     */
    get nItems(): {
        [x: string]: number;
        [x: number]: number;
    };
    /**
     * The responses received by each Cat instance.
     */
    get resps(): {
        [x: string]: (0 | 1)[];
        [x: number]: (0 | 1)[];
    };
    /**
     * The zeta (item parameters) received by each Cat instance.
     */
    get zetas(): {
        [x: string]: Zeta[];
        [x: number]: Zeta[];
    };
    /**
     * The early stopping condition in the Clowder configuration.
     */
    get earlyStopping(): EarlyStopping | undefined;
    /**
     * The stopping reason in the Clowder configuration.
     */
    get stoppingReason(): string | null;
    /**
     * Updates the ability estimates for the specified Cat instances.
     *
     * @param {string[]} catNames - The names of the Cat instances to update.
     * @param {Zeta | Zeta[]} zeta - The item parameter(s) (zeta) for the given stimuli.
     * @param {(0 | 1) | (0 | 1)[]} answer - The corresponding answer(s) (0 or 1) for the given stimuli.
     * @param {string} [method] - Optional method for updating ability estimates. If none is provided, it will use the default method for each Cat instance.
     *
     * @throws {Error} If any `catName` is not found among the existing Cat instances.
     */
    updateAbilityEstimates(catNames: string[], zeta: Zeta | Zeta[], answer: (0 | 1) | (0 | 1)[], method?: string): void;
    /**
     * Update the ability estimates for the specified `catsToUpdate` and select the next stimulus for the `catToSelect`.
     * This function processes previous items and answers, updates internal state, and selects the next stimulus
     * based on the remaining stimuli and `catToSelect`.
     *
     * @param {Object} input - The parameters for updating the Cat instance and selecting the next stimulus.
     * @param {string} input.catToSelect - The Cat instance to use for selecting the next stimulus.
     * @param {string | string[]} [input.catsToUpdate=[]] - A single Cat or array of Cats for which to update ability estimates.
     * @param {Stimulus[]} [input.items=[]] - An array of previously presented stimuli.
     * @param {(0 | 1) | (0 | 1)[]} [input.answers=[]] - An array of answers (0 or 1) corresponding to `items`.
     * @param {string} [input.method] - Optional method for updating ability estimates (if applicable).
     * @param {string} [input.itemSelect] - Optional item selection method (if applicable).
     * @param {boolean} [input.randomlySelectUnvalidated=false] - Optional flag indicating whether to randomly select an unvalidated item for `catToSelect`.
     *
     * @returns {Stimulus | undefined} - The next stimulus to present, or `undefined` if no further validated stimuli are available.
     *
     * @throws {Error} If `items` and `answers` lengths do not match.
     * @throws {Error} If any `items` are not found in the Clowder's corpora (validated or unvalidated).
     *
     * The function operates in several steps:
     * 1. Validate:
     *    a. Validates the `catToSelect` and `catsToUpdate`.
     *    b. Ensures `items` and `answers` arrays are properly formatted.
     * 2. Update:
     *    a. Updates the internal list of seen items.
     *    b. Updates the ability estimates for the `catsToUpdate`.
     * 3. Select:
     *    a. Selects the next item using `catToSelect`, considering only remaining items that are valid for that cat.
     *    b. If desired, randomly selects an unvalidated item for catToSelect.
     */
    updateCatAndGetNextItem({ catToSelect, catsToUpdate, items, answers, method, itemSelect, randomlySelectUnvalidated, returnUndefinedOnExhaustion, }: {
        catToSelect: string;
        catsToUpdate?: string | string[];
        items?: MultiZetaStimulus | MultiZetaStimulus[];
        answers?: (0 | 1) | (0 | 1)[];
        method?: string;
        itemSelect?: string;
        randomlySelectUnvalidated?: boolean;
        returnUndefinedOnExhaustion?: boolean;
    }): Stimulus | undefined;
}