bead 0.1.0__py3-none-any.whl

bead/deployment/jspsych/templates/randomizer.js

@@ -0,0 +1,241 @@
+// This file is generated from Python OrderingConstraint specifications
+// Do not edit manually - regenerate using bead.deployment.jspsych.randomizer
+
+// Embedded metadata for constraint checking
+const trialMetadata = {{ metadata | tojson }};
+
+// Constraint specifications
+const constraints = {{ constraints | tojson }};
+
+/**
+ * Shuffle array in place using Fisher-Yates algorithm
+ * @param {Array} array - Array to shuffle
+ * @param {function} rng - Random number generator
+ */
+function shuffle(array, rng) {
+    for (let i = array.length - 1; i > 0; i--) {
+        const j = Math.floor(rng() * (i + 1));
+        [array[i], array[j]] = [array[j], array[i]];
+    }
+}
+
+{% if has_precedence %}
+/**
+ * Check if trial order satisfies precedence constraints
+ * @param {Array} trials - Array of trial objects with item_id property
+ * @param {Array} pairs - Array of [itemA_id, itemB_id] precedence pairs
+ * @returns {boolean} True if all precedence constraints satisfied
+ */
+function checkPrecedence(trials, pairs) {
+    const positions = {};
+    trials.forEach((trial, idx) => {
+        positions[trial.item_id] = idx;
+    });
+
+    for (const [itemA, itemB] of pairs) {
+        if (positions[itemA] !== undefined && positions[itemB] !== undefined) {
+            if (positions[itemA] >= positions[itemB]) {
+                return false;
+            }
+        }
+    }
+    return true;
+}
+{% endif %}
+
+{% if has_no_adjacent %}
+/**
+ * Check if no adjacent trials have same property value
+ * @param {Array} trials - Array of trial objects
+ * @param {string} property - Property path to check
+ * @param {Object} metadata - Trial metadata
+ * @returns {boolean} True if no adjacent items have same value
+ */
+function checkNoAdjacent(trials, property, metadata) {
+    for (let i = 0; i < trials.length - 1; i++) {
+        const valueA = getPropertyValue(metadata[trials[i].item_id], property);
+        const valueB = getPropertyValue(metadata[trials[i + 1].item_id], property);
+
+        if (valueA !== undefined && valueB !== undefined && valueA === valueB) {
+            return false;
+        }
+    }
+    return true;
+}
+{% endif %}
+
+{% if has_min_distance %}
+/**
+ * Check if minimum distance constraint is satisfied
+ * @param {Array} trials - Array of trial objects
+ * @param {string} property - Property path to check
+ * @param {number} minDist - Minimum distance required
+ * @param {Object} metadata - Trial metadata
+ * @returns {boolean} True if minimum distance satisfied
+ */
+function checkMinDistance(trials, property, minDist, metadata) {
+    const valuePositions = {};
+
+    trials.forEach((trial, idx) => {
+        const value = getPropertyValue(metadata[trial.item_id], property);
+        if (value !== undefined) {
+            if (!valuePositions[value]) {
+                valuePositions[value] = [];
+            }
+            valuePositions[value].push(idx);
+        }
+    });
+
+    for (const positions of Object.values(valuePositions)) {
+        for (let i = 0; i < positions.length - 1; i++) {
+            const distance = positions[i + 1] - positions[i] - 1;
+            if (distance < minDist) {
+                return false;
+            }
+        }
+    }
+    return true;
+}
+{% endif %}
+
+/**
+ * Get property value from nested object using dot notation
+ * @param {Object} obj - Object to query
+ * @param {string} path - Dot-notation path (e.g., "item_metadata.condition")
+ * @returns {*} Property value or undefined
+ */
+function getPropertyValue(obj, path) {
+    const parts = path.split('.');
+    let current = obj;
+    for (const part of parts) {
+        if (current === undefined || current === null) {
+            return undefined;
+        }
+        current = current[part];
+    }
+    return current;
+}
+
+/**
+ * Check if trial order satisfies all constraints
+ * @param {Array} trials - Array of trial objects
+ * @param {Object} metadata - Trial metadata
+ * @returns {boolean} True if all constraints satisfied
+ */
+function checkAllConstraints(trials, metadata) {
+    {% if has_precedence %}
+    // Check precedence constraints
+    for (const constraint of constraints) {
+        if (constraint.precedence_pairs && constraint.precedence_pairs.length > 0) {
+            if (!checkPrecedence(trials, constraint.precedence_pairs)) {
+                return false;
+            }
+        }
+    }
+    {% endif %}
+
+    {% if has_no_adjacent %}
+    // Check no-adjacent constraints
+    for (const constraint of constraints) {
+        if (constraint.no_adjacent_property) {
+            if (!checkNoAdjacent(trials, constraint.no_adjacent_property, metadata)) {
+                return false;
+            }
+        }
+    }
+    {% endif %}
+
+    {% if has_min_distance %}
+    // Check minimum distance constraints
+    for (const constraint of constraints) {
+        if (constraint.min_distance && constraint.no_adjacent_property) {
+            if (!checkMinDistance(trials, constraint.no_adjacent_property, constraint.min_distance, metadata)) {
+                return false;
+            }
+        }
+    }
+    {% endif %}
+
+    return true;
+}
+
+/**
+ * Main entry point: randomize trials with constraint enforcement
+ * @param {Array} trials - Array of jsPsych trial objects with item_id property
+ * @param {string|number} seed - Random seed (usually participant ID)
+ * @returns {Array} Randomized trials satisfying all constraints
+ */
+function randomizeTrials(trials, seed) {
+    const rng = new Math.seedrandom(seed);
+
+    {% if has_practice %}
+    // Separate practice items (must come first)
+    const practiceTrials = trials.filter(t => {
+        const meta = trialMetadata[t.item_id];
+        const value = getPropertyValue(meta, '{{ practice_property }}');
+        return value === true;
+    });
+    const mainTrials = trials.filter(t => {
+        const meta = trialMetadata[t.item_id];
+        const value = getPropertyValue(meta, '{{ practice_property }}');
+        return value !== true;
+    });
+    {% else %}
+    const practiceTrials = [];
+    const mainTrials = trials.slice();
+    {% endif %}
+
+    {% if has_blocking %}
+    // Group main trials by block property
+    const blocks = {};
+    mainTrials.forEach(t => {
+        const blockValue = getPropertyValue(trialMetadata[t.item_id], '{{ block_property }}');
+        const blockKey = blockValue !== undefined ? String(blockValue) : '__undefined__';
+        if (!blocks[blockKey]) {
+            blocks[blockKey] = [];
+        }
+        blocks[blockKey].push(t);
+    });
+
+    // Randomize block order
+    const blockKeys = Object.keys(blocks);
+    shuffle(blockKeys, rng);
+
+    let randomizedMain = [];
+    blockKeys.forEach(key => {
+        const blockTrials = blocks[key];
+        {% if randomize_within_blocks %}
+        // Randomize within blocks
+        shuffle(blockTrials, rng);
+        {% endif %}
+        randomizedMain = randomizedMain.concat(blockTrials);
+    });
+    {% else %}
+    // Rejection sampling: try to find valid order
+    const maxAttempts = 1000;
+    let randomizedMain = mainTrials.slice();
+    let lastAttempt = randomizedMain.slice();
+
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+        shuffle(randomizedMain, rng);
+        lastAttempt = randomizedMain.slice();
+
+        if (checkAllConstraints(randomizedMain, trialMetadata)) {
+            break;
+        }
+
+        if (attempt === maxAttempts - 1) {
+            console.warn('Could not find constraint-satisfying order after ' +
+                        maxAttempts + ' attempts. Using last attempt.');
+            randomizedMain = lastAttempt;
+        }
+    }
+    {% endif %}
+
+    return practiceTrials.concat(randomizedMain);
+}
+
+// Export for use in jsPsych experiments
+if (typeof module !== 'undefined' && module.exports) {
+    module.exports = { randomizeTrials };
+}

bead/deployment/jspsych/templates/randomizer.js.template

@@ -0,0 +1,313 @@
+/**
+ * Constraint-Aware Trial Randomization
+ * Generated by sash deployment system
+ *
+ * This code implements runtime trial randomization while satisfying
+ * ordering constraints (precedence, no-adjacency, blocking, distance).
+ */
+
+// Item metadata for constraint checking
+const ITEM_METADATA = {{ metadata_json }};
+
+/**
+ * Main entry point for trial randomization
+ * @param {Array} trials - Array of jsPsych trial objects
+ * @param {string} participantId - Participant ID for seeding
+ * @returns {Array} Randomized trials satisfying all constraints
+ */
+function randomizeTrials(trials, participantId) {
+    // Initialize seeded random number generator
+    const rng = new Math.seedrandom(participantId);
+
+    {% if has_practice_items %}
+    // Separate practice and main trials
+    const practiceTrials = trials.filter(t => {
+        const itemId = t.data?.item_id || t.item_id;
+        return itemId && ITEM_METADATA[itemId]?.{{ practice_property }};
+    });
+
+    const mainTrials = trials.filter(t => {
+        const itemId = t.data?.item_id || t.item_id;
+        return !itemId || !ITEM_METADATA[itemId]?.{{ practice_property }};
+    });
+    {% else %}
+    const practiceTrials = [];
+    const mainTrials = trials.slice();
+    {% endif %}
+
+    {% if has_blocking %}
+    // Block by property: {{ block_property }}
+    const blocks = {};
+    mainTrials.forEach(trial => {
+        const itemId = trial.data?.item_id || trial.item_id;
+        const blockKey = itemId && ITEM_METADATA[itemId]?.{{ block_property }}
+            ? ITEM_METADATA[itemId].{{ block_property }}
+            : 'default';
+
+        if (!blocks[blockKey]) {
+            blocks[blockKey] = [];
+        }
+        blocks[blockKey].push(trial);
+    });
+
+    // Randomize within blocks
+    {% if randomize_within_blocks %}
+    const randomizedBlocks = Object.values(blocks).map(block =>
+        shuffleWithConstraints(block, rng)
+    );
+    {% else %}
+    const randomizedBlocks = Object.values(blocks);
+    {% endif %}
+
+    // Shuffle block order
+    const finalMainTrials = shuffle(randomizedBlocks, rng).flat();
+    {% else %}
+    // Randomize main trials with constraint checking
+    const finalMainTrials = shuffleWithConstraints(mainTrials, rng);
+    {% endif %}
+
+    // Combine practice (randomized) + main trials
+    const randomizedPractice = shuffle(practiceTrials, rng);
+    return [...randomizedPractice, ...finalMainTrials];
+}
+
+/**
+ * Shuffle trials while satisfying all constraints
+ * Uses greedy construction with constraint checking
+ * @param {Array} trials - Trials to shuffle
+ * @param {Function} rng - Seeded random number generator
+ * @returns {Array} Shuffled trials satisfying constraints
+ */
+function shuffleWithConstraints(trials, rng) {
+    if (trials.length === 0) return [];
+
+    // First try greedy construction for distance/no-adjacent constraints
+    {% if has_distance or has_no_adjacent %}
+    const constructed = greedyConstruction(trials, rng);
+    if (constructed && checkAllConstraints(constructed)) {
+        return constructed;
+    }
+    {% endif %}
+
+    // Fall back to rejection sampling with limited attempts
+    const maxAttempts = 10000;
+    let attempt = 0;
+
+    while (attempt < maxAttempts) {
+        const shuffled = shuffle(trials.slice(), rng);
+
+        if (checkAllConstraints(shuffled)) {
+            return shuffled;
+        }
+
+        attempt++;
+    }
+
+    // Final fallback: return random shuffle
+    console.error(`Could not find valid trial order after ${maxAttempts} attempts`);
+    return shuffle(trials.slice(), rng);
+}
+
+{% if has_distance or has_no_adjacent %}
+/**
+ * Greedy construction algorithm for spacing out items
+ * @param {Array} trials - Trials to place
+ * @param {Function} rng - Random number generator
+ * @returns {Array|null} Constructed array or null if failed
+ */
+function greedyConstruction(trials, rng) {
+    const result = [];
+    const remaining = trials.slice();
+    shuffle(remaining, rng); // Randomize initial order
+
+    while (remaining.length > 0) {
+        let placed = false;
+
+        // Try to place each remaining item
+        for (let i = 0; i < remaining.length; i++) {
+            const trial = remaining[i];
+            result.push(trial);
+
+            // Check if this placement is valid
+            if (checkAllConstraints(result)) {
+                remaining.splice(i, 1);
+                placed = true;
+                break;
+            }
+
+            // Invalid, remove and try next
+            result.pop();
+        }
+
+        if (!placed) {
+            // Couldn't place any item, construction failed
+            return null;
+        }
+    }
+
+    return result;
+}
+{% endif %}
+
+/**
+ * Check if trial order satisfies all constraints
+ * @param {Array} trials - Trial order to check
+ * @returns {boolean} True if all constraints satisfied
+ */
+function checkAllConstraints(trials) {
+    {% if has_precedence %}
+    // Check precedence constraints
+    if (!checkPrecedenceConstraints(trials)) {
+        return false;
+    }
+    {% endif %}
+
+    {% if has_no_adjacent %}
+    // Check no-adjacency constraints
+    if (!checkNoAdjacentConstraints(trials)) {
+        return false;
+    }
+    {% endif %}
+
+    {% if has_distance %}
+    // Check distance constraints
+    if (!checkDistanceConstraints(trials)) {
+        return false;
+    }
+    {% endif %}
+
+    return true;
+}
+
+{% if has_precedence %}
+/**
+ * Check precedence constraints (item A must appear before item B)
+ * @param {Array} trials - Trial order to check
+ * @returns {boolean} True if precedence constraints satisfied
+ */
+function checkPrecedenceConstraints(trials) {
+    const precedencePairs = {{ precedence_pairs_json }};
+
+    for (const [beforeId, afterId] of precedencePairs) {
+        let beforeIndex = -1;
+        let afterIndex = -1;
+
+        for (let i = 0; i < trials.length; i++) {
+            const itemId = trials[i].data?.item_id || trials[i].item_id;
+            if (itemId === beforeId) beforeIndex = i;
+            if (itemId === afterId) afterIndex = i;
+        }
+
+        // If both items present, check ordering
+        if (beforeIndex !== -1 && afterIndex !== -1 && beforeIndex >= afterIndex) {
+            return false;
+        }
+    }
+
+    return true;
+}
+{% endif %}
+
+{% if has_no_adjacent %}
+/**
+ * Check no-adjacency constraints (no adjacent items with same property)
+ * @param {Array} trials - Trial order to check
+ * @returns {boolean} True if no-adjacency constraints satisfied
+ */
+function checkNoAdjacentConstraints(trials) {
+    const property = "{{ no_adjacent_property }}";
+
+    for (let i = 0; i < trials.length - 1; i++) {
+        const itemId1 = trials[i].data?.item_id || trials[i].item_id;
+        const itemId2 = trials[i + 1].data?.item_id || trials[i + 1].item_id;
+
+        if (!itemId1 || !itemId2) continue;
+
+        const value1 = ITEM_METADATA[itemId1]?.[property];
+        const value2 = ITEM_METADATA[itemId2]?.[property];
+
+        if (value1 !== undefined && value2 !== undefined && value1 === value2) {
+            return false;
+        }
+    }
+
+    return true;
+}
+{% endif %}
+
+{% if has_distance %}
+/**
+ * Check distance constraints (min/max distance between items)
+ * @param {Array} trials - Trial order to check
+ * @returns {boolean} True if distance constraints satisfied
+ */
+function checkDistanceConstraints(trials) {
+    const distanceConstraints = {{ distance_constraints_json }};
+
+    for (const constraint of distanceConstraints) {
+        const {item1_id, item2_id, min_distance, max_distance} = constraint;
+
+        let index1 = -1;
+        let index2 = -1;
+
+        for (let i = 0; i < trials.length; i++) {
+            const itemId = trials[i].data?.item_id || trials[i].item_id;
+            if (itemId === item1_id) index1 = i;
+            if (itemId === item2_id) index2 = i;
+        }
+
+        // If both items present, check distance
+        if (index1 !== -1 && index2 !== -1) {
+            // Distance is number of items between them (not including the items themselves)
+            const distance = Math.abs(index2 - index1) - 1;
+
+            if (min_distance !== null && distance < min_distance) {
+                return false;
+            }
+
+            if (max_distance !== null && distance > max_distance) {
+                return false;
+            }
+        }
+    }
+
+    return true;
+}
+{% endif %}
+
+/**
+ * Seeded Fisher-Yates shuffle
+ * @param {Array} array - Array to shuffle
+ * @param {Function} rng - Seeded random number generator
+ * @returns {Array} Shuffled array
+ */
+function shuffle(array, rng) {
+    const arr = array.slice();
+    for (let i = arr.length - 1; i > 0; i--) {
+        const j = Math.floor(rng() * (i + 1));
+        [arr[i], arr[j]] = [arr[j], arr[i]];
+    }
+    return arr;
+}
+
+/**
+ * Get nested property from object using dot notation
+ * @param {Object} obj - Object to query
+ * @param {string} path - Property path (e.g., "item_metadata.condition")
+ * @returns {*} Property value or undefined
+ */
+function getNestedProperty(obj, path) {
+    if (!obj || !path) return undefined;
+
+    const parts = path.split('.');
+    let current = obj;
+
+    for (const part of parts) {
+        if (current === null || current === undefined) {
+            return undefined;
+        }
+        current = current[part];
+    }
+
+    return current;
+}