bead 0.1.0__py3-none-any.whl

bead/deployment/jspsych/src/plugins/rating.ts

@@ -0,0 +1,248 @@
+/**
+ * bead-rating plugin
+ *
+ * jsPsych plugin for ordinal scale judgments (Likert scales, rating scales).
+ *
+ * Features:
+ * - Discrete scales (e.g., 1-7, 1-9)
+ * - Custom labels for scale points
+ * - Keyboard shortcuts (number keys 1-9)
+ * - Material Design styling
+ * - Required response validation
+ * - Preserves all item and template metadata
+ *
+ * @author Bead Project
+ * @version 0.1.0
+ */
+
+import type { JsPsych, JsPsychPlugin, KeyboardResponseInfo, PluginInfo } from "../types/jspsych.js";
+
+/** Task specification from bead metadata */
+interface TaskSpec {
+  scale_bounds?: [number, number];
+  scale_labels?: Record<number, string>;
+  prompt?: string;
+}
+
+/** Bead item/template metadata */
+interface BeadMetadata {
+  task_spec?: TaskSpec;
+  [key: string]: unknown;
+}
+
+/** Rating trial parameters */
+export interface RatingTrialParams {
+  /** The prompt to display above the rating scale */
+  prompt: string | null;
+  /** Minimum value of the scale */
+  scale_min: number;
+  /** Maximum value of the scale */
+  scale_max: number;
+  /** Labels for specific scale points (e.g., {1: "Strongly Disagree", 7: "Strongly Agree"}) */
+  scale_labels: Record<number, string>;
+  /** Whether to require a response before continuing */
+  require_response: boolean;
+  /** Text for the continue button */
+  button_label: string;
+  /** Complete item and template metadata (automatically populated from trial.data) */
+  metadata: BeadMetadata;
+}
+
+/** Rating response data */
+interface RatingResponse {
+  rating: number | null;
+  rt: number | null;
+}
+
+/** Plugin info constant */
+const info: PluginInfo = {
+  name: "bead-rating",
+  parameters: {
+    prompt: {
+      type: 8, // ParameterType.HTML_STRING
+      default: null,
+    },
+    scale_min: {
+      type: 2, // ParameterType.INT
+      default: 1,
+    },
+    scale_max: {
+      type: 2, // ParameterType.INT
+      default: 7,
+    },
+    scale_labels: {
+      type: 12, // ParameterType.OBJECT
+      default: {},
+    },
+    require_response: {
+      type: 0, // ParameterType.BOOL
+      default: true,
+    },
+    button_label: {
+      type: 1, // ParameterType.STRING
+      default: "Continue",
+    },
+    metadata: {
+      type: 12, // ParameterType.OBJECT
+      default: {},
+    },
+  },
+};
+
+/**
+ * BeadRatingPlugin - jsPsych plugin for ordinal scale judgments
+ */
+class BeadRatingPlugin implements JsPsychPlugin<typeof info, RatingTrialParams> {
+  static info = info;
+
+  private jsPsych: JsPsych;
+
+  constructor(jsPsych: JsPsych) {
+    this.jsPsych = jsPsych;
+  }
+
+  trial(display_element: HTMLElement, trial: RatingTrialParams): void {
+    const response: RatingResponse = {
+      rating: null,
+      rt: null,
+    };
+
+    const start_time = performance.now();
+
+    // Override scale bounds from metadata if available
+    if (trial.metadata.task_spec?.scale_bounds) {
+      trial.scale_min = trial.metadata.task_spec.scale_bounds[0];
+      trial.scale_max = trial.metadata.task_spec.scale_bounds[1];
+    }
+
+    // Override scale labels from metadata if available
+    if (trial.metadata.task_spec?.scale_labels) {
+      trial.scale_labels = trial.metadata.task_spec.scale_labels;
+    }
+
+    // Override prompt from metadata if available
+    if (trial.metadata.task_spec?.prompt && !trial.prompt) {
+      trial.prompt = trial.metadata.task_spec.prompt;
+    }
+
+    // Create HTML
+    let html = '<div class="bead-rating-container">';
+
+    if (trial.prompt !== null) {
+      html += `<div class="bead-rating-prompt">${trial.prompt}</div>`;
+    }
+
+    html += '<div class="bead-rating-scale">';
+
+    // Create rating buttons
+    for (let i = trial.scale_min; i <= trial.scale_max; i++) {
+      const label = trial.scale_labels[i] ?? i;
+      html += `
+        <div class="bead-rating-option">
+          <button class="bead-rating-button" data-value="${i}">${i}</button>
+          <div class="bead-rating-label">${label}</div>
+        </div>
+      `;
+    }
+
+    html += "</div>"; // Close scale
+
+    // Continue button
+    html += `
+      <div class="bead-rating-button-container">
+        <button class="bead-button bead-continue-button" id="bead-rating-continue" disabled>
+          ${trial.button_label}
+        </button>
+      </div>
+    `;
+
+    html += "</div>"; // Close container
+
+    display_element.innerHTML = html;
+
+    // Add event listeners for rating buttons
+    const rating_buttons =
+      display_element.querySelectorAll<HTMLButtonElement>(".bead-rating-button");
+    for (const button of rating_buttons) {
+      button.addEventListener("click", (e) => {
+        const target = e.target as HTMLButtonElement;
+        const valueAttr = target.getAttribute("data-value");
+        if (valueAttr !== null) {
+          const value = Number.parseInt(valueAttr, 10);
+          select_rating(value);
+        }
+      });
+    }
+
+    // Keyboard listener
+    const keyboard_listener = this.jsPsych.pluginAPI.getKeyboardResponse({
+      callback_function: (info: KeyboardResponseInfo) => {
+        // Check if key is 1-9
+        const key = info.key;
+        const num = Number.parseInt(key, 10);
+        if (!Number.isNaN(num) && num >= trial.scale_min && num <= trial.scale_max) {
+          select_rating(num);
+        }
+      },
+      valid_responses: "ALL_KEYS",
+      rt_method: "performance",
+      persist: true,
+      allow_held_key: false,
+    });
+
+    // Continue button listener
+    const continue_button =
+      display_element.querySelector<HTMLButtonElement>("#bead-rating-continue");
+    if (continue_button) {
+      continue_button.addEventListener("click", () => {
+        if (response.rating !== null || !trial.require_response) {
+          end_trial();
+        }
+      });
+    }
+
+    const select_rating = (value: number): void => {
+      // Update response
+      response.rating = value;
+      response.rt = performance.now() - start_time;
+
+      // Update UI
+      for (const btn of rating_buttons) {
+        btn.classList.remove("selected");
+      }
+      const selected_button = display_element.querySelector<HTMLButtonElement>(
+        `[data-value="${value}"]`,
+      );
+      if (selected_button) {
+        selected_button.classList.add("selected");
+      }
+
+      // Enable continue button
+      if (continue_button) {
+        continue_button.disabled = false;
+      }
+    };
+
+    const end_trial = (): void => {
+      // Kill keyboard listener
+      if (keyboard_listener) {
+        this.jsPsych.pluginAPI.cancelKeyboardResponse(keyboard_listener);
+      }
+
+      // Preserve all metadata from trial.metadata and add response data
+      const trial_data: Record<string, unknown> = {
+        ...trial.metadata, // Spread all metadata
+        rating: response.rating,
+        rt: response.rt,
+      };
+
+      // Clear display
+      display_element.innerHTML = "";
+
+      // End trial
+      this.jsPsych.finishTrial(trial_data);
+    };
+  }
+}
+
+export { BeadRatingPlugin };

bead/deployment/jspsych/src/slopit/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Slopit bundle for bead experiments.
+ *
+ * This module re-exports the slopit jsPsych adapter for use in
+ * browser-based experiments.
+ */
+
+// Re-export the jsPsych extension from slopit
+export { SlopitExtension } from "@slopit/adapter-jspsych";

bead/deployment/jspsych/src/types/jatos.d.ts

@@ -0,0 +1,256 @@
+/**
+ * Type declarations for JATOS (Just Another Tool for Online Studies) API.
+ *
+ * JATOS provides a server-side infrastructure for running online experiments
+ * with features like batch sessions, worker management, and data storage.
+ */
+
+/** JATOS URL query parameters (typically from Prolific/MTurk) */
+export interface JatosUrlParams {
+  /** Prolific participant ID */
+  PROLIFIC_PID?: string;
+  /** Prolific study ID */
+  STUDY_ID?: string;
+  /** Prolific session ID */
+  SESSION_ID?: string;
+  /** Generic participant ID */
+  participant_id?: string;
+  /** Any other URL parameters */
+  [key: string]: string | undefined;
+}
+
+/** Batch session data stored in JATOS */
+export interface BatchSessionData {
+  /** Assignment queue for random/sequential distribution */
+  assignment_queue?: number[];
+  /** Counts of participants assigned to each list */
+  assignment_counts?: Record<string, number>;
+  /** Latin square counter for counterbalancing */
+  latin_square_counter?: number;
+  /** Quota tracking per list */
+  quotas?: Record<string, number>;
+  /** Workers currently assigned (for completion tracking) */
+  active_workers?: Record<string, number>;
+  /** Workers who completed the study */
+  completed_workers?: string[];
+  /** Custom metadata for stratification */
+  stratification_state?: Record<string, unknown>;
+  /** Version for optimistic locking */
+  version?: number;
+  /** Any other batch session data */
+  [key: string]: unknown;
+}
+
+/** JATOS batch session API */
+export interface JatosBatchSession {
+  /**
+   * Get a value from the batch session by path.
+   * Uses dot notation (e.g., "assignment_counts.list_0").
+   */
+  get<T = unknown>(path: string): T | undefined;
+
+  /**
+   * Check if a path is defined in the batch session.
+   */
+  defined(path: string): boolean;
+
+  /**
+   * Set a value in the batch session.
+   * Returns a promise that resolves when the write is confirmed.
+   */
+  set<T>(path: string, value: T): JatosPromise<void>;
+
+  /**
+   * Replace the entire batch session data.
+   * Useful for atomic updates.
+   */
+  replace(data: BatchSessionData): JatosPromise<void>;
+
+  /**
+   * Remove a value from the batch session.
+   */
+  remove(path: string): JatosPromise<void>;
+
+  /**
+   * Find a value using JSON pointer or path.
+   */
+  find(path: string): unknown;
+
+  /**
+   * Get all batch session data.
+   */
+  getAll(): BatchSessionData;
+
+  /**
+   * Clear all batch session data.
+   */
+  clear(): JatosPromise<void>;
+}
+
+/** JATOS-style promise with .fail() for error handling */
+export interface JatosPromise<T> extends Promise<T> {
+  /**
+   * Handle errors (JATOS uses .fail() instead of .catch()).
+   */
+  fail(onRejected: (reason: Error) => void): JatosPromise<T>;
+
+  /**
+   * Chain operations (alias for .then()).
+   */
+  then<TResult1 = T, TResult2 = never>(
+    onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | null,
+    onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null,
+  ): JatosPromise<TResult1 | TResult2>;
+}
+
+/** Component result state */
+export type ComponentResultState =
+  | "PRE"
+  | "STARTED"
+  | "DATA_RETRIEVED"
+  | "RESULTDATA_POSTED"
+  | "FINISHED"
+  | "RELOADED"
+  | "ABORTED"
+  | "FAIL";
+
+/** Study result state */
+export type StudyResultState =
+  | "PRE"
+  | "STARTED"
+  | "DATA_RETRIEVED"
+  | "FINISHED"
+  | "ABORTED"
+  | "FAIL";
+
+/** Main JATOS API interface */
+export interface JatosAPI {
+  /** Current JATOS version */
+  version: string;
+
+  /** Worker ID assigned by JATOS */
+  workerId: string;
+
+  /** Current study result ID */
+  studyResultId: string;
+
+  /** Current component result ID */
+  componentResultId: string;
+
+  /** Study ID */
+  studyId: string;
+
+  /** Component ID */
+  componentId: string;
+
+  /** Batch ID */
+  batchId: string;
+
+  /** Group result ID (if in group study) */
+  groupResultId?: string;
+
+  /** URL query parameters */
+  urlQueryParameters: JatosUrlParams;
+
+  /** Study properties set in JATOS GUI */
+  studyProperties: Record<string, unknown>;
+
+  /** Component properties set in JATOS GUI */
+  componentProperties: Record<string, unknown>;
+
+  /** Study session data (persists across components) */
+  studySessionData: Record<string, unknown>;
+
+  /** Batch session API */
+  batchSession: JatosBatchSession;
+
+  /**
+   * Called when JATOS is ready.
+   */
+  onLoad(callback: () => void): void;
+
+  /**
+   * Submit result data to JATOS.
+   */
+  submitResultData(data: string | object): JatosPromise<void>;
+
+  /**
+   * Append to result data.
+   */
+  appendResultData(data: string | object): JatosPromise<void>;
+
+  /**
+   * End the study successfully.
+   */
+  endStudy(successful?: boolean, message?: string): void;
+
+  /**
+   * End the study and redirect to a URL.
+   */
+  endStudyAndRedirect(url: string, message?: string): void;
+
+  /**
+   * End the current component and move to next.
+   */
+  startNextComponent(): void;
+
+  /**
+   * End the current component and move to a specific component.
+   */
+  startComponent(componentId: number | string): void;
+
+  /**
+   * End the current component and move to the last component.
+   */
+  startLastComponent(): void;
+
+  /**
+   * Abort the study.
+   */
+  abortStudy(message?: string): void;
+
+  /**
+   * Add an abort button to the page.
+   */
+  addAbortButton(): void;
+
+  /**
+   * Remove the abort button.
+   */
+  removeAbortButton(): void;
+
+  /**
+   * Log a message to the JATOS console.
+   */
+  log(message: string): void;
+
+  /**
+   * Set study session data.
+   */
+  setStudySessionData(data: Record<string, unknown>): JatosPromise<void>;
+
+  /**
+   * Upload a file to JATOS.
+   */
+  uploadResultFile(file: File | Blob, filename: string): JatosPromise<{ url: string }>;
+
+  /**
+   * Download study assets.
+   */
+  downloadAssetFile(filename: string): Promise<Blob>;
+
+  /**
+   * Get the component result state.
+   */
+  getComponentResultState(): ComponentResultState;
+
+  /**
+   * Get the study result state.
+   */
+  getStudyResultState(): StudyResultState;
+}
+
+/** Global JATOS instance */
+declare global {
+  const jatos: JatosAPI;
+}