bead 0.1.0__py3-none-any.whl

bead/deployment/jspsych/randomizer.py

@@ -0,0 +1,299 @@
+"""JavaScript randomizer code generator from OrderingConstraints.
+
+This module converts Python OrderingConstraint models into JavaScript code
+that performs constraint-aware trial randomization at jsPsych runtime. This
+enables per-participant randomization while satisfying all ordering constraints.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from uuid import UUID
+
+from jinja2 import Environment, FileSystemLoader
+
+from bead.data.base import JsonValue
+from bead.lists.constraints import OrderingConstraint
+
+
+def generate_randomizer_function(
+    item_ids: list[UUID],
+    constraints: list[OrderingConstraint],
+    metadata: dict[UUID, dict[str, JsonValue]],
+) -> str:
+    """Generate JavaScript code for constraint-aware trial randomization.
+
+    This function converts OrderingConstraints into JavaScript code that can
+    randomize trial order at runtime while satisfying all constraints. The
+    generated code uses seeded randomization for reproducibility and rejection
+    sampling to satisfy constraints.
+
+    Parameters
+    ----------
+    item_ids : list[UUID]
+        List of item IDs included in the experiment.
+    constraints : list[OrderingConstraint]
+        Ordering constraints to enforce.
+    metadata : dict[UUID, dict[str, JsonValue]]
+        Item metadata needed for constraint checking (keyed by item UUID).
+
+    Returns
+    -------
+    str
+        JavaScript code implementing randomizeTrials() function.
+
+    Examples
+    --------
+    >>> from uuid import UUID
+    >>> item1 = UUID("12345678-1234-5678-1234-567812345678")
+    >>> item2 = UUID("87654321-4321-8765-4321-876543218765")
+    >>> constraint = OrderingConstraint(
+    ...     no_adjacent_property="item_metadata.condition"
+    ... )
+    >>> metadata = {
+    ...     item1: {"condition": "A"},
+    ...     item2: {"condition": "B"}
+    ... }
+    >>> js_code = generate_randomizer_function(
+    ...     [item1, item2],
+    ...     [constraint],
+    ...     metadata
+    ... )
+    >>> "function randomizeTrials" in js_code
+    True
+    >>> "checkNoAdjacentConstraints" in js_code
+    True
+    """
+    # prepare template context
+    context = _prepare_template_context(item_ids, constraints, metadata)
+
+    # load and render template
+    template_dir = Path(__file__).parent / "templates"
+    env = Environment(loader=FileSystemLoader(str(template_dir)))
+    template = env.get_template("randomizer.js.template")
+
+    return template.render(**context)
+
+
+def _prepare_template_context(
+    item_ids: list[UUID],
+    constraints: list[OrderingConstraint],
+    metadata: dict[UUID, dict[str, JsonValue]],
+) -> dict[str, JsonValue]:
+    """Prepare Jinja2 template context from constraints.
+
+    Parameters
+    ----------
+    item_ids : list[UUID]
+        Item IDs in the experiment.
+    constraints : list[OrderingConstraint]
+        Ordering constraints.
+    metadata : dict[UUID, dict[str, JsonValue]]
+        Item metadata.
+
+    Returns
+    -------
+    dict[str, JsonValue]
+        Template context for Jinja2 rendering.
+    """
+    context: dict[str, JsonValue] = {
+        "metadata_json": _serialize_metadata(metadata),
+        "has_practice_items": False,
+        "practice_property": "",
+        "has_blocking": False,
+        "block_property": "",
+        "randomize_within_blocks": True,
+        "has_precedence": False,
+        "precedence_pairs_json": "[]",
+        "has_no_adjacent": False,
+        "no_adjacent_property": "",
+        "has_distance": False,
+        "distance_constraints_json": "[]",
+    }
+
+    # combine all constraints (multiple OrderingConstraints can be active)
+    for constraint in constraints:
+        # practice items
+        if constraint.practice_item_property:
+            context["has_practice_items"] = True
+            # extract property name from path
+            # (e.g., "item_metadata.is_practice" -> "is_practice")
+            context["practice_property"] = _extract_property_name(
+                constraint.practice_item_property
+            )
+
+        # blocking
+        if constraint.block_by_property:
+            context["has_blocking"] = True
+            context["block_property"] = _extract_property_name(
+                constraint.block_by_property
+            )
+            context["randomize_within_blocks"] = constraint.randomize_within_blocks
+
+        # precedence
+        if constraint.precedence_pairs:
+            context["has_precedence"] = True
+            # convert UUID pairs to string pairs for JSON
+            pairs = [[str(a), str(b)] for a, b in constraint.precedence_pairs]
+            context["precedence_pairs_json"] = json.dumps(pairs)
+
+        # no-adjacency
+        if constraint.no_adjacent_property:
+            context["has_no_adjacent"] = True
+            # extract property name since metadata is already extracted
+            context["no_adjacent_property"] = _extract_property_name(
+                constraint.no_adjacent_property
+            )
+
+        # distance constraints
+        if constraint.min_distance or constraint.max_distance:
+            context["has_distance"] = True
+            # generate distance constraints for all item pairs
+            distance_constraints = _generate_distance_constraints(
+                item_ids, constraint, metadata
+            )
+            context["distance_constraints_json"] = json.dumps(distance_constraints)
+
+    return context
+
+
+def _serialize_metadata(metadata: dict[UUID, dict[str, JsonValue]]) -> str:
+    """Serialize metadata dictionary to JSON.
+
+    Converts UUID keys to strings for JSON serialization.
+
+    Parameters
+    ----------
+    metadata : dict[UUID, dict[str, JsonValue]]
+        Item metadata with UUID keys.
+
+    Returns
+    -------
+    str
+        JSON string of metadata.
+    """
+    # convert UUID keys to strings
+    serializable = {str(k): v for k, v in metadata.items()}
+    return json.dumps(serializable, indent=2)
+
+
+def _extract_property_name(property_path: str) -> str:
+    """Extract final property name from dot-notation path.
+
+    Parameters
+    ----------
+    property_path : str
+        Dot-notation property path (e.g., "item_metadata.is_practice").
+
+    Returns
+    -------
+    str
+        Final property name (e.g., "is_practice").
+
+    Examples
+    --------
+    >>> _extract_property_name("item_metadata.is_practice")
+    'is_practice'
+    >>> _extract_property_name("condition")
+    'condition'
+    """
+    parts = property_path.split(".")
+    return parts[-1]
+
+
+def _generate_distance_constraints(
+    item_ids: list[UUID],
+    constraint: OrderingConstraint,
+    metadata: dict[UUID, dict[str, JsonValue]],
+) -> list[dict[str, str | int | None]]:
+    """Generate distance constraints for all relevant item pairs.
+
+    Distance constraints are applied to items that share the same value
+    for the no_adjacent_property (if specified).
+
+    Parameters
+    ----------
+    item_ids : list[UUID]
+        Item IDs in the experiment.
+    constraint : OrderingConstraint
+        Ordering constraint with distance specifications.
+    metadata : dict[UUID, dict[str, JsonValue]]
+        Item metadata.
+
+    Returns
+    -------
+    list[dict[str, str | int | None]]
+        List of distance constraint specifications.
+    """
+    distance_constraints: list[dict[str, str | int | None]] = []
+
+    # group items by property value if no_adjacent_property is set
+    if constraint.no_adjacent_property:
+        property_path = constraint.no_adjacent_property
+        # extract just the property name from the path
+        # (e.g., "condition" from "item_metadata.condition")
+        # because metadata is already extracted from items
+        property_name = _extract_property_name(property_path)
+
+        # group items by property value
+        groups: dict[JsonValue, list[UUID]] = {}
+        for item_id in item_ids:
+            item_meta = metadata.get(item_id, {})
+            value = item_meta.get(property_name)
+
+            if value is not None:
+                if value not in groups:
+                    groups[value] = []
+                groups[value].append(item_id)
+
+        # create pairwise distance constraints within each group
+        for _value, item_group in groups.items():
+            if len(item_group) > 1:
+                # create constraints for all pairs in this group
+                for i, item1 in enumerate(item_group):
+                    for item2 in item_group[i + 1 :]:
+                        distance_constraints.append(
+                            {
+                                "item1_id": str(item1),
+                                "item2_id": str(item2),
+                                "min_distance": constraint.min_distance,
+                                "max_distance": constraint.max_distance,
+                            }
+                        )
+
+    return distance_constraints
+
+
+def _get_nested_property(obj: dict[str, JsonValue], path: str) -> JsonValue:  # pyright: ignore[reportUnusedFunction]
+    """Get nested property from dictionary using dot notation.
+
+    Parameters
+    ----------
+    obj : dict[str, JsonValue]
+        Object to query.
+    path : str
+        Property path (e.g., "item_metadata.condition").
+
+    Returns
+    -------
+    JsonValue
+        Property value or None if not found.
+
+    Examples
+    --------
+    >>> obj = {"item_metadata": {"condition": "A"}}
+    >>> _get_nested_property(obj, "item_metadata.condition")
+    'A'
+    >>> _get_nested_property(obj, "missing.path") is None
+    True
+    """
+    parts = path.split(".")
+    current = obj
+
+    for part in parts:
+        if not isinstance(current, dict) or part not in current:
+            return None
+        current = current[part]
+
+    return current

bead/deployment/jspsych/src/lib/list-distributor.test.ts

@@ -0,0 +1,327 @@
+/**
+ * Unit tests for list-distributor.ts helper functions.
+ *
+ * Tests the pure functions that can be tested without JATOS.
+ * The main ListDistributor class requires JATOS batch sessions.
+ */
+
+import { describe, expect, test } from "vitest";
+
+// Helper functions copied from list-distributor.ts for isolated testing.
+// These are internal functions not exported from the module.
+
+function generateBalancedLatinSquare(n: number): number[][] {
+  const square: number[][] = [];
+  for (let i = 0; i < n; i++) {
+    const row: number[] = [];
+    for (let j = 0; j < n; j++) {
+      if (i % 2 === 0) {
+        row.push((Math.floor(i / 2) + j) % n);
+      } else {
+        row.push((Math.floor(i / 2) + n - j) % n);
+      }
+    }
+    square.push(row);
+  }
+  return square;
+}
+
+function shuffleArray<T>(array: T[]): void {
+  for (let i = array.length - 1; i > 0; i--) {
+    const j = Math.floor(Math.random() * (i + 1));
+    const temp = array[i];
+    const swapVal = array[j];
+    if (temp !== undefined && swapVal !== undefined) {
+      array[i] = swapVal;
+      array[j] = temp;
+    }
+  }
+}
+
+interface ExperimentList {
+  id: string;
+  name: string;
+  list_number: number;
+  list_metadata?: Record<string, unknown>;
+  item_refs: string[];
+}
+
+interface QueueEntry {
+  list_index: number;
+  list_id: string;
+}
+
+interface DistributionConfig {
+  strategy_type: string;
+  strategy_config?: {
+    factors?: string[];
+    weight_expression?: string;
+    normalize_weights?: boolean;
+    participants_per_list?: number;
+    allow_overflow?: boolean;
+    filter_expression?: string;
+    rank_expression?: string;
+    rank_ascending?: boolean;
+  };
+  max_participants?: number;
+}
+
+function initializeRandom(
+  _config: DistributionConfig,
+  lists: ExperimentList[],
+  maxParticipants: number,
+): QueueEntry[] {
+  const queue: QueueEntry[] = [];
+  const perList = Math.ceil(maxParticipants / lists.length);
+  for (let i = 0; i < lists.length; i++) {
+    const list = lists[i];
+    if (list) {
+      for (let j = 0; j < perList; j++) {
+        queue.push({ list_index: i, list_id: list.id });
+      }
+    }
+  }
+  shuffleArray(queue);
+  return queue;
+}
+
+function initializeSequential(
+  _config: DistributionConfig,
+  lists: ExperimentList[],
+  maxParticipants: number,
+): QueueEntry[] {
+  const queue: QueueEntry[] = [];
+  for (let i = 0; i < maxParticipants; i++) {
+    const listIndex = i % lists.length;
+    const list = lists[listIndex];
+    if (list) {
+      queue.push({ list_index: listIndex, list_id: list.id });
+    }
+  }
+  return queue;
+}
+
+function initializeLatinSquare(
+  _config: DistributionConfig,
+  lists: ExperimentList[],
+): { queue: QueueEntry[]; matrix: number[][] } {
+  const matrix = generateBalancedLatinSquare(lists.length);
+  const queue: QueueEntry[] = [];
+
+  for (let row = 0; row < matrix.length; row++) {
+    const matrixRow = matrix[row];
+    if (matrixRow) {
+      for (let col = 0; col < matrixRow.length; col++) {
+        const listIndex = matrixRow[col];
+        if (listIndex !== undefined) {
+          const list = lists[listIndex];
+          if (list) {
+            queue.push({ list_index: listIndex, list_id: list.id });
+          }
+        }
+      }
+    }
+  }
+
+  return { queue, matrix };
+}
+
+function initializeQuotaBased(
+  config: DistributionConfig,
+  lists: ExperimentList[],
+): { queue: QueueEntry[]; quotas: Record<number, number> } {
+  const quota = config.strategy_config?.participants_per_list ?? 10;
+  const quotas: Record<number, number> = {};
+  const queue: QueueEntry[] = [];
+
+  for (let i = 0; i < lists.length; i++) {
+    quotas[i] = quota;
+    const list = lists[i];
+    if (list) {
+      for (let j = 0; j < quota; j++) {
+        queue.push({ list_index: i, list_id: list.id });
+      }
+    }
+  }
+
+  shuffleArray(queue);
+  return { queue, quotas };
+}
+
+describe("generateBalancedLatinSquare", () => {
+  test("generates correct 4x4 balanced Latin square", () => {
+    const square = generateBalancedLatinSquare(4);
+
+    expect(square).toHaveLength(4);
+    expect(square[0]).toHaveLength(4);
+
+    // Check each row contains 0,1,2,3
+    for (const row of square) {
+      const sorted = [...row].sort();
+      expect(sorted).toEqual([0, 1, 2, 3]);
+    }
+  });
+
+  test("generates correct 2x2 balanced Latin square", () => {
+    const square = generateBalancedLatinSquare(2);
+
+    expect(square).toHaveLength(2);
+    // Row 0 (even): (floor(0/2) + j) % 2 = (0 + j) % 2
+    expect(square[0]).toEqual([0, 1]);
+    // Row 1 (odd): (floor(1/2) + 2 - j) % 2 = (0 + 2 - j) % 2
+    expect(square[1]).toEqual([0, 1]);
+  });
+
+  test("generates square with balanced counterbalancing", () => {
+    const square = generateBalancedLatinSquare(4);
+
+    // Verify first column follows the algorithm pattern
+    // i=0 (even): (floor(0/2) + 0) % 4 = 0
+    expect(square[0]?.[0]).toBe(0);
+    // i=1 (odd): (floor(1/2) + 4 - 0) % 4 = (0 + 4) % 4 = 0
+    expect(square[1]?.[0]).toBe(0);
+    // i=2 (even): (floor(2/2) + 0) % 4 = 1
+    expect(square[2]?.[0]).toBe(1);
+    // i=3 (odd): (floor(3/2) + 4 - 0) % 4 = (1 + 4) % 4 = 1
+    expect(square[3]?.[0]).toBe(1);
+  });
+});
+
+describe("initializeRandom", () => {
+  test("generates queue with equal entries per list", () => {
+    const lists: ExperimentList[] = [
+      { id: "list_1", name: "list_1", list_number: 0, item_refs: [] },
+      { id: "list_2", name: "list_2", list_number: 1, item_refs: [] },
+      { id: "list_3", name: "list_3", list_number: 2, item_refs: [] },
+    ];
+    const config: DistributionConfig = { strategy_type: "random" };
+    const maxParticipants = 30;
+
+    const queue = initializeRandom(config, lists, maxParticipants);
+
+    expect(queue.length).toBe(30);
+    // Count entries per list
+    const counts: Record<number, number> = { 0: 0, 1: 0, 2: 0 };
+    for (const entry of queue) {
+      counts[entry.list_index] = (counts[entry.list_index] ?? 0) + 1;
+    }
+    // Should be roughly equal (10 each)
+    expect(counts[0]).toBeGreaterThanOrEqual(9);
+    expect(counts[0]).toBeLessThanOrEqual(11);
+  });
+});
+
+describe("initializeSequential", () => {
+  test("generates sequential queue with round-robin", () => {
+    const lists: ExperimentList[] = [
+      { id: "list_1", name: "list_1", list_number: 0, item_refs: [] },
+      { id: "list_2", name: "list_2", list_number: 1, item_refs: [] },
+      { id: "list_3", name: "list_3", list_number: 2, item_refs: [] },
+    ];
+    const config: DistributionConfig = { strategy_type: "sequential" };
+    const maxParticipants = 10;
+
+    const queue = initializeSequential(config, lists, maxParticipants);
+
+    expect(queue.length).toBe(10);
+    expect(queue[0]?.list_index).toBe(0);
+    expect(queue[1]?.list_index).toBe(1);
+    expect(queue[2]?.list_index).toBe(2);
+    expect(queue[3]?.list_index).toBe(0); // Wraps around (3 % 3 = 0)
+    expect(queue[4]?.list_index).toBe(1); // 4 % 3 = 1
+    expect(queue[9]?.list_index).toBe(0); // 9 % 3 = 0
+  });
+});
+
+describe("initializeLatinSquare", () => {
+  test("generates queue from Latin square matrix", () => {
+    const lists: ExperimentList[] = [
+      { id: "list_1", name: "list_1", list_number: 0, item_refs: [] },
+      { id: "list_2", name: "list_2", list_number: 1, item_refs: [] },
+      { id: "list_3", name: "list_3", list_number: 2, item_refs: [] },
+    ];
+    const config: DistributionConfig = { strategy_type: "latin_square" };
+
+    const { queue, matrix } = initializeLatinSquare(config, lists);
+
+    expect(matrix).toHaveLength(3);
+    expect(queue.length).toBe(9); // 3x3 matrix
+    // Verify queue entries match matrix
+    let queueIndex = 0;
+    for (let row = 0; row < matrix.length; row++) {
+      const matrixRow = matrix[row];
+      if (matrixRow) {
+        for (let col = 0; col < matrixRow.length; col++) {
+          expect(queue[queueIndex]?.list_index).toBe(matrixRow[col]);
+          queueIndex++;
+        }
+      }
+    }
+  });
+
+  test("includes both queue and matrix in result", () => {
+    const lists: ExperimentList[] = [
+      { id: "list_1", name: "list_1", list_number: 0, item_refs: [] },
+      { id: "list_2", name: "list_2", list_number: 1, item_refs: [] },
+    ];
+    const config: DistributionConfig = { strategy_type: "latin_square" };
+
+    const result = initializeLatinSquare(config, lists);
+
+    expect(result).toHaveProperty("queue");
+    expect(result).toHaveProperty("matrix");
+    expect(Array.isArray(result.queue)).toBe(true);
+    expect(Array.isArray(result.matrix)).toBe(true);
+  });
+});
+
+describe("initializeQuotaBased", () => {
+  test("generates queue and quotas correctly", () => {
+    const lists: ExperimentList[] = [
+      { id: "list_1", name: "list_1", list_number: 0, item_refs: [] },
+      { id: "list_2", name: "list_2", list_number: 1, item_refs: [] },
+      { id: "list_3", name: "list_3", list_number: 2, item_refs: [] },
+    ];
+    const config: DistributionConfig = {
+      strategy_type: "quota_based",
+      strategy_config: {
+        participants_per_list: 5,
+      },
+    };
+
+    const { queue, quotas } = initializeQuotaBased(config, lists);
+
+    expect(queue.length).toBe(15); // 3 lists * 5 participants
+    expect(quotas[0]).toBe(5);
+    expect(quotas[1]).toBe(5);
+    expect(quotas[2]).toBe(5);
+
+    // Count entries per list
+    const counts: Record<number, number> = { 0: 0, 1: 0, 2: 0 };
+    for (const entry of queue) {
+      counts[entry.list_index] = (counts[entry.list_index] ?? 0) + 1;
+    }
+    expect(counts[0]).toBe(5);
+    expect(counts[1]).toBe(5);
+    expect(counts[2]).toBe(5);
+  });
+
+  test("includes both queue and quotas in result", () => {
+    const lists: ExperimentList[] = [
+      { id: "list_1", name: "list_1", list_number: 0, item_refs: [] },
+    ];
+    const config: DistributionConfig = {
+      strategy_type: "quota_based",
+      strategy_config: {
+        participants_per_list: 10,
+      },
+    };
+
+    const result = initializeQuotaBased(config, lists);
+
+    expect(result).toHaveProperty("queue");
+    expect(result).toHaveProperty("quotas");
+    expect(Array.isArray(result.queue)).toBe(true);
+    expect(typeof result.quotas).toBe("object");
+  });
+});