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

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

import { MultiZetaStimulus, Stimulus, Zeta } from './type';
/**
 * A constant map from the symbolic item parameter names to their semantic
 * counterparts.
 */
export declare const ZETA_KEY_MAP: {
    a: string;
    b: string;
    c: string;
    d: string;
};
/**
 * Return default item parameters (i.e., zeta)
 *
 * @param {'symbolic' | 'semantic'} desiredFormat - The desired format for the output zeta object.
 * @returns {Zeta} the default zeta object in the specified format.
 */
export declare const defaultZeta: (desiredFormat?: 'symbolic' | 'semantic') => Zeta;
/**
 * Validates the item (a.k.a. zeta) parameters, prohibiting redundant keys and
 * optionally requiring all parameters.
 *
 * @param {Zeta} zeta - The zeta parameters to validate.
 * @param {boolean} requireAll - If `true`, ensures that all required keys are present. Default is `false`.
 *
 * @throws {Error} Will throw an error if any of the validation rules are violated.
 */
export declare const validateZetaParams: (zeta: Zeta, requireAll?: boolean) => void;
/**
 * Fills in default zeta parameters for any missing keys in the provided zeta object.
 *
 * @remarks
 * This function merges the provided zeta object with the default zeta object, converting
 * the keys to the desired format if specified. If no desired format is provided, the
 * keys will remain in their original format.
 *
 * @param {Zeta} zeta - The zeta parameters to fill in defaults for.
 * @param {'symbolic' | 'semantic'} desiredFormat - The desired format for the output zeta object. Default is 'symbolic'.
 *
 * @returns A new zeta object with default values filled in for any missing keys,
 *   and converted to the desired format if specified.
 */
export declare const fillZetaDefaults: (zeta: Zeta, desiredFormat?: 'symbolic' | 'semantic') => Zeta;
/**
 * Converts zeta parameters between symbolic and semantic formats.
 *
 * @remarks
 * This function takes a zeta object and a desired format as input. It converts
 * the keys of the zeta object from their current format to the desired format.
 * If the desired format is 'symbolic', the function maps the keys to their
 * symbolic counterparts using the `ZETA_KEY_MAP`. If the desired format is
 * 'semantic', the function maps the keys to their semantic counterparts using
 * the inverse of `ZETA_KEY_MAP`.
 *
 * @param {Zeta} zeta - The zeta parameters to convert.
 * @param {'symbolic' | 'semantic'} desiredFormat - The desired format for the output zeta object. Must be either 'symbolic' or 'semantic'.
 *
 * @throws {Error} - Will throw an error if the desired format is not 'symbolic' or 'semantic'.
 *
 * @returns {Zeta} A new zeta object with keys converted to the desired format.
 */
export declare const convertZeta: (zeta: Zeta, desiredFormat: 'symbolic' | 'semantic') => Zeta;
/**
 * Validates a corpus of multi-zeta stimuli to ensure that no cat names are
 * duplicated.
 *
 * @remarks
 * This function takes an array of `MultiZetaStimulus` objects, where each
 * object represents an item containing item parameters (zetas) associated with
 * different CAT models. The function checks for any duplicate cat names across
 * each item's array of zeta values. It throws an error if any are found.
 *
 * @param {MultiZetaStimulus[]} corpus - An array of `MultiZetaStimulus` objects representing the corpora to validate.
 *
 * @throws {Error} - Throws an error if any duplicate cat names are found across the corpora.
 */
export declare const checkNoDuplicateCatNames: (corpus: MultiZetaStimulus[]) => void;
/**
 * Filters a list of multi-zeta stimuli based on the availability of model parameters for a specific CAT.
 *
 * This function takes an array of `MultiZetaStimulus` objects and a `catName` as input. It then filters
 * the items based on whether the specified CAT model parameter is present in the item's zeta values.
 * The function returns an object containing two arrays: `available` and `missing`. The `available` array
 * contains items where the specified CAT model parameter is present, while the `missing` array contains
 * items where the parameter is not present.
 *
 * @param {MultiZetaStimulus[]} items - An array of `MultiZetaStimulus` objects representing the stimuli to filter.
 * @param {string} catName - The name of the CAT model parameter to check for.
 *
 * @returns An object with two arrays: `available` and `missing`.
 *
 * @example
 * ```typescript
 * const items: MultiZetaStimulus[] = [
 *   {
 *     stimulus: 'Item 1',
 *     zetas: [
 *       { cats: ['Model A', 'Model B'], zeta: { a: 1, b: 0.5, c: 0.2, d: 0.8 } },
 *       { cats: ['Model C'], zeta: { a: 2, b: 0.7, c: 0.3, d: 0.9 } },
 *     ],
 *   },
 *   {
 *     stimulus: 'Item 2',
 *     zetas: [
 *       { cats: ['Model B', 'Model C'], zeta: { a: 2.5, b: 0.8, c: 0.35, d: 0.95 } },
 *     ],
 *   },
 * ];
 *
 * const result = filterItemsByCatParameterAvailability(items, 'Model A');
 * console.log(result.available);
 * // Output: [
 * //   {
 * //     stimulus: 'Item 1',
 * //     zetas: [
 * //       { cats: ['Model A', 'Model B'], zeta: { a: 1, b: 0.5, c: 0.2, d: 0.8 } },
 * //       { cats: ['Model C'], zeta: { a: 2, b: 0.7, c: 0.3, d: 0.9 } },
 * //     ],
 * //   },
 * // ]
 * console.log(result.missing);
 * // Output: [
 * //   {
 * //     stimulus: 'Item 2',
 * //     zetas: [
 * //       { cats: ['Model B', 'Model C'], zeta: { a: 2.5, b: 0.8, c: 0.35, d: 0.95 } },
 * //     ],
 * //   },
 * // ]
 * ```
 */
export declare const filterItemsByCatParameterAvailability: (items: MultiZetaStimulus[], catName: string) => {
    available: MultiZetaStimulus[];
    missing: MultiZetaStimulus[];
};
/**
 * Converts an array of Stimulus objects into an array of MultiZetaStimulus objects.
 * The user specifies cat names and a delimiter to identify and group parameters.
 *
 * @param {Stimulus[]} items - An array of stimuli, where each stimulus contains parameters
 *   for different CAT instances.
 * @param {string[]} catNames - A list of CAT names to be mapped to their corresponding zeta values.
 * @param {string} delimiter - A delimiter used to separate CAT instance names from the parameter keys in the stimulus object.
 * @param {'symbolic' | 'semantic'} itemParameterFormat - Defines the format to convert zeta values ('symbolic' or 'semantic').
 * @returns {MultiZetaStimulus[]} - An array of MultiZetaStimulus objects, each containing
 *   the cleaned stimulus and associated zeta values for each CAT instance.
 *
 * This function iterates through each stimulus, extracts parameters relevant to the specified
 * CAT instances, converts them to the desired format, and returns a cleaned structure of stimuli
 * with the associated zeta values.
 */
export declare const prepareClowderCorpus: (items: Stimulus[], catNames: string[], delimiter: '.' | string, itemParameterFormat?: 'symbolic' | 'semantic') => MultiZetaStimulus[];